Developer guide

Working from a Fortran counterpart

For a parity change, read the complete Fortran routine and all callees that establish units, indexing, ownership, or collective behavior. Map each saved module variable to its C++ owner, preserve operation ordering where rounding or random streams matter, and add a focused test before optimizing.

Do not translate array syntax mechanically. Record each lower bound, halo, periodicity rule, and flattened-index formula. C++ public indices are zero-based unless the header explicitly documents a retained Fortran convention.

Adding a module or API

• Put the user-facing scientific contract in the header with @brief, units, normalization, valid ranges, ownership, collective behavior, and side effects.
• Keep implementation history and line-by-line parity notes in the .cpp unless they are necessary to call the API correctly.
• Use Real, Complex, and selector enums from prec_const.hpp.
• Make host/device transfers explicit at FFTW, LAPACK, HDF5, and MPI boundaries.
• Release static Kokkos views before Kokkos finalization.
• Add unit coverage and, for physics behavior, a reference regression observable.

Documentation conventions

Use @param[in], @param[out], and @param[in,out] where direction is not obvious. State whether species/mode/grid indices are zero-based, whether a method is collective, and whether a view is host-accessible. Use Doxygen math for the scientific definition rather than an informal variable-name expansion.

Run the documentation target after changing a public header:

cmake --build build --target docs

Warnings are written to build/doxygen-warnings.log; malformed commands and broken references fail the target.

The canonical API site is published from the generated build/docs/html directory to orb5x-docs.pages.dev. The main branch CI deploys it after a successful build when the repository contains the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID Actions secrets. The token needs Cloudflare Pages edit permission for the orb5x-docs project. The PAIDynamics website links to this deployment instead of carrying a copied Doxygen tree.

Review checklist

• The implementation and adjacent Fortran reference agree on signs and units.
• Bounds and flattened layouts have tests at endpoints and periodic seams.
• MPI calls use the intended communicator and matching counts/types.
• Kokkos kernels do not dereference host-only state.
• Restart/output schema changes are deliberate and documented.
• New input selectors have names, defaults, validation, and a benchmark case.