Module ffi 

C ABI for readcon-db (always linked into cdylib/staticlib).

Status codes mirror a small subset of readcon-core style (negative = error).

Constants

RKRDB_ABI_LAYOUT_REVISION

Layout revision for exported records and the handle contract.

RKRDB_ABI_VERSION_MAJOR

Breaking-change major for the public C ABI.

RKRDB_ABI_VERSION_MINOR

Additive-change minor for the public C ABI.

RKRDB_ERR

RKRDB_NOT_FOUND

RKRDB_NULL

RKRDB_OK

Functions

rkrdb_abi_compatible

Returns 1 when the loaded library can serve a caller built against the given RKRDB_ABI_VERSION_MAJOR, RKRDB_ABI_VERSION_MINOR and RKRDB_ABI_LAYOUT_REVISION, and 0 otherwise.

rkrdb_abi_layout_revision

Returns the layout revision of the loaded library’s C ABI.

rkrdb_abi_stamp

Returns the stable human-readable ABI negotiation stamp.

rkrdb_abi_version_major

Returns the breaking-change major of the loaded library’s C ABI.

rkrdb_abi_version_minor

Returns the additive-change minor of the loaded library’s C ABI.

rkrdb_append_trajectory^⚠

rkrdb_append_trajectory_frame^⚠

Ingest one parsed RKRConFrame* from libreadcon_core. Caller keeps the handle.

rkrdb_append_trajectory_str^⚠

Ingest CON text. source may be NULL ("memory").

rkrdb_append_trajectory_units^⚠

units_json is optional JSON ({"length":"A","energy":"ev"}). NULL stamps nothing.

rkrdb_close^⚠

rkrdb_cook_frame^⚠

Opt-in cook: derive RCSO into frames_soa from CON text in frames (CON remains authority).

rkrdb_delete_cooked^⚠

Drop cooked tier only; CON text and indexes unchanged.

rkrdb_extend_trajectory^⚠

rkrdb_extend_trajectory_frame^⚠

Extend an existing trajectory with one parsed frame, or create it. Returns the total frame count. Caller retains ownership of the frame.

rkrdb_extend_trajectory_units^⚠

Create the trajectory or append frames after the live count. units_json is optional; NULL stamps nothing on the new frames.

rkrdb_frame_formula^⚠

Canonical composition formula for a stored frame (same as core index_proj). Writes into buf (NUL-terminated). Returns RKRDB_OK, RKRDB_NOT_FOUND, RKRDB_ERR, or buffer size need as positive? On success returns RKRDB_OK; if buflen too small returns RKRDB_ERR and sets last_error.

rkrdb_frame_hash^⚠

Hash frame blob at key; writes 16 LE bytes to out_hash16.

rkrdb_frame_units^⚠

Write the frame units object as JSON into buf (NUL-terminated).

rkrdb_get_forces^⚠

Prefer cooked forces when present; writes N×3 doubles. Sets *out_has_forces 0/1.

rkrdb_get_frame^⚠

Parse stored CON text into a readcon-core RKRConFrame. Caller frees with free_rkr_frame from libreadcon_core. NULL on error.

rkrdb_get_frame_text^⚠

Copy frame CON text into buf (NUL-terminated). Returns length excluding NUL, or error code.

rkrdb_get_positions^⚠

Prefer cooked positions (no CON parse on hit); else parse CON. Writes *out_natoms * 3 doubles into out_xyz (row-major N×3). capacity_atoms is max N.

rkrdb_get_velocities^⚠

rkrdb_h5md_edges^⚠

rkrdb_h5md_forces^⚠

rkrdb_h5md_positions^⚠

Row-major [T][N][3] dest-Å positions from collect_h5md.

rkrdb_h5md_shape^⚠

nframes and natoms for one trajectory’s H5MD arrays.

rkrdb_h5md_species^⚠

Integer Z, length N (collect_h5md species_z).

rkrdb_h5md_times^⚠

Dest-ps times from collect_h5md (CON time or i * timestep, else index).

rkrdb_h5md_velocities^⚠

rkrdb_has_valid_cooked^⚠

Returns 1 if valid RCSO present, 0 if missing/corrupt, negative on error.

rkrdb_last_error^⚠

Last error message (thread-safe snapshot into caller buffer). Returns bytes written excluding NUL, or -1 if truncated / null.

rkrdb_open^⚠

Open corpus directory. On success writes opaque handle id to out_id (>=0). Returns RKRDB_OK or error code.

rkrdb_open_readonly^⚠

Open an existing corpus MDB_RDONLY. No mkdir, no write txn.

rkrdb_pack_frame^⚠

Pack one frame as RCSO bytes for MPI_Bcast on the caller communicator. buf == NULL returns the required size. Rank 0 of that comm calls this; other ranks never open the env.

rkrdb_pack_frames^⚠

Pack many frames as one RCSB envelope. buf == NULL returns the required size. Rank 0 of the caller comm packs; others never open the env.

rkrdb_recook_all^⚠

Cook every frame that has CON text (recook_all).

rkrdb_reindex^⚠

Rebuild secondary indexes from authoritative frame blobs.

rkrdb_result_count^⚠

rkrdb_result_key^⚠

Write traj_id and frame_idx for result index i (0-based).

rkrdb_select_basic^⚠

Select by required symbol (optional) and natoms range (use 0, UINT32_MAX for any). Results stored internally; use rkrdb_result_count / rkrdb_result_key.

rkrdb_select_campaign^⚠

Campaign select: composition formula (NUL-terminated, may be null), optional fmax window. use_fmax_range non-zero applies fmax_min/max. Flags: bit0 forces, bit1 velocities, bit2 energy. Element constraints: pass elem_sym + elem_count + elem_exact (1=exact, 0=min) for one pair (null skips).

rkrdb_select_hash^⚠

Select by exact xxHash3-128 (16 bytes LE).

rkrdb_select_meta^⚠

Metadata / section filters. Pass use_energy_range=0 to ignore energy bounds. Flags: bit0=require_forces, bit1=require_velocities, bit2=require_energy.

rkrdb_set_units^⚠

Convert stored numbers and rewrite CON units for every frame of traj_id.

rkrdb_set_velocity_time_unit^⚠

Override D10 for later rkrdb_h5md_* calls. The same unit is the clock when a v3.1 frame has no units.time. NULL clears the override.

rkrdb_unpack_batch_item^⚠

Unpack one RCSO item from an RCSB envelope into xyz. No corpus handle.

rkrdb_unpack_batch_nframes^⚠

Number of RCSO blobs in an RCSB envelope. No corpus handle.

rkrdb_unpack_positions^⚠

Unpack RCSO positions (no corpus handle — MPI worker side).

rkrdb_xxh3_128^⚠

xxHash3-128 of arbitrary bytes (LE 16 bytes) — for clients hashing off-line blobs.