pg-rad/docs/quickstart.md

## Installation

See the [installation guide](installation.md).

## 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](installation.md).

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 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](config-spec.md).

=== "Example 1"

    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.

    ``` yaml
    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
    ```

=== "Example 2"

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

    ``` yaml
    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
    ```

=== "Example 3"

    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](explainers/prefab_roads.ipynb).

    ``` yaml
    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
    ```

=== "Example 4"

    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

    ``` yaml
    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
    ```

=== "Example 5"

    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.

    ``` yaml
    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
    ```