Third Matter Specification is a declarative YAML/JSONL metalanguage and reference toolchain for describing atomistic simulations: structures, defects, magnetic state, environment, reactions, DFT/MLIP/MD calculations, workflows, sanity gates, results, and provenance.
Status: v0.2 (draft) · Package: 0.2.0 · License: MIT (code) + CC-BY-4.0 (spec)
Source: github.com/exopoiesis/tm-spec · JSON Schema:
/0.2.json
One YAML file per calculation, schema-validated, exportable to FAIR archives, with first-class sanity gates compiled from real project lessons-learned. v0.2 adds:
SinglePointCalculation for single SCF/electronic-structure results.RelaxCalculation for geometry optimisations.tm-spec import-nomad and import-nomad-batch for public NOMAD
Archive entries.Designed for niches that mainstream workflow managers do not own:
| Document | What it covers |
|---|---|
| v0.2 specification | Current draft: v0.1 core plus SinglePoint/Relax and NOMAD import provenance. |
| v0.2 JSON Schema | Machine-readable schema (Draft 2020-12). Resolves at https://exopoiesis.github.io/tm-spec/0.2.json. |
| v0.1 specification | Legacy initial draft retained for old documents. |
| Design decisions | Decision log D-01..D-25 with rationale, sources, and breaking-change flags. |
| Standards alignment | Field-by-field mapping to parent standards. |
| Landscape | Strategic positioning vs AiiDA / atomate2 / FireWorks / CWL / Snakemake. |
| Literature review | Survey of related metalanguages. |
pip install tm-spec
tm-spec validate examples/pyr_smoke.tm.yaml
tm-spec import-nomad <entry_id> --out imported.tm.yaml
Validate directly against the published schema:
python -m jsonschema -i my.tm.yaml https://exopoiesis.github.io/tm-spec/0.2.json
See the README on GitHub for the full toolchain.
If TM-Spec helps your paper SI, cite:
Morozov, I. (2026). TM-Spec: a declarative YAML metalanguage for reproducible atomistic calculations. Version 0.2. github.com/exopoiesis/tm-spec
A CITATION.cff file is in the repository root.