>>=============================================================================================<<
_____ _____ _ _ ______ ___ _____ ______ _____ ______ _ _ ______
/ __ \ _ _ / __ \| | | || _ \ / _ \ / ___|| ___ \| _ | | _ \| | | || ___ \
| / \/ _| |_ _| |_ | / \/| | | || | | |/ /_\ \ \ `--. | |_/ /| | | | | | | || | | || |_/ /
| | |_ _||_ _| | | | | | || | | || _ | `--. \| __/ | | | | | | | || | | || /
| \__/\ |_| |_| | \__/\| |_| || |/ / | | | | /\__/ /| | \ \_/ / | |/ / \ \_/ /| |\ \
\____/ \____/ \___/ |___/ \_| |_/ \____/ \_| \___/ |___/ \___/ \_| \_|
>>=============================================================================================<<
A modern C++20 rewrite of the Fortran SPO-DVR code: six-dimensional quantum wave-packet dynamics of a diatomic molecule scattering from a surface (coordinates Z, r, x, y, θ, φ). It uses split-operator propagation, FFT grids in Z, r, x and y, and a Gauss-Legendre/FFT DVR in θ and φ.
This project is a full reimplementation of the original SPO-DVR Fortran 90 code, written by Dr. Mark F. Somers during his PhD at Leiden University:
- M. F. Somers, Six-Dimensional Quantum Dynamics of Dissociative Chemisorption of Hydrogen on Metal Surfaces, PhD thesis, Leiden University (2004), repository.
- G. J. Kroes and M. F. Somers, Six-dimensional dynamics of dissociative chemisorption of H₂ on metal surfaces, J. Theor. Comput. Chem. 4, 493 (2005), DOI.
I am very grateful that I could use the original Fortran code during my own PhD. Making it faster and porting it to CUDA has been a years-long endeavour: faster calculations open the door to more avenues of approach with quantum dynamics calculations.
Over the years SPO-DVR has been my go-to code whenever I wanted to apply newly learned programming skills to highly complex, performance-critical code. I tinkered with and refactored small parts of it by hand, but it took Claude to pull all the ideas together into a working program and to benchmark its accuracy. Without Claude this would have been too big for a hobby project.
This program is a port of the Fortran SPO-DVR code. The port started from version 5.19 (2023);
every regression gate compares with upstream 5.24 at svn r1713 (2026), built with -O3
(docs/validation.md). The production-grid validation and the
Fortran benchmark below used 5.19. Built with -O3, 5.24 is bitwise identical to it on every gate
case (the benchmark case among them) and on the production grid's potential and first 40 steps
(reference data,
production grid). The port status of each upstream change
since 5.19 is in docs/upstream_sync.md, every known difference from the
Fortran code in docs/fortran_deviations.md, and the gates that
compare the two programs in docs/validation.md.
The table lists the features of the Fortran code (5.24 r1713) and their status in the C++:
- ported: the C++ does what the Fortran does; a note in parentheses names a Fortran quirk that is kept, or a deliberate difference in a single check or edge case (with its ID);
- deviation: ported, but different on purpose;
- partly ported: the cell says what is missing;
- not ported: the cell says what such an input does in the C++;
- not planned: decided not to port; the cell gives the reason.
"Input error": the program stops with a message naming the key (exit code 2). "Refused": the program stops with a "not supported" message (exit code 3).
| Feature | What it does | Status | Details |
|---|---|---|---|
| Run modes | |||
New run (NewCalc: true; Fortran nread 0) |
propagates the initial wave packet and analyses it on the fly | ported | validation |
Restart (NewCalc: false; nread 1) |
continues a run from its saved wave packet; the S matrix covers the whole run | ported | restart |
Analysis-only run (onlyAnalysis; nread 2) |
the fine analysis of the BK coefficients of an earlier run, without propagation | ported | output_files |
Fine analysis after the run (alsoAnalysis) |
the same analysis right after the propagation | deviation: the fine results are written next to the on-the-fly ones (the Fortran replaces them) | fortran_deviations: Fine analysis, kept |
Potential-only run (Potential; nread 6) |
computes the potential and the gas-phase states, then stops | partly ported: V is computed and checked but not saved (the .pes cache, below, is not ported) |
input_schema |
2D potential cut (write2DPES, x2DPES, y2DPES, theta2DPES, phi2DPES) |
writes V(r, Z) at fixed x, y, θ, φ to a file, then stops | not ported: refused | input_schema |
| Grids and wave packet | |||
Six dimensions (ZDoF, RDoF, XDoF, YDoF, ThetaDoF, PhiDoF) |
the coordinates Z, r, x, y, θ, φ; both codes accept only all six | ported | input_schema |
Molecule (Mass1, Mass2, HomoNuc) |
the atom masses; homonuclear (one parity of j) or heteronuclear | ported | input_schema |
Z grids (ZStart, dZ, nZ, nZSpecular) |
FFT grids in the molecule–surface distance Z: the scattering grid and the longer specular grid | ported; a specular grid shorter than the scattering grid is an input error | inputs/README |
r grid (RStart, dR, nR) |
FFT grid in the bond length r | ported (RStart ≤ 0 rejected, as in 5.24) |
upstream_sync |
Surface grid (nX, nY) |
FFT grid over the surface unit cell, whose lattice and skew angle the PES defines | ported | input_schema |
Rotational basis (JMax, MJMax) |
spherical harmonics up to JMax, on a Gauss–Legendre grid in θ and an FFT grid in φ | ported (MJMax ≤ 0 means JMax, as in the Fortran) |
fortran_deviations: MJMax <= 0 |
| Gas-phase states | the potential far from the surface, V_asy(r), and its rovibrational states (Fourier grid Hamiltonian) | ported | validation |
Initial wave packet (EMinWP, EMaxWP, Z0, VIn, JIn, MJIn, TolSp) |
a Gaussian in Z at Z0 that spans the energies EMinWP to EMaxWP, times the initial state (v, j, mJ) | ported (TolSp is required: the Fortran has no default) |
inputs/README |
Oblique incidence (EParallel, PhiParallel) |
the parallel translational energy and its azimuth, by a momentum shift on the x, y grid | ported | input_schema |
| Propagation | |||
Split-operator propagation (tStart, tEnd, dtStep, nStep) |
exp(−iT·dt/2) exp(−iV·dt) exp(−iT·dt/2) per step: T by FFTs in Z, r, x, y and in the rotational basis, V on the angular grid | ported | validation |
Two grids (ProjOp: 2) |
the initial channel on the long specular grid, the rest of the wave on the scattering grid | ported | input_schema |
Single grid (ProjOp: 1, 0) |
1: moves the specular wave onto the scattering grid once little of it lies beyond that grid; 0: one grid from the start | not planned: 1 is a legacy option, and the Fortran rejects 0 itself; both are input errors | fortran_deviations: ProjOp = 1 |
Potentials (SystemID) |
|||
HardWallPES |
test potential: a 1/Z⁴ wall on an H₂ curve in r, without x, y, θ, φ dependence | ported | validation |
H2Cu111DaiLight |
H₂/Cu(111): the analytic LEPS PES of Dai and Zhang (J. Chem. Phys. 102, 6280 (1995); the DZ PES of the thesis), called Dai–Light in the Fortran and in the test and case names | ported | validation |
H2Cu111Persson |
H₂/Cu(111): analytic LEPS of Persson et al. (J. Chem. Phys. 110, 2240 (1999); the ER PES of the thesis, ER = Eley–Rideal) | ported (a lattice-period quirk kept) | fortran_deviations: Persson PES quirk |
CRPlibrary (CRPlibDataSet) |
any C3v, C4v or C6v data set of the CRP library of M. Wijzenbroek | ported (deviations) | crp_library |
CRPDistrtSurface (CRPlibDataSet and the SCM keys; new in 5.24) |
a CRP data set plus the static corrugation model (SCM) of one snapshot of a distorted slab | ported (position files v2/v3 only, SCM D5; SCM deviations) | scm, keys |
H2Cu111PW91 |
H₂/Cu(111): CRP fit of PW91 DFT data | not ported: input error | data |
H2Cu111RPBE |
H₂/Cu(111): CRP fit of RPBE DFT data | not ported: input error | data |
H2Cu111PW91RPBE (PESMixingAlfa) |
H₂/Cu(111): α·PW91 + (1 − α)·RPBE of the two above (SRP) | not ported: input error (refused if PESMixingAlfa is given) |
data |
H2Cu111SRPnMode4 (PESMixingAlfa) |
4-mode expansion of H2Cu111PW91RPBE about its barrier |
not ported: input error (refused if PESMixingAlfa is given) |
data |
H2Cu111SRPnMode5 (PESMixingAlfa) |
5-mode expansion of H2Cu111PW91RPBE about its barrier |
not ported: input error (refused if PESMixingAlfa is given) |
data |
H2Cu111Grow |
H₂/Cu(111): GROW fit (Collins) of DFT data | not ported: input error | data |
H2Cu110 |
H₂/Cu(110), from its data files | not ported: input error | data |
H2Cu100PES5 |
H₂/Cu(100): corrugation-reducing fit, PES number 5 | not ported: input error | data |
H2Pt111 |
H₂/Pt(111): interpolated ab initio data (direct or corrugation-reducing) | not ported: input error | data |
H2Pt111nMode4 |
4-mode expansion of H2Pt111 about its barrier |
not ported: input error | data |
H2Pt111nMode5 |
5-mode expansion of H2Pt111 about its barrier |
not ported: input error | data |
HDPt111 |
HD/Pt(111): H2Pt111 in the HD centre-of-mass frame |
not ported: input error | data |
H2Pd111 |
H₂/Pd(111): interpolated ab initio data | not ported: input error | data |
H2Ru0001PW91 |
H₂/Ru(0001): corrugation-reducing fit of PW91 data | not ported: input error | data |
H2Ru0001RPBE |
H₂/Ru(0001): corrugation-reducing fit of RPBE data | not ported: input error | data |
H2Ru0001PW91RPBE (PESMixingAlfa) |
H₂/Ru(0001): α·PW91 + (1 − α)·RPBE of the two above | not ported: input error (refused if PESMixingAlfa is given) |
data |
H2CORu0001Grow |
H₂ on CO-covered Ru(0001): GROW fit | not ported: input error | data |
H2NiAl110 |
H₂/NiAl(110): interpolated ab initio data, on a rectangular unit cell | not ported: input error | data |
H2TiAl100GrowPES |
H₂/TiAl(100): GROW fit | not ported: input error | data |
H2Al110 |
H₂/Al(110), adapted from the Cu(110) module | not ported: input error | data |
H2W100 |
H₂/W(100): corrugation-reducing fit with van der Waals | not ported: input error | data |
H2W110 (new in 5.24) |
H₂/W(110): corrugation-reducing fit with van der Waals | not ported: input error | data |
HW110 (new in 5.24) |
an H atom on W(110): a test potential built on H2W110 |
not ported: input error | data |
| Potential options | |||
Potential limits (ImposeVMin, VMin, ImposeVMax, VMax) |
clamps V from below or above | ported | input_schema |
Switching to the gas phase (UseSwitching, ZminSwitch, ZmaxSwitch) |
switches V over to V_asy(r) between ZminSwitch and ZmaxSwitch; the asymptotic region then starts at ZmaxSwitch | ported | input_schema |
Potential cache (.pes file) |
saves V on disk and reads it back in a later run on the same grids | not ported: V is always computed; a .pes file is ignored |
upstream_sync |
PES morphing (pesmorphparameters.dat; new in 5.24) |
scales or shifts expansion coefficients of V with Gaussians in Z and r | not ported: the file is ignored, without a warning | upstream_sync |
PES mixing, r cut-off (SystemMix, SystemID2, SystemMixCoeff, UseRCutOff, RCutOff) |
read by the Fortran, but without effect (no mixing code; the cut-off is forced off) | not planned: nothing to port; refused when switched on or given | fortran_deviations: Not planned: PES mixing, r cut-off |
| Surface symmetry | |||
C6v symmetry (UseSymmetry) |
computes and stores V only at the symmetry-unique (x, y) points | ported (nX or nY = 1 is an input error; the Fortran warns) | input_schema |
C2v and C4v symmetry (UseSymmetry) |
the same for these point groups; the Fortran switches it off with a warning | deviation: used | fortran_deviations: Surface symmetry, deviations |
Optimal φ grid (nPhisOptimal) |
raises nφ to a multiple that the whole point group can use | ported | input_schema |
| Absorbers | |||
High-end absorbers (ZOpt…, ROpt…, ZSpOpt…: Start, End, Energy or Factor) |
negative imaginary potentials, quadratic in the coordinate, at large Z on both Z grids and at large r | ported (absorber D1, absorber D2) | inputs/README |
Low-Z absorbers (ZOptLow…, ZSpOptLow…; new in 5.24) |
the same, mirrored, at the low-Z end of both Z grids | ported (low-Z D1–D4) | inputs/README |
| Analyses | |||
Analysis line (Zana, dtAna) |
projects ψ at Z = Zana on the asymptotic channels every dtAna (Balint-Kurti coefficients) | ported | validation |
Specular analysis line (DynamZSpAna, ZAnaSp) |
where the initial channel is analysed on the specular grid: following the packet's tail inwards, or fixed | ported (Fortran quirks kept) | inputs/README |
Analysed channels (VAna, JAna, DifOrdAna) |
the vibrational, rotational and diffraction states analysed; by default the open ones | ported | input_schema |
| Diffraction orders | the order of each diffraction channel, per surface point group | deviation: derived from the reciprocal lattice; the same orders | fortran_deviations: Diffraction order |
Analysis energies (NrOfEs) |
the collision energies at which S is computed; −95 puts them on the grid of multiples of π/tEnd | ported (NrOfEs = 0 and 1 are input errors: analysis D1) | input_schema |
| S matrix and probabilities | the energy-resolved S matrix from the BK coefficients during the run: state-to-state, diffraction and reaction probabilities | ported | validation |
| Mean final energies | the mean vibrational, rotational and diffraction energy of the scattered molecules | partly ported: the means per final v are not written | fortran_deviations: Output not reproduced |
| Fine analysis | FFT of the whole BK time series onto the spectral grid, interpolated to the analysis energies | deviation: two Fortran interpolation bugs fixed | fortran_fine_analysis_bugs |
Optional tables (writeProbs, writeRDProbs, writeSMatrix) |
probabilities per (v, j, mJ) and per diffraction order; the S matrix on the spectral grid | ported (as TSV files) | output_files |
Flux analysis (doFluxAnalysis, rFluxAnalysis, EMinFluxAna, EMaxFluxAna, DeltaEFluxAna) |
the reaction probability from the flux through r = r_c, and its (x, y) density | not ported: a propagating run refuses it; its input checks are ported, two of them corrected (flux Q1, flux Q2) | flux_analysis_findings |
Averages (dtAve) |
the norm, ⟨Z⟩, ⟨r⟩ and the rest norm (between the two analysis lines) every dtAve | ported | validation |
| Restart files | |||
| Fortran restart files (fort.9 → fort.8: wave packet; fort.21 → fort.22: BK coefficients) | what a run writes for a restart or a fine analysis, and what those read | ported: read and written (RestartFormat, CheckpointFormat) |
input_schema |
| Analysis state across a restart | the state of the specular analysis line carried into the restarted run | deviation: a Fortran bug fixed (anlyTol is not saved) |
fortran_deviations: Fortran restart bug, fixed |
| Input and output | |||
Input file (DVR.inp, InputNew.f90; Title) |
the run parameters as named fields with defaults | deviation: a JSON file with the Fortran's key names, case-sensitive | input_schema, fortran_deviations: Input file |
Input checks (InputNew.f90, Setup.f90, setupdvr.f90, transform.f90) |
stop on inconsistent parameters before the run | ported; stricter where the Fortran continues silently; exit code 2 (the Fortran's is 0) | input_schema, fortran_input_bugs |
Old input reader (Input.f90) |
the earlier input format | not planned: dead code (the build uses InputNew.f90) |
fortran_deviations: Not ported by decision |
Debug output (DoDump; FullSMatrix) |
DoDump writes the gas-phase states to debug_asyp.dat; FullSMatrix is only printed |
deviation: both keys are ignored; the states are always written, to gas_phase_states.dat |
fortran_deviations: Output not reproduced |
| Screen output | input echo, grids, gas-phase states, averages, results per energy | deviation: a new layout with the same quantities | Running |
Result files (fort.25, fil10, unit 3, averages.out) |
S matrix, probabilities, spectrum and averages on disk | deviation: TSV and JSON files (additions below) | output_files |
CPU timings (CpuTimings.f90, fort.99) |
the time spent per operator and per stage | partly ported: only the times of the potential, the propagation and the fine analysis | fortran_deviations: Output not reproduced |
Post-processing tools (upstream tools.dir) |
read fil10 and fort.25, compare .pes files, site-specific reaction (flux density), n-H₂ averaging, plots, FFT sizes, wave-packet set-up |
not ported: the TSV files need no reader; the input checks FFT sizes; tools/wave_packet_check.py checks the wave packet |
inputs/README |
| Parallelism and build | |||
| OpenMP | threads share the grid points | ported: the results do not depend on the thread count | performance |
MPI (MPI_*.f90, USE_MPI) |
distributes the grid over several computers | not planned: OpenMP and the GPU instead | fortran_deviations: Not ported by decision |
FFTs (ffts.f90, fftw_2_scs.f90) |
the 1D and 2D FFTs of the grids, through FFTW or oneMKL | ported: an FFT layer of its own (oneMKL's FFTW3 interface or FFTW) | performance |
Platform code (*_hack.f90; the ESSL and SCSL FFTs) |
thread queries, timers and vendor FFT libraries per machine type | not planned: standard C++ and OpenMP instead | fortran_deviations: Not ported by decision |
Build flags (upstream GNU.mk since 5.24) |
-Ofast -march=native: fast-math and FMA |
not ported: not relevant; strict floating point without FMA, and the reference is built with -O3 |
upstream_sync |
| Addition | What it does | Details |
|---|---|---|
GPU backend (--device cuda) |
propagates on an NVIDIA GPU with the wave packet in GPU memory; agrees with the CPU code to rounding | cuda |
C3v and C3 symmetry; PES self-check (SymmetryTolerance) |
symmetry-reduced V for point groups the Fortran has no code for; checks that the PES has the symmetry before using it | input_schema |
Native restart files (checkpoint.bin, bk_coefficients.bin; RestartDir) |
restart files that record the run parameters; a restart checks them and names any that differ | output_files |
| TSV and JSON results | tables with commented headers in full precision, and the run metadata in analysis.json |
output_files |
Loop scheduling (--threads, --schedule) |
shares the uneven work per (Z, r) point over threads and NUMA nodes; the results do not depend on it | performance |
| Set-up reports | a memory estimate before V is computed; the ranges of a CRP data set; the SCM checks; the absorber grid-point warning | performance, scm |
Build variants (SPODVR_FAST_MATH, PGO) |
optional faster builds; the default build is strict floating point without FMA | performance |
| Checking tools | compare the final wave packet of two builds or devices; check a wave packet; regenerate and compare the Fortran references | Testing, fortran_reference |
- Build tools: a C++20 compiler with OpenMP (tested with GCC 15, the Ubuntu 26.04 default), CMake ≥ 3.24, Ninja, pkg-config (CMake looks up FFTW3 through it).
- Math libraries, one of:
- Intel oneMKL (recommended; tested with 2026.2, found through its
MKLConfig.cmake): BLAS/LAPACK and the FFTs (through its FFTW3 interface); - FFTW3 + LAPACK (fallback when oneMKL is not installed).
- Intel oneMKL (recommended; tested with 2026.2, found through its
- nlohmann/json and GoogleTest are downloaded by CMake (internet access needed on the first configure).
- Optional, for the GPU backend: an NVIDIA GPU with its driver, and the CUDA toolkit (nvcc, cudart, cuFFT, and at run time nvJitLink and NVRTC for the cuFFT callback). Recommended: the newest CUDA 13 the GPU driver supports (tested with 13.3, the first release that accepts GCC 15; nvcc uses the same compiler as the rest of the build). FP64 speed matters: data-centre GPUs (A100, H100) run FP64 at 1/2 of the FP32 rate, GeForce cards at 1/64.
On Debian/Ubuntu (also under WSL2):
1. Build tools (always needed):
sudo apt install build-essential cmake ninja-build pkg-configAny C++20 GCC works; the project is tested with GCC 15 (Ubuntu 26.04's default). For another
compiler, configure a new build directory with e.g. CXX=g++-14 cmake ...; nvcc then uses it too.
2a. Intel oneMKL (recommended), from Intel's apt repository:
wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
| gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg]" \
"https://apt.repos.intel.com/oneapi all main" \
| sudo tee /etc/apt/sources.list.d/oneAPI.list
sudo apt update
sudo apt install intel-oneapi-mkl-develCMake finds oneMKL in $MKLROOT or in /opt/intel/oneapi/mkl/latest (no setvars.sh needed for
building). The program always uses the sequential, LP64 oneMKL.
2b. Without oneMKL, FFTW3 and LAPACK instead:
sudo apt install libfftw3-dev liblapack-dev3. CUDA (optional, for --device cuda), CUDA 13 from NVIDIA's apt repository (repository
wsl-ubuntu under WSL2, ubuntu2604 / ubuntu2404 on a native Ubuntu 26.04 / 24.04):
nvidia-smi # the GPU must be visible; note "CUDA Version" (newest CUDA the driver runs)
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install cuda-toolkit-13-3 # newest 13.x not above the driver's CUDA version; installs into /usr/local/cuda- Do not install a toolkit newer than the driver supports: it compiles, but the kernels then fail at run time.
- WSL2: the GPU driver is the Windows NVIDIA driver (update it in Windows). Never install a
Linux driver inside WSL; the
wsl-ubunturepository contains none. /usr/local/cuda/binneed not be onPATH: CMake finds nvcc there. It also sets the GPU architecture fromnvidia-smi(override with-DCMAKE_CUDA_ARCHITECTURES, e.g."80-real;90-real"for A100 and H100).- Ubuntu's own packages (
sudo apt install nvidia-cuda-toolkit) work as well, but are older (Ubuntu 24.04: CUDA 12.0 with g++-12 as nvcc's host compiler; untested since the kernels became C++20). - nvcc compiles with the C++ compiler of the build. If the CUDA release rejects that GCC
("unsupported GNU version"; GCC 15 needs CUDA ≥ 13.3), set
CUDAHOSTCXXor-DCMAKE_CUDA_HOST_COMPILERto a GCC it accepts.
git clone https://github.com/ewfsmeets/Cpp-SPO-DVR.git
cd Cpp-SPO-DVR
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build buildThe configure step reports which libraries it uses, e.g.
SPO-DVR: BLAS/LAPACK from oneMKL 2026.2 (sequential), FFT library MKL.
How to run the tests: see Testing.
With the GPU backend:
cmake -S . -B build-cuda -G Ninja -DCMAKE_BUILD_TYPE=Release -DSPODVR_USE_CUDA=ON
cmake --build build-cudaThe kernels are compiled for the GPU of the build machine (native); for another GPU set
-DCMAKE_CUDA_ARCHITECTURES (89-real RTX 40xx, 80-real A100, 90-real H100). The configure step prints the nvcc version, host compiler and architectures.
Useful CMake options:
| Option | Default | Meaning |
|---|---|---|
-DSPODVR_USE_MKL=OFF |
ON |
ignore oneMKL; use the system LAPACK and FFTW |
-DSPODVR_FFT_LIBRARY=FFTW |
AUTO |
use the real FFTW for the FFTs even when oneMKL is present (AUTO picks oneMKL when found) |
-DSPODVR_ARCH=native |
x86-64-v3 |
-march value (x86-64-v3 = AVX2; x86-64-v4 = AVX-512) |
-DSPODVR_PGO=GENERATE/USE |
OFF |
profile-guided optimisation, two builds and a training run (see docs/performance.md) |
-DSPODVR_FAST_MATH=ON |
OFF |
experimental: -ffast-math with NaN and inf kept (with CUDA also --use_fast_math, i.e. FMA, in the GPU kernels); changes results at the 1e-12 to 1e-11 level (details and known test failures) |
-DSPODVR_USE_CUDA=ON |
OFF |
build the GPU backend (--device cuda, NVIDIA GPU, CUDA toolkit; see docs/cuda.md) |
-DSPODVR_BUILD_TESTS=OFF |
ON |
skip the tests |
Performance notes, reproducibility across machines and the PGO workflow are in docs/performance.md.
The development builds live side by side in git-ignored directories.
tools/build_all.sh [variant ...] configures and builds them (all by default; the CUDA ones only
when nvcc is found). It does not use PGO; for that, see docs/performance.md:
| Directory | Options | Purpose |
|---|---|---|
build |
(defaults) | the reference build: oneMKL, no FMA, LTO |
build-fftw |
SPODVR_FFT_LIBRARY=FFTW |
oneMKL LAPACK with the real FFTW |
build-nomkl |
SPODVR_USE_MKL=OFF |
system LAPACK + FFTW: the fallback that must keep working |
build-poison |
SPODVR_POISON_UNINITIALISED=ON |
NaN-fills new large arrays: finds reads before the first write |
build-fast |
SPODVR_FAST_MATH=ON, SPODVR_ARCH=native |
fast CPU build (results differ at the 1e-12 to 1e-11 level; add PGO by hand for the fastest) |
build-cuda |
SPODVR_USE_CUDA=ON |
GPU backend, no FMA (results comparable with the CPU build) |
build-cuda-fast |
SPODVR_USE_CUDA=ON, SPODVR_FAST_MATH=ON, SPODVR_ARCH=native |
fastest GPU build (FMA in the kernels; no PGO) |
Native restart files (checkpoint.bin, bk_coefficients.bin) only work between builds with the
same SPODVR_FAST_MATH setting. A restart or onlyAnalysis run checks the stored set-up parameters
exactly, and the fast-math builds compute one of them (the effective ZOptFactor) 1 ulp
differently, so a default build refuses a fast-math build's native files and vice versa. Files in
the Fortran format (CheckpointFormat "fortran" or "both", read with RestartFormat
"fortran") carry no parameter list and can be used across builds.
clang-format runs as a git pre-commit hook; clang-tidy is run on demand. Both versions are pinned
in .pre-commit-config.yaml and installed by pre-commit itself (no system packages needed):
pipx install pre-commit # once per machine
pre-commit install # once per clone
pre-commit run --all-files # format everything
pre-commit run clang-tidy --hook-stage manual --all-files # lint (needs build/compile_commands.json)OMP_NUM_THREADS=8 ctest --test-dir build --output-on-failure # everything (~9.5 min)
OMP_NUM_THREADS=8 ctest --test-dir build-cuda -R Cuda --output-on-failure # GPU tests (~1.5 min)The times: 809 tests (803 pass, 6 long or reference-less tests skipped) and 24 GPU tests, measured 2026-11-15 at 8b3df8d with 8 threads on an AMD Ryzen 7 5800X and an RTX 4070 Ti.
- Run ctest serially (no
-j): many tests already use all OpenMP threads. SetOMP_NUM_THREADSto the number of physical cores (not hyperthreads). - What is tested:
- unit tests, one program per module (
tests/test_<module>.cpp); - regression tests against the original Fortran code (
tests/test_regression_*.cpp, test namesRegression…/Gate…): potential, gas-phase states, propagation (norms and averages), on-the-fly analysis (probabilities, BK coefficients) and fine analysis. The Fortran reference output is stored intests/reference/(the CRP and SCM driver outputs intests/crplib/reference/andtests/scm/reference/). The gates, their tolerances and cases: docs/validation.md; - GPU tests (
tests/cuda/, namesCuda…): only in builds with-DSPODVR_USE_CUDA=ON. They skip on a machine without a GPU.
- unit tests, one program per module (
- Selecting tests (ctest
-R/-Etake a regular expression on the test name;ctest --test-dir build -Nlists them all):ctest --test-dir build -E Regression # unit tests only (~2.5 min) ctest --test-dir build -R Gate3 # one acceptance gate ./build/tests/test_input --gtest_filter='Input.*' # one test program directly (GoogleTest)
- Long tests: the full 7000-step regression runs (hard wall and Dai–Light; the latter alone takes
about 10 minutes on 8 cores), the negative tests of the low-Z and the SCM gates (1000- and
3000-step runs) and the CRP cluster-pruning check on ten million points
(
CrpLib.ClusterPruningLong.TenMillionPoints) are skipped unlessSPODVR_LONG_TESTSis set:The regular expression selects the names that end inSPODVR_LONG_TESTS=1 OMP_NUM_THREADS=8 ctest --test-dir build -R 'Long($|\.)' --output-on-failure SPODVR_LONG_TESTS=1 OMP_NUM_THREADS=8 ctest --test-dir build-cuda -R 'Cuda.*Long($|\.)' --output-on-failure
Long(or whose suite does); a plain-R Longalso runs the shortScmFiles.ScmD6LongPathsAreNotTruncated. - Skipped regression tests: a regression test skips (it does not fail) when its Fortran
reference file is missing; the tests of the SCM cases
scm_cu111_srp48_small*fail instead. The scripts intools/fortran_reference/regenerate the files; they need a Fortran reference install (tools/fortran_reference/README.md; how to get the Fortran code: there). Running the tests needs only the committed reference files.ctest -R ReferenceManifestfails when a file listed in a case'sMANIFEST.tsvis missing or edited, or a case has noMANIFEST.tsv(MANIFEST.tsv). - Other build variants (Build variants): run the same
ctest command in their build directory. Use
build-poisonafter touching the uninitialised-memory code. The fast-math builds (build-fast,build-cuda-fast) are expected to fail a few tests that compare exact values; their gates pass. The list, with the reason for each: docs/performance.md. - Docs consistency:
python3 -I -B tools/check_docs.py [--spodvr build/spodvr](under 1 s) checks the docs against the code: input keys, output files, links and anchors, decision IDs, local paths, command-line options (with--spodvr), gates, environment variables, and the upstream commit ofdocs/upstream_sync.mdagainst the pin intools/fortran_reference/reference_config.sh(and the install the runs use against it); it also lists numbers repeated across docs (report-only). ctest runs it asDocs.Consistency(ctest --test-dir build -R Docs). Accepted findings, each with a reason, are intools/check_docs_allowlist.tsv; a row that no longer suppresses anything fails the check. - Numerically neutral changes (refactors) must leave the results bitwise unchanged:
tools/check_bitwise_refactor.sh [base-ref](defaultHEAD). It builds both trees in a scratch directory. For changes that may alter rounding:tools/compare_propagation.sh [base-ref] [tolerance](its comparison,tools/compare/compare_averages.py, is tested byctest -R ComparePropagation). Both build throughtools/scratch_build.sh; to configure without network access, setFETCHCONTENT_SOURCE_DIR_NLOHMANN_JSONto the nlohmann_json sources. The final wave packet of two builds, or of the CPU and the GPU:spodvr_dump_waveandspodvr_compare_wave(docs/performance.md). - Production-grid validation: beyond the gates, the full thesis calculation
(
inputs/thesis_fig5_3_dz, 7000 steps) was run with the Fortran, the C++ CPU and the C++ GPU code and compared state by state: docs/validation_thesis_fig5_3_dz. With the default (strict) GPU build, all 111 reaction probabilities match the Fortran's 7 printed digits.
The program reads one JSON input file:
./build/spodvr inputs/hardwall_small/input.json --threads 8 --output-dir runs/hardwall_smallThis example (inputs/hardwall_small, 7000 time steps) takes about 3 minutes with 8 threads on a
desktop machine (AMD Ryzen 7 5800X: the long gate Gate3FullRunLong, which runs this input, took
164 s on 2026-11-15). Its set-up prints two
warnings, "Rotational basis too small to describe all open channels" and "the diffraction basis is
too small to describe all open channels": JMax = 4 and the 4 × 4 surface grid are kept small for
speed. They are harmless here because the hard wall depends only on Z and r, so the wave packet
stays in the initial rotational state and the specular diffraction channel.
Command-line options:
spodvr <input.json> [--threads N] [--schedule dynamic|static] [--device cpu|cuda] [--output-dir DIR] [--no-color]
[--help] [--version]
--device cpu|cuda: propagate on the CPU (default) or on an NVIDIA GPU, where the wave packet stays in GPU memory (needs a build with-DSPODVR_USE_CUDA=ON; see docs/cuda.md). The results agree with the CPU's to rounding (≈1e-13, the level of a different FFT library).--threads N: number of OpenMP threads (default: the OpenMP default, i.e.OMP_NUM_THREADSor all hardware threads). The results do not depend on it. Use the number of physical cores: hyperthreads do not speed up these memory- and FFT-bound loops.--schedule dynamic|static: how the (Z, r) points are shared out over the threads.dynamicbalances the uneven work best (one NUMA node, i.e. one CPU socket);statickeeps every thread on the memory it first wrote (several NUMA nodes). Default: chosen from the number of NUMA nodes. The results do not depend on it.--output-dir DIR: where the data files are written (default: the current directory).
Exit codes (src/app/run.cpp, src/app/main.cpp):
- 0: success (also
--helpand--version); - 1: any other error, e.g. an output file that cannot be opened;
- 2: an input error (the message names the key) or a wrong command line;
- 3: not supported: a feature that is not ported ("Not supported: …");
- 4: a checkpoint or BK file error: a restart or analysis-only file that is missing, corrupt or written with other parameters, or a checkpoint that cannot be written.
Output:
- Screen: an input summary, the grids, a memory estimate, the surface symmetry (with
UseSymmetry), the gas-phase states, the initial wave packet, the analysis basis, a table of averages during the propagation (on a terminal with a live progress line: step, time per step, estimated remaining time), and compact probability tables (one row per energy) at the end. Colour and the progress line are off when the output is not a terminal (a pipe,tee, a file) or with--no-color. - Data files (in the output directory, numbers in full precision):
- the results: tab-separated tables (
.tsv, energies in eV) with#comment lines that explain every column, then one header line; they load withpandas.read_csv(f, sep="\t", comment="#"); analysis.json: the run metadata;- the
.datfiles: space-separated columns after#comment lines (atomic units, unless a column says otherwise); they load withnumpy.loadtxt(f); - the binary restart files.
- the results: tab-separated tables (
| File | Content |
|---|---|
scattering_summary.tsv |
per energy: total scattering and reaction probability, P(v), average final energies |
s_matrix.tsv |
per energy and open final state (v, j, mJ, n, m): S-matrix element, probability, phase |
probabilities_rovib.tsv |
per energy and (v, j, mJ), summed over diffraction |
probabilities_diffraction.tsv |
per energy, (v, j, mJ) and diffraction order |
analysis.json |
run metadata: basis sizes, initial state, energy grid, file list; the SCM identity of a CRPDistrtSurface run |
averages.dat |
time (a.u.), norm, ⟨Z⟩, ⟨r⟩ (bohr), rest norm during the propagation |
asymptotic_potential.dat, gas_phase_states.dat |
set-up data: V_asy(r) (hartree and eV); the gas-phase energies (hartree) and wave functions |
checkpoint.bin, bk_coefficients.bin |
final wave packet and Balint-Kurti coefficients, for a restart |
With alsoAnalysis (or an analysis-only run, onlyAnalysis) the fine-analysis results are written
to fine_analysis/ in the output directory. The file formats are described in
docs/output_files.md.
Set "NewCalc": false, "tStart" to the end time of the earlier run, "nStep" to the number of
steps to add and "tEnd" to tStart + nStep·dtStep (the input check requires this), and
"RestartDir" to the earlier run's output directory; use a different --output-dir. All other
parameters must stay the same, apart from output switches (the program checks the grids, masses,
time steps, wave packet and absorbers against the checkpoint). The S-matrix of the restarted run
covers the whole propagation; a split run gives bitwise the same results as one long run. Runs can
also be continued from the Fortran code's files ("RestartFormat": "fortran": fort.8/fort.9 and
fort.22/fort.21) and written for it ("CheckpointFormat": "fortran" or "both"); see
docs/input_schema.md.
Inside the build tree the oneMKL library path is built into the executable. If you copy or install the executable elsewhere, make the oneMKL libraries findable first:
source /opt/intel/oneapi/setvars.sh # or: export LD_LIBRARY_PATH=/opt/intel/oneapi/mkl/latest/libOptional: export MKL_CBWR=AVX2 gives bitwise identical results across machines with different
vector extensions (see docs/performance.md).
inputs/ holds ready-to-run example inputs:
| Directory | Content |
|---|---|
inputs/hardwall_small/ |
The hard wall reference case (H₂ on a hard wall, Cu(211)-like grid, 0.2–0.6 eV). input.json is the C++ input. DVR.inp is the same calculation for the Fortran reference code. |
inputs/scm_example/ |
A technical example of the SCM potential (CRPDistrtSurface): one snapshot on a small grid, not physics; see its README. |
inputs/thesis_fig5_3_dz/, inputs/thesis_fig5_3_er/ |
H₂ + Cu(111) on the Dai–Zhang (DZ; SystemID H2Cu111DaiLight) and the Persson et al. ER PES (H2Cu111Persson), the two curves of Fig. 5.3 of M. F. Somers' PhD thesis, at the grid sizes of the thesis (except a finer Z grid, see their READMEs; JMax 28, ψ ≈ 6 GB; hours per run). Each directory has a README with the parameter choices. The DZ case is the GPU benchmark. |
- The JSON keys mirror the Fortran
DVR.inpfield names. All keys, defaults, units and checks are described in docs/input_schema.md. - How to choose the Z grids, the wave packet, the analysis lines and the absorbers for a new input: inputs/README.md.
- Unknown keys and inconsistent parameters are reported as errors.
- The test copies of these inputs (with the Fortran reference output) live in
tests/reference/, together with the corrugated test cases (cu111_dailight_*,cu111_persson_small, andcrp_*_synthetic_small, which must be run from the repository root because theirCRPlibDataSetpath is relative to it), whoseinput.jsonfiles can be run in the same way. - The hard wall and test grids are deliberately tiny so that they run quickly. Production calculations use much larger grids: the thesis inputs above need 7.9 GiB (DZ) and 9.7 GiB (ER) of memory on the CPU (their set-up memory estimates: validation record, inputs/thesis_fig5_3_er); finer grids and larger rotational bases need more.
Full Dai–Light run (tests/reference/cu111_dailight_small): 7000 time steps on a 176 × 56 × 8 × 8
(Z, r, x, y) grid with 15 rotational states, plus the on-the-fly analysis. AMD Ryzen 7 5800X
(8 cores), 8 threads, the three runs one after another; measured 2026-11-05 (GCC 13, Fortran 5.19),
not re-run since:
| Binary | Wall time | CPU time | Threads busy on average |
|---|---|---|---|
| Fortran | 680 s | 5255 s | 7.7 |
| C++, current flags | 764 s | 5040 s | 6.6 |
| C++, fast-math + native + PGO | 675 s | 4489 s | 6.7 |
The C++ code needed less CPU time than the Fortran code, but kept the threads less busy, so it was
slower in wall time: load imbalance in the fused T_xy + V loop, which has since been scheduled
dynamically (−9 to −13 % on the thesis grids; docs/performance.md). The fast-math build (then plain
-ffast-math) passed the regression gates except the hard-wall Vasy table (by 1.6e-14, with
GCC 15; since NaN and inf are kept it passes that too), and its results differ from the default build: by ~1e-12 on the gate grids, by 7.8e-12 on the thesis grid (GPU builds)
(validation report).
It is therefore not the default.
Details in docs/performance.md.
GPU (--device cuda), DZ case of inputs/thesis_fig5_3_dz as of 3c1d91b (128 × 40 × 12 × 12 grid, 435 rotational
states, 4.8 GiB wave function; the input now has 160 Z points and a 6.0 GiB wave function), NVIDIA RTX 4070 Ti (a GeForce card: FP64 at 1/64 rate) against
8 threads of the Ryzen 7 5800X, per time step:
| Build | Time per step | Speed-up |
|---|---|---|
| CPU, default flags | 3.6 s | 1× |
GPU, build-cuda (no FMA; agrees with the CPU to ≈1e-14 here) |
0.61 s | 5.9× |
GPU, build-cuda-fast (FMA; S matrix of the thesis run 7.8e-12 from build-cuda) |
0.54–0.57 s | 6.3–6.7× |
At these speeds, the 10 000 steps that the DZ input had then (tEnd 25 000 a.u.; it now has 7000) take about 1.5–1.8 h on the GPU instead of about 10 h. On the current 160-point grid the validation record's 7000-step runs took 0.73 s per step on the GPU (strict build) and 4.24 s on the CPU (fast-math build) (timing table). Details and the limits of this card in docs/cuda.md.
| Path | Content |
|---|---|
src/ |
the program: input/, grids/, potential/, symmetry/, gasphase/, propagation/, analysis/, io/, fft/, linalg/, core/, report/, app/, cuda/ (optional GPU backend), crplib/ (the CRP library port), fortran_text/ (the Fortran list-directed reader shared by crplib/ and the SCM code) |
tests/ |
unit tests (one file per module) and regression tests against Fortran reference output (tests/reference/, tests/crplib/reference/, tests/scm/reference/) |
tools/ |
Fortran reference scripts, benchmark and comparison tools, the docs consistency checker |
docs/ |
input schema, output files, validation against the Fortran (validation.md, fortran_deviations.md), the upstream changes and their port status (upstream_sync.md), the flux analysis findings (flux_analysis_findings.md), the SCM potential (scm.md, scm_open_questions.md), the CRP library (crp_library.md), the Fortran bugs found (fortran_input_bugs.md, fortran_fine_analysis_bugs.md), performance notes, GPU backend |
inputs/ |
example inputs |
potentials/ |
data files of the Fortran potentials, one directory per system (verbatim copy of potential.dir of the upstream Fortran repository) |
This program is free software, licensed under the GNU General Public License, version 3. See LICENSE.