mirror of
https://github.com/pim-n/pg-rad
synced 2026-06-17 15:59:35 +02:00
update docs
This commit is contained in:
Pim Nelissen
BIN
docs/explainers/Nelissen_Pim_Thesis_MORC_PGRAD.pdf
Normal file
BIN
docs/explainers/Nelissen_Pim_Thesis_MORC_PGRAD.pdf
Normal file
Binary file not shown.
@ -6,28 +6,4 @@ Primary Gamma RADiation Landscapes (PG-RAD) is a Python package for research in
|
||||
|
||||
This software has been developed as part of dissertation work for the degree of master of Computational Science and Physics at Lund University, Sweden. The work has been done at the department of Medical Radiation Physics (MSF), Faculty of Medicine. The radiological emergency preparedness research group of MSF is assigned by the Swedish Radiation Safety Authority (SSM) to aid in preparation for effective mitigation of radiological or nuclear disasters on Swedish soil.
|
||||
|
||||
## Value proposition
|
||||
|
||||
PG-RAD is a toolbox that allows for simulation of detector response for a wide variety of source localization scenarios. The strength of the software lies in its simple and minimal configuration and user input, while its flexibility allows for reconstruction of specific scenarios with relative ease. PG-RAD is also general enough that novel methods such as UAV-borne detectors can be simulated and evaluated.
|
||||
|
||||
User input takes the form of an input file (YAML), describing the path, detector and source(s), and optional parameters. The output of the program is visualizations of the world (the path and sources), as well as the detector count rate as a function of distance travelled along the path.
|
||||
|
||||
Users can provide experimental / geographical coordinates representing real roads. Alternatively, users can let PG-RAD generate a procedural road, where the user can easily control what that road should look like. The user can specify a single point source, several point sources, as well as a field of radioactive material covering a large area.
|
||||
```
|
||||
|
||||
See how to get started with PG-RAD with your own Python code [here](pg-rad-in-python).
|
||||
|
||||
## For developers
|
||||
```
|
||||
git clone https://github.com/pim-n/pg-rad
|
||||
cd pg-rad
|
||||
git checkout dev
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
git@github.com:pim-n/pg-rad.git
|
||||
cd pg-rad
|
||||
git checkout dev
|
||||
```
|
||||
To read more about PG-RAD and the applications it was tested with, you can read the thesis [here](explainers/Nelissen_Pim_Thesis_MORC_PGRAD.pdf).
|
||||
|
||||
@ -1,47 +1,33 @@
|
||||
## Requirements
|
||||
[](https://www.python.org/downloads/release/python-312/)
|
||||
[](https://github.com/pim-n/pg-rad/actions/workflows/ci-tests.yml)
|
||||
|
||||
PG-RAD requires Python `>=3.12.4` and `<3.13`. It has been tested on `3.12.9`. The guides below assume a unix-like system. You can check the Python version you have installed as follows:
|
||||
PG-RAD is a Python 3.12 package and is only tested on x86_64 Linux systems. The following installation instructions were testing for a fresh virtual machine running Ubuntu 26.04 LTS.
|
||||
|
||||
```
|
||||
python --version
|
||||
```
|
||||
### Conda installation (Tested and recommended)
|
||||
|
||||
If you don't have the right version installed there are various ways to get a compatible version, such as [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation).
|
||||
1. Install git by `sudo apt update && sudo apt install git`
|
||||
2. Install miniforge by following [these](https://conda-forge.org/download/) instructions.
|
||||
3. Create a file called `environment.yml`, and paste the following in there:
|
||||
|
||||
## Installation (CLI)
|
||||
```yaml
|
||||
name: my-pgrad-env
|
||||
channels:
|
||||
- conda-forge
|
||||
dependencies:
|
||||
- python=3.12
|
||||
- pip:
|
||||
- git+ssh://git@github.com/pim-n/pg-rad.git@v0.1.1
|
||||
```
|
||||
You can replace the name of the environment if desired.
|
||||
|
||||
<!--pipx seems like a possible option to install python package in a contained environment on unix-->
|
||||
4. Run `conda env create -f environment.yml` to create the environment
|
||||
5. Run `conda activate my-pgrad-env`. You should now be in the conda environment `my-pgrad-env`.
|
||||
6. To test if installation was succesful, run `pgrad --example --show`. If this runs without errors and produces visual output, PG-RAD is correctly installed.
|
||||
|
||||
Lorem ipsum
|
||||
### Manual installation
|
||||
|
||||
## Installation (Python module)
|
||||
If you prefer another virtual environment, you still need git installed. Ensure the Python version of the environment is `>3.12.4` and `<3.13`. Then, with your virtual environment activated, run `pip install git+ssh://git@github.com/pim-n/pg-rad.git@main`. Run `pgrad --example --show` to check if the installation was successful.
|
||||
|
||||
If you are interested in using PG-RAD in another Python project, create a virtual environment first:
|
||||
### Usage
|
||||
|
||||
```
|
||||
python -m venv .venv
|
||||
```
|
||||
|
||||
Then install PG-RAD in it:
|
||||
|
||||
```
|
||||
source .venv/bin/activate
|
||||
(.venv) pip install git+https://github.com/pim-n/pg-rad
|
||||
```
|
||||
|
||||
See how to get started with PG-RAD with your own Python code [here](pg-rad-in-python).
|
||||
|
||||
## For developers
|
||||
```
|
||||
git clone https://github.com/pim-n/pg-rad
|
||||
cd pg-rad
|
||||
git checkout dev
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
git@github.com:pim-n/pg-rad.git
|
||||
cd pg-rad
|
||||
git checkout dev
|
||||
```
|
||||
For usage, see the [Quickstart Guide](quickstart.md).
|
||||
|
||||
@ -1,35 +0,0 @@
|
||||
{
|
||||
"cells": [
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"id": "5e30f59a",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# The design of PG-RAD\n",
|
||||
"\n",
|
||||
"This discusses the overall design of the code by using an interactive notebook demo."
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"kernelspec": {
|
||||
"display_name": ".venv",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
"language_info": {
|
||||
"codemirror_mode": {
|
||||
"name": "ipython",
|
||||
"version": 3
|
||||
},
|
||||
"file_extension": ".py",
|
||||
"mimetype": "text/x-python",
|
||||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.12.9"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 5
|
||||
}
|
||||
@ -1,6 +1,6 @@
|
||||
## Installation
|
||||
|
||||
See the [installation guide](installation.md).
|
||||
See the [Installation Guide](installation.md).
|
||||
|
||||
## Test your installation
|
||||
|
||||
@ -35,6 +35,20 @@ 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
|
||||
@ -185,4 +199,4 @@ The easiest way to get started is to take one of these example configs, and adju
|
||||
position: [0, 0, 0]
|
||||
|
||||
detector: dummy
|
||||
```
|
||||
```
|
||||
|
||||
@ -60,4 +60,6 @@ nav:
|
||||
- 'Tutorial: Writing a Config File': config-spec.md
|
||||
- Explainers:
|
||||
- explainers/planar_curve.ipynb
|
||||
- explainers/prefab_roads.ipynb
|
||||
- explainers/prefab_roads.ipynb
|
||||
- explainers/count_rate_along_path.ipynb
|
||||
- Thesis: explainers/Nelissen_Pim_Thesis_MORC_PGRAD.pdf
|
||||
Reference in New Issue
Block a user