Python Reference¶

Return bool(key in self).

Delete self[key].

Return self[key].

Implement iter(self).

Return len(self).

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.

Return the dtype string for the given column.

Returns:

Raises:

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.

validity optionally attaches a per-row mask — the write side of :meth:validity. validity[i] is False where row i of values is a hole: the array still carries something there (typically a zero) and the mask is the only place that says it is not a stated value. An all-True mask states nothing and is dropped, so :meth:validity keeps answering None.

Parameters:

Raises:

Examples:

>>> b = Block()
>>> b.insert("x", np.zeros(3, dtype=np.float32))
>>> b.insert("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:

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.

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.core.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).

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.

The frames joined end to end, block by block — :meth:replicate for parts that differ.

Every block name any part has becomes one block of the parts' rows in order; a column one part lacks is filled for its rows and marked null. Every endpoint of a relation block (bonds, angles, …, or any block carrying atomi..atoml) in part p is offset by the rows the block it indexes has in the parts before it. Every other column — id / mol_id included — is copied verbatim. meta and the box are the first part's. No part is modified.

Parameters:

Returns:

Raises:

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.

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.

Return self[key].

Return len(self).

Return repr(self).

A new trajectory of func(frame) for every frame, keeping this one's step / time labels. This trajectory is not modified.

Raises:

Return repr(self).

copy.copy(graph): an independent copy with a copy of its :attr:props. Handles are preserved (view.handle of a node names the same node in the copy).

copy.deepcopy(graph): the same independent copy as copy.copy — a graph holds no Python objects to recurse into.

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

Raises:

Add an atom carrying props and return its view.

Parameters:

Returns:

Raises:

Add a bond between atoms a and b of this graph, carrying props, and return its view.

Raises:

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

Raises:

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

Raises:

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

Parameters:

Raises:

Add a row to the term block block (cmaps, constraints, drudes, exclusions, pairs, virtual_sites, a block declared with :meth:declare_term, or any block this graph already holds) over atoms, carrying props, and return its view.

The block's arity is the one this graph registered for it, else the Frame schema's; the block is registered on first use.

Raises:

The bond joining atoms a and b, or None.

Deterministic canonical atom order from canonical labeling, so two isomorphic graphs line up node by node.

Mass-weighted centre (Å) of atoms (views or a Refs).

R = sum_i m_i r_i / sum_i m_i, reading positions from x / y / z and masses from mass; a node listed twice counts twice. No periodic imaging: a group split across a box face must be unwrapped first (:meth:Box.unwrap).

Returns:

Raises:

Declare the term block block with arity atoms per row, so :meth:add_term accepts a block the Frame schema does not define (a force-field term such as urey_bradleys). Re-declaring a block at the same arity is a no-op.

Raises:

Delete angle; its view goes stale.

Delete every angle of angles (views or a Refs). Atomic.

Delete atom and every relation touching it; their views go stale.

Raises:

Delete every atom of atoms (views or a Refs) and every relation touching one. Atomic: on an error (an atom of another graph, a deleted atom, an atom listed twice) nothing is deleted.

Delete bond; its view goes stale.

Delete every bond of bonds (views or a Refs). Atomic: on an error nothing is deleted.

Delete dihedral; its view goes stale.

Delete every dihedral of dihedrals (views or a Refs). Atomic.

Delete improper; its view goes stale.

Delete every improper of impropers (views or a Refs). Atomic.

Delete port (its bond stays); its view goes stale.

Delete every port of ports (their bonds stay). Atomic.

Delete the term term; its view goes stale.

Delete every term of terms — views of ONE term block. Atomic: on an error nothing is deleted.

Radius ball around centers (atom views or a Refs) 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.

Build an Atomistic from a :class:~molrs.core.Frame: one atom per atoms row (each needs atomic_number; convert symbols first with Element.fill_atomic_numbers), then the relation blocks.

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. 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 deletes existing relations of the requested kinds first. Returns (n_angles_added, n_dihedrals_added, n_impropers_added).

The subgraph induced by atoms (views or a Refs), with the map {node of this graph: node of the subgraph}.

Propagate each frag_id to the unlabelled degree-1 atoms bonded to a labelled one (one pass); returns how many were labelled.

Whether self and other are isomorphic as labelled graphs.

The leaving group of port: the atoms of its handle's connected component once the anchor–handle bond is cut, in handle order.

Join port a to port b and return the new anchor–anchor bond.

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

Raises:

Merge other into this graph and return its atoms, now in this graph, in other's former row order. other is left empty; its views go stale.

Raises:

Number of rows of the term block block.

The bonds of atom, as (neighbour, bond) pairs.

The port on the (anchor, handle_atom) valence, or None.

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 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 atom that has coordinates by angle radians about axis, pivoting on about (Å; None: the origin).

Raises:

Scale every atom that has coordinates by the per-axis factor about about (Å; None: the origin). Pass [s, s, s] for a uniform scale.

Set a bond's chemical class and its localized bond number — the one door that writes bond_type / bond_number (a view refuses them).

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.

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

A stable, reproducible dedup key over the graph's node and bond labels: identical for a node-permuted copy, sensitive to any label or connectivity change, reproducible across runs and processes.

The term blocks this graph holds, in registration order.

Every row of the term block block, in row order; empty for a canonical block this graph holds no row of.

Raises:

Export to a tabular :class:~molrs.core.Frame in the shared vocabulary. Select columns on the frame's blocks afterwards.

Raises:

Single-source shortest-path (BFS) distances over the bond graph from atom, as (atom, hops) pairs for every atom reachable from it (atom itself at 0), up to max_hops when given. Atoms of another connected component are omitted.

Translate every atom that has coordinates by delta (Å).

copy.copy(graph): an independent copy with a copy of its :attr:props. Handles are preserved (view.handle of a node names the same node in the copy).

copy.deepcopy(graph): the same independent copy as copy.copy — a graph holds no Python objects to recurse into.

Add a bead carrying props and return its view.

Parameters:

Raises:

Add a bond between beads a and b of this graph, carrying props, and return its view.

Raises:

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

Parameters:

Raises:

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 node of its group to the site; a one-node site's axis is zero.

Returns:

Raises:

The nodes bead groups, as views of the member world (empty when it groups none).

Raises:

The bead_type of each of beads, in the listed order.

Raises:

The beads whose membership includes node (a view of the member world), in bead-handle order.

Deterministic canonical bead order from canonical labeling, so two isomorphic graphs line up node by node.

Mass-weighted centre (Å) of beads (views or a Refs).

R = sum_i m_i r_i / sum_i m_i, reading positions from x / y / z and masses from mass; a node listed twice counts twice. No periodic imaging: a group split across a box face must be unwrapped first (:meth:Box.unwrap).

Returns:

Raises:

Delete bead, its bonds and its membership; their views go stale.

Delete every bead of beads (views or a Refs), their bonds and memberships. Atomic.

Delete bond; its view goes stale.

Delete every bond of bonds (views or a Refs). Atomic: on an error nothing is deleted.

Delete port (its bond stays); its view goes stale.

Delete every port of ports (their bonds stay). Atomic.

Radius ball around bead centers (views or a Refs) over CG bonds.

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 (raw handles of no graph: :meth:bead_members refuses them). bead_type comes from the first column present: bead_type, then type, then type_id (rendered in decimal). CG bonds, ports and membership survive; other topology blocks are ignored.

Raises:

The subgraph induced by beads (views or a Refs), with the map {node of this graph: node of the subgraph}.

Propagate each frag_id to the unlabelled degree-1 beads bonded to a labelled one (one pass); returns how many were labelled.

Whether self and other are isomorphic as labelled graphs.

The leaving group of port: the beads of its handle's connected component once the anchor–handle bond is cut, in handle order.

Join port a to port b and return the new anchor–anchor bond.

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

Raises:

Merge other into this graph and return its beads, now in this graph, in other's former row order. other is left empty; its views go stale. Memberships come along: both graphs' members must name one member world.

Raises:

The bonds of bead, as (neighbour, bond) pairs.

The port on the (anchor, handle_atom) valence, or None.

The positions of beads (views or a Refs), one row per listed bead, in the listed order.

Returns:

Raises:

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 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 bead that has coordinates by angle radians about axis, pivoting on about (Å; None: the origin).

Raises:

Scale every bead that has coordinates by the per-axis factor about about (Å; None: the origin). Pass [s, s, s] for a uniform scale.

Record the nodes bead groups (its membership), replacing any previous set; an empty iterable clears it.

members are node views of one source graph — the member world, which the first membership fixes.

Raises:

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

A stable, reproducible dedup key over the graph's node and bond labels: identical for a node-permuted copy, sensitive to any label or connectivity change, reproducible across runs and processes.

Export to a tabular :class:~molrs.core.Frame in the shared vocabulary. Select columns on the frame's blocks afterwards.

Raises:

Translate every bead that has coordinates by delta (Å).

Add a node carrying props and return its handle.

Parameters:

Returns:

Raises:

Add a relation of kind over node handles, carrying props.

Parameters:

Returns:

Raises:

Zero-copy adopt: move other's storage into self, leaving other empty. Handles in the adopted world stay valid (the whole generational slotmap is moved, not reindexed).

Clear field key of node node (no-op if absent).

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

Clear field key of relation rel of kind (no-op if absent).

The field 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 node at row i); i32, bool and str columns are copied. The view borrows the world's storage; structural mutation (add_node / del_node) may reallocate or reorder the column and invalidate an outstanding view — re-fetch after such ops.

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

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

Delete node node and every relation touching it.

Raises:

Delete every node of nodes and every relation touching one. Atomic: on an error (a stale handle, a handle listed twice) nothing is deleted.

Delete relation rel of kind.

Delete every relation of rels of kind. Atomic: on an error nothing is deleted.

Every field of node node, as a new dict.

Raises:

Relation rel of kind: its endpoint node handles, in order, and a new dict of its fields.

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

Propagate each frag_id to the unlabelled degree-1 nodes hanging off a labelled one (one pass); returns how many were labelled.

Fixed endpoint count of a registered relation kind.

Names of all registered relation kinds, in registration order.

Join port a to port b with a new anchor–anchor bond and return the bond's relation handle.

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

Raises:

Number of relations of kind.

All live node handles, in row 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.

Set field key of node node (value is bool|int|float|str).

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

Set field key of relation rel of kind.

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

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

Return self==value.

Return self>=value.

Return self>value.

Return hash(self).

int(self)

Return self<=value.

Return self<value.

Return self!=value.

Return repr(self).

The class a stored code names; a code outside 0..=4 is Unknown.

The bond number a non-aromatic class implies; None for Aromatic and Unknown.

Whether this is an aromatic bond.

Return self==value.

Return self>=value.

Return self>value.

Return hash(self).

int(self)

Return self<=value.

Return self<value.

Return self!=value.

Return repr(self).

The number as a count, for valence sums; Unknown counts as 0.

The number a stored code names; a code outside 0..=4 is Unknown.

The bond class this number implies — the inverse of :meth:BondOrder.implied_number. Quadruple is classed Double; Unknown implies Unknown.