Fortran potentials: porting rules¶
Why kernels are ported and why they gather are explained in Fortran kernels: port, not wrap.
1 Rules¶
Module, ``implicit none``, ``private`` by default. Export the physics entry points
and the parameter type; nothing else.
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.
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.
Every dummy argument gets ``intent``, and arrays that cross into kernels are
contiguous where the caller can guarantee it.
No ``goto``, no arithmetic ``if``, no labelled ``do``. Structured control flow only.
cycle and exit replace jump targets.
Kernels are ``pure`` (or
elemental) wherever the algorithm allows, which is
also what do concurrent requires of anything it calls.
Failures return a status. No
stop, nowrite(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.
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>.f90parameters, pure kernels, the energy/force driver.
Pure Fortran, testable without the C++ stack.
rgpot_<pot>_capi.f90the
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_dependencythat 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.
4.2 Windows Flang + MSVC link¶
Flang emits COFF objects that MSVC link.exe can consume, but the flang-shipped
llvm-ar wraps them in a GNU archive.
link.exe then fails with LNK1107 when it opens the static library.
Force MSVC’s librarian (lib.exe) via AR=lib and the Meson native file
ci/gha/machines/win-flang-msvc.ini so the archives are COFF .lib and
link_whole into librgpot succeeds.
That is the supported Windows kernel path; do not disable Fortran to dodge the
archiver.