Update Documentation (#74)

* improve acecssability

* upgrade rtd

* update readme

Author: ScSteffen

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

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.
 
 

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,28 +48,32 @@
 }
 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')
                 line = line.replace('CLASS_DIAGRAMS         = YES', 'CLASS_DIAGRAMS         = NO')
                 line = line.replace('@DOXYGEN_OUTPUT_DIR@', outputDir)
                 line = line.replace('@DOXYGEN_INPUT_DIR@', inputDir)
                 fout.write(line)
-    subprocess.call('doxygen', shell=True)
+    subprocess.call('doxygen', cwd=conf_dir, shell=True)

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

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

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.

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

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`.

doc/quadratures/qgausslegendretensorized2D.rst

@@ -1,5 +1,5 @@
 QGaussLegendreTensorized2D
-========================
+===========================
 
 .. doxygenclass:: QGaussLegendreTensorized2D
    :members:

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