diff --git a/CMakeLists.txt b/CMakeLists.txt index 26b0c32d..dd9e2d45 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -324,7 +324,7 @@ if( BUILD_DOC ) set( SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx ) set( SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html ) add_custom_command( OUTPUT ${SPHINX_INDEX_FILE} - COMMAND ${SPHINX_EXECUTABLE} ${SPHINX_SOURCE} ${SPHINX_BUILD} + COMMAND ${CMAKE_COMMAND} -E env KITRT_DOXYGEN_XML=${DOXYGEN_OUTPUT_DIR}/xml ${SPHINX_EXECUTABLE} ${SPHINX_SOURCE} ${SPHINX_BUILD} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/doc/index.rst ${DOXYGEN_INDEX_FILE} MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py diff --git a/README.md b/README.md index 9498e6c9..4238b3e2 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,15 @@ KiT-RT has two layers: - `kitrt_code`: this C++ solver repository. Use it to build the solver, run one deterministic config, or extend solver internals. - `CharmKiT`: the Python workflow layer for lattice/hohlraum sweeps, SLURM submission, CSV inputs, and QOI collection. +<<<<<<< HEAD +Prerequisites for the CPU smoke test: + +- C++17 compiler, CMake 3.16+, Git, and initialized submodules +- OpenMP, BLAS, LAPACK, and VTK development libraries +- Python 3.10+ for `tools/check_smoke_output.py` + +======= +>>>>>>> 79e9379a02585184b95f4031d61ae086a483267f ### Ten-minute CPU smoke test ```bash @@ -96,7 +105,7 @@ Applications include: ### Neural–PDE Integration * **Structure-Preserving Operator Learning** — *arXiv:2402.16613* \[[PDF](https://arxiv.org/abs/2402.16613)] -* **Structure-preserving neural networks for entropy-based closure** — *Journal of Computational Physics* \[[DOI](https://doi.org/10.1016/j.jcp.2025.113967)], *ICML* \[[Link]([https://doi.org/10.1016/j.jcp.2025.113967](https://proceedings.mlr.press/v162/schotthofer22a.html))], *AIAA* \[[DOI](https://doi.org/10.2514/6.2021-2895)] +* **Structure-preserving neural networks for entropy-based closure** — *Journal of Computational Physics* \[[DOI](https://doi.org/10.1016/j.jcp.2025.113967)], *ICML* \[[Link](https://proceedings.mlr.press/v162/schotthofer22a.html)], *AIAA* \[[DOI](https://doi.org/10.2514/6.2021-2895)] * [PhD Thesis: Synergies between Numerical Methods for Kinetic Equations and Neural Networks](https://doi.org/10.5445/IR/1000158838) @@ -126,7 +135,8 @@ cd .. #### 1b) Docker installation ```bash -docker run --rm -it -v $(pwd):/mnt -w /mnt kitrt/test:latest /bin/bash +docker build -t kitrt/test:local tools/docker +docker run --rm -it -v "$(pwd):/mnt" -w /mnt kitrt/test:local /bin/bash mkdir -p build_docker_omp cd build_docker_omp cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=OFF -DBUILD_ML=OFF .. @@ -255,7 +265,7 @@ gcovr -r .. --html-details coverage.html ## Python API -The Python interface is provided via [charm_kit](https://github.com/KiT-RT/charm_kit), allowing seamless integration into AI and outer-loop (UQ, Optimization) workflows. +The Python workflow interface is provided via [CharmKiT](https://github.com/KiT-RT/CharmKiT), allowing integration into AI and outer-loop (UQ, Optimization) workflows. Check the corresponding readme for further info. diff --git a/doc/conf.py b/doc/conf.py index a811533e..130da6bf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,8 @@ -import subprocess, os +import os +import subprocess project = 'KiT-RT' -copyright = '2022, Karlsruhe Institute of Technology' +copyright = '2024, Steffen Schotthoefer, Pia Stammer, Jonas Kusch' author = 'Jonas Kusch, Steffen Schotthöfer, Pia Stammer, Jannick Wolters, Tianbai Xiao' version = '1.2.0' @@ -13,9 +14,32 @@ 'sphinx_rtd_theme' ] -#templates_path = ['_templates'] +# templates_path = ['_templates'] master_doc = 'index' -exclude_patterns = [] + +# Legacy API stub pages for classes that have been removed, renamed, or folded +# into aggregate pages. Excluding them keeps source-discovery builds from +# publishing stale API references. +exclude_patterns = [ + 'optimizers/mloptimizer.rst', + 'problems/checkerboardpn.rst', + 'problems/checkerboardsn.rst', + 'problems/electronrt.rst', + 'problems/icru.rst', + 'problems/linesourcepn.rst', + 'problems/linesourcesn.rst', + 'problems/linesourcesnpseudo1d.rst', + 'problems/linesourcesnpseudo1dphysics.rst', + 'problems/musclebonelung.rst', + 'problems/phantom2d.rst', + 'problems/slabgeohg.rst', + 'problems/waterphantom.rst', + 'solvers/csdsnsolverfp.rst', + 'solvers/csdsnsolvernotrafo.rst', + 'solvers/csdsolvertrafofp.rst', + 'solvers/csdsolvertrafofp2d.rst', + 'solvers/csdsolvertrafofpsh2d.rst', +] html_theme = 'sphinx_rtd_theme' html_theme_options = { @@ -24,23 +48,27 @@ } html_logo = 'images/KiT-RT_logo_small.png' html_static_path = ['_static'] + def setup(app): app.add_css_file('theme_overrides.css') +conf_dir = os.path.abspath(os.path.dirname(__file__)) +default_doxygen_xml = os.path.abspath(os.path.join(conf_dir, '..', 'build', 'docs', 'doxygen', 'xml')) +doxygen_xml = os.environ.get('KITRT_DOXYGEN_XML', default_doxygen_xml) + breathe_projects = { - "KiT-RT": "../build/docs/doxygen/xml", + 'KiT-RT': doxygen_xml, } -breathe_default_project = "KiT-RT" +breathe_default_project = 'KiT-RT' read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' if read_the_docs_build: - inputDir = '../' - outputDir = '../build/docs/doxygen' - if not os.path.exists(outputDir): - os.makedirs(outputDir) - with open("Doxyfile.in", "rt") as fin: - with open("Doxyfile", "wt") as fout: + inputDir = os.path.abspath(os.path.join(conf_dir, '..')) + outputDir = os.path.abspath(os.path.join(conf_dir, '..', 'build', 'docs', 'doxygen')) + os.makedirs(outputDir, exist_ok=True) + with open(os.path.join(conf_dir, 'Doxyfile.in'), 'rt') as fin: + with open(os.path.join(conf_dir, 'Doxyfile'), 'wt') as fout: for line in fin: line = line.replace('GENERATE_HTML = YES', 'GENERATE_HTML = NO') line = line.replace('SEARCH_INCLUDES = YES', 'SEARCH_INCLUDES = NO') @@ -48,4 +76,4 @@ def setup(app): line = line.replace('@DOXYGEN_OUTPUT_DIR@', outputDir) line = line.replace('@DOXYGEN_INPUT_DIR@', inputDir) fout.write(line) - subprocess.call('doxygen', shell=True) + subprocess.call('doxygen', cwd=conf_dir, shell=True) diff --git a/doc/configFiles.rst b/doc/configFiles.rst index 73be07a8..2699ddf8 100644 --- a/doc/configFiles.rst +++ b/doc/configFiles.rst @@ -70,6 +70,9 @@ Output control: Current enum values (from code) -------------------------------- +These names come from ``include/common/globalconstants.hpp`` and are the strings +accepted by the config parser. + `SOLVER`: - `SN_SOLVER` @@ -84,9 +87,9 @@ Current enum values (from code) - `LINESOURCE`, `LINESOURCE_1D` - `CHECKERBOARD`, `CHECKERBOARD_1D` -- `AIRCAVITY_1D`, `WATERPHANTOM`, `RADIATIONCT` +- `STARMAP_VALIDATION`, `AIRCAVITY_1D` +- `WATERPHANTOM`, `WATERPHANTOM_1D`, `RADIATIONCT` - `MELTINGCUBE`, `MELTINGCUBE_1D` -- `STARMAP_VALIDATION` - `HOHLRAUM`, `SYMMETRIC_HOHLRAUM`, `QUARTER_HOHLRAUM` - `LATTICE`, `HALF_LATTICE` @@ -108,6 +111,42 @@ Current enum values (from code) - `SPHERICAL_MONOMIALS` - `SPHERICAL_MONOMIALS_ROTATED` +`ENTROPY_FUNCTIONAL`: + +- `QUADRATIC` +- `MAXWELL_BOLTZMANN` +- `BOSE_EINSTEIN` +- `FERMI_DIRAC` + +`ENTROPY_OPTIMIZER`: + +- `NEWTON` +- `REGULARIZED_NEWTON` +- `PART_REGULARIZED_NEWTON` +- `REDUCED_NEWTON` +- `REDUCED_PART_REGULARIZED_NEWTON` +- `ML` + +`VOLUME_OUTPUT`: + +- `ANALYTIC`, `MINIMAL`, `MOMENTS`, `DUAL_MOMENTS`, `MEDICAL` + +`SCREEN_OUTPUT` and `HISTORY_OUTPUT`: + +- `ITER`, `WALL_TIME`, `SIM_TIME`, `MASS`, `RMS_FLUX` +- `VTK_OUTPUT`, `CSV_OUTPUT` +- `CUR_OUTFLOW`, `TOTAL_OUTFLOW`, `CUR_OUTFLOW_P1`, `TOTAL_OUTFLOW_P1` +- `CUR_OUTFLOW_P2`, `TOTAL_OUTFLOW_P2`, `MAX_OUTFLOW` +- `CUR_PARTICLE_ABSORPTION`, `TOTAL_PARTICLE_ABSORPTION`, `MAX_PARTICLE_ABSORPTION` +- `TOTAL_PARTICLE_ABSORPTION_CENTER`, `TOTAL_PARTICLE_ABSORPTION_VERTICAL`, `TOTAL_PARTICLE_ABSORPTION_HORIZONTAL` +- `PROBE_MOMENT_TIME_TRACE`, `VAR_ABSORPTION_GREEN`, `ABSORPTION_GREEN_BLOCK` +- `AVG_ABSORPTION_GREEN_BLOCK_INTEGRATED`, `VAR_ABSORPTION_GREEN_BLOCK_INTEGRATED`, `ABSORPTION_GREEN_LINE` + +`SAMPLER_NAME`: + +- `CLASSIFICATION_SAMPLER` +- `REGRESSION_SAMPLER` + HPC SN config pattern --------------------- diff --git a/doc/developer_guide.rst b/doc/developer_guide.rst index 5553829e..ae3ebb14 100644 --- a/doc/developer_guide.rst +++ b/doc/developer_guide.rst @@ -26,6 +26,20 @@ A typical local developer workflow is: ./build_dev/unit_tests ctest --test-dir build_dev --output-on-failure +Documentation build +------------------- + +A local Doxygen/Sphinx build uses the active CMake build directory for generated +Doxygen XML: + +.. code-block:: bash + + python -m pip install -r doc/requirements.txt + cmake -S . -B build_doc -DCMAKE_BUILD_TYPE=Release -DBUILD_DOC=ON -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=OFF -DBUILD_HIP_HPC=OFF -DBUILD_ML=OFF + cmake --build build_doc -j + +Open ``build_doc/docs/sphinx/index.html`` to inspect the generated docs. + CI -- diff --git a/doc/getting_started.rst b/doc/getting_started.rst index 49ea1607..e3ef99dd 100644 --- a/doc/getting_started.rst +++ b/doc/getting_started.rst @@ -26,7 +26,8 @@ Ten-minute CPU path ------------------- Run these commands from a fresh clone on a machine with the required CPU -dependencies installed: +dependencies installed. See :doc:`installation` for BLAS/LAPACK, VTK, and +Python package requirements. .. code-block:: bash @@ -45,7 +46,15 @@ details. Container path -------------- -Apptainer is supported through ``KITRT_CONTAINER_RUNTIME=apptainer``. -Singularity remains supported through ``KITRT_CONTAINER_RUNTIME=singularity``. -If your site does not permit root builds, use a prebuilt SIF or a remote pull -URI instead of building containers on the cluster login node. +Container definitions live under ``tools/singularity``. Apptainer is supported +through ``KITRT_CONTAINER_RUNTIME=apptainer``; Singularity remains supported +through ``KITRT_CONTAINER_RUNTIME=singularity``. A local CPU image can be built +with: + +.. code-block:: bash + + cd tools/singularity + KITRT_CONTAINER_RUNTIME=apptainer ./build_container.sh cpu + +If your site does not permit local SIF builds, use a site-provided image or a +remote pull URI instead of building containers on the cluster login node. diff --git a/doc/index.rst b/doc/index.rst index 5c86358b..783b1905 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -15,7 +15,7 @@ Supported solver families - :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) +- HPC :math:`S_N` path (CPU MPI/OpenMP and optional CUDA or HIP backend) For a solver-focused overview (including numerical background references and code mapping), see :doc:`solvers_overview`. @@ -32,6 +32,7 @@ Table of contents tutorials/smoke_test troubleshooting release + philosophy configFiles solvers_overview physics diff --git a/doc/installation.rst b/doc/installation.rst index 6ebb50e2..eb68af67 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -6,20 +6,33 @@ Installation Requirements ------------ -Required: +Required for the documented CPU build and smoke test: - C++17 compiler - CMake 3.16+ +- Git and initialized submodules +- Python 3.10+ for the smoke-test checker - OpenMP -- LAPACK (and optionally BLAS) -- VTK -- Git +- BLAS and LAPACK development libraries +- VTK development libraries + +On Ubuntu systems, the CPU prerequisites are typically provided by packages like: + +.. code-block:: bash + + sudo apt-get update + sudo apt-get install -y build-essential cmake git python3 libopenblas-dev liblapack-dev libvtk9-dev + +Package names vary by distribution and cluster module stack. The important CMake +packages are OpenMP, BLAS, LAPACK, and VTK. Optional features: -- MPI (`-DBUILD_MPI=ON`) +- MPI (`-DBUILD_MPI=ON`; for example Open MPI or MPICH) - CUDA backend for the HPC SN solver (`-DBUILD_CUDA_HPC=ON`) +- HIP/ROCm backend for the HPC SN solver (`-DBUILD_HIP_HPC=ON`; requires CMake 3.21+) - TensorFlow backend for neural closure (`-DBUILD_ML=ON`) +- Documentation build (`-DBUILD_DOC=ON`; requires Doxygen plus `doc/requirements.txt`) Get the source and submodules ----------------------------- @@ -57,9 +70,17 @@ 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 -S . -B build_cuda -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=ON -DBUILD_HIP_HPC=OFF -DBUILD_ML=OFF cmake --build build_cuda -j +MPI + ROCm/HIP build for HPC SN HIP backend: + +.. code-block:: bash + + mkdir -p build_rocm + cmake -S . -B build_rocm -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=ON -DBUILD_CUDA_HPC=OFF -DBUILD_HIP_HPC=ON -DBUILD_ML=OFF + cmake --build build_rocm -j + Build with tests: .. code-block:: bash @@ -102,3 +123,17 @@ Tests ./build_test/unit_tests ctest --test-dir build_test --output-on-failure + +Documentation +------------- + +Install the Sphinx Python dependencies and build Doxygen plus Sphinx through +CMake: + +.. code-block:: bash + + python -m pip install -r doc/requirements.txt + cmake -S . -B build_doc -DCMAKE_BUILD_TYPE=Release -DBUILD_DOC=ON -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=OFF -DBUILD_HIP_HPC=OFF -DBUILD_ML=OFF + cmake --build build_doc -j + +The generated HTML entry point is `build_doc/docs/sphinx/index.html`. diff --git a/doc/quadratures/qgausslegendretensorized2D.rst b/doc/quadratures/qgausslegendretensorized2D.rst index 41b94ca3..6c4fc86f 100644 --- a/doc/quadratures/qgausslegendretensorized2D.rst +++ b/doc/quadratures/qgausslegendretensorized2D.rst @@ -1,5 +1,5 @@ QGaussLegendreTensorized2D -======================== +=========================== .. doxygenclass:: QGaussLegendreTensorized2D :members: diff --git a/doc/release.rst b/doc/release.rst index bf091697..b34078ed 100644 --- a/doc/release.rst +++ b/doc/release.rst @@ -6,7 +6,7 @@ Release Notes ===== The CMake project version is currently ``1.2.0``. Until GitHub releases and -published container artifacts are available, cite the exact commit hash used for +release container artifacts are available, cite the exact commit hash used for reproducibility. Recommended release artifacts diff --git a/doc/status.rst b/doc/status.rst index 8af56d0f..73d8b06f 100644 --- a/doc/status.rst +++ b/doc/status.rst @@ -12,9 +12,3 @@ Current onboarding status - Use :doc:`tutorials/smoke_test` for the laptop smoke test and expected output checks. - Use :doc:`troubleshooting` before opening an installation or cluster support issue. -Release status --------------- - -Until versioned GitHub releases and container artifacts are published, cite the -exact Git commit used for a run and record local compiler/container details with -your simulation outputs. diff --git a/doc/toolboxes/index.rst b/doc/toolboxes/index.rst index dc0baa08..f8dab5aa 100644 --- a/doc/toolboxes/index.rst +++ b/doc/toolboxes/index.rst @@ -9,5 +9,8 @@ Toolboxes textprocessingtoolbox pyhelper reconstructor + sphericalharmonics + sphericalmonomials + shpericalbase epics icru diff --git a/doc/toolboxes/sphericalmonomials.rst b/doc/toolboxes/sphericalmonomials.rst index 311b33ca..5b4812b5 100644 --- a/doc/toolboxes/sphericalmonomials.rst +++ b/doc/toolboxes/sphericalmonomials.rst @@ -1,5 +1,5 @@ SphericalMonomials -============= +================== .. doxygenclass:: SphericalMonomials :members: diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index fb7e7400..fc637045 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -10,12 +10,15 @@ Troubleshooting * - ``VTK not found`` during CMake configure - Missing VTK development package - Install your distro's VTK dev package or use a container. - * - ``LAPACK not found`` + * - ``BLAS not found`` or ``LAPACK not found`` - Missing BLAS/LAPACK implementation - Install OpenBLAS/LAPACK development packages and rerun CMake. * - Smoke checker reports missing output directory - Solver did not complete or was launched from the wrong path - Run from the repository root and inspect solver output. + * - ``python tools/check_smoke_output.py`` fails with syntax errors + - Python is older than the checker requires + - Use Python 3.10 or newer. * - ``mpirun`` works locally but fails on a cluster - Container MPI does not match host MPI or launcher policy - Use the site-recommended MPI/container binding and update the SLURM template. diff --git a/doc/tutorials/smoke_test.rst b/doc/tutorials/smoke_test.rst index c1bf1733..97aa51f9 100644 --- a/doc/tutorials/smoke_test.rst +++ b/doc/tutorials/smoke_test.rst @@ -9,6 +9,9 @@ checks. Build and run ------------- +This path requires the CPU build dependencies from :doc:`../installation`, +including BLAS, LAPACK, VTK, OpenMP, and Python 3.10+ for the checker. + .. code-block:: bash cmake -S . -B build_omp -DCMAKE_BUILD_TYPE=Release -DBUILD_MPI=OFF -DBUILD_CUDA_HPC=OFF -DBUILD_ML=OFF @@ -29,5 +32,5 @@ Common failures --------------- - ``MESH_FILE`` not found: run from the repository root and use ``examples/configs/smoke_test.cfg`` unchanged first. -- Missing VTK/LAPACK/OpenMP libraries: install the development packages or use a container build. +- Missing BLAS/LAPACK/VTK/OpenMP libraries: install the development packages or use a container build. - No CSV log: inspect solver stderr/stdout; the run likely failed before history output was written. diff --git a/src/common/io.cpp b/src/common/io.cpp index a8042c51..990fb6bd 100644 --- a/src/common/io.cpp +++ b/src/common/io.cpp @@ -592,7 +592,8 @@ void PrintLogHeader( std::string inputFile ) { log->info( "| |_|\\_\\___| |_| |_| \\_\\|_| |" ); log->info( "| |" ); log->info( "------------------------------------------------------------------------" ); - log->info( "| Copyright: MIT Licence |" ); + log->info( "| Copyright: Steffen Schotthoefer, Pia Stammer, Jonas Kusch |" ); + log->info( "| License: MIT License |" ); // log->info( "| Authors: S. Schotthöfer, J. Kusch, J. Wolters, P. Stammer ad T. Xiao |" ); log->info( "| Date: 21th April 2022 |" ); log->info( "------------------------------------------------------------------------" );