Add rst docs

doc/authors.rst

+.. _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

doc/configFiles.rst

+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
+
+
+
+

doc/guide_developer.rst

+================
+Guidance
+================
+

doc/index.rst

@@ -9,7 +9,11 @@ Welcome to KiT-RT's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-
+   introduction
+   authors
+   installation
+   configFiles
+   philosophy
 
 
 Indices and tables

doc/installation.rst

+.. _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.
+
+
+
+

doc/introduction.rst

+.. _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).

doc/philosophy.rst

+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
+***********************

doc/physics.rst

+================
+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.

doc/release.rst

+=============
+Release Notes
+=============
+
+.. toctree::
+  :maxdepth: 1
+
+  0.1.0