Standardized identifiers¶
The containers have no special fields. The identifiers below restore interoperability. They follow the Frame/Block naming that molpy documents as the interchange representation — the same names molrs serializes.
The identifiers are recommended: a producer need not use them, and a reader
preserves blocks and columns outside this list. A producer that does use
one uses it with its canonical dtype and shape (below). Names reserved by
the layout itself — box and _validity among a frame's children, the
trajectory's own children — are listed in
Root layout and
Ragged trajectory.
MolRec specifies the Frame/Block interchange representation. MolPy's Entity
graph (itom / jtom object references) is a construction API.
Block names are lowercase and plural. Field names are lowercase with underscores for multi-word names.
Canonical dtypes¶
A canonical column key has one dtype and one shape wherever it appears —
in any block, under frame, system or trajectory, on the frame path
and the trajectory path alike. Every key in this chapter is one value per
row (<dtype>[N], no trailing axes), at the dtype the trees below give it.
| Keys | dtype |
|---|---|
x y z vx vy vz fx fy fz charge mass |
f64 |
quatw quati quatj quatk mux muy muz axis_x axis_y axis_z occupancy b_factor |
f64 |
id atomic_number type_id mol_id res_id atom_map n_bonds |
u64 |
atomi atomj atomk atoml atomm ibead bond_type bond_number |
u64 |
formal_charge |
i64 |
ix iy iz |
i32 |
free exclude_14 |
bool |
element type name res_name bead_type chain icode altloc style |
string |
The table is published as
schema/core/vocabulary.json
({key: dtype}), generated from the models.
- A writer MUST NOT store a canonical key at any other dtype or shape.
A writer whose producer hands it a narrower unsigned array under one of
these keys may widen it exactly (a
u32atomibecomesu64) and write the canonical dtype. - The unsigned identifiers and relation endpoints —
id,atomic_number,type_id,mol_id,res_id,atomi,atomj,atomk,atoml,atomm,ibead,bond_type,bond_number— are exactlyu64. A reader MUST refuse one stored at any other width or signedness rather than widen it on read: a record that holds one narrower came from a writer that broke the contract, and reading it back asu64would hide that. - A reader SHOULD refuse any other canonical key at another dtype too.
- The per-step scalars are canonical the same way: a
declared
pe,ke,etotal,temp,pressorvolumekey isf64.
atoms¶
An atoms block holds per-particle properties. All arrays have length N,
the number of particles. Positions are stored as three separate 1-D columns
x, y, z — the standardized form; there is no packed xyz column.
atoms
\-- (x, y, z: f64[N])
\-- (vx, vy, vz: f64[N])
\-- (fx, fy, fz: f64[N])
\-- (ix, iy, iz: i32[N])
\-- (id: u64[N])
\-- (atomic_number: u64[N])
\-- (element: string[N])
\-- (type: string[N])
\-- (type_id: u64[N])
\-- (name: string[N])
\-- (charge: f64[N])
\-- (formal_charge: i64[N])
\-- (atom_map: u64[N])
\-- (mass: f64[N])
\-- (mol_id: u64[N])
\-- (res_id: u64[N])
\-- (res_name: string[N])
\-- (chain: string[N])
\-- (icode: string[N])
\-- (altloc: string[N])
\-- (occupancy: f64[N])
\-- (b_factor: f64[N])
\-- (bead_type: string[N])
\-- (free: bool[N])
\-- (quatw, quati, quatj, quatk: f64[N])
\-- (mux, muy, muz: f64[N])
\-- (axis_x, axis_y, axis_z: f64[N])
x, y, z
Cartesian coordinates.
vx, vy, vz
Cartesian velocity components.
fx, fy, fz
Cartesian force components on each particle: the negative gradient of the
state's potential energy (pe), as a producer computed or labelled it.
id
A stable per-atom identifier carried by the source file. Never an index — relation endpoints are 0-based row indices.
atomic_number
Atomic number Z.
element
IUPAC element symbol (e.g. "C").
type
Force-field type label. Always a string — a label is what survives a round
trip through a force field. Numeric type ordinals live in type_id.
charge, mass
Partial charge and atomic mass, in the charge and mass units the record
states (Units). Neither has a default — mass is not amu and
charge is not e unless the record says so — and a record that carries
the column states the unit. The same holds for coordinates, forces and
energies: none has a default unit.
Continuous quantities (x/y/z, vx/vy/vz, charge, mass) are
float-canonical: a value written as an integer is stored as a float so a
later fractional write is accepted.
Format-specific aliases (LAMMPS q, mol) exist only at the I/O boundary.
Readers canonicalize them to charge and mol_id.
The same atoms block may appear under system without coordinate columns.
When it does and trajectory/atoms exists too, the two are aligned 1:1 by
row order — every trajectory update has exactly the system row count — and
an id column present on both sides is equal row for row. A ragged
trajectory block never shares a name with a system block
(Trajectory).
formal_charge
Integer formal charge of each atom in the bonding pattern, in e. Distinct
from charge, the (partial) charge an energy model assigns.
atom_map
The atom-map number of each atom in a mapped SMILES string
(mapped_smiles), 0 for an unmapped atom. Row i of atoms is the atom
mapped atom_map[i].
ix, iy, iz
Periodic image flags along the first, second and third lattice vector: how
many cells the atom has crossed. The continuous position is
(x, y, z) + H · (ix, iy, iz) with H the box vectors; the stored
coordinate stays wrapped. Signed. They travel with the coordinates: a writer
that drops one drops all three.
res_id, res_name, chain, icode, altloc
The residue an atom belongs to and where it came from. res_id is the source
file's residue number (never a row index; unsigned — a reader renumbers a
negative one at its boundary), res_name its name, chain the chain label
(PDB chain identifier, mmCIF label_asym_id), icode the insertion code and
altloc the alternate-location indicator, "" for none. A residue is
identified by (chain, res_id, icode). There is no residues or chains
block: the per-atom columns are the one carrier.
occupancy, b_factor
Crystallographic occupancy (a fraction) and isotropic displacement parameter
B (length²).
free
Whether an atom may move when coordinates are optimized. false pins it. A
block without the column has every atom free.
quatw, quati, quatj, quatk
A per-particle orientation quaternion (w, i, j, k).
mux, muy, muz
A per-particle electric dipole moment (charge × length).
axis_x, axis_y, axis_z
A coarse-grained site's axis: from the first member of its group to the site (length).
Positions are Cartesian. Fractional coordinates are not a convention: a reader of a fractional format converts at its boundary.
Relations¶
Relation blocks reference atoms by 0-based u64 row indices into the
atoms block (atomi … atomm) — integers, never object references; a
relation that references another block says so with
targets.
bonds
\-- atomi: u64[E]
\-- atomj: u64[E]
\-- (type: string[E])
\-- (type_id: u64[E])
\-- (style: string[E])
\-- (bond_type: u64[E])
\-- (bond_number: u64[E])
bond_type is the chemical bond class: 0 unknown, 1 single, 2 double,
3 triple, 4 aromatic. bond_number is the integer bond number of the
localized Lewis/Kekulé structure (0 unknown, 1–4) — never fractional;
aromaticity is a bond type, not a number. The two are orthogonal: an
aromatic bond is bond_type = 4 carrying a bond_number of 1 or 2. There
is no float order column.
| Block | Endpoints | Optional |
|---|---|---|
bonds |
atomi, atomj |
type, type_id, style, bond_type, bond_number |
angles |
atomi, atomj (vertex), atomk |
type, type_id, style |
dihedrals |
atomi … atoml |
type, type_id, style, exclude_14 |
impropers |
atomi … atoml |
type, type_id, style, exclude_14 |
pairs |
atomi, atomj, and the required n_bonds |
epsilon, sigma, charge_product, lj_scale, coul_scale |
constraints |
atomi, atomj |
type, type_id, style |
virtual_sites |
atomi (the site), atomj, atomk, atoml (constructing atoms) |
type, type_id, style |
drudes |
atomi (core), atomj (Drude particle) |
type, type_id, style |
cmaps |
atomi … atomm |
type, type_id, style |
members |
ibead, atom (both declared in targets) |
— |
type names a row of the record's force field
and style picks the style when several hold that name. type_id is a
format-local ordinal (LAMMPS) and plays no part in linking. A relation may
carry per-instance parameters as further columns named as its style names
them (r0 on constraints, kb on an MMFF bonds).
pairs lists the system's special pairs: the pairs of atoms the pair
styles price otherwise than at full strength. Every pair of atoms no row
names is priced at full strength. A row names its unordered pair once and
carries n_bonds, the pair's class: the number of bonds on the
shortest path between its atoms (1, 2 or 3 for a 1-2, 1-3 or 1-4 pair,
whose weight is the force field's special_bonds of that class), or for a
pair a format names that the bonds do not class (a GROMACS [ exclusions ]
row beyond three bonds) its actual distance, 0 when no bonds connect it.
A row links no force-field row: its pair is priced by the pair styles
through its atoms' types, and its nullable f64 columns epsilon,
sigma, charge_product, lj_scale and coul_scale override them for
that one pair (special pairs); an excluded
pair is a row whose scales are 0. A system with bonds and no pairs
block states no special pairs: every pair, bonded ones included, is at full
strength, which is rarely what a force field means, so a writer of one
SHOULD generate the rows with its angles and dihedrals. An absent
pairs block and one with zero rows mean the same thing, so the record
cannot tell "none" from "not generated": a consumer that evaluates an
energy over a system with bonds, no pairs rows, and a force field whose
special_bonds weights are not all 1
SHOULD refuse or warn rather than price every bonded pair at full
strength in silence, and a validator SHOULD report it.
exclude_14 marks a torsion whose 1-4 non-bonded term is suppressed
(AMBER's negative third index).
A virtual_sites row constructs the particle atomi (an atoms row,
usually massless) from up to three others; a site built from fewer leaves
the trailing endpoints null. A drudes row pairs a core atom with its Drude
particle; both are atoms rows. A cmaps row is a CMAP cross term over two
consecutive dihedrals, atomi–atomj–atomk–atoml (φ) and
atomj–atomk–atoml–atomm (ψ); its type names a row of a
cmap table.
A coarse-grained frame stores its beads as atoms rows (with bead_type)
and its bonds in bonds. members maps beads to the atoms they group, one
row per (bead, atom). Neither column is one of the five implicit endpoints
(row references), so both are references only
when targets declares them: ibead → atoms (the beads of the same
frame), atom → the all-atom block (/frame/atoms, …). Undeclared, either
is a plain number, an opaque handle a reader neither range-checks nor
renumbers.
There is no residues, chains or molecules block: per-atom res_id,
res_name, chain, icode and mol_id are what every format carries, and
a block would be a second carrier of one fact. Residue-level data a producer
needs goes in a block of its own, referenced with targets.
Other entity sets (fragments, a producer's own groupings) follow the same pattern with their own block name.
The naming conventions do not change with the record section. An atoms
block under trajectory carries the same columns it carries under frame.
The box identifiers (vectors, origin,
boundary, cell_defined) are part of the cell, not of these blocks.
Per-step scalars¶
Per-step scalars of a trajectory land under trajectory/meta/<key>
(Ragged trajectory). The standard keys are
all f64:
| Key | Meaning |
|---|---|
pe |
potential energy |
ke |
kinetic energy |
etotal |
total energy |
temp |
temperature |
press |
pressure |
volume |
cell volume |
As with columns, the tag carries no unit: the record states it (Units). Producers add other keys freely and readers preserve them.
Units¶
A record states one unit system, in meta.units
(Metadata): a map from quantity to unit string. A
collection states it once, in its own meta.units,
for every record in it, and a record of a collection carries none.
| Quantity | The unit of | Required when the record carries |
|---|---|---|
length |
x y z, the cell |
a column x, y or z |
energy |
pe ke etotal |
a meta key pe, ke or etotal |
force |
fx fy fz |
a column fx, fy or fz |
charge |
charge |
a column charge |
mass |
mass |
a column mass |
time |
the trajectory's time |
a trajectory with time |
pressure |
press |
a meta key press |
temperature |
temp |
a meta key temp |
angle |
no standardized key | — |
A column counts in any block of frame, system or trajectory; a meta
key on a frame, on a system, or among a trajectory's per-step keys. A
trajectory that declares the column or the key requires the unit even when
it holds no frame.
- A required unit is stated, never defaulted. A record that carries one
of the quantities above without its unit is refused, on write and on read.
A record that carries none of them may leave
unitsout. - Nothing else is required. A name outside the table —
vx,volume, the cell,total_charge,formal_charge— requires no entry, and nothing requiresangle. - A unit string is a label (
angstrom,kcal/mol,kcal/mol/angstrom,e,amu). A reader hands it back as written; nothing converts it and nothing parses it. - A quantity left unset is absent, never
null; a key the table does not name is preserved.
A column's own unit. A column may carry unit, a unit string for that
column alone. It replaces the record's unit for that one column and never
stands in for it: a record whose x states unit: "nm" still states
length. A column outside the table may carry one too. It is stored where
the column is — the array's attribute unit on the
Zarr binding, on the frame path and the
trajectory path alike; the column's header entry on LMDB
— and it is no part of a trajectory's sequence_schema. A trajectory column
states one unit string for the run: frames that state different ones are
refused, and a frame that states none takes the one another frame stated. A
force-field style table's columns carry none.
The force field's units are its own. The
forcefield document states the units of its
parameters, with presets; that object and meta.units are two statements,
and neither is read for the other.
A meta key named units. On a frame or system it is an ordinary
meta value, kept under its tag like any other. It is not the record's unit
system and does not satisfy the requirement above.
Composition and identity keys¶
Keys of a system (or frame) meta document that say what the particles
are, as opposed to what state they are in. Recommended; a reader
preserves others.
| Key | Type | Meaning |
|---|---|---|
total_charge |
integer | net charge of the system, in e |
spin |
integer | spin multiplicity 2S + 1 |
smiles |
string | SMILES of the system |
mapped_smiles |
string | atom-mapped SMILES; atoms.atom_map indexes it |
molecule_id |
string | identity of the molecule, shared by every record of it |
source_record_id |
string | the record's identifier in the upstream source |
molecule_id is what keeps two records of one molecule on the same side of
a train/test split. Two records carry equal molecule_id exactly when they
describe the same molecule.
Typed JSON values¶
JSON has no NaN, no infinity, no complex number, and a reader whose numbers
are binary64 (JavaScript, a wasm viewer) silently rounds an integer beyond
2⁵³. Wherever a JSON value has a declared dtype — a per-step fill in
sequence_schema, a per-step value in an LMDB frame header, a
value of a frame's or system's meta
(typed by _meta_types, Root layout) — it
is written in exactly one form:
| Element dtype | JSON form |
|---|---|
f64 |
a JSON number when finite; the strings "NaN", "Infinity", "-Infinity" otherwise |
c64, c128 |
a two-element array [re, im], each part an f64 as above |
| an integer dtype | a JSON number when |v| ≤ 2⁵³; its decimal string ("18446744073709551615") beyond |
bool, string |
itself |
json (meta tag) |
the document itself, which must be finite JSON |
A vector tag (f64x3, u64x3, …) is a JSON array of its elements, each in
the form above.
- A writer serializes every document with NaN and infinity forbidden
(
allow_nan=Falseor its equivalent) and hands numbers over as plain JSON numbers, never as a language's native scalar type. - A reader accepts exactly these forms, plus an exact JSON integer beyond
2⁵³ (what a writer with 64-bit integers may emit), and refuses everything
else:
nullwhere a number is declared is a broken value, not a NaN, and a real where an integer is declared is not rounded. - A value is held to its dtype's range: an
i32fill of2³¹is refused.
An untyped document — the record's meta, status, method, the
forcefield document — has no declared dtype; its numbers are plain JSON,
and a producer that needs NaN in one stores it as data, not as a document
key. A frame's meta is typed: every key has a tag.