diff --git a/doc/common/index.rst b/doc/common/index.rst index 783cd9bd..178f228a 100644 --- a/doc/common/index.rst +++ b/doc/common/index.rst @@ -5,4 +5,5 @@ Common :maxdepth: 1 config + io mesh diff --git a/doc/common/io.rst b/doc/common/io.rst index 302aa831..b68d12f0 100644 --- a/doc/common/io.rst +++ b/doc/common/io.rst @@ -1,8 +1,4 @@ IO -==== - -.. doxygenclass:: IO - :members: - :protected-members: - :private-members: +== +.. doxygenfile:: io.hpp diff --git a/doc/configFiles.rst b/doc/configFiles.rst index 5987dba3..73be07a8 100644 --- a/doc/configFiles.rst +++ b/doc/configFiles.rst @@ -1,96 +1,141 @@ -Configuration files ------------------------ - -Configuration files are written in `TOML-style `_ -. 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> _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 _MarkerDirichlet; // Dirichlet BC markers. - std::vector _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 _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 _screenOutput; // Output groups for screen output - unsigned short _screenOutputFrequency; // Frequency of screen output - - unsigned short _nHistoryOutput; // Number of screen outputs - std::vector _historyOutput; // Output groups for screen output - unsigned short _historyOutputFrequency; // Frequency of screen output - - - - +Configuration files +=================== + +KiT-RT uses a simple key-value format parsed by `Config` (see +`src/common/config.cpp`). It is not strict TOML. + +Syntax +------ + +- One option per line: `KEY = VALUE` +- Lists use parentheses: `SCREEN_OUTPUT = (ITER, MASS, RMS_FLUX)` +- Comments often use `%` in existing examples +- Boolean values use `YES/NO` +- Relative paths are resolved from the config file directory + +Minimal example +--------------- + +.. code-block:: cfg + + OUTPUT_DIR = ../../../result + OUTPUT_FILE = checkerboard_SN + LOG_DIR = ../../../result/logs + MESH_FILE = ../../mesh_files/checkerboard.su2 + + PROBLEM = CHECKERBOARD + SOLVER = SN_SOLVER + CFL_NUMBER = 0.5 + TIME_FINAL = 0.4 + + BC_DIRICHLET = ( void ) + + QUAD_TYPE = GAUSS_LEGENDRE_TENSORIZED_2D + QUAD_ORDER = 4 + + VOLUME_OUTPUT = (MINIMAL) + +Core options +------------ + +File and paths: + +- `OUTPUT_DIR`, `OUTPUT_FILE`, `LOG_DIR`, `LOG_FILE` +- `MESH_FILE`, `CT_FILE`, `DATA_DIR` +- `LOAD_RESTART_SOLUTION`, `SAVE_RESTART_SOLUTION_FREQUENCY` + +Solver setup: + +- `SOLVER`, `PROBLEM`, `HPC_SOLVER` +- `CFL_NUMBER`, `TIME_FINAL`, `RECONS_ORDER`, `TIME_INTEGRATION_ORDER` +- `MAX_MOMENT_SOLVER`, `SPATIAL_DIM`, `SN_ALL_GAUSS_PTS` + +Physics and closures: + +- `KERNEL`, `SPHERICAL_BASIS` +- `ENTROPY_FUNCTIONAL`, `ENTROPY_OPTIMIZER` +- `REGULARIZER_GAMMA`, `NEWTON_*`, `NEURAL_MODEL_*` + +Boundary and quadrature: + +- `BC_DIRICHLET`, `BC_NEUMANN` +- `QUAD_TYPE`, `QUAD_ORDER` + +Output control: + +- `VOLUME_OUTPUT`, `VOLUME_OUTPUT_FREQUENCY` +- `SCREEN_OUTPUT`, `SCREEN_OUTPUT_FREQUENCY` +- `HISTORY_OUTPUT`, `HISTORY_OUTPUT_FREQUENCY` + +Current enum values (from code) +-------------------------------- + +`SOLVER`: + +- `SN_SOLVER` +- `PN_SOLVER` +- `MN_SOLVER` +- `MN_SOLVER_NORMALIZED` +- `CSD_SN_SOLVER` +- `CSD_PN` +- `CSD_MN` + +`PROBLEM`: + +- `LINESOURCE`, `LINESOURCE_1D` +- `CHECKERBOARD`, `CHECKERBOARD_1D` +- `AIRCAVITY_1D`, `WATERPHANTOM`, `RADIATIONCT` +- `MELTINGCUBE`, `MELTINGCUBE_1D` +- `STARMAP_VALIDATION` +- `HOHLRAUM`, `SYMMETRIC_HOHLRAUM`, `QUARTER_HOHLRAUM` +- `LATTICE`, `HALF_LATTICE` + +`QUAD_TYPE`: + +- `MONTE_CARLO` +- `GAUSS_LEGENDRE_TENSORIZED`, `GAUSS_LEGENDRE_TENSORIZED_2D`, `GAUSS_LEGENDRE_1D` +- `LEVEL_SYMMETRIC`, `LEBEDEV`, `LDFESA`, `TESSALATION`, `PRODUCT` +- `MIDPOINT_1D`, `MIDPOINT_2D`, `MIDPOINT_3D` +- `RECTANGULAR_1D`, `RECTANGULAR_2D`, `RECTANGULAR_3D` + +`KERNEL`: + +- `ISOTROPIC`, `ISOTROPIC_1D` + +`SPHERICAL_BASIS`: + +- `SPHERICAL_HARMONICS` +- `SPHERICAL_MONOMIALS` +- `SPHERICAL_MONOMIALS_ROTATED` + +HPC SN config pattern +--------------------- + +The HPC path is selected with: + +- `SOLVER = SN_SOLVER` +- `HPC_SOLVER = YES` + +Example (from validation inputs): + +.. code-block:: cfg + + PROBLEM = LATTICE + SOLVER = SN_SOLVER + HPC_SOLVER = YES + RECONS_ORDER = 2 + TIME_INTEGRATION_ORDER = 2 + QUAD_TYPE = GAUSS_LEGENDRE_TENSORIZED_2D + QUAD_ORDER = 4 + +Reference configs +----------------- + +Validated examples are under: + +- `tests/input/validation_tests/SN_solver` +- `tests/input/validation_tests/PN_solver` +- `tests/input/validation_tests/MN_solver` +- `tests/input/validation_tests/CSD_PN_solver` +- `tests/input/validation_tests/CSD_MN_solver` +- `tests/input/validation_tests/SN_solver_hpc` diff --git a/doc/cpp_doc.rst b/doc/cpp_doc.rst index 7b64787a..dd80a276 100644 --- a/doc/cpp_doc.rst +++ b/doc/cpp_doc.rst @@ -7,8 +7,9 @@ C++ Documentation .. toctree:: :maxdepth: 2 - + common/index + datagenerator/index entropies/index fluxes/index kernels/index diff --git a/doc/datagenerator/datagenerator1D.rst b/doc/datagenerator/datagenerator1D.rst index 98a7d43b..59b56191 100644 --- a/doc/datagenerator/datagenerator1D.rst +++ b/doc/datagenerator/datagenerator1D.rst @@ -1,7 +1,12 @@ -DataGeneratorBase -============= +Data Generators 1D +================== -.. doxygenclass:: DataGeneratorBase +.. doxygenclass:: DataGeneratorClassification1D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: DataGeneratorRegression1D :members: :protected-members: :private-members: diff --git a/doc/datagenerator/datagenerator2D.rst b/doc/datagenerator/datagenerator2D.rst index 98a7d43b..1875a812 100644 --- a/doc/datagenerator/datagenerator2D.rst +++ b/doc/datagenerator/datagenerator2D.rst @@ -1,7 +1,12 @@ -DataGeneratorBase -============= +Data Generators 2D +================== -.. doxygenclass:: DataGeneratorBase +.. doxygenclass:: DataGeneratorClassification2D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: DataGeneratorRegression2D :members: :protected-members: :private-members: diff --git a/doc/datagenerator/datagenerator3D.rst b/doc/datagenerator/datagenerator3D.rst index 98a7d43b..82def251 100644 --- a/doc/datagenerator/datagenerator3D.rst +++ b/doc/datagenerator/datagenerator3D.rst @@ -1,7 +1,7 @@ -DataGeneratorBase -============= +Data Generators 3D +================== -.. doxygenclass:: DataGeneratorBase +.. doxygenclass:: DataGeneratorRegression3D :members: :protected-members: :private-members: diff --git a/doc/datagenerator/datageneratorbase.rst b/doc/datagenerator/datageneratorbase.rst index 98a7d43b..91e09d6d 100644 --- a/doc/datagenerator/datageneratorbase.rst +++ b/doc/datagenerator/datageneratorbase.rst @@ -1,5 +1,5 @@ DataGeneratorBase -============= +================= .. doxygenclass:: DataGeneratorBase :members: diff --git a/doc/datagenerator/datageneratorclassification.rst b/doc/datagenerator/datageneratorclassification.rst index 98a7d43b..122fadb9 100644 --- a/doc/datagenerator/datageneratorclassification.rst +++ b/doc/datagenerator/datageneratorclassification.rst @@ -1,7 +1,7 @@ -DataGeneratorBase -============= +DataGeneratorClassification +=========================== -.. doxygenclass:: DataGeneratorBase +.. doxygenclass:: DataGeneratorClassification :members: :protected-members: :private-members: diff --git a/doc/datagenerator/datageneratorregression.rst b/doc/datagenerator/datageneratorregression.rst index 98a7d43b..8ddbad84 100644 --- a/doc/datagenerator/datageneratorregression.rst +++ b/doc/datagenerator/datageneratorregression.rst @@ -1,7 +1,7 @@ -DataGeneratorBase -============= +DataGeneratorRegression +======================= -.. doxygenclass:: DataGeneratorBase +.. doxygenclass:: DataGeneratorRegression :members: :protected-members: :private-members: diff --git a/doc/datagenerator/index.rst b/doc/datagenerator/index.rst index ccd4874f..4a66ec5e 100644 --- a/doc/datagenerator/index.rst +++ b/doc/datagenerator/index.rst @@ -1,12 +1,12 @@ -datagenerator -========= +Data Generators +=============== .. toctree:: :maxdepth: 1 + datageneratorbase + datageneratorclassification + datageneratorregression datagenerator1D datagenerator2D datagenerator3D - datageneratorbase - datageneratorregression - datageneratorclassification diff --git a/doc/developer_guide.rst b/doc/developer_guide.rst index f5bb665a..5553829e 100644 --- a/doc/developer_guide.rst +++ b/doc/developer_guide.rst @@ -1,49 +1,34 @@ -================ Developer Guide -================ +=============== +Coding style +------------ -Coding Style -============== +Please follow the project naming conventions used throughout the codebase: -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)`` +- class members commonly use leading underscore (for example `_foo`) +- methods use upper camel case (for example `GetSettings()`) +- compound names use camel case (for example `GetAllCellsAdjacentTo`) -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``). +Format code with the repository style file: +- `.clang-format` -Continuous Integration (CI) -============================ +Build and test workflow +----------------------- -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. +A typical local developer workflow is: -If you add additional libraries to the code, these also need to be added to the test environment, i.e. the respective docker container. +.. code-block:: bash -Little guide: + cmake -S . -B build_dev -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON + cmake --build build_dev -j + ./build_dev/unit_tests + ctest --test-dir build_dev --output-on-failure -Test the library installation in the docker container +CI +-- -.. 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. \ No newline at end of file +The repository uses GitHub Actions for build and test checks. Before opening a +PR, run local builds/tests and verify that new dependencies are reflected in the +build configuration and container setups used by CI. diff --git a/doc/fluxes/numericalflux.rst b/doc/fluxes/numericalflux.rst index b765bc1c..5b075d75 100644 --- a/doc/fluxes/numericalflux.rst +++ b/doc/fluxes/numericalflux.rst @@ -1,7 +1,7 @@ -NumericalFlux -============= +NumericalFluxBase +================= -.. doxygenclass:: NumericalFlux +.. doxygenclass:: NumericalFluxBase :members: :protected-members: :private-members: diff --git a/doc/index.rst b/doc/index.rst index 21989763..703406db 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,55 +2,35 @@ KiT-RT: A kinetic transport solver for radiation therapy =========================================================== -The KiT-RT framework is an open source project for radiation transport written in C++ programming language. -It is interested in the evolution of many-particle systems, e.g. photons, neutrons, electrons, etc. -Based on the finite volume method (FVM), it provides an efficient tool to solve the Boltzmann and related equations in multiple dimensions. -Special attention has been paid to the application of radiation therapy and treatment planning. -The framework provides rich deterministic solver types for different domain-specific problems. -A list of current supported models and equations is as follows. +KiT-RT is an open source C++ framework for deterministic radiation transport. +It targets linear Boltzmann-type models with finite-volume discretizations and +supports both standard solver paths and an HPC-oriented :math:`S_N` workflow. -- linear Boltzmann (:math:`S_N`) equation -- spherical harmonics (:math:`P_N`) moment equations -- entropy-closure (:math:`M_N`) moment equations -- continuous slowing down equation +The source code is publicly available on `GitHub `_. -The source code is publicly available on `Github `_. +Supported solver families +------------------------- -Design philosophy ------------------------- -The code hierarchy is designed as intuitive and neat as possible. -It's dedicated to providing a friendly interface for educational usage in kinetic theory and rich functionality for scientific research. -Benefiting from the brilliant expressiveness and low-overhead abstraction provided by the C++ programming language, we implement the easily extensible code structure, -which allow the users to focus on physics or easily extend the codes with their own methods. - - -What is new? ------------------------- -Finite volume method is a proven approach for simulating conservation laws. -Compared with the existing open-source softwares, e.g. OpenFOAM, SU2 and Clawpack, Kit-RT holds the novelty through the following points: - -- Comprehensive support for kinetic theory and phase-space equations -- Special focus on radiation therapy -- Lightweight design to ensure the flexibility for secondary development - - -How to get help? ------------------------- -The software is being developed by members of the group `CSMM `_ at the Karlsruhe Institute of Technology (KIT). -If you are interested in using KiT-RT or are trying to figure out how to use it, please feel free to get in touch with `us `_. -Do open an issue or pull request if you have questions, suggestions or solutions. +- :math:`S_N` (discrete ordinates) +- :math:`P_N` (spherical harmonics moments) +- :math:`M_N` (entropy-closure moments, including normalized variant) +- Continuous slowing-down (CSD) variants for :math:`S_N`, :math:`P_N`, and :math:`M_N` +- HPC :math:`S_N` path (CPU MPI/OpenMP and optional CUDA backend) +For a solver-focused overview (including numerical background references and +code mapping), see :doc:`solvers_overview`. Table of contents ------------------------- +----------------- .. toctree:: :maxdepth: 1 - + installation + configFiles + solvers_overview physics implement - configFiles cpp_doc developer_guide authors diff --git a/doc/installation.rst b/doc/installation.rst index 29ca4646..4ee715c5 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,87 +1,96 @@ -.. _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 -********** - -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. - ---------------------------------------------------------------- - -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. +.. _installation: + +Installation +============ + +Requirements +------------ + +Required: + +- C++17 compiler +- CMake 3.16+ +- OpenMP +- LAPACK (and optionally BLAS) +- VTK +- Git + +Optional features: + +- MPI (`-DBUILD_MPI=ON`) +- CUDA backend for the HPC SN solver (`-DBUILD_CUDA_HPC=ON`) +- TensorFlow backend for neural closure (`-DBUILD_ML=ON`) + +Get the source and submodules +----------------------------- + +.. code-block:: bash + + git clone https://github.com/KiT-RT/kitrt_code.git + cd kitrt_code + git submodule update --init --recursive + +Build examples +-------------- + +Run all commands from the repository root. + +CPU/OpenMP build (no MPI, no CUDA, no ML): + +.. code-block:: bash + + mkdir -p build_omp + cmake -S . -B build_omp -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=OFF -DBUILD_ML=OFF + cmake --build build_omp -j + +MPI/OpenMP build for HPC SN: + +.. code-block:: bash + + mkdir -p build_mpi + cmake -S . -B build_mpi -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=OFF -DBUILD_ML=OFF + cmake --build build_mpi -j + +MPI + CUDA build for HPC SN CUDA backend: + +.. code-block:: bash + + mkdir -p build_cuda + cmake -S . -B build_cuda -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=ON -DBUILD_ML=OFF + cmake --build build_cuda -j + +Build with tests: + +.. code-block:: bash + + mkdir -p build_test + cmake -S . -B build_test -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON + cmake --build build_test -j + +Run +--- + +The executable is produced inside the build directory (for example, `build_omp/KiT-RT`). + +Single-process run: + +.. code-block:: bash + + ./build_omp/KiT-RT tests/input/validation_tests/SN_solver/checkerboard_SN.cfg + +MPI run (HPC SN config): + +.. code-block:: bash + + mpirun -np 4 ./build_mpi/KiT-RT tests/input/validation_tests/SN_solver_hpc/lattice_hpc_200_cpu_order2.cfg + +If `HPC_SOLVER = YES` and CUDA support is compiled in, KiT-RT uses the CUDA HPC +solver when a GPU is available and falls back to CPU HPC otherwise. + +Tests +----- + +.. code-block:: bash + + ./build_test/unit_tests + ctest --test-dir build_test --output-on-failure diff --git a/doc/optimizers/index.rst b/doc/optimizers/index.rst index 71f6b849..d0cbd9a0 100644 --- a/doc/optimizers/index.rst +++ b/doc/optimizers/index.rst @@ -5,5 +5,9 @@ Optimizers :maxdepth: 1 optimizerbase - mloptimizer - newtonoptimizer \ No newline at end of file + newtonoptimizer + regularizednewtonoptimizer + partregularizednewtonoptimizer + reducednewtonoptimizer + reducedpartregularizednewtonoptimizer + neuralnetworkoptimizer diff --git a/doc/optimizers/neuralnetworkoptimizer.rst b/doc/optimizers/neuralnetworkoptimizer.rst new file mode 100644 index 00000000..68c91561 --- /dev/null +++ b/doc/optimizers/neuralnetworkoptimizer.rst @@ -0,0 +1,7 @@ +NeuralNetworkOptimizer +====================== + +.. doxygenclass:: NeuralNetworkOptimizer + :members: + :protected-members: + :private-members: diff --git a/doc/optimizers/partregularizednewtonoptimizer.rst b/doc/optimizers/partregularizednewtonoptimizer.rst new file mode 100644 index 00000000..1bc13e2c --- /dev/null +++ b/doc/optimizers/partregularizednewtonoptimizer.rst @@ -0,0 +1,7 @@ +PartRegularizedNewtonOptimizer +============================== + +.. doxygenclass:: PartRegularizedNewtonOptimizer + :members: + :protected-members: + :private-members: diff --git a/doc/optimizers/reducednewtonoptimizer.rst b/doc/optimizers/reducednewtonoptimizer.rst new file mode 100644 index 00000000..a3293911 --- /dev/null +++ b/doc/optimizers/reducednewtonoptimizer.rst @@ -0,0 +1,7 @@ +ReducedNewtonOptimizer +====================== + +.. doxygenclass:: ReducedNewtonOptimizer + :members: + :protected-members: + :private-members: diff --git a/doc/optimizers/reducedpartregularizednewtonoptimizer.rst b/doc/optimizers/reducedpartregularizednewtonoptimizer.rst new file mode 100644 index 00000000..98294ff8 --- /dev/null +++ b/doc/optimizers/reducedpartregularizednewtonoptimizer.rst @@ -0,0 +1,7 @@ +ReducedPartRegularizedNewtonOptimizer +===================================== + +.. doxygenclass:: ReducedPartRegularizedNewtonOptimizer + :members: + :protected-members: + :private-members: diff --git a/doc/optimizers/regularizednewtonoptimizer.rst b/doc/optimizers/regularizednewtonoptimizer.rst new file mode 100644 index 00000000..d483aa34 --- /dev/null +++ b/doc/optimizers/regularizednewtonoptimizer.rst @@ -0,0 +1,7 @@ +RegularizedNewtonOptimizer +========================== + +.. doxygenclass:: RegularizedNewtonOptimizer + :members: + :protected-members: + :private-members: diff --git a/doc/problems/aircavity1d.rst b/doc/problems/aircavity1d.rst index dbd1a7c6..cbef35e3 100644 --- a/doc/problems/aircavity1d.rst +++ b/doc/problems/aircavity1d.rst @@ -5,3 +5,8 @@ AirCavity1D :members: :protected-members: :private-members: + +.. doxygenclass:: AirCavity1D_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/checkerboard.rst b/doc/problems/checkerboard.rst new file mode 100644 index 00000000..65052d0b --- /dev/null +++ b/doc/problems/checkerboard.rst @@ -0,0 +1,22 @@ +Checkerboard Family +=================== + +.. doxygenclass:: Checkerboard_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: Checkerboard_Moment + :members: + :protected-members: + :private-members: + +.. doxygenclass:: Checkerboard_SN_1D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: Checkerboard_Moment_1D + :members: + :protected-members: + :private-members: diff --git a/doc/problems/halflattice.rst b/doc/problems/halflattice.rst new file mode 100644 index 00000000..ca139c77 --- /dev/null +++ b/doc/problems/halflattice.rst @@ -0,0 +1,12 @@ +HalfLattice Family +================== + +.. doxygenclass:: HalfLattice_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: HalfLattice_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/hohlraum.rst b/doc/problems/hohlraum.rst new file mode 100644 index 00000000..22bfa73d --- /dev/null +++ b/doc/problems/hohlraum.rst @@ -0,0 +1,12 @@ +Hohlraum Family +=============== + +.. doxygenclass:: Hohlraum + :members: + :protected-members: + :private-members: + +.. doxygenclass:: Hohlraum_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/index.rst b/doc/problems/index.rst index 488b7f9e..e3e5a789 100644 --- a/doc/problems/index.rst +++ b/doc/problems/index.rst @@ -6,16 +6,14 @@ Problems problembase aircavity1d - checkerboardpn - checkerboardsn - electronrt - icru linesource - linesourcepn - linesourcesn - linesourcesnpseudo1d - linesourcesnpseudo1dphysics - musclebonelung - phantom2d - slabgeohg - waterphantom \ No newline at end of file + checkerboard + meltingcube + lattice + halflattice + hohlraum + symmetrichohlraum + quarterhohlraum + starmapvalidation + phantomimage + radiationctimage diff --git a/doc/problems/lattice.rst b/doc/problems/lattice.rst new file mode 100644 index 00000000..bba42e52 --- /dev/null +++ b/doc/problems/lattice.rst @@ -0,0 +1,12 @@ +Lattice Family +============== + +.. doxygenclass:: Lattice_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: Lattice_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/linesource.rst b/doc/problems/linesource.rst index 54ff4488..53b264f0 100644 --- a/doc/problems/linesource.rst +++ b/doc/problems/linesource.rst @@ -1,7 +1,27 @@ -LineSource -========== +LineSource Family +================= .. doxygenclass:: LineSource :members: :protected-members: :private-members: + +.. doxygenclass:: LineSource_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: LineSource_Moment + :members: + :protected-members: + :private-members: + +.. doxygenclass:: LineSource_SN_1D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: LineSource_Moment_1D + :members: + :protected-members: + :private-members: diff --git a/doc/problems/meltingcube.rst b/doc/problems/meltingcube.rst new file mode 100644 index 00000000..0b6ce3b2 --- /dev/null +++ b/doc/problems/meltingcube.rst @@ -0,0 +1,27 @@ +MeltingCube Family +================== + +.. doxygenclass:: MeltingCube + :members: + :protected-members: + :private-members: + +.. doxygenclass:: MeltingCube_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: MeltingCube_Moment + :members: + :protected-members: + :private-members: + +.. doxygenclass:: MeltingCube_SN_1D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: MeltingCube_Moment_1D + :members: + :protected-members: + :private-members: diff --git a/doc/problems/phantomimage.rst b/doc/problems/phantomimage.rst new file mode 100644 index 00000000..e8796c39 --- /dev/null +++ b/doc/problems/phantomimage.rst @@ -0,0 +1,7 @@ +PhantomImage +============ + +.. doxygenclass:: PhantomImage + :members: + :protected-members: + :private-members: diff --git a/doc/problems/quarterhohlraum.rst b/doc/problems/quarterhohlraum.rst new file mode 100644 index 00000000..adb104df --- /dev/null +++ b/doc/problems/quarterhohlraum.rst @@ -0,0 +1,12 @@ +QuarterHohlraum Family +====================== + +.. doxygenclass:: QuarterHohlraum + :members: + :protected-members: + :private-members: + +.. doxygenclass:: QuarterHohlraum_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/radiationctimage.rst b/doc/problems/radiationctimage.rst new file mode 100644 index 00000000..0e8520c3 --- /dev/null +++ b/doc/problems/radiationctimage.rst @@ -0,0 +1,12 @@ +RadiationCTImage Family +======================= + +.. doxygenclass:: RadiationCTImage + :members: + :protected-members: + :private-members: + +.. doxygenclass:: RadiationCTImage_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/starmapvalidation.rst b/doc/problems/starmapvalidation.rst new file mode 100644 index 00000000..fb36467d --- /dev/null +++ b/doc/problems/starmapvalidation.rst @@ -0,0 +1,12 @@ +StarMapValidation Family +======================== + +.. doxygenclass:: StarMapValidation_SN + :members: + :protected-members: + :private-members: + +.. doxygenclass:: StarMapValidation_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/problems/symmetrichohlraum.rst b/doc/problems/symmetrichohlraum.rst new file mode 100644 index 00000000..09eb96b8 --- /dev/null +++ b/doc/problems/symmetrichohlraum.rst @@ -0,0 +1,12 @@ +SymmetricHohlraum Family +======================== + +.. doxygenclass:: SymmetricHohlraum + :members: + :protected-members: + :private-members: + +.. doxygenclass:: SymmetricHohlraum_Moment + :members: + :protected-members: + :private-members: diff --git a/doc/quadratures/index.rst b/doc/quadratures/index.rst index bec22056..01e4569e 100644 --- a/doc/quadratures/index.rst +++ b/doc/quadratures/index.rst @@ -15,3 +15,6 @@ Quadratures qlookupquadrature qmontecarlo qproduct + qmidpointtensorized + qrectangular + qsphericaltessalation diff --git a/doc/quadratures/qgausschebyshev1D.rst b/doc/quadratures/qgausschebyshev1D.rst index 2e0f5fcc..6ed6ca71 100644 --- a/doc/quadratures/qgausschebyshev1D.rst +++ b/doc/quadratures/qgausschebyshev1D.rst @@ -1,7 +1,7 @@ -QGausschebyshev1D -================ +QGaussChebyshev1D +================= -.. doxygenclass:: QGausschebyshev1D +.. doxygenclass:: QGaussChebyshev1D :members: :protected-members: :private-members: diff --git a/doc/quadratures/qmidpointtensorized.rst b/doc/quadratures/qmidpointtensorized.rst new file mode 100644 index 00000000..338e665e --- /dev/null +++ b/doc/quadratures/qmidpointtensorized.rst @@ -0,0 +1,17 @@ +QMidpoint Family +================ + +.. doxygenclass:: QMidpointTensorized + :members: + :protected-members: + :private-members: + +.. doxygenclass:: QMidpointTensorized2D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: QMidpoint1D + :members: + :protected-members: + :private-members: diff --git a/doc/quadratures/qrectangular.rst b/doc/quadratures/qrectangular.rst new file mode 100644 index 00000000..dec91f26 --- /dev/null +++ b/doc/quadratures/qrectangular.rst @@ -0,0 +1,17 @@ +QRectangular Family +=================== + +.. doxygenclass:: QRectangular + :members: + :protected-members: + :private-members: + +.. doxygenclass:: QRectangular2D + :members: + :protected-members: + :private-members: + +.. doxygenclass:: QRectangular1D + :members: + :protected-members: + :private-members: diff --git a/doc/quadratures/qsphericaltessalation.rst b/doc/quadratures/qsphericaltessalation.rst new file mode 100644 index 00000000..1497d9d9 --- /dev/null +++ b/doc/quadratures/qsphericaltessalation.rst @@ -0,0 +1,7 @@ +QSphericalTessalation +===================== + +.. doxygenclass:: QSphericalTessalation + :members: + :protected-members: + :private-members: diff --git a/doc/solvers/csdmnsolver.rst b/doc/solvers/csdmnsolver.rst new file mode 100644 index 00000000..1ad8d7e5 --- /dev/null +++ b/doc/solvers/csdmnsolver.rst @@ -0,0 +1,14 @@ +CSDMNSolver +=========== + +Continuous slowing-down MN solver. + +Source: + +- `include/solvers/csdmnsolver.hpp` +- `src/solvers/csdmnsolver.cpp` + +.. doxygenclass:: CSDMNSolver + :members: + :protected-members: + :private-members: diff --git a/doc/solvers/csdpnsolver.rst b/doc/solvers/csdpnsolver.rst index 438dd5fd..2b03fc8d 100644 --- a/doc/solvers/csdpnsolver.rst +++ b/doc/solvers/csdpnsolver.rst @@ -1,5 +1,12 @@ CSDPNSolver -============= +=========== + +Continuous slowing-down PN solver. + +Source: + +- `include/solvers/csdpnsolver.hpp` +- `src/solvers/csdpnsolver.cpp` .. doxygenclass:: CSDPNSolver :members: diff --git a/doc/solvers/csdsnsolver.rst b/doc/solvers/csdsnsolver.rst index a3483871..91bee00d 100644 --- a/doc/solvers/csdsnsolver.rst +++ b/doc/solvers/csdsnsolver.rst @@ -1,6 +1,13 @@ CSDSNSolver =========== +Continuous slowing-down SN solver. + +Source: + +- `include/solvers/csdsnsolver.hpp` +- `src/solvers/csdsnsolver.cpp` + .. doxygenclass:: CSDSNSolver :members: :protected-members: diff --git a/doc/solvers/index.rst b/doc/solvers/index.rst index 687ccf1a..02e8b733 100644 --- a/doc/solvers/index.rst +++ b/doc/solvers/index.rst @@ -5,13 +5,12 @@ Solvers :maxdepth: 1 solverbase - csdpnsolver - csdsnsolver - csdsnsolverfp - csdsnsolvernotrafo - csdsolvertrafofp - csdsolvertrafofp2d - csdsolvertrafofpsh2d - mnsolver - pnsolver snsolver + snsolver_hpc + snsolver_hpc_cuda + pnsolver + mnsolver + mnsolver_normalized + csdsnsolver + csdpnsolver + csdmnsolver diff --git a/doc/solvers/mnsolver.rst b/doc/solvers/mnsolver.rst index 2ccbe0ea..090e0040 100644 --- a/doc/solvers/mnsolver.rst +++ b/doc/solvers/mnsolver.rst @@ -1,6 +1,13 @@ MNSolver ======== +Entropy-closure moment solver. + +Source: + +- `include/solvers/mnsolver.hpp` +- `src/solvers/mnsolver.cpp` + .. doxygenclass:: MNSolver :members: :protected-members: diff --git a/doc/solvers/mnsolver_normalized.rst b/doc/solvers/mnsolver_normalized.rst new file mode 100644 index 00000000..1bcf5496 --- /dev/null +++ b/doc/solvers/mnsolver_normalized.rst @@ -0,0 +1,14 @@ +MNSolverNormalized +================== + +Normalized MN solver variant. + +Source: + +- `include/solvers/mnsolver_normalized.hpp` +- `src/solvers/mnsolver_normalized.cpp` + +.. doxygenclass:: MNSolverNormalized + :members: + :protected-members: + :private-members: diff --git a/doc/solvers/pnsolver.rst b/doc/solvers/pnsolver.rst index f64e4258..de82b9f4 100644 --- a/doc/solvers/pnsolver.rst +++ b/doc/solvers/pnsolver.rst @@ -1,8 +1,14 @@ PNSolver ======== +Standard spherical harmonics moment solver. + +Source: + +- `include/solvers/pnsolver.hpp` +- `src/solvers/pnsolver.cpp` + .. doxygenclass:: PNSolver :members: :protected-members: :private-members: - diff --git a/doc/solvers/snsolver.rst b/doc/solvers/snsolver.rst index 66772e96..b14faa43 100644 --- a/doc/solvers/snsolver.rst +++ b/doc/solvers/snsolver.rst @@ -1,6 +1,13 @@ SNSolver ======== +Standard (non-HPC) discrete ordinates solver implementation. + +Source: + +- `include/solvers/snsolver.hpp` +- `src/solvers/snsolver.cpp` + .. doxygenclass:: SNSolver :members: :protected-members: diff --git a/doc/solvers/snsolver_hpc.rst b/doc/solvers/snsolver_hpc.rst new file mode 100644 index 00000000..7a26b2c6 --- /dev/null +++ b/doc/solvers/snsolver_hpc.rst @@ -0,0 +1,15 @@ +SNSolverHPC +=========== + +High-performance SN solver path (CPU implementation, MPI/OpenMP capable). +Selected at runtime with `HPC_SOLVER = YES`. + +Source: + +- `include/solvers/snsolver_hpc.hpp` +- `src/solvers/snsolver_hpc.cpp` + +.. doxygenclass:: SNSolverHPC + :members: + :protected-members: + :private-members: diff --git a/doc/solvers/snsolver_hpc_cuda.rst b/doc/solvers/snsolver_hpc_cuda.rst new file mode 100644 index 00000000..6fd7d06b --- /dev/null +++ b/doc/solvers/snsolver_hpc_cuda.rst @@ -0,0 +1,15 @@ +SNSolverHPCCUDA +=============== + +CUDA backend for the HPC SN solver path. +Compiled when `-DBUILD_CUDA_HPC=ON`. + +Source: + +- `include/solvers/snsolver_hpc_cuda.hpp` +- `src/solvers/snsolver_hpc.cu` + +.. doxygenclass:: SNSolverHPCCUDA + :members: + :protected-members: + :private-members: diff --git a/doc/solvers_overview.rst b/doc/solvers_overview.rst new file mode 100644 index 00000000..cc075ebe --- /dev/null +++ b/doc/solvers_overview.rst @@ -0,0 +1,85 @@ +Solver overview +=============== + +This page maps the current solver pathways in the repository to their +implementation files and to relevant numerical background references. + +Runtime solver selection +------------------------ + +KiT-RT selects the execution path in `src/main.cpp`: + +- If `DATA_GENERATOR_MODE = YES`, it runs data generation. +- Otherwise, if `HPC_SOLVER = YES`, it runs the HPC SN implementation: + - `SNSolverHPC` on CPU (`src/solvers/snsolver_hpc.cpp`) + - `SNSolverHPCCUDA` when CUDA is compiled and a GPU is detected + (`src/solvers/snsolver_hpc.cu`) +- If `HPC_SOLVER = NO`, it uses `SolverBase::Create(...)` and the standard + solver factory (`src/solvers/solverbase.cpp`). + +Non-HPC solver stack +-------------------- + +Implemented non-HPC solver classes: + +- `SNSolver` +- `PNSolver` +- `MNSolver` +- `MNSolverNormalized` +- `CSDSNSolver` +- `CSDPNSolver` +- `CSDMNSolver` + +Code locations: + +- `include/solvers/*.hpp` +- `src/solvers/*.cpp` + +Numerical background reference for deterministic non-HPC solver families +(:math:`S_N`, :math:`P_N`, and entropy-based moment closures): + +- `Structure-preserving neural networks for entropy-based moment closure methods `_ + +HPC SN stack +------------ + +Implemented HPC SN classes: + +- `SNSolverHPC` (CPU MPI/OpenMP) +- `SNSolverHPCCUDA` (CUDA backend) + +Core files: + +- `include/solvers/snsolver_hpc.hpp` +- `src/solvers/snsolver_hpc.cpp` +- `include/solvers/snsolver_hpc_cuda.hpp` +- `src/solvers/snsolver_hpc.cu` + +The HPC solver path is designed around large SN systems and benchmark-style +problems such as lattice and hohlraum configurations. + +Numerical background reference for the HPC SN benchmark workflow: + +- `Reference solutions for linear radiation transport: the Hohlraum and Lattice benchmarks `_ + +Practical config pattern +------------------------ + +To run the HPC SN path: + +.. code-block:: cfg + + SOLVER = SN_SOLVER + HPC_SOLVER = YES + +To run the standard SN path: + +.. code-block:: cfg + + SOLVER = SN_SOLVER + HPC_SOLVER = NO + +Reference validation inputs: + +- `tests/input/validation_tests/SN_solver` +- `tests/input/validation_tests/SN_solver_hpc` diff --git a/doc/toolboxes/epics.rst b/doc/toolboxes/epics.rst new file mode 100644 index 00000000..0ab45d93 --- /dev/null +++ b/doc/toolboxes/epics.rst @@ -0,0 +1,7 @@ +EPICS +===== + +.. doxygenclass:: EPICS + :members: + :protected-members: + :private-members: diff --git a/doc/toolboxes/icru.rst b/doc/toolboxes/icru.rst new file mode 100644 index 00000000..7959a63c --- /dev/null +++ b/doc/toolboxes/icru.rst @@ -0,0 +1,7 @@ +ICRU +==== + +.. doxygenclass:: ICRU + :members: + :protected-members: + :private-members: diff --git a/doc/toolboxes/index.rst b/doc/toolboxes/index.rst index 6ea6cd9b..dc0baa08 100644 --- a/doc/toolboxes/index.rst +++ b/doc/toolboxes/index.rst @@ -9,6 +9,5 @@ Toolboxes textprocessingtoolbox pyhelper reconstructor - shpericalbase - sphericalmonomials - sphericalharmonics + epics + icru diff --git a/doc/toolboxes/pyhelper.rst b/doc/toolboxes/pyhelper.rst index 6cedf250..ce26c07e 100644 --- a/doc/toolboxes/pyhelper.rst +++ b/doc/toolboxes/pyhelper.rst @@ -1,7 +1,12 @@ -PyHelper -============= +Py Helper +========= -.. doxygenclass:: PyHelper +.. doxygenclass:: CPyInstance + :members: + :protected-members: + :private-members: + +.. doxygenclass:: CPyObject :members: :protected-members: :private-members: diff --git a/doc/toolboxes/textprocessingtoolbox.rst b/doc/toolboxes/textprocessingtoolbox.rst index c294678c..c5ae0ad9 100644 --- a/doc/toolboxes/textprocessingtoolbox.rst +++ b/doc/toolboxes/textprocessingtoolbox.rst @@ -1,7 +1,5 @@ TextProcessingToolbox -============= +===================== -.. doxygenclass:: TextProcessingToolbox +.. doxygennamespace:: TextProcessingToolbox :members: - :protected-members: - :private-members: