C and C++ API

Header: include/readcon-db.h.

#include "readcon-db.h"

size_t id;
rkrdb_open("/tmp/corpus", &id);
uint32_t n;
rkrdb_append_trajectory(id, 1, "run.con", &n);
rkrdb_append_trajectory_units(id, 1, "run.con",
    "{\"length\":\"A\",\"energy\":\"ev\"}", &n);
rkrdb_extend_trajectory_units(id, 1, "more.con",
    "{\"length\":\"A\",\"energy\":\"ev\"}", &n);
rkrdb_set_units(id, 1, "{\"length\":\"nm\",\"energy\":\"eV\"}", &n);
char ubuf[256];
rkrdb_frame_units(id, 1, 0, ubuf, sizeof ubuf);
double t[64]; uint32_t nt = 0;
rkrdb_h5md_times(id, 1, t, 64, &nt);
uint32_t nf = 0, na = 0;
rkrdb_h5md_shape(id, 1, &nf, &na);
double xyz[4096];
rkrdb_h5md_positions(id, 1, xyz, 4096, &nf, &na);
double edges[64], frc[4096], vel[4096];
rkrdb_h5md_edges(id, 1, edges, 64);
rkrdb_h5md_forces(id, 1, frc, 4096);
rkrdb_h5md_velocities(id, 1, vel, 4096);
int32_t z[256]; uint32_t nz = 0;
rkrdb_h5md_species(id, 1, z, 256, &nz);
uint32_t npos = 0, nfrc = 0, nvel = 0; uint8_t has_f = 0, has_v = 0;
rkrdb_get_positions(id, 1, 0, xyz, 256, &npos);
rkrdb_get_forces(id, 1, 0, frc, 256, &nfrc, &has_f);
rkrdb_get_velocities(id, 1, 0, vel, 256, &nvel, &has_v);
rkrdb_cook_frame(id, 1, 0);
rkrdb_recook_all(id);
rkrdb_select_basic(id, 1, "Cu", 1, 100000, 0);
/* Metadata filters: flags bit0=forces, bit1=velocities, bit2=energy present */
rkrdb_select_meta(id, /*traj*/ -1, "Cu", 1, 100000,
                  /*energy*/ -50.0, 0.0, /*use_energy_range*/ 1,
                  /*flags*/ 1u /* forces */, /*limit*/ 0);
int m = rkrdb_result_count(id);
uint64_t traj; uint32_t frame;
rkrdb_result_key(id, 0, &traj, &frame);
uint8_t hash[16];
rkrdb_frame_hash(id, traj, frame, hash);
rkrdb_select_hash(id, hash);
rkrdb_close(id);
rkrdb_open_readonly("/tmp/corpus", &id);
rkrdb_close(id);

Status: RKRDB_OK (0), RKRDB_ERR (-1), RKRDB_NOT_FOUND (-2), RKRDB_NULL (-3).

Link libreadcon_db from cargo build --release (cdylib / staticlib), or unpack the prebuilt readcon-db-clib-$VERSION-$target.tar.gz Release asset and pkg-config --libs readcon-db. See install.

C++ RAII:

#include "readcon-db.h"
readcon_db::Corpus db("/tmp/corpus");
readcon_db::Corpus ro("/tmp/corpus", /*readonly=*/true);
db.append_trajectory(1, "run.con", "{\"length\":\"A\",\"energy\":\"ev\"}");
db.extend_trajectory(1, "more.con", "{\"length\":\"A\",\"energy\":\"ev\"}");
db.set_units(1, "{\"length\":\"nm\",\"energy\":\"eV\"}");
char ubuf[256];
db.frame_units(1, 0, ubuf, sizeof ubuf);
uint32_t nf = 0, na = 0;
db.h5md_shape(1, &nf, &na);
double t[64];
db.h5md_times(1, t, 64);
double xyz[4096], edges[64], frc[4096], vel[4096];
db.h5md_positions(1, xyz, 4096, &nf, &na);
db.h5md_edges(1, edges, 64);
db.h5md_forces(1, frc, 4096);
db.h5md_velocities(1, vel, 4096);
int32_t z[256];
db.h5md_species(1, z, 256);
bool has_f = false, has_v = false;
db.get_positions(1, 0, xyz, 256);
db.get_forces(1, 0, frc, 256, &has_f);
db.get_velocities(1, 0, vel, 256, &has_v);
db.cook_frame(1, 0);
db.recook_all();
db.select_basic(1, "Cu", 1, 100000, 0);
db.select_meta(-1, "Cu", 1, 100000, -50.0, 0.0, 1, 1u, 0);

MPI: pack on root, Bcast on the caller communicator

Optional header include/readcon-db-mpi.h (not linked into libreadcon_db). Pass the communicator the host already uses. LAMMPS pair/fix code passes lmp->world or a sub-comm; a plugin must not call MPI_Init if the host already did.

#include "readcon-db-mpi.h"   /* needs <mpi.h> */

uint8_t *buf = NULL;
int nbytes = 0;
/* comm is lmp->world, a Dup, a Split — not substituted by this helper */
int st = rkrdb_bcast_packed_frame(comm, /*root*/ 0, "/scratch/corpus",
                                  /*traj*/ 1, /*frame*/ 0, &buf, &nbytes);
uint32_t natoms = 0;
double xyz[3 * 4096];
rkrdb_unpack_positions(buf, (size_t)nbytes, xyz, 4096, &natoms);
free(buf);

Many frames, one Bcast:

int st = rkrdb_bcast_packed_frames(comm, 0, dir, trajs, frames, nkeys, &buf, &nbytes);
uint32_t nfr = 0;
rkrdb_unpack_batch_nframes(buf, (size_t)nbytes, &nfr);
uint32_t natoms = 0;
double xyz[3 * 4096];
rkrdb_unpack_batch_item(buf, (size_t)nbytes, 0, xyz, 4096, &natoms);
free(buf);

C++ readcon_db::Corpus::pack_frame (buf == NULL size query) / pack_frames / unpack_batch_nframes / unpack_batch_item / unpack_positions. C rkrdb_pack_frame / rkrdb_pack_frames also size-query when buf == NULL. Fortran INTEGER comms: rkrdb_bcast_packed_frame_f and rkrdb_bcast_packed_frames_f (MPI_Comm_f2c of the MPI_Fint). Standalone driver: examples/mpi_bcast_frame.c (MPI_Initialized + MPI_Comm_dup).

Cooked SoA (RCSO)

See docs/orgmode/cooked-soa.org. Tier is opt-in; CON text remains authority. Bindings expose cook / delete / has-valid / positions / forces / velocities.