Commit b035c451 authored by Tianbai Xiao's avatar Tianbai Xiao
Browse files

Add rst docs


Former-commit-id: 2356b187
parent a5533637
.. _authors:
Authors
------------------
*****************
KiT-RT Software
*****************
+--------------------+------------------------+
|Main contributors | - Jannick Wolters |
| | - Jonas Kusch |
| | - Steffen Schotthöfer |
| | - Tianbai Xiao |
| | - Pia Stammer |
+--------------------+------------------------+
|Other contributors | |
+--------------------+------------------------+
*********************
KiT-RT Dokumentation
*********************
+--------------------+------------------------+
|Main authors | - Jannick Wolters |
| | - Jonas Kusch |
| | - Steffen Schotthöfer |
| | - Tianbai Xiao |
| | - Pia Stammer |
+--------------------+------------------------+
|Other contributors | |
+--------------------+------------------------+
\ No newline at end of file
Configuration files
-----------------------
Configuration files are written in `TOML-style <https://github.com/toml-lang/toml>`_
. A number of examples (link examples) can be found in the ``./code/input`` folder. Users can also handover their own files, which should follow the following specifications:
********************
Parameters
********************
Below you can see the possible parameters that can be specified in a config file. Which of these parameters are required depends on the chosen application and solver
.. code-block:: c++
// --- Options ---
// File Structure
std::string _inputDir; // Directory for input files
std::string _outputDir; // Directory for output files
std::string _outputFile; // Name of output file
std::string _logDir; // Directory of log file
std::string _logFileName; // Name of log file
std::string _meshFile; // Name of mesh file
std::string _ctFile; // Name of CT file
// Quadrature
QUAD_NAME _quadName; // Quadrature Name
unsigned short _quadOrder; // Quadrature Order
unsigned _nQuadPoints;
// Mesh
unsigned _nCells;
// Solver
double _CFL; // CFL Number for Solver
double _tEnd; // Final Time for Simulation
PROBLEM_NAME _problemName; // Name of predefined Problem
SOLVER_NAME _solverName; // Name of the used Solver
ENTROPY_NAME _entropyName; // Name of the used Entropy Functional
unsigned short _maxMomentDegree; // Maximal Order of Moments for PN and MN Solver
unsigned short _reconsOrder; // Spatial Order of Accuracy for Solver
// Linesource
double _sigmaS; // Scattering coeffient for Linesource test case
/*If true, very low entries (10^-10 or smaller) of the flux matrices will be set to zero,
* to improve floating point accuracy */
bool _cleanFluxMat;
/*If true, the SN Solver uses all Gauss pts in the quadrature */
bool _allGaussPts;
/*If true, continuous slowing down approximation will be used */
bool _csd;
std::string _hydrogenFile; // Name of hydrogen cross section file
std::string _oxygenFile; // Name of oxygen cross section file
// Boundary Conditions
/*List of all Pairs (marker, BOUNDARY_TYPE), e.g. (farfield,DIRICHLET).
*Each Boundary Conditions must have an entry in enum BOUNDARY_TYPE*/
std::vector<std::pair<std::string, BOUNDARY_TYPE>> _boundaries;
unsigned short _nMarkerDirichlet; // Number of Dirichlet BC markers. Enum entry: DIRICHLET
unsigned short _nMarkerNeumann; // Number of Neumann BC markers. Enum entry: Neumann
std::vector<std::string> _MarkerDirichlet; // Dirichlet BC markers.
std::vector<std::string> _MarkerNeumann; // Neumann BC markers.
// Scattering Kernel
KERNEL_NAME _kernelName; // Scattering Kernel Name
// Optimizer
OPTIMIZER_NAME _entropyOptimizerName; // Choice of optimizer
double _optimizerEpsilon; // termination criterion epsilon for Newton Optmizer
unsigned short _newtonIter; // Maximal Number of newton iterations
double _newtonStepSize; // Stepsize factor for newton optimizer
unsigned short _newtonLineSearchIter; // Maximal Number of line search iterations for newton optimizer
bool _newtonFastMode; // If true, we skip the NewtonOptimizer for quadratic entropy and assign alpha = u
// Output Options
unsigned short _nVolumeOutput; // Number of volume outputs
std::vector<VOLUME_OUTPUT> _volumeOutput; // Output groups for volume output
unsigned short _volumeOutputFrequency; // Frequency of vtk write of volume output
unsigned short _nScreenOutput; // Number of screen outputs
std::vector<SCALAR_OUTPUT> _screenOutput; // Output groups for screen output
unsigned short _screenOutputFrequency; // Frequency of screen output
unsigned short _nHistoryOutput; // Number of screen outputs
std::vector<SCALAR_OUTPUT> _historyOutput; // Output groups for screen output
unsigned short _historyOutputFrequency; // Frequency of screen output
================
Guidance
================
......@@ -9,7 +9,11 @@ Welcome to KiT-RT's documentation!
.. toctree::
:maxdepth: 2
:caption: Contents:
introduction
authors
installation
configFiles
philosophy
Indices and tables
......
.. _installation:
Installation
------------------------
*****
Build
*****
Required dependencies
=====================
- Compiler with C++17 support
- cmake >= v3.12.4
- LAPACK
- OpenMP
- MPI
- VTK
- git
- ninja or make
Obtain submodules
==================
Note that an **active internet connection is required for the first build** in order to download the latest versions of the required submodules!
For the first build only, download all submodules:
.. code-block:: bash
git submodule update --init --recursive
Compile the code
================
**Make** build system (available on most systems)
.. code-block:: bash
cd code/build/release
cmake -DCMAKE_BUILD_TYPE=Release ../../
make
If building in parallel is desired, change the last line to `make -jN`, where `N` optimally is equal to the number of available threads+1.
**Ninja** build system:
.. code-block:: bash
cd code/build/release
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../../
ninja
The resulting executable will automatically be placed in the `code/bin` folder.
----------------------------------------------------------
**********
Run
**********
Local
===========
Execute the compiled binary from the `bin` folder and hand over a valid *TOML*-styled config file.
Example from inside the `code` directory:
```bash
./KiT-RT ../input/example.cfg
```
In order to run the code in parallel execute:
```bash
OMP_NUM_THREADS=N mpirun -np J ./KiT-RT ../input/example.cfg
```
with `N` equal to the number of shared memory threads and `J` equal to the number of distrubuted memory threads.
BwUniCluster
==============
As VTK is not available on the bwUniCluster, it needs to be installed first. This just needs to be done once. Example:
.. code-block:: bash
module load devel/cmake/3.16
module load compiler/gnu/9.2
wget --no-check-certificate --quiet https://www.vtk.org/files/release/8.2/VTK-8.2.0.tar.gz
tar xzf VTK-8.2.0.tar.gz
mkdir VTK-build
cd VTK-build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_DOCUMENTATION=OFF -DBUILD_TESTING=OFF -
DCMAKE_INSTALL_PREFIX=~/VTK-install ../VTK-8.2.0
make -j
make install
cd -
rm -r VTK-8.2.0 VTK-build
Example for build and run on bwUniCluster:
Get the code
.. code-block:: bash
git clone https://git.scc.kit.edu/rtsn/rtsn.git KiT-RT
cd KiT-RT/
git submodule init
git submodule update
Append ``HINTS VTK_INSTALL_DIR` to the ``find_package( VTK ... )`` line in the CMakeLists.txt. E.g.:
.. code-block:: bash
find_package( VTK REQUIRED COMPONENTS vtkIOGeometry vtkFiltersCore HINTS ~/VTK-install )
Compile it
.. code-block:: bash
module load devel/cmake/3.16
module load compiler/gnu/9.2
module load mpi/openmpi/4.0
cd code/build/release/
cmake -DCMAKE_BUILD_TYPE=Release ../../
make -j
---------------------------------------------------------------
Tests
============================
After compiling the framework as described above just run:
.. code-block:: bash
make test
The ``unit_tests`` executable will also be placed in in the build folder.
.. _introduction:
KiT-RT - The kinetic transport solver for radiation therapy
---------------------------------------------
The KiT-RT framework is a powerful open source platform for radiation transport. Its main focus is on radiotherapy planning in cancer treatment. To allow problem-specific method selection, the framework provides different deterministic solver types. This not only facilitates treatment planning, but also provides tools to investigate various research questions in the field of radiative transfer. This goal is supported by an easily extensible code structure that allows straightforward implementation of additional methods and techniques.
The software is being developed by members of the group `CSMM <https://www.scc.kit.edu/forschung/13971.php?tab=%5B14114%5D#tabpanel-14114>`_ at the Karlsruhe Institute of Technology (KIT). For more information, please contact any of our authors (link to authors page).
Philosophy
-------------
*************
Open Science
*************
****************************
Code development
****************************
Continuous Integration (CI)
============================
Every commit on the master branch will trigger a build test and unit tests.
If either of the tests fail you will get an email, telling you the 'pipeline' has failed. If this happens, visit the 'CI/CD' tab and check what went wrong and try to fix the error as soon as possible.
Creating a merge request from a branch into the master branch will (not tested yet) also trigger the tests and your merge will be rejected in case any test fails.
As a temporary solution, these tests will currently be done on a low power virtual machine running on a 24/7 online PC at Jannick's place (i.e. don't create computationally expensive tests right now as they will fail if exceeding 1GB of memory).
If you add additional libraries to the code, these also need to be added to the test environment, i.e. the respective docker container.
Little guide:
Test the library installation in the docker container
.. code-block:: bash
docker run -it --rm rtsn/test:latest bash
Note the steps required and add them to the `Dockerfile` in the `scripts` folder.
Build the new container (takes some time)
.. code-block:: bash
cd docker build -t rtsn/test:latest .
or commit your changes to the image (google that procedure).
Push the new image to `hub.docker.com`
.. code-block:: bash
docker push rtsn/test:latest
This last step requires a preceeding `docker login`. Ask Jannick for login credentials.
Coding Style
==============
Please stick to the following coding style for easier code readability:
- class variables start with an underscore and lowercase letters e.g. ``_foo``
- functions start with a capital letter e.g. ``GetSettings()``
- any variable/function names have capital letters at each individual word e.g. ``GetAllCellsAdjacentTo(Cell i)``
Please also use the provided ``code/.clang-format`` style format to format your code before pushing your latest commits.
Some editors offer to automatically apply the style format upon saving a file (e.g. ``Qtcreator``).
***********************
Scrum
***********************
================
Transport Theory
================
The kinetic theory is dedicated to describe the dynamical behavior of a many-particle system through ensemble averaging.
Particles, e.g. molecules, photons, neutrons, electrons and plasmas, travel along the trajectories and undergo occasional collisions that change their directions and energies.
Such dynamics can be formulated via operator splitting approach in the Boltzmann equation, i.e.
.. math::
:label: boltzmann
\frac{\partial \psi}{\partial t}+v \cdot \nabla_x \psi = Q(\psi)
where :math:`\psi` is the one-particle probability distribution function, :math:`v` is velocity and :math:`Q(\psi)` is the scattering term.
In the Kit-RT solver, we consider the liner Boltzmann equation
.. math::
:label: linearbz
\partial_{t} f(v)+v \cdot \nabla_{x} f(v)=\sigma \int k\left(v, v^{\prime}\right)\left(f\left(v^{\prime}\right)-f(v)\right) d v^{\prime}-\tau f(v)
where the particles don't interact with one another but scatter with the background material.
For convenience, we reformulate the particle velocity into polar coordinates.
=============
Release Notes
=============
.. toctree::
:maxdepth: 1
0.1.0
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment