From 798ed020e5e11e7b379e981aa147d4aac83da07b Mon Sep 17 00:00:00 2001 From: Steffen Date: Fri, 13 Feb 2026 16:16:03 -0500 Subject: [PATCH 1/2] add mpi cuda --- CMakeLists.txt | 2 +- README.md | 6 +- include/solvers/snsolver_hpc_cuda.hpp | 2 +- src/solvers/snsolver_hpc.cu | 59 ++++++++++++++----- .../install_kitrt_singularity_cuda.sh | 2 +- 5 files changed, 49 insertions(+), 22 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 894a3d99..32bab039 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -9,7 +9,7 @@ option( BUILD_UNITY "enables unity build for faster compile times" ON ) option( BUILD_CODE_COV "enables compiler option required for code coverage analysis" OFF ) option( BUILD_ML "enables build with tensorflow backend access" OFF ) option( BUILD_MPI "enables build with MPI access" OFF ) -option( BUILD_CUDA_HPC "enables CUDA backend for SN HPC solver (single GPU)" OFF ) +option( BUILD_CUDA_HPC "enables CUDA backend for SN HPC solver (MPI rank to GPU mapping)" OFF ) ################################################# diff --git a/README.md b/README.md index 987ab671..33f62ebd 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ singularity exec tools/singularity/kit_rt_MPI.sif \ mpirun -np 4 ./build_singularity_mpi/KiT-RT tests/input/validation_tests/SN_solver_hpc/lattice_hpc_200_cpu_order2.cfg ``` -### 3. CPU + single GPU (OpenMP + CUDA) +### 3. CPU + CUDA (single or multi-GPU via MPI) #### 3a) Singularity installation ```bash @@ -152,11 +152,11 @@ cd ../.. mkdir -p build_singularity_cuda cd build_singularity_cuda singularity exec --nv ../tools/singularity/kit_rt_MPI_cuda.sif \ - cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=ON -DBUILD_ML=OFF .. + cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=ON -DBUILD_ML=OFF .. singularity exec --nv ../tools/singularity/kit_rt_MPI_cuda.sif make -j cd .. singularity exec --nv tools/singularity/kit_rt_MPI_cuda.sif \ - ./build_singularity_cuda/KiT-RT tests/input/validation_tests/SN_solver_hpc/lattice_hpc_200_cuda_order2.cfg + mpirun -np 2 ./build_singularity_cuda/KiT-RT tests/input/validation_tests/SN_solver_hpc/lattice_hpc_200_cuda_order2.cfg ``` When compiled with `-DBUILD_CUDA_HPC=ON`, HPC runs use the CUDA backend if a GPU is visible, and fall back to CPU if no GPU is detected. diff --git a/include/solvers/snsolver_hpc_cuda.hpp b/include/solvers/snsolver_hpc_cuda.hpp index 5a6f73f0..651d729e 100644 --- a/include/solvers/snsolver_hpc_cuda.hpp +++ b/include/solvers/snsolver_hpc_cuda.hpp @@ -151,7 +151,7 @@ class SNSolverHPCCUDA std::vector _historyOutputFields; /*!< @brief Solver Output: dimensions (FieldID). */ std::vector _historyOutputFieldNames; /*!< @brief Names of the outputFields: dimensions (FieldID) */ - // CUDA backend (single GPU for first version) + // CUDA backend state bool _cudaInitialized; int _cudaDeviceId; DeviceBuffers* _device; diff --git a/src/solvers/snsolver_hpc.cu b/src/solvers/snsolver_hpc.cu index e016c797..c6facfca 100644 --- a/src/solvers/snsolver_hpc.cu +++ b/src/solvers/snsolver_hpc.cu @@ -369,21 +369,14 @@ SNSolverHPCCUDA::SNSolverHPCCUDA( Config* settings ) { ErrorMessages::Error( "The number of processors must be less than or equal to the number of quadrature points.", CURRENT_FUNCTION ); } - if( _numProcs == 1 ) { - _localNSys = _nSys; - _startSysIdx = 0; - _endSysIdx = _nSys; - } - else { - _localNSys = _nSys / ( _numProcs - 1 ); - _startSysIdx = _rank * _localNSys; - _endSysIdx = _rank * _localNSys + _localNSys; - - if( _rank == _numProcs - 1 ) { - _localNSys = _nSys - _startSysIdx; - _endSysIdx = _nSys; - } - } + const unsigned long numRanks = static_cast( _numProcs ); + const unsigned long rankIndex = static_cast( _rank ); + const unsigned long baseChunk = _nSys / numRanks; + const unsigned long remainder = _nSys % numRanks; + + _localNSys = baseChunk + ( rankIndex < remainder ? 1UL : 0UL ); + _startSysIdx = rankIndex * baseChunk + std::min( rankIndex, remainder ); + _endSysIdx = _startSysIdx + _localNSys; // std::cout << "Rank: " << _rank << " startSysIdx: " << _startSysIdx << " endSysIdx: " << _endSysIdx << " localNSys: " << _localNSys << // std::endl; @@ -613,9 +606,29 @@ void SNSolverHPCCUDA::InitCUDA() { ErrorMessages::Error( "No CUDA-capable GPU detected, but SNSolverHPCCUDA was requested.", CURRENT_FUNCTION ); } - _cudaDeviceId = 0; // first version: pin to one GPU + int localRank = 0; + int localSize = 1; +#ifdef IMPORT_MPI + MPI_Comm localComm = MPI_COMM_NULL; + MPI_Comm_split_type( MPI_COMM_WORLD, MPI_COMM_TYPE_SHARED, _rank, MPI_INFO_NULL, &localComm ); + MPI_Comm_rank( localComm, &localRank ); + MPI_Comm_size( localComm, &localSize ); + MPI_Comm_free( &localComm ); +#endif + + _cudaDeviceId = localRank % nDevices; CheckCuda( cudaSetDevice( _cudaDeviceId ), "cudaSetDevice" ); + if( _rank == 0 ) { + auto log = spdlog::get( "event" ); + if( log ) { + log->info( "| CUDA backend: {} local MPI rank(s), {} visible CUDA device(s).", localSize, nDevices ); + if( localSize > nDevices ) { + log->warn( "| CUDA backend: {} local MPI rank(s) exceed {} visible device(s); GPUs will be shared.", localSize, nDevices ); + } + } + } + _device = new DeviceBuffers(); const std::size_t nCells = static_cast( _nCells ); @@ -805,6 +818,20 @@ void SNSolverHPCCUDA::Solve() { RK2AverageAndScalarFluxKernel<<>>( _nCells, _localNSys, _device->quadWeights, _device->solRK0, _device->sol, _device->scalarFlux ); CheckCuda( cudaGetLastError(), "RK2AverageAndScalarFluxKernel launch" ); +#ifdef IMPORT_MPI + CheckCuda( cudaMemcpy( _scalarFlux.data(), + _device->scalarFlux, + static_cast( _nCells ) * sizeof( double ), + cudaMemcpyDeviceToHost ), + "download scalar flux after RK2 average" ); + std::vector tempScalarFlux( _scalarFlux ); + MPI_Barrier( MPI_COMM_WORLD ); + MPI_Allreduce( tempScalarFlux.data(), _scalarFlux.data(), _nCells, MPI_DOUBLE, MPI_SUM, MPI_COMM_WORLD ); + MPI_Barrier( MPI_COMM_WORLD ); + CheckCuda( + cudaMemcpy( _device->scalarFlux, _scalarFlux.data(), static_cast( _nCells ) * sizeof( double ), cudaMemcpyHostToDevice ), + "sync allreduced scalar flux after RK2 average" ); +#endif } else { ( _spatialOrder == 2 ) ? FluxOrder2() : FluxOrder1(); diff --git a/tools/singularity/install_kitrt_singularity_cuda.sh b/tools/singularity/install_kitrt_singularity_cuda.sh index b88fe4a1..a59653d2 100755 --- a/tools/singularity/install_kitrt_singularity_cuda.sh +++ b/tools/singularity/install_kitrt_singularity_cuda.sh @@ -4,5 +4,5 @@ set -euo pipefail cd ../../ mkdir -p build_singularity_cuda cd build_singularity_cuda -cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=ON -DBUILD_ML=OFF .. +cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=ON -DBUILD_ML=OFF .. make -j From dd5d030d2b583712877852b41479410c3d1d4f76 Mon Sep 17 00:00:00 2001 From: Steffen Date: Mon, 16 Feb 2026 09:31:55 -0500 Subject: [PATCH 2/2] updated docs --- doc/common/index.rst | 1 + doc/common/io.rst | 8 +- doc/configFiles.rst | 237 +++++++++++------- doc/cpp_doc.rst | 3 +- doc/datagenerator/datagenerator1D.rst | 11 +- doc/datagenerator/datagenerator2D.rst | 11 +- doc/datagenerator/datagenerator3D.rst | 6 +- doc/datagenerator/datageneratorbase.rst | 2 +- .../datageneratorclassification.rst | 6 +- doc/datagenerator/datageneratorregression.rst | 6 +- doc/datagenerator/index.rst | 10 +- doc/developer_guide.rst | 59 ++--- doc/fluxes/numericalflux.rst | 6 +- doc/index.rst | 54 ++-- doc/installation.rst | 183 +++++++------- doc/optimizers/index.rst | 8 +- doc/optimizers/neuralnetworkoptimizer.rst | 7 + .../partregularizednewtonoptimizer.rst | 7 + doc/optimizers/reducednewtonoptimizer.rst | 7 + .../reducedpartregularizednewtonoptimizer.rst | 7 + doc/optimizers/regularizednewtonoptimizer.rst | 7 + doc/problems/aircavity1d.rst | 5 + doc/problems/checkerboard.rst | 22 ++ doc/problems/halflattice.rst | 12 + doc/problems/hohlraum.rst | 12 + doc/problems/index.rst | 22 +- doc/problems/lattice.rst | 12 + doc/problems/linesource.rst | 24 +- doc/problems/meltingcube.rst | 27 ++ doc/problems/phantomimage.rst | 7 + doc/problems/quarterhohlraum.rst | 12 + doc/problems/radiationctimage.rst | 12 + doc/problems/starmapvalidation.rst | 12 + doc/problems/symmetrichohlraum.rst | 12 + doc/quadratures/index.rst | 3 + doc/quadratures/qgausschebyshev1D.rst | 6 +- doc/quadratures/qmidpointtensorized.rst | 17 ++ doc/quadratures/qrectangular.rst | 17 ++ doc/quadratures/qsphericaltessalation.rst | 7 + doc/solvers/csdmnsolver.rst | 14 ++ doc/solvers/csdpnsolver.rst | 9 +- doc/solvers/csdsnsolver.rst | 7 + doc/solvers/index.rst | 17 +- doc/solvers/mnsolver.rst | 7 + doc/solvers/mnsolver_normalized.rst | 14 ++ doc/solvers/pnsolver.rst | 8 +- doc/solvers/snsolver.rst | 7 + doc/solvers/snsolver_hpc.rst | 15 ++ doc/solvers/snsolver_hpc_cuda.rst | 15 ++ doc/solvers_overview.rst | 85 +++++++ doc/toolboxes/epics.rst | 7 + doc/toolboxes/icru.rst | 7 + doc/toolboxes/index.rst | 5 +- doc/toolboxes/pyhelper.rst | 11 +- doc/toolboxes/textprocessingtoolbox.rst | 6 +- 55 files changed, 793 insertions(+), 328 deletions(-) create mode 100644 doc/optimizers/neuralnetworkoptimizer.rst create mode 100644 doc/optimizers/partregularizednewtonoptimizer.rst create mode 100644 doc/optimizers/reducednewtonoptimizer.rst create mode 100644 doc/optimizers/reducedpartregularizednewtonoptimizer.rst create mode 100644 doc/optimizers/regularizednewtonoptimizer.rst create mode 100644 doc/problems/checkerboard.rst create mode 100644 doc/problems/halflattice.rst create mode 100644 doc/problems/hohlraum.rst create mode 100644 doc/problems/lattice.rst create mode 100644 doc/problems/meltingcube.rst create mode 100644 doc/problems/phantomimage.rst create mode 100644 doc/problems/quarterhohlraum.rst create mode 100644 doc/problems/radiationctimage.rst create mode 100644 doc/problems/starmapvalidation.rst create mode 100644 doc/problems/symmetrichohlraum.rst create mode 100644 doc/quadratures/qmidpointtensorized.rst create mode 100644 doc/quadratures/qrectangular.rst create mode 100644 doc/quadratures/qsphericaltessalation.rst create mode 100644 doc/solvers/csdmnsolver.rst create mode 100644 doc/solvers/mnsolver_normalized.rst create mode 100644 doc/solvers/snsolver_hpc.rst create mode 100644 doc/solvers/snsolver_hpc_cuda.rst create mode 100644 doc/solvers_overview.rst create mode 100644 doc/toolboxes/epics.rst create mode 100644 doc/toolboxes/icru.rst 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: