Installation

RadCluster has two layers: a Python package and a C++17 solver. There are three ways to get a working installation.

Way	When to use it
Container image	to try the code, or to run it without building anything
Python environment only	to build a material graph, inspect the model, and run the reference graph walker
Python environment and C++ solver	for production runs

Container image

A published image carries the compiled solver, the Python layer and the input workbook.

docker pull ghcr.io/ghoniem/radcluster:v2.2.0
docker run --rm -it ghcr.io/ghoniem/radcluster:v2.2.0

Inside the container, solver is on PATH, and /work holds py_utils/, input/ and codes/ with PYTHONPATH already set.

The output is written inside the container, and it is lost when the container exits. Mount a host directory to keep it:

docker run --rm -v "$PWD/output:/work/output" ghcr.io/ghoniem/radcluster:v2.2.0 \
    python3 codes/Python_Testing/check_eurofer_rag.py

Note: The solver in the image is compiled for x86-64-v2, so that it runs on any x86-64 processor from about 2009 onwards. This costs a little speed. For sustained production runs, build the solver from source.

Python environment

git clone https://github.com/Ghoniem/RadCluster.git
cd RadCluster
python -m pip install -r requirements.txt
python -m ipykernel install --user --name radcluster --display-name "RadCluster"   # optional

Python 3.9 or newer is required, with numpy, scipy, pandas, matplotlib, openpyxl, jupyter and ipykernel. The package networkx is optional. It is used only by the graph-diagnostics export.

C++ solver

Requirements

• a C++17 compiler (GCC, Clang or MSVC)
• CMake 3.15 or newer
• SUNDIALS 7.1.1 (CVODE)

The build looks for SUNDIALS in a folder Libraries/ that is a sibling of the repository root, as Libraries/sundials-7.1.1/mac_install/ or Libraries/sundials-7.1.1/win_install/. If SUNDIALS is not there, the build uses whatever find_package(SUNDIALS) resolves, for example a system install.

Optional dependencies

Each optional dependency is detected at configure time.

Dependency	Enables	If missing
LAPACK/BLAS	the Woodbury preconditioner	it is compiled out, and the solver falls back to the Jacobi preconditioner
OpenMP	the parallel right-hand side of the active_window mode	that mode runs on one thread
SuiteSparse/KLU, with SUNDIALS built with -DENABLE_KLU=ON	the klu sparse-direct linear solver	that option stops at run time with a diagnostic

Build

cd radcluster_code
cmake -S cpp_utils -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

The binary is written to build/, or to build/Release/ with multi-configuration generators. The Python bridge py_utils/cpp_bridge.py finds it in both places.

The driver notebook builds the solver on first use. After you edit the C++ sources, set FORCE_REBUILD = True in the build cell of the notebook.

Note: Fast-math is deliberately not enabled. It alters IEEE-754 semantics, and it can make the error estimator of CVODE diverge on these stiff systems.

Next step

Continue with the Quick start.