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.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 callsMPI_Init— mpi4py and LAMMPS already started MPI.Rank
rootopens the corpus read-only and packs; every other rank oncommreceives 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.