Python Reference¶

Create and return a new object. See help(type) for accurate signature.

Return repr(self).

Whether other describes the same cell within an absolute tolerance.

True iff every cell-matrix entry and origin component differ by at most tol (length units), the PBC flags are identical and both boxes agree on cell_defined. tol=0.0 is exact equality.

Raises:

Eight Cartesian cell corners.

Create a cubic simulation box.

Parameters:

Returns:

Examples:

>>> box = Box.cube(10.0)
>>> box.volume()
1000.0

Compute displacement vectors between two point sets.

Calculates xyzu2 - xyzu1 with optional minimum-image convention for periodic systems.

Parameters:

Returns:

Raises:

Minimum-image distance between two points.

Squared minimum-image distance between two points.

Row-wise minimum-image distances between equally sized point arrays.

Create a tight orthorhombic box around a point cloud.

Parameters:

Raises:

Integer periodic image flags for Cartesian coordinates.

The flags are int32, the schema's integer type for the ix/iy/iz columns.

Test whether each point lies inside the primary simulation cell.

Parameters:

Returns:

Raises:

Return a lattice vector by index.

Parameters:

Returns:

Raises:

Create an orthorhombic (rectangular) simulation box.

Parameters:

Returns:

Raises:

Examples:

>>> box = Box.ortho(np.array([10.0, 20.0, 30.0]))

All pairwise minimum-image displacement vectors (points2 - points1).

All pairwise minimum-image distances.

Minimum-image displacement from r1 to r2.

Convert fractional coordinates to Cartesian coordinates.

Parameters:

Returns:

Raises:

Convert Cartesian coordinates to fractional coordinates.

Parameters:

Returns:

Raises:

Return a box whose cell matrix is right-multiplied by transformation.

Reconstruct unwrapped coordinates from wrapped coordinates and images.

images is int32, the schema's integer type, so a frame's ix/iy/iz columns pass in without a cast.

Volume of the simulation box.

Returns:

Wrap coordinates into the primary simulation cell.

Applies periodic wrapping along axes where PBC is enabled.

Parameters:

Returns:

Raises:

Return bool(key in self).

Delete self[key].

Return self[key].

Implement iter(self).

Return len(self).

Create and return a new object. See help(type) for accurate signature.

Pickle by logical state: columns, validity masks, declared precisions, row count and structural shape.

Return repr(self).

Set self[key] to value.

Restore the state __reduce__ produced.

A deep copy: new buffers for every column, masks and shape included.

Writing into the copy's columns (through numpy) never reaches this block, nor the numpy array a column was built from.

Owned numpy array of one column, shape included.

Numeric, bool and complex columns are copies of the zero-copy view block[key] returns. A string column is already a copy under block[key] — a numpy str array of the column's shape — and this returns another one.

Parameters:

Raises:

Examples:

>>> names = block.copy_column("element")

Return the dtype string for the given column.

Returns:

Raises:

True when key exists and is f64.

True when key exists and is a signed integer column (i8, i16, i32, or i64).

True when key exists and is a string column.

True when key exists and is an unsigned integer column (u8, u16, u32, or u64).

Insert a numpy array (or list of strings) as a named column, at the width given.

The typed write: unlike block[key] = array it does not convert to the schema dtype (an i64 column stays i64; a narrow float is promoted to float64, the one float width); a dtype the schema refuses raises. If a column with the same key already exists it is replaced. The array length must match the row count of existing columns, or the block must be empty.

Parameters:

Raises:

Examples:

>>> b = Block()
>>> b.insert("x", np.zeros(10, dtype=np.float32))

Insert a named column together with a per-row validity mask.

The write side of :meth:validity. validity[i] is False where row i of array is a hole: the array still carries something there — whatever the caller put in, typically a zero — and the mask is the only place that says it is not a stated value.

An all-True mask states nothing :meth:insert does not, so it is dropped rather than stored and :meth:validity keeps answering None. Apart from the mask this is :meth:insert, with the same accepted dtypes and the same row-count rule.

Parameters:

Raises:

Examples:

>>> b = Block()
>>> b.insert_nullable("frag_id", np.array([7, 0, 0]), [True, False, False])
>>> b.validity("frag_id")
array([ True, False, False])

List all column names.

The declared precision of a column, or None when it declares none.

Raises:

Remove a column by name.

Raises:

Rename a column in place, keeping its data and validity mask.

Renaming is a write into new_key: when the Frame schema declares new_key with a different dtype, the column adopts it if the values survive the conversion (a file's int64 serial renamed onto id becomes uint), and the rename is refused otherwise.

Parameters:

Raises:

Axis-0 length of an empty block, or reshape every column.

Return a new Block with rows gathered at indices (preserves the column set, dtypes and validity masks).

Raises:

Declare (or, with None, withdraw) the precision of an f64 column: an absolute tolerance in the column's own units.

A record writer rounds the column to the largest power of two not above precision (ties to even) before storing it, so the stored values are within precision / 2 of these and compress several times better; the values in memory are not touched. The declaration is stored with the column (frame / system) or in the trajectory's schema, and reads back. A rename keeps it; replacing the column with another dtype, or removing it, drops it.

Parameters:

Raises:

Examples:

>>> b = molrs.Block({"x": np.array([0.12345, 1.5])})
>>> b.set_precision("x", 1e-3)
>>> b.precision("x")
0.001

Declare this block as N-dimensional. Product of shape must equal the row count when the block has columns.

Declare (or, with None, withdraw) that a uint64 column holds 0-based row indices into target: "<block>" of the same frame, or "/<section>/<block>" of a frame-shaped section of the record ("/frame/atoms").

The relation endpoints atomi … atoml reference atoms without one; a declaration overrides that, and names what any other referencing column (members.atom) points into. Subsetting and replicating renumber same-frame references; a *.mrec writer and reader refuse a reference that does not resolve.

Raises:

Attach a validity mask to an existing column, whatever its dtype.

mask[i] is False where row i holds no value. The mask replaces any the column had; an all-True mask clears it, so :meth:validity answers None afterwards.

Parameters:

Raises:

Return a new Block sorted by the key column (original unchanged).

Parameters:

Raises:

Row-wise union of parts: their rows in order, under the union of their columns (first-seen order).

A column a part lacks is filled with the dtype's default for that part's rows and marked null in the column's validity mask. A part's own masks travel with its rows. The parts are not modified.

Parameters:

Returns:

Raises:

Examples:

>>> s = Block.stack([Block({"x": [0.0]}), Block({"x": [1.0], "q": [2.0]})])
>>> s.validity("q")
array([False,  True])

The declared target of a column, or None.

Raises:

Every declared target, as {column: target}.

The validity mask of a column, or None when the column has no holes.

A block column is dense, so a component that only some rows carry — frag_id on a partially labelled molecule, h_count declared on one bracket atom — needs a second array saying which cells are real. None is the common case and means "every cell is a stated value"; it is not an all-True array, and a caller must not read a missing mask as "all holes". A key that names no column is a different question and raises KeyError, as indexing and :meth:dtype do — were it to answer None, a misspelled key would read as a dense column.

Parameters:

Returns:

Raises:

Return bool(key in self).

Delete self[key].

Return self[key].

Return len(self).

Create and return a new object. See help(type) for accurate signature.

Pickle by logical state: the blocks, the typed metadata and the box.

Return repr(self).

Set self[key] to value.

Restore the state __reduce__ produced.

Return a deep copy of this frame.

All blocks (new column buffers), the simulation box, and typed metadata are copied into a new, independent frame backed by its own store.

Returns:

List all block names.

Returns:

A new frame holding count copies of this one, concatenated block by block — the inverse of :meth:subset for count identical molecules.

Copy c of row r lands at c * nrows + r. Every endpoint of a relation block (bonds, angles, …, or any block carrying atomi..atoml) in copy c is offset by c times the row count of the block it indexes. Every other column — identifiers (id, mol_id) included — is copied verbatim; regenerate them if the copies need distinct labels. Validity masks travel; meta and the box are copied unchanged. This frame is never modified.

Parameters:

Returns:

Raises:

A new frame holding rows rows of block, with every relation block that indexes it cut down and renumbered.

Old row rows[k] becomes new row k; every column travels. A relation block whose endpoints index block (bonds, angles, …, or any block carrying atomi..atoml) keeps only the rows whose endpoints all lie in the selection, in their original order, with each endpoint rewritten. Every other block, the box and meta are copied unchanged. Values keep their units. This frame is never modified.

Parameters:

Returns:

Raises:

Judge this frame against the canonical Frame schema.

Delegates to molrs's Validator::canonical — dtype, shape, required columns, and endpoint ranges. Callers must not re-implement those checks in Python.

Raises:

Return bool(key in self).

Delete self[key].

Return self==value.

Return self>=value.

Return self[key].

Return self>value.

Return self|=value.

Implement iter(self).

Return self<=value.

Return len(self).

Return self<value.

Return self!=value.

Return self|value.

Return repr(self).

Return value|self.

Set self[key] to value.

A plain dict snapshot; mutating it does not touch the frame.

The dtype tag stored for key, or None when the key is absent.

The same snapshot with every dtype kept, as dict[str, MetaValue].

dict(meta) throws the tags away, which is the right default for reading; this is what a copy or a pickle has to carry instead.

Create and return a new object. See help(type) for accurate signature.

Return repr(self).

Return bool(key in self).

Return self==value.

Return self>=value.

Return self[key].

Return self>value.

Implement iter(self).

Return self<=value.

Return len(self).

Return self<value.

Return self!=value.

Pickle by content: the plain copy, rebuilt through _from_plain — a document has no constructor.

Return repr(self).

Deep plain decode. Nested documents become dicts, nested arrays lists.

Create and return a new object. See help(type) for accurate signature.

Add an angle over three atom handles (j central).

Add an atom with element symbol and optional coordinates. Returns its stable handle.

Add a bond between two atom handles (default order 1.0). Returns its handle.

Add a dihedral over four atom handles.

Add an improper over four atom handles.

Record a descriptor on the (anchor, handle) valence; the ports relation kind is registered on first use.

Parameters:

Returns:

Raises:

Add a relation of kind over node handles, returning its handle.

Zero-copy adopt: move other's graph storage into self, leaving other empty. Handles in the adopted graph stay valid (the whole generational slotmap is moved, not reindexed). For taking ownership of a graph produced elsewhere without a per-node copy. Defined per leaf so it swaps the leaf's own backing store. Views of either graph taken before are stale afterwards.

The bond's localized (Kekulé) bond number; 0 when it has none.

The bond's chemical class code; 0 when it has none.

Deterministic canonical atom ordering (a list of atom handles) from the WL refinement, so two isomorphic molecules line up node-by-node.

Mass-weighted centre of every atom.

R = sum_i m_i r_i / sum_i m_i over all atoms, reading positions from x / y / z (Å) and masses from mass (g/mol). No periodic imaging: a molecule split across a box face must be unwrapped first (:meth:Box.unwrap).

Returns:

Raises:

The component column key, aligned to row order (length == n_nodes), as a numpy array of the column's own element type.

A f64 column is a zero-copy view that writes through to the world (col[i] = v updates the entity at row i); i32, bool and str columns are copied. The view borrows the world's storage; structural mutation (spawn/despawn) may reallocate or reorder the column and invalidate an outstanding view — re-fetch after such ops.

Every entity must carry the component: a column with a hole is a KeyError naming how many entities lack it, never a silently zero-filled array. Use :meth:validity to find the holes and :meth:get for entity-wise reads.

Names of every component column registered on the node table (a component set on at least one entity), in no particular order.

Return an independent deep copy of this Atomistic, with a copy of its :attr:props.

Handles are preserved (same generational keys as in self).

Add an angle a–b–c (b the vertex) and return its view.

Raises:

Add an atom carrying the fields of mapping and attrs (a None value is skipped) and return its view.

Raises:

Add a single bond between two atoms of this graph and return its view.

Routes through the native writer, so the bond carries both bond facts — bond_type = 1 and bond_number = 1 — before attrs are applied.

Raises:

Add a proper dihedral a–b–c–d and return its view.

Raises:

Add an improper over a, b, c, d in its style's slot order and return its view.

Raises:

Record a bonding descriptor on the (anchor, handle_atom) valence and return the port's view.

Routes through the native writer, which is where the validation lives: the anchor–handle bond check, the one-port-per-valence check, the glyph parse and the order check.

Parameters:

Raises:

Add a virtual site — an atom with a vsite field naming its kind — and return its view, of class kind (VirtualSite by default, DrudeParticle or MasslessSite). An explicit vsite in attrs wins over the one kind implies.

Raises:

Remove each of atoms and every relation touching it. Their views go stale: a read raises.

Raises:

Clear entity h's component key (no-op if absent).

key is a :class:molrs.keys.Key or str.

Clear property key on relation rh of kind (no-op if absent).

Remove an entity (cascades incident relations). Errors if stale.

All live entity handles, in row order.

Radius ball around centers over the bond graph.

When regenerate_topology is true, only bonds are copied and angles/dihedrals are perceived on the ball. When false, higher-order terms fully inside the ball are copied from the parent.

max_ring_size closes the ball on ring systems: a ring of at most that many atoms which the radius only partly reaches comes along whole, together with everything fused or bridged to it. A cut ring is not a smaller molecule — ring perception, and with it aromaticity and every ring-aware atom type, reads the remainder as something else. The added atoms lie beyond radius, so they arrive as context: their hops are larger than the radius asked for.

The bound is not a tuning knob, it is the claim's domain. Cutting a benzene changes the chemistry; cutting a 5000-membered macrocycle changes nothing any typifier can see, while closing on it would drag the whole loop into a ball that asked for nine atoms. Pass the largest ring your typifier can actually distinguish. None disables closure; the cost then, and with a bound, follows the ball and its neighbourhood — never the size of the parent graph.

The unit instance node came from, or None.

Build an Atomistic from a [Frame] (registers the chemistry kinds, then reads the relation blocks). A leaf constructor, not a conversion.

Perceive angle, dihedral and improper relations from the bond graph.

Angles are 2-edge paths i-j-k and proper dihedrals 3-edge paths i-j-k-l over the bonds (graph-theory via the native Topology-backed Topology). Impropers are the molecular-mechanics reading: one [centre, i, j, k] quartet per atom with exactly three neighbours, centre first, peripherals sorted — not every 3-combination at every centre of degree >= 3, which would hand an sp3 carbon four quartets. Whether a trivalent centre is planar enough to carry the term is force-field data, not a graph property, so every one is emitted.

Idempotent; clear_existing wipes existing relations of the requested kinds first. Returns (n_angles_added, n_dihedrals_added, n_impropers_added).

Read entity h's component key (None if absent).

key is a :class:molrs.keys.Key or str.

Read a property of relation rh of kind (None if absent).

Whether entity h has component key.

key is a :class:molrs.keys.Key or str.

Whether h is a live entity handle.

Relations of kind incident to node nh, as (relation_handle, other_node_handle) pairs, via the adjacency index (O(degree)). Only arity-2 kinds are tracked in adjacency.

Induced subgraph on an explicit list of atom handles.

Returns (subgraph, {parent_handle: new_handle}). Stale handles raise.

Propagate each frag_id to the unlabelled degree-1 nodes hanging off a labelled one (one pass); returns how many were labelled. The relabel step after a conformer added hydrogens.

Whether self and other are isomorphic as labeled molecular graphs.

Fixed endpoint count for a registered relation kind.

Names of all registered relation kinds.

Join port a to port b with a new anchor–anchor bond.

Both leaving groups are removed, their partial charge (e) folds onto the anchors, and the anchors are bonded with the port order. No coordinate moves.

Returns:

Raises:

Atom count of the largest fused/bridged ring system (naphthalene → 10).

Acyclic molecules → 0. Pure structure fact for molpy region typing.

Structural merge of other into self.

Consumes other's storage (other is left empty). Every node handle from other is remapped; returns {old_handle: new_handle}.

Raises:

Number of relations of kind.

Component keys currently set on entity h, in column order.

Register a relation kind (idempotent for a matching arity).

Live relation handles of kind, in row order.

Authoritative enumeration — callers must not probe opaque handle ranges. Returns an empty list for a registered kind with no relations; errors only if kind is unregistered.

Property keys currently set on relation rh of kind.

Endpoint node handles of relation rh of kind.

Remove an atom by handle, cascading incident bonds / angles / dihedrals / impropers. Errors if the handle is stale.

Remove a bond by handle (a relation handle from :meth:add_bond).

Remove each of links (relation views of this graph).

Raises:

Remove relation rh of kind.

Grow this graph by one rigid copy of template per transform.

Copy c is template moved by rotations[c] @ r + translations[c] and every node of it is stamped frag_id = frag_ids[c]. Every relation kind of template is copied with it. Column-wise and atomic: on an error this graph is unchanged. template is never mutated. The GIL is released while the copies are written.

Parameters:

Returns:

Raises:

Rotate every node that has coordinates by angle radians about axis, pivoting on about (default: the origin). Returns this graph, so moves chain.

Scale every node that has coordinates by a per-axis factor about about (default: the origin). Pass [s, s, s] for a uniform scale. Returns this graph, so moves chain.

Set entity h's component key (value is int|float|str).

key is a :class:molrs.keys.Key or str.

Set a bond's chemical class and its localized bond number.

The two are set together because they are only meaningful together: a class without a number leaves the bond un-standardized, and a number without a class leaves a consumer no way to tell aromatic from double.

Parameters:

Set a plain (non-aromatic) bond, whose class implies its number.

Aromatic (4) implies no number — the phase is a Kekulé assignment's to decide — so it goes through :meth:set_bond_class.

Record the unit instance node came from, under frag_id.

Raises:

Set a property on relation rh of kind.

Spawn a new entity, returning its stable handle.

Isomorphism-invariant Weisfeiler–Lehman structural hash (int).

A stable, reproducible dedup key over the molecular graph (element / charge / aromatic node labels, bond-order edge labels): identical for a node-permuted copy, sensitive to any label or connectivity change. Reproducible across runs and processes.

Export to a tabular [Frame] (atoms / bonds / angles / dihedrals / impropers blocks). Leaf-owned — self.inner.to_frame(), zero conversion.

Raises:

Single-source shortest-path (BFS) distances over the bond graph from source (a node handle), as (node_handle, hops) pairs for every atom reachable from source (including source itself at distance 0). Unreachable atoms (a different connected component) are omitted; an unknown source handle yields an empty list.

Translate every node that has coordinates by delta. Returns this graph, so moves chain.

Validity mask (numpy bool array, copied) of component column key, aligned to row order. True where the entity at that row has the component set.

key is a :class:molrs.keys.Key or str.

Create and return a new object. See help(type) for accurate signature.

Add a bead with bead_type and optional coordinates. Returns its handle.

Add a CG bond between two bead handles. Returns its handle.

Record a descriptor on the (anchor, handle) valence; the ports relation kind is registered on first use.

Parameters:

Returns:

Raises:

Add a relation of kind over node handles, returning its handle.

Zero-copy adopt: move other's graph storage into self, leaving other empty. Handles in the adopted graph stay valid (the whole generational slotmap is moved, not reindexed). For taking ownership of a graph produced elsewhere without a per-node copy. Defined per leaf so it swaps the leaf's own backing store. Views of either graph taken before are stale afterwards.

The site axes of beads, one row per listed bead, in the listed order. A site from Coarsener.coarsen carries the vector from the first bead of its group to the site; a one-bead site's axis is zero.

Parameters:

Returns:

Raises:

The atom handles a bead groups (empty if none recorded).

The bead_type of each of beads, in the listed order (a bead listed twice appears twice).

Parameters:

Returns:

Raises:

Bead handles whose membership includes atom, in bead-handle order.

Deterministic canonical bead ordering (a list of bead handles) from the WL refinement.

Mass-weighted centre of the bead group group.

R = sum_i m_i r_i / sum_i m_i over the listed beads, reading positions from x / y / z (Å) and masses from mass (g/mol). A bead listed twice counts twice. :meth:add_bead writes no mass, so give each bead one (or read it from a frame's mass column with :meth:from_frame) before asking for a centre.

No periodic imaging: the group's coordinates are used as stored. A group that straddles a box face must be unwrapped first (:meth:Box.unwrap), otherwise the centre lands between the images.

Parameters:

Returns:

Raises:

The component column key, aligned to row order (length == n_nodes), as a numpy array of the column's own element type.

A f64 column is a zero-copy view that writes through to the world (col[i] = v updates the entity at row i); i32, bool and str columns are copied. The view borrows the world's storage; structural mutation (spawn/despawn) may reallocate or reorder the column and invalidate an outstanding view — re-fetch after such ops.

Every entity must carry the component: a column with a hole is a KeyError naming how many entities lack it, never a silently zero-filled array. Use :meth:validity to find the holes and :meth:get for entity-wise reads.

Names of every component column registered on the node table (a component set on at least one entity), in no particular order.

Independent deep copy, with a copy of its :attr:props and the same member world. Handles are preserved.

Add a bead carrying the fields of mapping and attrs (a None value is skipped) and return its view. An atoms field is the bead's membership: atom views of one source graph.

Raises:

Add a CG bond between two beads of this graph and return its view.

Raises:

Clear entity h's component key (no-op if absent).

key is a :class:molrs.keys.Key or str.

Clear property key on relation rh of kind (no-op if absent).

Remove an entity (cascades incident relations). Errors if stale.

All live entity handles, in row order.

Radius ball around bead centers over CG bonds.

The unit instance node came from, or None.

Build a CoarseGrain from a frame holding one molecule.

Every atoms row becomes a bead and every bonds row a CG bond (atomi / atomj are 0-based atoms rows); a members block, when present, is read back as bead membership. bead_type comes from the first column present: bead_type, then type, then type_id (rendered in decimal). Other blocks are ignored.

Parameters:

Returns:

Raises:

Read entity h's component key (None if absent).

key is a :class:molrs.keys.Key or str.

Read a property of relation rh of kind (None if absent).

Whether entity h has component key.

key is a :class:molrs.keys.Key or str.

Whether h is a live entity handle.

Relations of kind incident to node nh, as (relation_handle, other_node_handle) pairs, via the adjacency index (O(degree)). Only arity-2 kinds are tracked in adjacency.

Induced subgraph on bead handles. Returns (subgraph, node_map).

Propagate each frag_id to the unlabelled degree-1 nodes hanging off a labelled one (one pass); returns how many were labelled. The relabel step after a conformer added hydrogens.

Whether self and other are isomorphic as labeled bead graphs.

Fixed endpoint count for a registered relation kind.

Names of all registered relation kinds.

Join port a to port b with a new anchor–anchor bond.

Both leaving groups are removed, their partial charge (e) folds onto the anchors, and the anchors are bonded with the port order. No coordinate moves.

Returns:

Raises:

Structural merge of other into self; other is emptied. Returns {old_handle: new_handle}.

Raises:

Number of relations of kind.

Component keys currently set on entity h, in column order.

The positions of beads, one row per listed bead, in the listed order (a bead listed twice appears twice).

Parameters:

Returns:

Raises:

Register a relation kind (idempotent for a matching arity).

Live relation handles of kind, in row order.

Authoritative enumeration — callers must not probe opaque handle ranges. Returns an empty list for a registered kind with no relations; errors only if kind is unregistered.

Property keys currently set on relation rh of kind.

Endpoint node handles of relation rh of kind.

Remove each of links (relation views of this graph).

Raises:

Remove relation rh of kind.

Grow this graph by one rigid copy of template per transform.

Copy c is template moved by rotations[c] @ r + translations[c] and every node of it is stamped frag_id = frag_ids[c]. Every relation kind of template is copied with it. Column-wise and atomic: on an error this graph is unchanged. template is never mutated. The GIL is released while the copies are written.

Parameters:

Returns:

Raises:

Rotate every node that has coordinates by angle radians about axis, pivoting on about (default: the origin). Returns this graph, so moves chain.