Software architecture

The execution path is intentionally close to ORB5 so physics parity can be reviewed module by module. C++ ownership, Kokkos memory, and explicit lifecycle rules replace Fortran module storage.

Control flow

1. main.cpp initializes MPI and Kokkos.
2. orb5x::ControlAll parses the run, creates output state, and initializes modules.
3. orb5x::OneStep advances fields, markers, collisions, sources, and diagnostics.
4. orb5x::Epilogue and module cleanup release HDF5, MPI, and Kokkos-owned state before their runtimes are finalized.

Principal layers

Layer	Representative API	Responsibility
Run control	orb5x::ControlAll, orb5x::ReadInput	configuration, lifecycle, files, restart
State/configuration	globals.hpp, prec_const.hpp	typed selectors, normalized parameters, shared module state
Particles	orb5x::ParticleModule, orb5x::ParMove, orb5x::SortingClass	loading, orbit push, migration, sorting, deposition
Fields	orb5x::FieldsModule, orb5x::PartFieldsModule	field storage, gather/scatter, gyroaveraging
Solver	orb5x::InterfaceSolverInOrb5, orb5x::SolverModule	B-splines, Fourier filtering, matrices, boundary conditions
Physics operators	collisions, sources, antenna, islands, background	split operators and optional models
Diagnostics	orb5x::Diagnostics, orb5x::DiagnosticBSpline, orb5x::Vis3d	reductions and HDF5 products
Numerical support	orb5x::spclibs	spline basis, quadrature, dense/band matrices

State and lifecycle

globals.hpp groups data by scientific subsystem rather than exposing thousands of unrelated global symbols. The process-wide pointers are initialized only after Kokkos::initialize(). Any static or global Kokkos::View must be cleared before Kokkos::finalize(); module destroyStaticViews() methods make that ordering explicit.

Memory spaces

Treat Kokkos::View memory space as part of an API contract. Host-only LAPACK, HDF5, FFTW, and MPI calls cannot generally dereference device memory. Use mirrors and Kokkos::deep_copy at explicit boundaries. Avoid capturing process-global pointers in device kernels unless their pointees have been reduced to trivially copyable device data.

Fortran reference relationship

Adjacent .F90 files are specifications and regression oracles, not build inputs of the C++ target. Comments such as “Fortran index” describe translation rules; the public C++ API is zero-based unless explicitly documented otherwise.