Skip to content

Update README.md #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ScSteffen merged 1 commit into from
Aug 10, 2025
Merged

Update README.md #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 115 additions & 98 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,145 +1,162 @@
[![CI](https://github.com/CSMMLab/KiT-RT/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/CSMMLab/KiT-RT/actions/workflows/c-cpp.yml)
# KiT-RT: Modular, HPC-Ready Radiative Transport Solver

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/KiT-RT/kitrt_code)](https://github.com/KiT-RT/kitrt_code/stargazers)
[![Build Status](https://github.com/CSMMLab/KiT-RT/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/CSMMLab/KiT-RT/actions/workflows/c-cpp.yml)
[![Coverage Status](https://coveralls.io/repos/github/CSMMLab/KiT-RT/badge.svg?branch=master)](https://coveralls.io/github/CSMMLab/KiT-RT?branch=master)
[![Documentation Status](https://readthedocs.org/projects/kit-rt/badge/?version=latest)](https://kit-rt.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# KiT-RT - an HPC Radio Therapy simulation framework
The KiT-RT (Kinetic Transport Solver for Radiation Therapy) framework is a high-performance open source platform for radiation transport. Its main focus is on radiotherapy planning in cancer treatment. To enable problem-specific method selection, the framework provides different deterministic solver types. This not only facilitates treatment planning, but also provides tools to investigate various research questions in the field of radiative transfer. This goal is supported by an easily extendable code structure that allows for straightforward implementation of additional methods and techniques.

The documentation can be found [here](https://kit-rt.readthedocs.io/en/develop/index.html).
The preprint for the KiT-RT journal paper is available [here](https://arxiv.org/abs/2205.08417).
## Contents

* [Capability](#what-kit-rt-is-capable-of)
* [Build](#build)
* [Run](#run)
* [Unit Tests](#unit-tests)
* [Docker](#docker)
* [Tensorflow](#tensorflow)
* [Citation Info](#Cite)

## What KiT-RT is capable of
### Theory
A short description of kinetic theory can be found [here](https://kit-rt.readthedocs.io/en/develop/physics.html).

## Build
### Required dependencies
- Compiler with C++17 support
- cmake >= v3.16
- LAPACK
- OpenMP
- MPI
- python3
- VTK
- git

### Tensorflow installation
If you choose to enable the machine learning tools via the BUILD_ML option, you need to install the tensorflow C-API:
```
FILENAME=libtensorflow-cpu-linux-x86_64-2.7.0.tar.gz
wget -q --no-check-certificate https://storage.googleapis.com/tensorflow/libtensorflow/${FILENAME}
tar -C /usr/local -xzf ${FILENAME}
ldconfig /usr/local/lib
```
[![Docs](https://readthedocs.org/projects/kit-rt/badge/?version=latest)](https://kit-rt.readthedocs.io/en/latest/?badge=latest)

### Python dependencies
- pydicom
- numpy
- pygmsh version 6.1.1
```bash
pip install pygmsh==6.1.1
```
(note that newer versions are not yet supported)

## Overview

### Obtain submodules
Note that an **active internet connection is required for the first build** in order to download the suitable versions of the required submodules!
For the first build only, download all submodules:
KiT-RT is an open-source, multi-fidelity **C++ PDE solver for radiative transport** in fusion, fission, and radiation therapy simulations. Designed from the ground up for **AI-accelerated scientific computing**, it supports hybrid neural–PDE workflows, enabling high-resolution reference solutions, scalable data generation for scientific foundation models, and outer-loop workflows such as uncertainty quantification and design optimization.

```bash
git submodule update --init --recursive
```

### Compile the code
In case of the **make** build system (available on most systems) run:

```bash
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
make -j
```

---
## Key Features

## Run
Execute the compiled binary by handing over a [valid config file](https://kit-rt.readthedocs.io/en/latest/configFiles.html), e.g.:
* **Modular, HPC-ready** architecture. Supports hybrid **MPI/OpenMP distributed parallelism**.
* **Containerized** for portable deployment across HPC systems (Docker & Singularity).
* **Python-wrapped** via [CharmKIT](https://github.com/KiT-RT/CharmKIT) — *like PyTorch for AI integration in scientific simulation*.
* Downstream applications:
- Data generation for scientific **foundation models**.
- high-resolution **reference solutions** for AI-based surrogate modeling.
- Plug-and-play integration for outer-loop workflows (**UQ, optimization**).

```bash
./KiT-RT ../examples/linesource_SN.cfg
```

In order to run the code in parallel execute:

```bash
OMP_NUM_THREADS=N mpirun -np J ./KiT-RT ../examples/linesource_SN.cfg
```
## Scientific Impact

with `N` equal to the number of shared memory threads and `J` equal to the number of distrubuted memory threads.
KiT-RT has been adopted by:

---
* Sandia National Labs
* Lawrence Livermore National Labs
* Oak Ridge National Labs
* Karlsruhe Institute of Technology
* TU Delft
* NMBU Norway
* Chung-Ang University, Korea
* RIKEN Japan

## Unit Tests
After compiling the framework with:

```bash
cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON ../
make -j
```
Applications include:

* Foundation model training for fusion simulation.
* Large-scale UQ experiments.
* Radiation therapy planning.
* Accelerated neural network inference.
* Reference dataset generation for ML-based surrogate models.



## Publications & References

### Core Software

* **KiT-RT: An Extendable Framework for Radiative Transfer and Therapy** — *ACM Transactions on Mathematical Software* \[[DOI](https://doi.org/10.1145/3630001)]

### Datasets & Benchmarks

* **Reference solutions for linear radiation transport: the Hohlraum and Lattice benchmarks** — *arXiv:2505.17284* \[[PDF](https://arxiv.org/abs/2505.17284)]

### 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)]
* [PhD Thesis: Synergies between Numerical Methods for Kinetic Equations and Neural Networks](https://doi.org/10.5445/IR/1000158838)



## Installation

Unit test can be run with:
### Plain cpp setup
```bash
make test
```
# Clone repository
git clone https://github.com/KiT-RT/kitrt_code.git
cd kitrt_code
git submodule update --init --recursive

---
# Build with CMake
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
make -j

## Docker
```
### Docker setup
A preconfigured docker container can also be used to run the code.
By running

```bash
docker run --rm -ti -v $(pwd):/home kitrt/test:latest
```


To use the tensorflow backend for neural network based entropy closures, please use the tensorflow equippend containter by running
Bash scripts are provided in the folder tools/CI to get started with the docker environments. To start an interactive docker environment, execute
```bash
docker run --rm -ti -v $(pwd):/home kitrt/test_ml:latest
docker run -i -t --rm -v $(pwd)/../..:/mnt kitrt/test:latest /bin/bash
```
from the current folder will be mounted to the docker container and the code can be executed without any of the required dependencies.

Bash scripts are provided in the folder tools/CI to get started with the docker environments. To start an interactive docker environment, execute
### Singularity setup
Create the singularity container
```bash
docker run -i -t --rm -v $(pwd)/../..:/mnt kitrt/test:latest /bin/bash
mkdir build_singularity
cd tools/singularity
sudo sh build_container.sh
chmod +x install_kitrt_singularity.sh
singularity exec kit_rt.sif ./install_kitrt_singularity.sh
```
Run the singularity container
```bash
singularity shell --bind $(pwd)/../..:/mnt kit_rt.sif
```

## Tensorflow
To use the neural network based entropy closure, one needs to install the tensorflow C++ backend. Just use the following commands:
## Running simulations
Within any of the above setups, navigate to the example folder and execute KiT-RT
```bash
cd examples
../<build_folder_name>/KiT-RT configs/lattice_SN.cfg
```

## Tensorflow backend
If you choose to enable the integrated machine learning tools via the BUILD_ML option, you need to install the tensorflow C-API:
```bash
FILENAME=libtensorflow-cpu-linux-x86_64-2.7.0.tar.gz
wget -q --no-check-certificate https://storage.googleapis.com/tensorflow/libtensorflow/${FILENAME}
tar -C /usr/local -xzf ${FILENAME}
ldconfig /usr/local/lib
```
and for a gpu based version (you need supported hardware and gpu drivers, see [here](https://www.tensorflow.org/install/gpu) ):
```
and for a gpu based version (you need supported hardware and gpu drivers, see here ):
```bash
FILENAME=libtensorflow-gpu-linux-x86_64-2.7.0.tar.gz
wget -q --no-check-certificate https://storage.googleapis.com/tensorflow/libtensorflow/${FILENAME}
tar -C /usr/local -xzf ${FILENAME}
ldconfig /usr/local/lib
```
## Cite
Or use the docker container
```bash
docker run --rm -ti -v $(pwd):/home kitrt/test_ml:latest
```


## Python API

The Python interface is provided via [CharmKIT](https://github.com/KiT-RT/CharmKIT), allowing seamless integration into AI and outer-loop (UQ, Optimization) workflows.
Check the corresponding readme for further info




## Scaling Studies

Performance benchmarks and scaling plots can be found \[[here](https://doi.org/10.1145/3630001)].



## License

KiT-RT is released under the MIT License. See [LICENSE](LICENSE) for details.

Cite this software using

```bash
@article{kitrt2023,
title={KiT-RT: An extendable framework for radiative transfer and therapy},
author={Kusch, Jonas and Schotth{\"o}fer, Steffen and Stammer, Pia and Wolters, Jannick and Xiao, Tianbai},
Expand Down