MolRec

MolRec is the backend-neutral record contract for the MolCrafts ecosystem.

It is not a store product, not a class named MolStore, and not “only a Frame format.” A Record is anything tools must share for reproducibility: molecular systems, snapshots and trajectories, scientific observables, and training or job execution logs.

MolRec defines:

1. A small general data model (Column / Block / Frame).
2. A Record root layout (sections under one package).
3. Conventions so independent tools agree on names.

A reader that knows only the model can traverse any record. A reader that also knows the conventions can interpret it.

The model (L1)

Three general containers:

Column     a typed N-dimensional array
Block      named columns sharing one length (+ optional structural shape)
Frame      named blocks + free-form metadata + an optional box

No key is privileged; no field is required by the model itself. Domain meaning is convention — see Conventions.

The Record (L2)

<record-root>/
├── meta/              # required
├── system/            # definition of the chemical/physical system
├── frame/             # instantaneous snapshot
├── trajectory/        # time series of frames
├── observables/       # scientific results
├── method/            # how it was produced
├── status/            # lifecycle / progress (run surface)
└── metrics/           # append-only run measurements

No root parameters/. Minimum shapes: Structure, System-def, Trajectory (system optional), Run (meta+status, frame optional). Contract cell name is Box; sole version is record_schema_version. Details: Record, Run surface.

Reading guide

Chapter	What it covers
Overview	L0–L4, model, minimum records, invariants
Record	Root layout, versioning, section map
Types	Column dtypes and structural shape
Frame	Frame, Block, Column, Box
System	System definition vs frame state
Conventions	Recommended block/field names
Trajectory	Frame sequences
Run surface	Training / job logs as records
Observables	Scientific result quantities
Status	Execution lifecycle
Metrics	Append-oriented measurements
Meta	Record-level metadata
Method	Scientific context

Reference implementation

molrs provides the reference L1 containers and the Zarr V3 binding for frames (and, over time, full record roots). Consumers (molpy, molnex, molexp, …) adopt this contract; they must not invent a parallel store product name for the same layout.