Struct ConCorpus 

pub struct ConCorpus { /* private fields */ }

Implementations

impl ConCorpus

pub fn open(path: impl AsRef<Path>) -> Result<Self>

pub fn open_existing(path: impl AsRef<Path>) -> Result<Self>

Write-open an existing corpus. Does not mkdir or mint data.mdb.

pub fn open_with_map_size( path: impl AsRef<Path>, map_size: usize, ) -> Result<Self>

Open or create a writable corpus with an explicit LMDB map size in bytes, overriding [MAP_SIZE_ENV] and [DEFAULT_MAP_SIZE]. The map is still at least twice an existing data.mdb.

pub fn map_size(&self) -> usize

Current LMDB map size in bytes.

pub fn reserve_map(&self, extra_bytes: usize) -> Result<usize>

Grow the map so at least extra_bytes fit beyond the pages already used. Never shrinks. Returns the resulting map size.

The write side of the transaction lock is held across the resize, so no transaction from this process is open. The MPI ingest calls it on each writer rank with the input size before its first batch.

pub fn open_readonly(path: impl AsRef<Path>) -> Result<Self>

Open an existing corpus with MDB_RDONLY. No mkdir, no write txn. MPI workers that only read should use this — or, better, rank 0 of the caller communicator Self::pack_frame and MPI_Bcast on that same handle so other ranks never open LMDB. Never initialize MPI here; the host (LAMMPS, mpi4py) already did.

pub fn pack_frame(&self, key: FrameKey) -> Result<Vec<u8>>

RCSO bytes for a unidirectional broadcast on the caller communicator (rank 0 of that comm packs, others unpack). Prefers a valid cooked blob; otherwise encodes from the CON text.

pub fn pack_frames(&self, keys: &[FrameKey]) -> Result<Vec<u8>>

Many RCSO blobs in one RCSB envelope for a single Bcast on the caller comm.

pub fn path(&self) -> &Path

pub fn close(self)

Wait until this process’s LMDB env is gone. Required before open_readonly on the same path in the same process.

pub fn snapshot_to(&self, dest_dir: impl AsRef<Path>) -> Result<()>

Compact snapshot of data.mdb only. No lockfile. Creates dest_dir if needed; refuses if dest_dir/data.mdb already exists.

pub fn list_frame_keys(&self) -> Result<Vec<FrameKey>>

All frame keys in this env (for compaction / export pipelines).

pub fn export_frame_blob(&self, key: FrameKey) -> Result<String>

Copy one frame blob+indexes from this corpus into dst (same FrameKey). Used by join compaction; prepare keys outside dst exclusive section via append path on text.

pub fn set_compress_frames(&self, compress: bool)

When false, later ingests store raw UTF-8. Reads of either form are unchanged.

pub fn canonical_dump(&self) -> Result<Vec<u8>>

Every table in LMDB key order as length-prefixed (name, key, value) records. LMDB page layout can differ between equal corpora; this dump cannot, so its digest is the determinism check for parallel ingest.

pub fn append_trajectory_path( &self, traj_id: TrajId, file: impl AsRef<Path>, ) -> Result<u32>

pub fn append_trajectory_path_units( &self, traj_id: TrajId, file: impl AsRef<Path>, units: Option<Value>, ) -> Result<u32>

Ingest a CON path and stamp canonical units into every frame’s metadata.

pub fn set_trajectory_units(&self, traj_id: TrajId, units: Value) -> Result<u32>

Rewrite every frame of traj_id into units. Stored numbers are converted so the new label matches the values (not a silent relabel).

pub fn frame_units(&self, key: FrameKey) -> Result<Option<Value>>

Units object on one frame (after canonicalize on write).

pub fn append_trajectory_str( &self, traj_id: TrajId, file_contents: &str, source: impl Into<String>, ) -> Result<u32>

pub fn append_trajectory_frames( &self, traj_id: TrajId, frames: &[ConFrame], source: impl Into<String>, ) -> Result<u32>

Ingest already-parsed frames (chemfiles / builder path). Serialize in prepare, not under write_txn.

pub fn append_trajectory_frames_with_precision( &self, traj_id: TrajId, frames: &[ConFrame], source: impl Into<String>, precision: usize, ) -> Result<u32>

Self::append_trajectory_frames with an explicit number of decimal places. Use Self::append_trajectory_frames_with_float_format and FloatFormat::RoundTrip for exact binary64 observation storage.

pub fn append_trajectory_frames_with_float_format( &self, traj_id: TrajId, frames: &[ConFrame], source: impl Into<String>, float_format: FloatFormat, ) -> Result<u32>

Append frames using the selected CON numeric representation.

pub fn extend_trajectory_frames( &self, traj_id: TrajId, frames: &[ConFrame], source_hint: impl Into<String>, ) -> Result<u32>

Append frames to an existing trajectory (or create it). Returns new total frame count. Concurrent extend of the same traj_id is rejected if n_frames moved (TOCTOU guard).

pub fn extend_trajectory_path( &self, traj_id: TrajId, file: impl AsRef<Path>, ) -> Result<u32>

Self::extend_trajectory_frames from a CON path: create the trajectory or append frames after the live count.

pub fn extend_trajectory_path_units( &self, traj_id: TrajId, file: impl AsRef<Path>, units: Option<Value>, ) -> Result<u32>

Append a CON path, optionally stamping canonical units on the new frames.

pub fn reindex(&self) -> Result<u32>

Rebuild all secondary indexes from authoritative frames blobs (schema upgrade path).

idx_topo is rebuilt from topo_by_frame only when every annotated trajectory records the same cutoff/graph/hops/method. Mixed parameters return an error without writing. Unannotated corpora leave idx_topo empty. The engine binary is not required for a matching rebuild.

pub fn traj_meta(&self, traj_id: TrajId) -> Result<Option<TrajMeta>>

pub fn frame_topo_key(&self, key: FrameKey) -> Result<Option<String>>

Stored topology HEX for one frame, if annotated.

pub fn annotate_topology(&self, opts: AnnotateTopologyOpts) -> Result<u32>

Populate idx_topo / topo_by_frame by shelling out to seams fingerprint FILE --format json.

Cutoff is required. Default graph is cutoff, hops is 2. The binary comes from opts.seams, SEAMS, or PATH. A recorded method that disagrees with this run is refused so methods are never mixed.

pub fn find_by_topology_path( &self, file: impl AsRef<Path>, ) -> Result<Vec<FrameKey>>

Fingerprint file with the recorded corpus parameters and look up idx_topo. Errors if nothing is annotated or if seams is missing.

pub fn find_by_topology_text(&self, text: &str) -> Result<Vec<FrameKey>>

Fingerprint CON text with the recorded corpus parameters.

pub fn get_frame_text(&self, key: FrameKey) -> Result<String>

pub fn get_frame_texts(&self, keys: &[FrameKey]) -> Result<Vec<String>>

Batch point-gets under one read transaction (extract / multi-reader hot path).

pub fn touch_trajectory_blobs( &self, traj_id: TrajId, n_frames: u32, ) -> Result<(u64, u64)>

Materialize every frame blob for traj_id in one read txn (full extract hot path).

Copies each frame’s CON text (decompressing a tagged value) into an owned String and folds those bytes so the campaign pays for the payload. Returns (sum of lengths, byte checksum) for observability.

pub fn get_frame(&self, key: FrameKey) -> Result<ConFrame>

pub fn get_cooked_soa_bytes(&self, key: FrameKey) -> Result<Option<Vec<u8>>>

Raw optional cooked SoA bytes for key (None if never cooked). Does not read frames (CON text).

pub fn has_valid_cooked_soa(&self, key: FrameKey) -> Result<bool>

True if a valid RCSO blob is stored (decode succeeds). Missing/corrupt → false. Authority APIs must not use this flag to skip CON text.

pub fn get_cooked_soa(&self, key: FrameKey) -> Result<Option<CookedSoa>>

Decode cooked SoA if present and valid; None if missing or corrupt (CON text unchanged). Reads only frames_soa—no CON parse.

pub fn get_positions(&self, key: FrameKey) -> Result<Vec<[f64; 3]>>

Prefer valid cooked SoA (no CON parse on hit); otherwise parse CON text in frames. RCSO is not fully equivalent to CON (no symbols/metadata/exact bytes)—do not omit frames.

pub fn get_forces(&self, key: FrameKey) -> Result<Option<Vec<[f64; 3]>>>

Prefer cooked forces when the RCSO flag block is present (no CON parse on hit); else parse CON (None if no forces on frame).

pub fn get_velocities(&self, key: FrameKey) -> Result<Option<Vec<[f64; 3]>>>

Prefer cooked velocities when present; else parse CON.

pub fn cook_frame(&self, key: FrameKey) -> Result<usize>

Cook one frame from authoritative CON text (overwrite existing cooked entry).

pub fn migrate_frames(&self) -> Result<u32>

Rewrite each trajectory’s frame values to the current codec.

Legacy UTF-8 and per-frame zstd become one shared zstd group when that group is shorter. A second call sees those bytes and writes nothing, so a group is not wrapped in another zstd frame. Hashes stay on the UTF-8. This does not cook frames_soa.

pub fn recook_all(&self) -> Result<u32>

Cook all frames that have CON text; returns number of frames cooked. Not called by ingest or Self::migrate_frames.

pub fn delete_cooked_soa(&self, key: FrameKey) -> Result<()>

Drop cooked tier for one key (CON text and indexes untouched).

pub fn append_trajectory_path_cook( &self, traj_id: TrajId, file: impl AsRef<Path>, cook: bool, ) -> Result<u32>

Ingest path with optional cook-on-write (still stores CON text as authority).

pub fn frame_hash(&self, key: FrameKey) -> Result<ContentHash>

pub fn find_by_hash(&self, hash: ContentHash) -> Result<Option<FrameKey>>

pub fn hash_con_text(text: &str) -> Result<ContentHash>

pub fn frame_formula(&self, key: FrameKey) -> Result<String>

Canonical formula for a stored frame (decode once).

pub fn select(&self, sel: &Select) -> Result<Vec<FrameKey>>

pub fn export_extxyz( &self, keys: &[FrameKey], path: impl AsRef<Path>, energy_key: &str, ) -> Result<usize>

pub fn ingest_directory( &self, dir: impl AsRef<Path>, start_traj_id: TrajId, ) -> Result<Vec<(TrajId, u32, String)>>

pub fn ingest_directory_units( &self, dir: impl AsRef<Path>, start_traj_id: TrajId, units: Option<Value>, ) -> Result<Vec<(TrajId, u32, String)>>

Ingest every .con/.convel in dir, optionally stamping units.

Files are sorted by path. Parse runs in chunks whose bounds depend only on the file count. Commits run in that same order. RAYON_NUM_THREADS sets the worker count (default: available parallelism).

pub fn ingest_directory_units_nthreads( &self, dir: impl AsRef<Path>, start_traj_id: TrajId, units: Option<Value>, threads: usize, ) -> Result<Vec<(TrajId, u32, String)>>

[ingest_directory_units] with an explicit worker count.

pub fn sorted_logical_dump(&self) -> Result<Vec<String>>

Sorted database key value lines for every logical entry. Values are hex so the dump does not depend on LMDB page layout.

pub fn unique_frame_keys(&self, sel: &Select) -> Result<Vec<FrameKey>>

impl ConCorpus

pub fn collect_h5md(&self, traj_id: u64) -> Result<H5mdArrays>

Collect one trajectory as H5MD-shaped arrays (fixed N). Times are dest ps: CON header.time(), or i * timestep, else the frame index. A v3.1 clock with no units.time is an error unless H5mdCollectOpts::velocity_time_unit is set. v1, v2, and v3.0 clocks with no units.time use fs. Velocities use D10 (see H5mdCollectOpts).

pub fn collect_h5md_with( &self, traj_id: u64, opts: &H5mdCollectOpts, ) -> Result<H5mdArrays>

[collect_h5md] with an explicit velocity time override.