================================= Fortran potentials: porting rules ================================= .. contents:: Why kernels are ported and why they gather are explained in :doc:`Fortran kernels: port, not wrap <../explanation/fortran-kernels>`. 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_.f90`` parameters, pure kernels, the energy/force driver. Pure Fortran, testable without the C++ stack. ``rgpot__capi.f90`` the ``bind(c)`` entries, each returning a status: ``rgpot__force_ws(handle, natoms, positions, cell, forces, energy)`` on a workspace from ``rgpot_fortran_workspace_new``, and the handle-free ``rgpot__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__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``. 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.