Skip to content

# Tutorial: Writing a Config File

Note

To get started quickly, you may copy and modify one of the example configs found here.

The config file must be a YAML file. YAML is a serialization language that works with key-value pairs, but in a syntax more readable than some other alternatives. The remainder of this chapter will explain the different required and optionals keys, what they represent, and allowed values.

## Required keys

### Simulation options

The first step is to name the simulation, and define the speed of the vehicle (assumed constant) and acquisition time.

#### Landscape name

The name is a string, which may include spaces, numbers and special characters.

Examples:

    name: test_landscape

    name: Test Landscape 1

#### Acquisition time

The acquisition time of the detector in seconds.

Example:

    acquisition_time: 1

Note

All units in the config file must be specified in SI units, e.g. meters and seconds, unless the key contains a unit itself (e.g. `activity_MBq` means activity in MegaBequerels).

#### Vehicle speed

The speed of the vehicle in m/s. Currently, the vehicle speed must be assumed constant. An example could be

    speed: 13.89 # this is approximately 50 km/h

Note

The text after the `#` signifies a comment. PG-RAD will ignore this, but it can be helpful for yourself to write notes.

### Path

The `path` keyword is used to create a path for the detector to travel along. There are two ways to specify a path; from experimental data or by specifying a procedural path.

#### Path - Experimental data

Currently the only supported coordinate format is the RT90 (East, North) coordinate system. If you have experimental data in CSV format with columns for these coordinates, then you can load that path into PG-RAD as follows:

    path:
      file: path/to/experimental_data.csv
      east_col_name: East
      north_col_name: North

#### Path - Procedural path

Alternatively, you can let PG-RAD generate a path for you. A procedural path can be specified with at least two subkeys: `length` and `segments`.

Currently supported segments are: `straight`, `turn_left` and `turn_right`, and are provided in a list under the `segments` subkey as follows:

    path:
      segments:
        - straight
        - turn_left
        - straight

The length must also be specified, using the `length` subkey. `length` can be specified in two ways: a list with the same length as the `segments` list

    path:
      segments:
        - straight
        - turn_left
        - straight
      length:
        - 500
        - 250
        - 500

which will assign that length (meters) to each segment. Alternatively, a single number can be passed:

    path:
      segments:
        - straight
        - turn_left
        - straight
      length: 1250

Setting the length for the total path will cause PG-RAD to randomly assign portions of the total length to each segment.

Finally, there is also an option to specify the turn angle in degrees:

    path:
      segments:
        - straight
        - turn_left: 90
        - straight
      length: 1250

Like with the lengths, if a turn segment has no angle specified, a random one (within pre-defined limits) will be taken.

Warning

Letting PG-RAD randomly assign lengths and angles can cause (expected) issues. That is because of physics restrictions. If the combination of length, angle (radius) and velocity of the vehicle is such that the centrifugal force makes it impossible to take this turn, PG-RAD will raise an error. To fix it, you can 1) reduce the speed; 2) define a smaller angle for the turn; or 3) assign more length to the turn segment.

Info

For more information about how procedural roads are generated, including the random sampling of lengths and angles, see this explainer.

### Sources

Currently, the only type of source supported is an isotropic point source. However, an arbitrary number of point sources can be added to the landscape. Point sources can be added under the `sources` key, where the subkey is the name of the source:

    sources:
      my_source: ...

the source name should not contain spaces or special characters other than `_` or `-`. There are three required subkeys under `sources.my_source`, which are: `activity_MBq`, `isotope` and `position`.

#### Source activity

The source activity is in MegaBequerels and must be a strictly positive number:

    sources:
      my_source:
        activity_MBq: 100

#### Source isotope

The isotope for the point source. This must be a string, following the naming convention of the symbol followed by the number of nucleons, e.g. `Cs137`:

    sources:
      my_source:
        activity_MBq: 100
        isotope: Cs137

Info

Currently the following isotopes are supported: `Cs137`

#### Source position

There are two ways to specify the source position. Either with absolute (x,y,z) coordinates

    sources:
      my_source:
        activity_MBq: 100
        isotope: Cs137
        position: [0, 0, 0]

or relative to the path, using the subkeys `along_path`, `dist_from_path` and `side`

    sources:
      my_source:
        activity_MBq: 100
        isotope: Cs137
        position:
          along_path: 100
          dist_from_path: 50
          side: left

Note that side is relative to the direction of travel. The path will by default start at (x,y) = (0,0) and initial heading is parallel to the x-axis.

### Detector

The final required key is the `detector`. Currently, custom detectors are not yet supported and you must choose from a list of existing detectors:

    detector: LU_HPGe_90

## Optional keys

The following subkeys are optional and should be put under the `options` key.

    options:
      air_density_kg_per_m3: 1.243
      seed: 1234