Commit 759950cb authored by Jannick Wolters's avatar Jannick Wolters
Browse files

merged doc into develop


Former-commit-id: 8d087a67
parents a2fcf152 f0a351c4
version: 2
python:
version: 3.7
install:
- requirements: doc/requirements.txt
sphinx:
builder: html
configuration: doc/conf.py
submodules:
exclude: all
formats: []
[![pipeline status](https://git.scc.kit.edu/rtsn/rtsn/badges/master/pipeline.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![coverage report](https://git.scc.kit.edu/rtsn/rtsn/badges/master/coverage.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master)
[![pipeline status](https://git.scc.kit.edu/rtsn/rtsn/badges/master/pipeline.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![coverage report](https://git.scc.kit.edu/rtsn/rtsn/badges/master/coverage.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![Documentation Status](https://readthedocs.org/projects/kit-rt/badge/?version=latest)](https://kit-rt.readthedocs.io/en/latest/?badge=latest)
# KiT-RT - an HPC Radio Therapy $`S_n`$ framework
TBD
......@@ -152,13 +152,13 @@ This last step requires a preceeding `docker login`. Ask Jannick for login crede
## Code structure
**WARNING: is not created automatically - might be out of date!**
Reverse engineered plantuml diagram of the current code structure:
![Can't load image](doc/KiT-RT.svg "UML diagram")
![Can't load image](doc/images/uml.svg "UML diagram")
<br/><br/>
Was created using [hpp2plantuml](https://github.com/thibaultmarin/hpp2plantuml) and [plantuml](https://plantuml.com/), e.g.:
```bash
cd doc
hpp2plantuml -i "../code/include/*.h" -i "../code/include/*/*.h" -o KiT-RT.puml
plantuml KiT-RT.puml -tsvg
hpp2plantuml -i "../code/include/*.h" -i "../code/include/*/*.h" -o uml.puml
plantuml uml.puml -tsvg
```
---
......
......@@ -4,8 +4,10 @@ project( KiT-RT VERSION 0.1.0 LANGUAGES CXX )
### OPTIONS #####################################
option( BUILD_TESTS "builds all available unit tests" OFF )
option( BUILD_GUI "additionally builds a user interface" OFF )
option( BUILD_DOC "builds Doxygen and Sphinx documentation" OFF )
#################################################
### COMPILER ####################################
set( CMAKE_CXX_STANDARD 17 )
set( CMAKE_CXX_STANDARD_REQUIRED ON )
......@@ -97,6 +99,8 @@ if( BUILD_TESTS )
set( CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/ext/Catch2/contrib ${CMAKE_MODULE_PATH} )
include( Catch )
set( CATCH_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/ext/Catch2/single_include/catch2 )
add_compile_definitions( BUILD_TESTING )
add_compile_definitions( TESTS_PATH="${CMAKE_SOURCE_DIR}/tests/" )
add_library( Catch INTERFACE )
target_include_directories( Catch INTERFACE ${CATCH_INCLUDE_DIR} )
file( GLOB_RECURSE TEST_SRCS RELATIVE ${CMAKE_SOURCE_DIR} "tests/*.cpp" )
......@@ -138,3 +142,40 @@ if( BUILD_GUI )
target_compile_options( ${CMAKE_PROJECT_NAME}_gui PUBLIC "$<$<CONFIG:RELEASE>:${KITRT_RELEASE_OPTIONS}>" )
endif()
#################################################
### BUILD DOCUMENTATION #########################
if( BUILD_DOC )
find_package( Doxygen REQUIRED )
find_package( Sphinx REQUIRED )
file( GLOB_RECURSE DOC_HEADER RELATIVE ${CMAKE_SOURCE_DIR} "include/*.h" )
set( DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR} )
set( DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen )
set( DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html )
set( DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/../doc/Doxyfile.in )
set( DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile )
configure_file( ${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY )
file( MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR} )
add_custom_command( OUTPUT ${DOXYGEN_INDEX_FILE}
DEPENDS ${DOC_HEADER}
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
COMMENT "Generating documentaion with Doxygen"
VERBATIM )
add_custom_target( Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE} )
set( SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/../doc )
set( SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx )
set( SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html )
add_custom_command( OUTPUT ${SPHINX_INDEX_FILE}
COMMAND ${SPHINX_EXECUTABLE} ${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../doc/index.rst ${DOXYGEN_INDEX_FILE}
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
COMMENT "Converting documentation from Doxygen to Sphinx" )
add_custom_target( Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE} )
endif()
#################################################
find_program( SPHINX_EXECUTABLE
NAMES sphinx-build
DOC "Path to sphinx-build executable" )
include( FindPackageHandleStandardArgs )
find_package_handle_standard_args( Sphinx
"Failed to find sphinx-build executable"
SPHINX_EXECUTABLE )
This diff is collapsed.
.wy-side-nav-search {
background-color: #009682;
}
.wy-nav-side {
background: #009682;
}
.. _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
Config
======
.. doxygenclass:: Config
:members:
Common
======
.. toctree::
:maxdepth: 1
config
mesh
Mesh
====
.. doxygenclass:: Mesh
:members:
import subprocess, os
project = 'KiT-RT'
copyright = '2021, Karlsruhe Institute of Technology'
author = 'Jonas Kusch, Steffen Schotthöfer, Pia Stammer, Jannick Wolters, Tianbai Xiao'
version = 'v0.1'
release = 'v0.1'
extensions = [
'breathe',
'sphinx_rtd_theme'
]
#templates_path = ['_templates']
master_doc = 'index'
exclude_patterns = []
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'logo_only': True,
'display_version': True,
}
html_logo = 'images/KiT-RT_logo_small.png'
html_static_path = ['_static']
def setup(app):
app.add_css_file('theme_overrides.css')
breathe_projects = {
"KiT-RT": "../code/build/debug/docs/doxygen/xml",
}
breathe_default_project = "KiT-RT"
read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
if read_the_docs_build:
inputDir = '../code'
outputDir = '../code/build/debug/docs/doxygen'
if not os.path.exists(outputDir):
os.makedirs(outputDir)
with open("Doxyfile.in", "rt") as fin:
with open("Doxyfile", "wt") as fout:
for line in fin:
line = line.replace('GENERATE_HTML = YES', 'GENERATE_HTML = NO')
line = line.replace('SEARCH_INCLUDES = YES', 'SEARCH_INCLUDES = NO')
line = line.replace('CLASS_DIAGRAMS = YES', 'CLASS_DIAGRAMS = NO')
line = line.replace('@DOXYGEN_OUTPUT_DIR@', outputDir)
line = line.replace('@DOXYGEN_INPUT_DIR@', inputDir)
fout.write(line)
subprocess.call('doxygen', shell=True)
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
C++ Documentation
=================
.. image:: images/uml.svg
:width: 800
:alt: UML diagram
.. toctree::
:maxdepth: 2
common/index
entropies/index
fluxes/index
kernels/index
optimizers/index
problems/index
quadratures/index
solvers/index
toolboxes/index
================
Developer Guide
================
EntropyBase
===========
.. doxygenclass:: EntropyBase
:members:
Entropies
=========
.. toctree::
:maxdepth: 1
entropybase
maxwellboltzmannentropy
quadraticentropy
\ No newline at end of file
MaxwellBoltzmannEntropy
=======================
.. doxygenclass:: MaxwellBoltzmannEntropy
:members:
QuadraticEntropy
================
.. doxygenclass:: QuadraticEntropy
:members:
Fluxes
======
.. toctree::
:maxdepth: 1
numericalflux
laxfriedrichsflux
upwindflux
\ No newline at end of file
LaxFriedrichsFlux
=================
.. doxygenclass:: LaxFriedrichsFlux
:members:
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