Guide

Install

pip install openmaterials-ai

The map data is public JSON under /data/, so reading it needs no install. To work on the map itself, clone the repository and install it in editable mode.

git clone https://github.com/openmaterials-ai/openmaterials-ai.git
cd openmaterials-ai
pip install -e .
python -m pytest -q            # run the test suite
python -m omai.map_data        # regenerate docs/data/*.json from the operator layer

Cite the map version your work used; the Cite block has the citation and a BibTeX entry. A repository can show the map version it pins as a badge: https://openmaterials.ai/badge/<version12>.svg renders the version it names, and /badge.svg always shows the current one.

[![OpenMaterials map version](https://openmaterials.ai/badge/<version12>.svg)](https://openmaterials.ai/)

Resolve a label

The resolver maps a method or quantity name, as a paper or an agent writes it, to the ids of typed, content-addressed nodes. The playground's Resolve tab runs the same resolver in the browser.

from omai.map_data import DOMAINS, build_graph_dict
from omai.semantics import build_semantics, resolve

sem = build_semantics(build_graph_dict(DOMAINS))
hits = resolve("quasi-harmonic approximation", sem)
print([h["id"] for h in hits][:2])
# ['QHAGibbsEnergy', 'ThermalExpansion']

An empty result means the map has no node for that phrase yet. The document's appendix "Extending the DAG" covers adding one.

Load the map

from omai.map_data import DOMAINS, build_graph_dict

g = build_graph_dict(DOMAINS)
print(len(g["nodes"]), "nodes,", len(g["links"]), "links")
# each node: id, type, symbol, formula, tier, uid
# each link: source, target, op, uid

The same dict is published as docs/data/graph.json, so a browser client reads it with one fetch.

A node's producing edges

from omai.map_data import DOMAINS, build_graph_dict

g = build_graph_dict(DOMAINS)
node = "ThermalConductivity[transport_model=qhgk]"
producers = sorted({l["op"] for l in g["links"]
                    if l["target"] == node and l.get("op")})
print([p for p in producers if p.startswith("compute")])
# ['compute_kappa[transport_model=qhgk]']

Identity and dimension

Every node has a content-addressed uid and a dimensional signature. The uid is what evidence pins to, so a value follows its quantity through the whole versioned history.

from omai.thermal_transport.operator.nodes import THERMAL_CONDUCTIVITY
from omai.operator.identity import node_id

print(node_id(THERMAL_CONDUCTIVITY)[:12], THERMAL_CONDUCTIVITY.fields[0].dimension.name)
# a03324d4def5 thermal_conductivity

The map's Lean layer is one package, lean/bridge, pinned to one Physlib revision. python -m omai.physlib_dimensions writes each node's dimension as a Physlib seven-base ISQ definition, and python -m omai.physlean_export publishes those declarations in docs/data/lean.json. A dimension says nothing about units: stored representations also use units such as linear THz and angstroms. Closed-form formulas are not restated as theorems, since a restatement certifies nothing.

The formula bridge proves conditional theorems about the map's formulas, citing Physlib declarations where it has a model (harmonic ensembles, the quasiharmonic producers, crystal lattice dynamics, thermoelectric coefficients) and as local proofs over Mathlib where it has none (elastic moduli, composite conductivity, cure kinetics); the two kinds are counted apart. Its inventory lists source mappings, compiled proofs, and gaps for existing scientific identities. A source link is not an equivalence proof: inspect the assumptions, normalization, tensor scope, and remaining obligations before applying a theorem. The map links to these records beside its formulas. The local static-plus-harmonic Cp response proof uses a common molar free-energy model and a stable constant-pressure branch; it does not verify numerical QHA producers. The thermal Grüneisen proof uses the same model and branch: an independently defined, heat-capacity-weighted mean of mode Grüneisen parameters equals alpha_V*K_T/C_V_vol; it does not verify mode-Grüneisen producers or phonopy's fitted quotient.

Export a sub-map as Mermaid

A derivation or sub-map exports as a Mermaid flowchart, which GitHub renders in Markdown files, issues, and pull requests. The playground's Sub-map tab has a Copy as Mermaid button, and the exporter also runs from Python:

from omai.mermaid import mermaid_lineage

print(mermaid_lineage("PhononDOS"))
# flowchart LR ... Frequency -- "compute dos" --> PhononDOS ...

Parse a paper

The command-line parser reads a PDF and proposes values for the map. Each value carries a verbatim quote and a page anchor, is validated against the map, and passes an adversarial review before a person accepts it. The playground's Learn tab runs a single-pass version in the browser. The CLI:

# writes proposals/<slug>.json (dry: no map changes)
python -m omai.paper_parser path/to/paper.pdf

# review the proposal
python -m omai.paper_db --show <slug>

# apply accepted values (writes committed instances)
python -m omai.paper_parser path/to/paper.pdf --apply --yes

The CLI parser reads an Anthropic API key from a .env file at the repository root, which .gitignore excludes. The Learn tab sends the paper text through our relay, which holds the project's key and enforces a daily budget, so trying it needs no key.

Data contract

python -m omai.map_data regenerates these files under docs/data/ from the operator layer:

graph.json

{nodes[], links[], tiers[]}
The structure: typed quantities and the operators between them.

codes.json

{code: {node: spec}}
Each code's representation: which quantities it computes, units, citation, license.

semantics.json

[{id, uid, kind, labels, curated}]
The labels per node and edge that the resolver matches.

instances.json

[{id, variable, material, conditions, value, units, uncertainty, source {kind, ref, detail}, node_uid}]
Evidence: measured or computed values attached to nodes.

spectra.json

[{variable, axis, values}]
Function-valued evidence (densities of states, profiles).

configurations.json

[{name, structure, canonical, retracted?}]
Atomic structures (pymatgen payload), the evaluation points. A retracted structure still resolves and is marked.

version.json

{version, graph_version, format_rules_version, genesis}
The map version, graph version, and genesis hash.

CLI reference

Each command regenerates artifacts or prints a report. The table shows the flags a command accepts.

python -m omai.map_data

Regenerate every docs/data/*.json from the operator layer.

python -m omai.index_data

Regenerate the per-code and per-paper index under index/.

python -m omai.sync

Show the diff between the Python operator layer and the store; --apply lands it through the gates.

python -m omai.semantics [label...]

Rebuild semantics.json and demo resolution of the given labels.

python -m omai.paper_db [--show <slug>]

Rebuild the local bibliography table; --show prints one paper's proposal.

python -m omai.paper_parser <pdf> [--apply --yes]

Parse a PDF into a proposal; apply accepted values.