Fortran API
===========

Module: ``fortran/ReadConDb/src/readcon_db.f90`` (``bind(C)`` to ``rkrdb_*``).

Link ``libreadcon_db`` from a checkout (``cargo build --release``) or from the prebuilt ``readcon-db-clib-$VERSION-$target.tar.gz`` Release asset (no local cargo). See :doc:`/howto/install` and ``fortran/README.md``.

.. code:: fortran

   use readcon_db
   integer(c_size_t) :: id
   integer(c_int) :: status
   integer(c_int32_t) :: n
   call db_open("/tmp/corpus"//c_null_char, id, status)
   call db_append(id, 1_c_int64_t, "run.con", n, status)
   call db_append_units(id, 1_c_int64_t, "run.con", &
     '{"length":"A","energy":"ev"}', n, status)
   call db_extend_units(id, 1_c_int64_t, "more.con", &
     '{"length":"angstrom","energy":"eV"}', n, status)
   call db_select_basic(id, 1_c_int64_t, "Cu", 1, 100000, 0, status)

See helpers ``db_open``, ``db_append``, ``db_select_basic``, ``db_result_count``, ``db_result_key``, ``db_frame_hash``, ``db_xxh3_128`` in the module source. Point your build system at ``include/`` for the C header if needed and ``target/release/`` (or the clib prefix ``lib/`` + ``PKG_CONFIG_PATH``). Campaign shard/drain/join is the CLI; a Fortran rank that owns one shard opens ``root/shard_XXXX`` with ``db_open`` (:doc:`/howto/campaign`).

MPI: pack on root, Bcast on the caller INTEGER communicator
-----------------------------------------------------------

Fortran MPI communicators are ``INTEGER``. Pass the handle the host already has (LAMMPS world / sub-comm). ``MPI_Bcast`` on that integer; do not substitute ``MPI_COMM_WORLD`` unless that is the handle the host passed. Do not ``MPI_Init`` if the host already did (``MPI_Initialized``).

.. code:: fortran

   use mpi
   use readcon_db
   ! comm is the INTEGER the host owns (LAMMPS world / a Dup)
   if (rank == 0) then
     call db_open_readonly(corpus, id, status)
     call db_pack_frame(id, traj, frame, buf, buflen, nbytes, status)
     call db_close(id, status)
   end if
   call MPI_Bcast(nbytes, 1, MPI_INTEGER, 0, comm, ierr)
   call MPI_Bcast(buf, nbytes, MPI_BYTE, 0, comm, ierr)
   call db_unpack_positions(buf, int(nbytes, c_size_t), xyz, cap, natoms, status)

C helpers from Fortran INTEGER: ``rkrdb_bcast_packed_frame_f`` and ``rkrdb_bcast_packed_frames_f`` in ``include/readcon-db-mpi.h`` (``MPI_Comm_f2c``). Batched helper packs an RCSB envelope on root and ``MPI_Bcast=s it on =comm``. Module ``db_pack_frame`` packs one RCSO blob (``buflen=0`` size-queries). ``db_pack_frames`` packs an RCSB envelope of many frames (``buflen=0`` size-queries). Unpack with ``db_unpack_batch_nframes`` and ``db_unpack_batch_item``. Standalone: ``examples/mpi_bcast_frame.f90``.

H5MD interchange and caller units: ``db_append_units``, ``db_set_units``, ``db_h5md_times``, ``db_h5md_shape``, ``db_h5md_positions`` (dest ``ps`` / Å). C symbols are ``rkrdb_append_trajectory_units``, ``rkrdb_extend_trajectory_units``, ``rkrdb_set_units``, ``rkrdb_frame_units``, ``rkrdb_h5md_times``, ``rkrdb_h5md_shape``, ``rkrdb_h5md_positions``, ``rkrdb_h5md_edges``, ``rkrdb_h5md_forces``, ``rkrdb_h5md_velocities``, ``rkrdb_h5md_species``. Fortran also has ``db_extend``, ``db_extend_units``, ``db_frame_units``, ``db_h5md_edges``, ``db_h5md_forces``, ``db_h5md_velocities``, ``db_h5md_species``, ``db_get_positions``, ``db_get_forces``, ``db_get_velocities``, ``db_cook_frame``, ``db_delete_cooked``, ``db_has_valid_cooked``, and ``db_recook_all``. Status constants include ``rkrdb_ok``, ``rkrdb_err``, and ``rkrdb_not_found``. CON line-2 ``units`` is the authority.

Cooked SoA (RCSO)
-----------------

See ``docs/orgmode/cooked-soa.org``. Tier is opt-in; CON text remains authority. Fortran exposes cook / delete / has-valid / ``db_get_positions`` / ``db_get_forces`` / ``db_get_velocities``.