Skip to content

# Quickstart Guide

## Installation

See the Installation Guide.

## Test your installation

First, see if PG-RAD is available on your system by typing

    pgrad --help

You should get output along the lines of

    usage: pg-rad [-h] ...

    Primary Gamma RADiation landscape tool

    ...

If you get something like `pgrad: command not found`, please consult the installation guide.

You can run a quick test by running the example landscape as follows:

    pgrad --example

This should produce an output like

    INFO: Landscape built successfully: Example landscape
    WARNING: No output produced. Use --save flag to save outputs and/or --showplots to display interactive plots.

Running

    pgrad --example --show

should produce visual output. Running

    pgrad --example --save

should create a new directory in whatever directory you ran `pgrad`, which contains the saved outputs.

## Running PG-RAD

In order to use the CLI for your own simulations, you need to provide a config file. To run with your config, run

    pgrad --config path/to/my_config.yml

where `path/to/my_config.yml` points to your config file. To check the results live, add the `--showplots` flag. If you want to save the results directly, then add the `--save` flag (you can use them at the same time as well).

## Example configs

The easiest way to get started is to take one of these example configs, and adjust them as needed. Alternatively, there is a detailed guide on how to write your own config file here.

Example 1Example 2Example 3Example 4Example 5

The position can be defined relative to the path. `along_path` means at what distance traveled along the path the source is found. If the path is 200 meters long and `along_path` is `100` then the source is halfway along the path. `dist_from_path` is the distance in meters from the path. `side` is the side of the path the source is located. This is relative to the direction the path is traveled.

    name: Example 1
    speed: 13.89
    acquisition_time: 1

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

    sources:
      source1:
      activity_MBq: 1000
      isotope: Cs137
      gamma_energy_keV: 662
      position:
        along_path: 100
        dist_from_path: 50
        side: left

    detector: dummy

The position can also just be defined with (x,y,z) coordinates.

    name: Example 2
    speed: 13.89
    acquisition_time: 1

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

    sources:
      source1:
        activity_MBq: 1000
        isotope: Cs137
        gamma_energy_keV: 662
        position: [104.3, 32.5, 0]
      source2:
        activity_MBq: 100
        isotope: Cs137
        gamma_energy_keV: 662
        position: [0, 0, 0]

    detector: dummy

This is an example of a procedural path with random apportionment of total length and random angles being assigned to turns. The parameter `alpha` is optional, and is related to randomness. A higher value leads to more uniform apportionment of lengths and a lower value to more random apportionment. More information about `alpha` can be found here.

    name: Example 3
    speed: 8.33
    acquisition_time: 1

    path:
      length: 1000
      segments:
        - straight
        - turn_left
        - straight
      alpha: 100

    sources:
      source1:
        activity_MBq: 1000
        isotope: Cs137
        gamma_energy_keV: 662
        position: [0, 0, 0]

    detector: dummy

This is an example of a procedural path that is partially specified. Note that turn_left now is a key for the corresponding angle of 45 degrees. The length is still divided randomly

    name: Example 4
    speed: 8.33
    acquisition_time: 1

    path:
      length: 1000
      segments:
        - straight
        - turn_left: 45
        - straight

    sources:
      source1:
        activity_MBq: 1000
        isotope: Cs137
        gamma_energy_keV: 662
        position: [0, 0, 0]

    detector: dummy

This is an example of a procedural path that is fully specified. See how length is now a list matching the length of the segments.

    name: Example 5
    speed: 8.33
    acquisition_time: 1

    path:
      length:
        - 400
        - 200
        - 400
      segments:
        - straight
        - turn_left: 45
        - straight

    sources:
      source1:
        activity_MBq: 1000
        isotope: Cs137
        gamma_energy_keV: 662
        position: [0, 0, 0]

    detector: dummy