Install

The map data is public and needs no install: fetch the JSON under docs/data/. To run the kernel, clone the commons and install the package in editable mode.

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

The kernel is Apache 2.0; the map data is CC BY 4.0. Cite the map version (docs/data/version.json) your work used; see CITATION.cff. A repository can state its pin as a badge, the way a CI badge states a build: 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/)

The three parts

openmaterials is one map in three parts. The commons (the versioned graph, its evidence, the protocol, the kernel) is stewarded by the OpenMaterials-AI initiative and licensed for open reuse. The interfaces (the map views, the playground, the codes bibliography) and the improvement engine (the paper parser, the scan agents) are built on top of the commons. The boundary rule: the commons owns the ledger and its laws; tools and products are built on top. See GOVERNANCE.md.

Resolve a label

The semantic layer turns fuzzy natural-language method names into typed, content-addressed identities. This is the loop the playground's query tab renders live.

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 is an honest coverage gap, not an error: a phrase the map has no home for feeds the encode queue.

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 dimensional layer is verified in Lean: python -m omai.physlean_export generates a PhysLean file where each node is a Dimension and each dimension-proven edge is a theorem. It compiles against PhysLean (Lean 4.29.1); the map and playground show the Lean for the element you select (green check). Two further Lean files are generated and compile: OpenMaterialsIdentities.lean proves the chained thermodynamic identities (ZT through the power factor, C_P through the molar volume) equal their expanded forms, and OpenMaterialsUnits.lean anchors the map's SI convention against PhysLean's unit-conversion structure.

Export a sub-map as Mermaid

Any derivation or map view renders natively wherever markdown does (GitHub, issues, PRs): the playground's Map tab has a Copy as Mermaid button, and the exporter runs from Python:

from omai.mermaid import mermaid_lineage

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

Parse a paper

The paper parser reads a PDF and proposes values for the map, each backed by a verbatim quote and a page anchor, validated against the map and adversarially reviewed before a human accepts them. Try it in the browser on the playground's Learn tab, or run 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 parser needs an Anthropic API key in a repo-root .env (never logged, never committed). The browser Learn tab runs on the project's key behind a cost-gated relay, so no key is needed to try it.

Data contract

The published artifacts under docs/data/, all regenerated by python -m omai.map_data from the operator layer:

CLI reference

Each entry runs on invocation (regenerating artifacts or printing a report); none takes flags except the parser.