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_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 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 at an explicit float precision. The writer default (6 decimals) is fine for structure handoff but lossy for ledgers that must round-trip f64 exactly (17 significant digits); the observation archive uses this path.

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 LMDB value into an owned String and folds bytes so the fair campaign pays for payload access—not merely mmap slice length. 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 recook_all(&self) -> Result<u32>

Cook all frames that have CON text; returns number of frames cooked.

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.

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. Missing units.time is CON default fs.