Fortran potentials: porting rules

Why kernels are ported and why they gather are explained in Fortran kernels: port, not wrap.

1 Rules

  1. Module, ``implicit none``, ``private`` by default. Export the physics entry points

and the parameter type; nothing else.

  1. Kinds from ``rgpot_kinds`` (wp, ip, lp).

No real*8, no double precision, no kind literals spelled out at use sites. The module asserts wp == c_double at compile time.

  1. No COMMON, no ``save`` state in the physics. Parameters live in a derived type

with defaults; scratch lives in local automatic arrays. Saved state is allowed only in the _capi module (the parameter set and the legacy workspace of the handle-free entry), never in a kernel. Per-caller neighbour tables live in workspaces from rgpot_workspace. params_ready is written once, under C++ std::call_once, and the parameter block is read-only after that. The handle-free entry’s legacy workspace is process-serial and is not on the Python path.

  1. Every dummy argument gets ``intent``, and arrays that cross into kernels are

contiguous where the caller can guarantee it.

  1. No ``goto``, no arithmetic ``if``, no labelled ``do``. Structured control flow only.

cycle and exit replace jump targets.

  1. Kernels are ``pure`` (or elemental) wherever the algorithm allows, which is

also what do concurrent requires of anything it calls.

  1. Failures return a status. No stop, no write(6,*) diagnostics from a

library kernel: set a message (in the workspace for a _ws entry, through rgpot_ferror for the handle-free entry) and return non-zero. The C++ wrapper turns that into an exception.

  1. Neighbours come from rgpot’s neighbour query (rgpot_nlist_fortran_build

in CppCore/rgpot/nlist/rgpot_nlist.h) through rgpot_neighbors. No pot builds its own list, and no pot repeats minimum-image arithmetic: the table carries pair vectors and distances.

2 Layout

Two modules per potential:

rgpot_<pot>.f90

parameters, pure kernels, the energy/force driver.

Pure Fortran, testable without the C++ stack.

rgpot_<pot>_capi.f90

the bind(c) entries, each returning a status:

rgpot_<pot>_force_ws(handle, natoms, positions, cell, forces, energy) on a workspace from rgpot_fortran_workspace_new, and the handle-free rgpot_<pot>_force(natoms, positions, cell, forces, energy) on the module’s legacy workspace. Potentials that take species (FeHe, CuH2, water-H) add atomic_numbers after positions in both, and rgpot_sw_force_ws adds a strain output. rgpot_<pot>_ensure_params sets the saved parameter set once. The C++ classes call the _ws entries.

The static library builds with hidden visibility. Only the C++ wrapper inside librgpot calls the entry points, so no Fortran symbol reaches the dynamic table and the old collision class (two potentials exporting force_) cannot recur.

2.1 Archive rules

The kernels are one of several PIC convenience archives that link_whole into a single librgpot. Three rules keep that arrangement sound; each was learned by breaking it.

  • A convenience archive takes a headers-only dependency on anything another

archive also links. Meson copies a static library’s objects into every static library that links it, so two archives that both link_with a third each carry its objects, and the umbrella then sees every symbol twice. Linking dependencies belong on the umbrella and on leaf binaries, where the objects arrive once. This is why vesin_dep has a vesin_hdr_dep counterpart, and ptlrpc_dep a ptlrpc_hdr_dep.

  • The Fortran runtime is named explicitly.

librgpot is a C++ target that takes the kernels through link_whole, so meson has no Fortran source of its own to infer -lgfortran (or the flang equivalent) from.

  • Generated sources propagate as headers. A declare_dependency that lists a

generated .cpp in sources: compiles that translation unit again in every consumer; list only the generated header.

The invariants are worth checking mechanically: no object appears in two whole- linked archives, librgpot carries no NEEDED entry on a sibling rgpot object (consumers that bundle the umbrella alone depend on this), and the Fortran runtime appears when the kernels are enabled.

3 Cell convention

C callers pass nine doubles, row-major, one cell vector per row. Fortran reads the same memory column-major, so a real(wp) :: cell(3, 3) dummy sees one cell vector per column, which is the layout rgpot_neighbors uses. No transpose anywhere in the chain.

4 Tests

Each port carries a Fortran-only test program alongside the Catch2 suite: translation invariance, vanishing net force on a periodic cell, and analytic forces against central differences of the energy. The finite-difference check is what catches a mis-attributed gather term, since such an error can leave the energy correct.

Pinned reference energies from the pre-port kernels live in the Catch2 tests, at the tolerances the original suites used. eam_al is the exception on the digits, not on the geometry. EON r2549 potinit.f writes the aluminium parameters as default-real literals, so a double-precision build stores the single-precision rounding. The four-atom al_fcc cluster is pinned to that Fortran energy, -5.217864006173226 eV, tighter than the historical relative 1e-4. Keeping the extra printed digits moves the same geometry by 1.76e-6 eV.

4.1 Compilers

CI builds the kernels with the conda-forge gfortran (13/14) and, on Windows, with LLVM Flang. The port was additionally built and tested under gfortran 15.2.0, which passes all of it and reports diagnostics the older compilers stay quiet about, notably Unused parameter ... which has been explicitly imported and -Wcompare-reals. Both classes are worth reading rather than silencing: the first is dead code, and the second is fair warning unless the comparison really is asking “are these the same number I was handed before” – cache validity or a switch parameter – in which case say so in a comment at the site.

Flang on x86_64-pc-windows-msvc cannot lower a by-value BIND(C) derived type; it aborts rather than diagnosing. Interfaces that must build there pass such structs by pointer, which is why the vendored vesin interface binds vesin_neighbors_byref.