Skip to content

Overview

The root of a MolRec package holds named sections. meta is always present (an empty document is a valid one). Every other section — system and frame included — is optional: take the ones that match the data, leave the rest off.

root
 \-- meta
 \-- (system)
 \-- (frame)
 \-- (trajectory)
 \-- (forcefield)
 \-- (observables)
 \-- (method)
 \-- (status)
 \-- (metrics)

A package includes meta and at least one of frame, system, trajectory, forcefield, or status. Inside a section, every group or array is again optional unless that section's chapter says otherwise.

Typical compositions:

Composition Sections Typical use
Structure meta, frame one conformation
System def meta, system topology without coordinates
Force field meta, forcefield a parameter set, distributed on its own
Trajectory meta, trajectory MD time series (system optional)
Run meta, status training job / workflow (metrics and/or method recommended)

Section kinds

A section is a named group at the root. Content falls into four kinds:

Document. A JSON object stored as group attributes. Small, structured facts: identity, lifecycle, scientific context. meta, status, and method are documents.

Frame-shaped. Named blocks of columns, a meta document (the group's attributes), optional box. Instantaneous or definitional tables. frame, system and forcefield are frame-shaped (Frame-shaped group).

Array. Named arrays, each beside a metadata document. observables is an array section: one data array of any shape per name, with its kind and the rest of its metadata under observables/meta/<name>; see Observables.

Sequence. An ordered series of frames with step and optional time. trajectory is the sequence section. Time-dependent data lives here; see Trajectory.

Live metrics append as text and densify to arrays; that hybrid is specified with the metrics section.

Design principles

Peer sections. Sections sit side by side at the root. A trajectory is a section, the same kind of thing as frame or status.

Compose what you have. A training run is meta + status + metrics. A packed snapshot is meta + frame. An MD package is meta + system + trajectory. The unused names stay absent.

Unknown siblings stay. A reader preserves sections and keys it does not recognise. That is how new content enters the ecosystem: add a sibling, and a tool that does not know it carries it through.

Conventional names, new names. If the data is atoms, bonds, a box, use the standardized identifiers. If it is something else — a mesh, a k-point grid, a docking pose — pick a new section or block name and keep it. Reserved names keep their meaning.

Facts vs arrays. Structured facts that fit in JSON belong on a document section (or a frame's meta document). N-dimensional values belong in columns. The parameters that define the energy model live in the forcefield section; how a job was run lives under method.

Modules name extra rules. A shared interpretation beyond this specification is declared under meta/modules/<name>, which names the module the record uses. Custom method types and custom metric types point there.

Adding your own content

Four places, in increasing size of the addition:

  1. Extra keys on an existing document (meta, status, method). Readers preserve them.
  2. Extra columns or blocks on frame, system, or trajectory. Same containers; your names. Readers preserve them.
  3. A new sibling section at the root. Same four kinds: document, frame-shaped, array, or sequence. A reader that does not know the name keeps the group. It is always a group — a lone array or a root attribute is not a section, and is not carried.
  4. A module under meta/modules when independent tools must agree on what that extra content means.

Worked sketches:

  • A volumetric density already fits: a block with structural shape [nx][ny][nz] on frame, cell on box.
  • A docking score is an observable (kind scalar, target /frame/atoms) or a column on a new poses block.
  • A custom optimiser log is metrics (run-local curves) plus extra keys on method.
  • A domain-specific tree (QM basis, crystal symmetry operations) is a new root section; declare a module if a second package must parse it.

Metadata

Identity of the package lives in meta. In the reference binding the contents are group attributes (one JSON object):

meta
 +-- (creator)
 |    +-- name: string[]
 |    +-- (version: string[])
 +-- (author)
 |    +-- name: string[]
 |    +-- (email: string[])
 +-- (created_at: string[])            RFC 3339 with an explicit offset
 +-- (source: string[])
 +-- (units)
 |    +-- (length | energy | force | charge | mass | time: string[])
 |    +-- (pressure | temperature | angle: string[])
 \-- (modules)
      \-- <module1>
           +-- (spec: string[])          URL of the module's specification

Every key of meta is optional, with one condition: a record that carries a continuous quantity states its unit in units (below). A record that carries none may leave meta empty. A record's identity is the path brand *.mrec/ / *.mrec.zip plus a Zarr root, not any key of meta.

Unknown keys. A key this chapter does not name is the producer's: a reader keeps it verbatim (a null-valued one included) and never interprets or refuses it, and a writer of the record writes it back as it was.

record_id, content_hash

Optional provenance: a producer-chosen identifier and a content digest. Both are opaque strings. This specification defines no digest: two conforming records of the same data differ byte for byte (Chunking), so a content_hash is whatever its producer computed over whatever it chose, comparable only with another from the same producer. A reader preserves it and never verifies it; a tool that rewrites the record's content drops it or recomputes it.

creator, author, created_at, source

Optional provenance.

units

The record's unit system: a map from quantity to unit string. A quantity is required once the record carries it — length beside an x column, energy beside a pe key — and none has a default; the quantities, what makes each required, and a column's own unit are Units. A record of a collection carries none: the collection states them.

modules

Each module is an entry keyed by its name: the module the record uses. It may carry spec, the URL of the module's specification, and any module-specific information. A module entry carries no version and no compatibility rule.