TM-Spec — one readable file per experiment (yes, another standard)
There’s an xkcd about this: “14 competing standards → let’s make a 15th.” We made TM-Spec anyway — so let me explain why it isn’t just that.
Before writing a line, we did the literature review. The honest finding: there is no universal “language of physics/chemistry.” What exists is a stack of excellent domain languages — NOMAD Metainfo, OPTIMADE, QCSchema, AiiDA, ASE, PHREEQC, Antimony, CALPHAD, AFLOW prototypes, magCIF. TM-Spec doesn’t try to replace any of them.
What it is: one human-readable YAML file that describes a whole atomistic calculation — structure, defects, magnetic state, environment, the DFT/MLIP/MD method, the workflow (NEB, umbrella sampling, metadynamics, MD, MLIP benchmark, single point, relaxation), results, post-hoc sanity gates, an optional predictive pre-flight block, and provenance.
Here’s a small real one — a pyrite single-point calculation imported from NOMAD:
spec: tm-spec/0.2
kind: SinglePointCalculation
id: tm.nomad.pyrite_sp_0001.2026-05-10
structure:
formula: Fe32S64 # FeS2 — pyrite
space_group: { number: 205, symbol: Pa-3 }
magnetic: { state: NM, collinear: true }
calculation:
method: DFT
level: { xc: GGA, xc_libxc: [GGA_X_PBE, GGA_C_PBE], spin: none }
code: { name: QuantumESPRESSO, version: "7.3.1" }
results: { status: PRELIMINARY, scf_converged: true, band_gap_eV: 0.8 }
sanity:
- { id: G05_scf_converged, observed: true, pass: true }
provenance:
import_source: { archive: nomad, entry_id: pyrite_sp_0001 }
The gap it fills — the missing middle. A paper’s supplementary today is usually either a code-specific input dump (pwscf.in) or a workflow archive that needs a special runtime to open. TM-Spec is the snapshot in between: a reviewer can read it in any text editor with zero runtime, a validator can check it against JSON Schema, and tools can ingest it — extract a stub from an existing ASE/QE/CP2K script, import from NOMAD / OPTIMADE / Materials Project / MAGNDATA, or export a NOMAD upload bundle. The same file describes Quantum ESPRESSO, CP2K, ABACUS, GPAW, MACE, or CHGNet at the same level of detail.
It aligns rather than competes: it isn’t a replacement for AiiDA or atomate2 — they own the provenance graph during the work; TM-Spec owns the paper-grade snapshot, and maps deliberately onto the standards above.
And this is the part we’re most interested in: TM-Spec is becoming a foundation we’re starting to build on — a support layer of tooling that produces and consumes these documents to drive real work. More on that in a future post.
Open and free: MIT (code) + CC-BY-4.0 (spec). pip install tm-spec.