Generated Python API#

This page is generated from the docstrings on readcon_db. The narrative guide is Streaming append and random reads.

LMDB corpus of CON frames. Parsing and writing CON text is readcon.

class readcon_db.AtomOrderHit#

A stored frame that matches a query up to atom-id row order.

permutation[i] is the index in the query of the atom whose atom_id equals stored atom i.

frame_idx#

Frame index of the stored frame.

permutation#

Index in the query of each stored atom, in stored order.

query_index#

Zero-based index of the query frame in the text or file.

traj_id#

Trajectory id of the stored frame.

class readcon_db.ConCorpus(path, readonly=False)#

One LMDB corpus directory (data.mdb and lock.mdb).

append_trajectory(traj_id, path, units=None)#

Ingest a UTF-8 CON path as a new trajectory. Gzip and zstd are not decompressed.

append_trajectory_frames(traj_id, frames, source='memory')#

Ingest already-parsed readcon frames, committing 64 frames at a time.

The first group is append_trajectory_str. Each later group is extend_trajectory_str. A read_con result is written from the stored frames, so this does not build a Python frame per index. The return value is the number of frames in the trajectory after the last commit.

append_trajectory_str(traj_id, text, source='memory')#

Ingest CON text without a temp file.

cook_frame(traj_id, frame_idx)#

Opt-in RCSO cook; CON text in frames remains authority.

delete_cooked_soa(traj_id, frame_idx)#

Delete the cooked numeric copy of one frame. The CON text stays.

export_extxyz(keys, path, energy_key=None)#

Write the selected frames as extended XYZ. The destination must not exist.

export_h5md(traj_id, path, velocity_time_unit=None)#

Cooked H5MD interchange (h5py). CON text stays authority in the corpus. One [T][N][3] dataset per trajectory. Fixed N only.

velocity_time_unit overrides D10. Pass fs when a v1, v2, or v3.0 file really stored Angstrom/fs, or the natural unit (amu*angstrom^2/eV)^0.5 when a v3.1 file mislabeled that unit as fs. The same string is the clock unit when a v3.1 frame has time or timestep and no units.time. A present units.time still scales the clock. v1, v2, and v3.0 clocks with no units.time are fs.

extend_trajectory(traj_id, path, units=None)#

Append a UTF-8 CON path to a trajectory, or create it when it is absent. Gzip and zstd are not decompressed.

find_by_atom_order(text)#

Stored frames that match text up to atom-id row order.

find_by_atom_order_path(path)#

[find_by_atom_order](Self::find_by_atom_order) for a CON path.

find_by_hash(hash)#

First (traj_id, frame_idx) stored under this 16-byte hash.

frame_canonical_identity(traj_id, frame_idx)#

Recomputed canonical identity of one stored frame: (version, hash).

hash is 16 bytes, little-endian. This does not read the index.

frame_formula(traj_id, frame_idx)#

Composition string of one frame, for example Cu:2|H:2.

frame_hash(traj_id, frame_idx)#

xxHash3-128 of the stored CON text, 16 bytes, little-endian.

get_forces(traj_id, frame_idx)#

Forces of one frame, or None when that frame has no forces.

get_frame(traj_id, frame_idx)#

Random-access parse of one stored frame.

The frame is parsed in Rust. atoms[i] materialises that atom only, and xyz is the coordinate rows. This does not build a Python atom for every site and does not call read_con_string.

get_frame_text(traj_id, frame_idx)#

CON text of one stored frame.

get_frame_texts(keys)#

CON text of each (traj_id, frame_idx) key, in order.

get_positions(traj_id, frame_idx)#

Prefer frames_soa; fallback parse CON. List of (x,y,z).

get_units(traj_id, frame_idx)#

Units JSON stored on one frame, or None when the frame has no units object.

get_velocities(traj_id, frame_idx)#

Velocities of one frame, or None when that frame has no velocities.

has_valid_cooked_soa(traj_id, frame_idx)#

True when a cooked numeric copy of this frame is stored and decodes.

index_canonical_identity()#

Build the atom-id canonical index. Returns the number of frames indexed.

The xxHash3 content hash is unchanged. Run this again after the stored CON text is rewritten.

ingest_directory(dir, start_traj_id=None, units=None)#

Ingest every .con and .convel file in dir, numbered from start_traj_id.

pack_frame(traj_id, frame_idx)#

RCSO bytes for a unidirectional broadcast on the caller communicator. Rank 0 packs; workers call unpack_positions() on the copy.

pack_frames(keys)#

Many RCSO blobs in one RCSB envelope (one Bcast on the caller comm).

recook_all()#

Rewrite the cooked numeric copy of every frame. Returns the frame count.

reindex()#

Rebuild the secondary indexes from the stored CON text. Returns the frame count.

select(traj_id=None, symbol=None, natoms_min=0, natoms_max=Ellipsis, exact_hash=None, energy_min=None, energy_max=None, fmax_min=None, fmax_max=None, mass_min=None, mass_max=None, volume_min=None, volume_max=None, frame_index_min=None, frame_index_max=None, charge_min=None, charge_max=None, element_exact=None, element_min=None, formula=None, require_forces=False, require_velocities=False, require_energy=False, limit=None)#

Return (traj_id, frame_idx) pairs that match every predicate.

set_units(traj_id, units)#

Write caller units onto every frame of traj_id (canonical names in CON text).

A v3.1 frame with a clock or velocities and no units.time is an error. The missing time unit is not treated as fs. v1, v2, and v3.0 clocks with no units.time still convert as fs.

touch_trajectory(traj_id, n_frames)#

Materialize all frame blobs for traj_id in one LMDB read txn (full extract). Returns (total_bytes, payload_checksum) so callers cannot elide the copy.

static unpack_batch(buf)#

Positions from an RCSB batch packed by pack_frames, one list per frame.

static unpack_positions(buf)#

Positions from an RCSO blob packed by pack_frame.

static xxh3_128(data)#

xxHash3-128 of data, 16 bytes, little-endian.

class readcon_db.StoredAtom#

One atom built by indexing StoredAtoms.

symbol#
x#
y#
z#
class readcon_db.StoredAtoms#

Atoms of a stored frame. Indexing builds that one atom.

class readcon_db.StoredFrame#

One stored frame.

xyz is every coordinate row. atoms[i] builds that atom only. cell is the three box lengths and angles is the three box angles. This is not a readcon.ConFrame. get_frame_text plus readcon.read_con_string still returns one.

angles#

Three box angles, in degrees.

atoms#

Atom list. Indexing builds that atom only.

cell#

Three box lengths.

xyz#

Coordinate rows (x, y, z) for every atom.

readcon_db.bcast_packed_frame(comm, corpus_dir, traj_id, frame_idx, root=0)#

Unidirectional RCSO broadcast on the caller’s mpi4py communicator.

comm is an mpi4py.MPI.Comm (LAMMPS world/subcomm, Comm.Split, Comm.Dup). This function never names the process-wide world handle and never calls MPI_Init — mpi4py and LAMMPS already started MPI.

Rank root opens the corpus read-only and packs; every other rank on comm receives the bytes and never opens LMDB.

readcon_db.bcast_packed_frames(comm, corpus_dir, keys, root=0)#

Many frames, one collective on the caller mpi4py comm.

readcon_db.canonicalize_unit(expr)#

Canonical name for one unit expression. Aliases such as A and ev are accepted.

readcon_db.unit_conversion_factor(from_unit, to_unit)#

Metatomic-style conversion: value_to = factor * value_from.