OpenNDM

Open Nodal Diffusion Method — a three-dimensional, multi-group nodal diffusion solver for reactor core analysis, with a C++17 core, a pybind11 Python API, and a group-constant generation path built natively on the OpenMC stack.

OpenNDM is the second stage of a two-step lattice → core calculation scheme in which OpenMC performs the lattice-physics stage. Its distinguishing goal:

A user who already has an openmc.mgxs.Library object should be able to run a full-core nodal calculation without writing a single line of format-conversion code.

See docs/requirements.md for the full software requirements specification, and docs/status.md for exactly which of those requirements are implemented today.

Status

Pre-1.0 (v0.3.0). The static solver is verified against an analytic solution and the published IAEA-2D/3D and BIBLIS-2D benchmarks. Transients and steady thermal-hydraulic feedback are implemented; transients with feedback and pin power reconstruction are not. docs/status.md maps every requirement ID to its state — read it before assuming a feature exists.

Implemented and tested:

• 3D Cartesian geometry on an abstract node/surface graph, non-uniform mesh, inactive core-map positions, per-face zero-flux / vacuum / reflective / albedo boundaries
• Arbitrary group count with full G×G scattering including upscattering, assembly discontinuity factors with assembly rotation, branch-parameterised libraries with multilinear interpolation, and √T Doppler feedback
• Three run-time-selectable kernels: FDM, polynomial nodal (NEM) and semi-analytic nodal (SANM), coupled through a nonlinear two-node CMFD iteration, with a one-node problem closing the boundary faces
• Power iteration with Wielandt shift, ILU0-preconditioned BiCGSTAB inners, forward / adjoint / fixed-source modes, critical boron search
• Control rod banks addressed by position, a cusping correction for a partially rodded node, and integral and differential worth curves
• Transients: θ-weighted time integration with delayed precursors integrated in closed form
• Thermal-hydraulic feedback at steady state: closed-channel energy balance with homogeneous equilibrium boiling, radial pin conduction and the effective Doppler temperature, IAPWS-IF97 water properties, and a Picard coupling that also drives a boron search against the coupled state. Any external solver can take the channel model's place through the ThermalSolver protocol
• openndm.gc ingestion of openmc.mgxs.Library, mgxs.h5 files and statepoints, with OpenMC as an optional dependency, validated end to end against a real OpenMC run (C-1)
• HDF5 statepoint output and an openndm.StatePoint reader, and VTK export for ParaView

Installation

pip install openndm      # wheels for Linux and macOS, Python 3.10 to 3.13

From a checkout, pip install . builds the extension with a C++17 compiler; CMake and ninja come from pip. CONTRIBUTING.md has the development setup.

OpenMC is optional and only needed for openndm.gc.

Examples

Four executed notebooks live in examples/. The one the package exists for is 02_openmc_to_openndm.ipynb: an OpenMC lattice calculation becomes a nodal core calculation with no format conversion written by hand. On the run committed there it reproduces OpenMC's k_inf to 12 pcm, 0.2σ.

docs/user-guide.md is the reference.

Quick start

import numpy as np
import openndm

# A 2-group, 3D quarter-core model.
lib = openndm.XSLibrary(n_groups=2, n_compositions=2)
lib.set_composition(
    0,                                                 # fuel
    D=[1.5, 0.4], absorption=[0.010, 0.085],
    nu_fission=[0.0, 0.135], kappa_fission=[0.0, 0.135],
    chi=[1.0, 0.0], scatter=[[0.0, 0.020], [0.0, 0.0]],
)
lib.set_composition(
    1,                                                 # reflector
    D=[2.0, 0.3], absorption=[0.0, 0.010],
    scatter=[[0.0, 0.040], [0.0, 0.0]],
)
lib.finalize()                                         # validates, returns warnings

core = np.zeros((10, 9, 9), dtype=int)
core[:, 8, :] = 1                                      # radial reflector
core[:, :, 8] = 1

geom = openndm.Geometry.from_lattice(
    core, pitch=(20.0, 20.0, 20.0),
    boundaries={"x_min": "reflective", "y_min": "reflective",
                "x_max": "zero_flux", "y_max": "zero_flux",
                "z_min": "vacuum", "z_max": "vacuum"},
)

model = openndm.Model(geom, lib, openndm.Settings(kernel="sanm", verbosity=0))
result = model.solve()

print(result.k_eff)              # 1.036855
print(result.radial_power())     # assembly-wise relative power, (9, 9)
print(result.f_q, result.f_dh)   # peaking factors

Verification

pytest tests/python runs the verification suite, and ctest --test-dir build the C++ one. The checks that pin down correctness:

• V-1, analytic buckling. A bare homogeneous cuboid against k = νΣf / (Σa + D B²). The nodal kernels converge at fourth order and FDM at second; at 64 nodes per side the error is under 0.01 pcm nodal and 0.86 pcm FDM.
• V-1, reflected slab. A core plus reflector against the transcendental criticality condition D₁B tan(B a) = D₂κ coth(κb), which exercises a material interface, a reflector and two boundary conditions at once.
• Albedo boundary. Against its own analytic condition D B tan(B a) = γ across five albedo values, plus all three limits: β=1 is reflective, β=0 is vacuum, β=−1 is zero flux.
• V-2, manufactured solutions. The full multi-group operator, scattering and fission included, against a solution chosen in advance, with the observed order of accuracy of each kernel.
• V-3, kernel consistency. Coarse-mesh SANM and NEM against a refined FDM solution of the same problem. On the IAEA-2D core map SANM and NEM agree to the last digit printed from four nodes per assembly onward, and all three kernels converge to the same eigenvalue under refinement. This is the check that catches a wrong transverse leakage, a wrong discontinuity factor convention or a broken two-node closure; mesh refinement alone would not, because a kernel with any of those defects still converges smoothly, just to the wrong answer.
• V-4, adjoint reciprocity. Forward and adjoint eigenvalues agree to under 1 pcm while the flux shapes differ.
• V-4, perturbation theory. First-order adjoint-weighted reactivity against a direct re-solve. This tests the adjoint flux shape; eigenvalue equality alone only confirms the operator was transposed.
• Neutron balance. Every node conserves neutrons to 3e-12, and the core-wide leakage-plus-absorption-equals-production identity closes to 1e-9.
• Symmetry. A symmetric core map gives a symmetric power; rotating or mirroring a lopsided core is a pure relabelling.
• Determinism. Bit-identical results on 1, 2, 4 and 8 threads.

OpenMC coupling

tests/validation/ runs the specification's coupling validation cases.

C-1 is a uniform infinite medium in OpenMC with continuous-energy physics, whose multi-group cross sections are then solved by OpenNDM. It isolates the translation path from every other source of error, and reproduces OpenMC's k_inf to 12 pcm, 1.2σ over 90M histories.

C-2 is a single reflected assembly, which must give discontinuity factors of exactly 1.0 when homogeneous and a thermal factor above 1.0 when it is a pin lattice. Measured: 1.0 to 1.2σ, and 1.045 thermal / 0.993 fast.

Between them these found three defects that stand-in test doubles could not have caught, two of which fail silently — see tests/validation/README.md.

Benchmarks

All four static decks meet the specification's 100 pcm acceptance criterion. See benchmarks/README.md for the full convergence tables and for the two transcription errors the structural invariants now catch.

Documentation

The full documentation is at openndm.readthedocs.io, built with Sphinx using a theme provided by Read the Docs. The same material is readable as Markdown in this repository:

Author

OpenNDM was initiated and is developed by Rizki Oktavian, PhD (@rizkiokt).

If you would like to contribute, or want to discuss using OpenNDM in your own work, get in touch at rizkiokt@purdue.edu. Bug reports and feature requests are better filed as issues, and CONTRIBUTING.md describes the pull request workflow.

Citing

If OpenNDM contributes to published work, please cite it. GitHub renders CITATION.cff into BibTeX from the Cite this repository button in the sidebar.

License

MIT — see LICENSE.

OpenNDM is research software. It carries no nuclear quality assurance pedigree and is not qualified for licensing or safety analysis; see SECURITY.md.