Module archive 

Asynchronous observation archive over a ConCorpus.

Active-learning consumers (GP surrogates pruning their training sets) need a durable record of every configuration an expensive oracle evaluated: the active set is a view, the archive is the ledger. This module owns that contract once, behind a C ABI, so every consumer shares one implementation instead of re-deriving frame serialization, threading, and read-back ordering.

Writes follow the async-logger shape: ObservationArchive::append copies the row into a channel and returns; a dedicated writer thread drains the channel and commits each row as a single-frame trajectory built natively with ConFrameBuilder (no temporary files, no serialization on the caller thread). Disk-side failures are counted, never raised into the caller. Readers synchronize with ObservationArchive::flush; LMDB’s MVCC makes the read snapshot safe against the concurrent writer.

Atom ordering: CON groups atoms by type, so stored frames are a permutation of the caller’s order. ObservationArchive::fetch inverts that permutation through the stored atom_ids and returns rows in the caller’s original order — the property a training-set consumer actually needs.

Structs

ObservationArchive

Fixed-composition archive of oracle evaluations.

Functions

rkrdb_archive_append^⚠

Enqueue one evaluation: flat 3 * natoms position and force buffers in caller order plus the total energy. Non-blocking; disk failures are counted via rkrdb_archive_dropped.

rkrdb_archive_appended^⚠

Rows accepted by append, including any still queued (prior runs included). Key cache refreshes on this; fetch bounds on rkrdb_archive_count after a flush.

rkrdb_archive_close^⚠

Drain the writer, close the corpus, release the handle.

rkrdb_archive_count^⚠

Rows committed to the corpus (including prior runs).

rkrdb_archive_dropped^⚠

Rows the writer thread could not persist.

rkrdb_archive_fetch^⚠

Fetch committed row index in the caller’s original atom order. positions and forces receive 3 * natoms doubles; out_energy the total energy. Flush first for a complete snapshot.

rkrdb_archive_flush^⚠

Block until every enqueued row is committed or counted dropped.

rkrdb_archive_open^⚠

Open (or create) an observation archive at dir for a fixed composition: z is the per-atom atomic-number list in caller order (natoms entries), cell3 the three orthorhombic box lengths. Writes the opaque handle to out_id.