tm-spec

TM-Spec v0.2 — Draft

Date: 2026-05-10. Status: [DRAFT].
Schema: ../../schemas/0.2.json.
v0.2 is an additive extension of v0.1: all v0.1 calculation kinds remain valid after changing spec: tm-spec/0.1 to spec: tm-spec/0.2.

1. Header

Every TM-Spec v0.2 document MUST include:

spec: tm-spec/0.2
kind: <Kind>
id: tm.<slug>.<YYYY-MM-DD>
schema_url: https://exopoiesis.github.io/tm-spec/0.2.json

The id is human-readable and stable enough for SI references. Persistent archive identifiers (NOMAD entry id, DOI, Zenodo record) belong in provenance.import_source or provenance.parents.

2. Core sections inherited from v0.1

v0.2 keeps the v0.1 core sections:

• structure
• defects
• magnetic
• environment
• reactions
• calculation
• workflow
• results
• sanity
• provenance

The original v0.1 workflow families are unchanged:

• NEBCalculation
• USCalculation
• MetaDynCalculation
• MDCalculation
• MLIPBenchmark
• compositional fragments: Structure, Defects, Magnetic, Environment, Reaction, SanityReport, Provenance

See v0.1.md for the section-by-section narrative examples. The machine contract is the v0.2 JSON Schema.

3. New kind: SinglePointCalculation

SinglePointCalculation describes a single SCF/electronic-structure calculation: energy, forces, stress, DOS, bands, charges, Bader analysis, magnetic moments, or similar post-SCF results.

Required sections:

spec: tm-spec/0.2
kind: SinglePointCalculation
id: tm.nomad.example.2026-05-10

structure: { ... }
calculation: { ... }
results:
  status: PRELIMINARY
sanity:
  - { id: G05_scf_converged, rule: "SCF converged", pass: true }
provenance:
  date: 2026-05-10
  author: import@nomad

Optional results fields include:

• energy_eV
• energy_per_atom_eV
• forces_eV_per_A (path to artefact)
• max_force_eV_per_A
• stress_GPa
• band_gap_eV
• fermi_energy_eV
• magmoms_final_uB
• paper_quotable
• validated_by
• notes

Optional electronic_structure_analysis can record DOS, band structure, band gap, charges, Fermi energy, and atomic magnetic moments.

4. New kind: RelaxCalculation

RelaxCalculation describes a geometry optimisation as a single trajectory, distinct from NEB (multiple endpoints) and MD (time evolution).

Required additional section:

relax_protocol:
  optimizer: BFGS
  fmax_eV_per_A: 0.03
  max_steps: 200
  cell_relax: none

Required results.status; optional result fields include:

• final_energy_eV
• fmax_achieved_eV_per_A
• n_steps_actual
• converged
• final_structure_ref
• final_volume_A3
• stress_GPa
• paper_quotable
• validated_by
• notes

5. NOMAD import provenance

v0.2 adds provenance.import_source for documents imported from external archives. The bundled importer currently targets NOMAD Archive entries.

provenance:
  date: 2026-05-10
  author: import@nomad
  import_source:
    archive: nomad
    entry_id: example-entry-id
    upload_id: example-upload-id
    url: https://nomad-lab.eu/prod/v1/gui/entry/id/example-entry-id
    imported_at: 2026-05-10T12:00:00+00:00
    importer: tm-spec import-nomad@0.2.0
    raw_keys:
      - results.material
      - results.method.simulation.dft
      - results.properties.energies.energy_total
  compute:
    host: nomad-archive
    cost_usd: 0.0

Importers SHOULD preserve enough raw-key traceability for a human to audit the mapping from the source archive to TM-Spec.

6. CLI additions in v0.2

tm-spec import-nomad <entry_id> --out imported.tm.yaml
tm-spec import-nomad-batch --query '{"results.method.method_name":"DFT"}' \
  --limit 25 --out-dir imported/

Both commands use anonymous reads by default. NOMAD_API_TOKEN can be set for authenticated/rate-limited environments.

7. Compatibility

• A v0.1 document MUST validate against schema 0.1.json.
• A v0.2 document MUST validate against schema 0.2.json.
• The reference validator selects the schema from the document’s spec field.
• Existing v0.1 examples were bumped to tm-spec/0.2 because v0.2 is an additive superset.

8. Implementation notes

Reference implementation version 0.2.0 provides:

• tm_spec.validator
• tm_spec.extract
• tm_spec.lint
• tm_spec.sanity_fill
• tm_spec.exporters.nomad
• tm_spec.importers.nomad
• tm_spec.cli

The spec text is intentionally concise; exact required/optional fields are defined by the JSON Schema and guarded by tests.

This site is open source. Improve this page.