MESS-Materials

This repository is a downstream mirror. Source of truth lives in the messai-ai monorepo; this mirror is updated on each release. Issues and Discussions are welcome here. PRs against this mirror will be redirected — see CONTRIBUTING.md.

History was reset as part of the 2026 monorepo consolidation. Versions tagged before that (e.g. v0.2.0) remain accessible as historical refs.

DFT-computed material properties for Microbial Electrochemical Systems (MES) components — electrodes, membranes, chambers, current collectors, catalysts, gaskets, and supports. A sidecar to Messai-io/MESS-Parameters, keyed by the same material slugs.

⚠️ Attribution required (Materials Project, CC-BY-4.0)

All property data in data/mp-materials-rich.json is derived from the Materials Project under CC-BY-4.0. Any downstream use — paper, report, or product UI — that displays these values must cite:

Jain, A., Ong, S. P., Hautier, G., Chen, W., Richards, W. D., Dacek, S., Cholia, S., Gunter, D., Skinner, D., Ceder, G., & Persson, K. A. (2013). Commentary: The Materials Project: A materials genome approach to accelerating materials innovation. APL Materials, 1(1), 011002. https://doi.org/10.1063/1.4812323

A link to https://materialsproject.org must accompany any visible MP-derived field. Full terms in data/SCIENTIFIC_INTEGRITY.md.

What this repo is

MESS-Parameters owns the MES parameter ontology and literature extractions. For each material-named parameter slug in that ontology (carbon_cloth, nafion_membrane, platinum_cathode, anion_exchange_membrane, …), this repo publishes the DFT-computed physical properties pulled from the Materials Project (MP) and related open databases:

• Summary properties: band gap, formation energy, energy above hull, density, metallicity.
• Pourbaix stability at MES operating conditions (MFC anode, MFC cathode, MEC cathode).
• Crystal structure (CIF) — reserved for later ML feature extraction.
• Later (v0.2+): elasticity tensors, surface energies, composite scores (EVS / BCS / LSS).

What this repo is not

• Not a replacement for MESS-Parameters. The parameter ontology, extraction corpus, and literature-value database stay there.
• Not a source of experimental data. Everything here is computed from first principles or derived from DFT databases. Experimental values belong in MESS-Parameters.
• Not an ML training repo. MACE / CHGNet / EquiformerV2 embedding and transfer-learning work lives in MESS-Learning. This repo publishes the structures those models consume, not the models themselves.

How it connects to MESS-Parameters

MESS-Parameters (tag v0.2.0)              MESS-Materials (this repo, tag v0.1.0)
  parameter-definitions-rich.json   ◄── slug join key ──►  mp-materials-rich.json
  (narrative, extractions, slugs)                          (DFT properties)

MESS-Parameters is not modified by this project. Its v0.2.0 schema stays frozen. The join happens in downstream consumers (messai-ai) by matching slugs across both rich.json files.

See also: cross-package joins — how to join parameter observations, material DFT properties, microbe records, and physics validation by slug / canonical ID.

See docs/plans/v0.1-mp-ingest.md for the full producer plan and docs/consumer-contract.md (arriving with v0.1.0-pilot) for the shape downstream consumers can depend on.

Status

v0.1+ — data populated. Verified against origin/development @ 6890797a0 on 2026-05-13. The status line above ("v0.0 scaffolding, no data yet") was stale.

Data inventory

File	Records	Correct verification
data/mp-materials-rich.json	44 materials as of 2026-05-13 — verify before quoting (Pt, Cu, Ni foam, stainless steel, carbon cloth/felt/paper/brush, MnO₂, Fe₃O₄, MoS₂, MoC, MXenes Ti₃C₂Tₓ/Nb₂CTₓ/V₂CTₓ, BDD, TiO₂, etc. — DFT + elasticity + surface + Pourbaix + paper-crossref)	jq '.materials | length' data/mp-materials-rich.json
data/mess-material-slugs.json	36 slugs declared	jq '.slugs | length' data/mess-material-slugs.json
data/unmapped-materials.json	8 deferred (PEM, AEM, bipolar membrane, polymer coatings, etc. — out-of-scope for DFT)	jq '.unmapped | length' data/unmapped-materials.json
data/slug-to-mp.yaml	Materials Project ID mappings	Read file
data/material-paper-crossref.json	Paper cross-reference DB	Read file
data/pourbaix-results.json	Pourbaix stability per material	Read file
data/mp-cache/, mp-cache-elasticity/, mp-cache-surfaces/	Raw Materials Project API responses per mp_id	Per-file JSON
data/SCIENTIFIC_INTEGRITY.md	Quality caveats + CC-BY-4.0 attribution	Read file

Common audit mistake: jq 'length' data/mp-materials-rich.json returns 4 (count of top-level keys: generated_at, materials, mess_parameters_tag, schema_version). That is not the material count. Use jq '.materials | length' for the actual record count (44 as of 2026-05-13; grows as curators add materials). Same trap for mess-material-slugs.json and unmapped-materials.json.

mp-materials-rich.json structure

The top level is an object with schema_version, generated_at, mess_parameters_tag, and a materials array. Each entry in materials has the following shape (verified against the 2026-05-13 snapshot):

Field	Type	Meaning
slug	string	Join key — the MESS-Parameters material slug (e.g. platinum_cathode, carbon_cloth)
components[]	array	One or more MP structures: { mp_id, role, loading, proxy, formula }. mp_id is the Materials Project ID; proxy: true = crystalline stand-in for a disordered real material
confidence_tier	high|medium|low	DFT-match confidence (see SCIENTIFIC_INTEGRITY.md)
mp_snapshot_date	string	Date the MP data was pulled
mp_functional_default	string	DFT functional (e.g. PBE)
band_gap_eV	number	Band gap
is_metal	boolean	Metallicity
formation_energy_eV_per_atom	number	Formation energy
energy_above_hull_eV_per_atom	number	Thermodynamic stability (0 = on the convex hull)
density_g_per_cm3	number	Mass density
total_magnetization_uB	number	Total magnetization (Bohr magnetons)
pourbaix	object	Stability at MES conditions: mfc_anode, mfc_cathode, mec_cathode, each { state, stable_phase, decomposition_energy_eV, notes }
elasticity	object | null	{ bulk_modulus_GPa, shear_modulus_GPa, youngs_modulus_GPa, poissons_ratio, universal_anisotropy, debye_temperature_K, source_functional } (present on ~35/44)
surface	object | null	{ weighted_surface_energy_J_per_m2, work_function_eV, surface_anisotropy, shape_factor, has_reconstructed, source_functional } (present on ~28/44)
structure_cif	string	Crystal structure as CIF text
paper_cross_reference	object	Pre-computed corpus summary: { paper_count, year_range, system_type_distribution, power_output_median_mW_per_m2, efficiency_median_pct, … }
notes	string | null	Curator note

elasticity and surface are null when the property was not computed for that material; always null-check before reading their subfields.

Query guide

Everything is a single JSON file, so filtering is a plain array operation.

import json

data = json.load(open("data/mp-materials-rich.json"))
materials = data["materials"]

# 1. Look up a material's Materials Project IDs by slug
by_slug = {m["slug"]: m for m in materials}
print(by_slug["carbon_cloth"]["components"])  # [{"mp_id": "...", "proxy": true, ...}]

# 2. Filter: metallic electrodes that are on the convex hull (most stable)
stable_metals = [
    m for m in materials
    if m["is_metal"] and m["energy_above_hull_eV_per_atom"] == 0
]
print(f"{len(stable_metals)} stable metallic materials")

# 3. Filter: materials stable as an MFC anode (Pourbaix)
mfc_anode_stable = [
    m for m in materials
    if m["pourbaix"]["mfc_anode"]["state"] == "stable"
]
print([m["slug"] for m in mfc_anode_stable])

# 4. Rank by DFT stiffness (guard the nullable elasticity block)
stiff = sorted(
    (m for m in materials if m.get("elasticity")),
    key=lambda m: m["elasticity"]["youngs_modulus_GPa"],
    reverse=True,
)
print([(m["slug"], m["elasticity"]["youngs_modulus_GPa"]) for m in stiff[:5]])

The equivalent one-liners with jq:

# Materials Project IDs for one slug
jq '.materials[] | select(.slug=="carbon_cloth") | .components[].mp_id' data/mp-materials-rich.json

# Slugs stable as MFC anodes
jq -r '.materials[] | select(.pourbaix.mfc_anode.state=="stable") | .slug' data/mp-materials-rich.json

Dual storage

In addition to this package's data, the messai-ai monorepo has a richer runtime catalog at apps/web/src/app/lab/components/electrode-catalog.ts (1190 lines, 141 physics-field references) with Phase B/C electrochemistry fields (exchange current density, Tafel slope, transfer coefficient, ASR, double-layer capacitance) + organism-affinity tags + cost/embodied-carbon metadata. There are also 28 per-material JSON files at apps/web/public/data/materials/*.json (DFT + Pourbaix, snapshot 2026-05-06).

Source-of-truth architectural decision pending (Stream Z-B.1 in ~/.claude/plans/i-think-we-need-radiant-castle.md): consolidate the rich electrode-catalog.ts data into this open-source package, OR formally keep the app-level catalog as runtime source and document this package as DFT-properties-only.

Sibling historical snapshot

An older snapshot of this package lives at /Users/samfrons/repos/mess-materialsv1/ (separate repo, not a worktree). That version has 18 materials, 26 slugs, 8 unmapped. Useful for diffing against the current state if a regression is suspected.

Licensing

• This repo's curated data is licensed CC-BY-4.0.
• Upstream Materials Project data is also CC-BY-4.0 — any downstream consumer displaying MP-derived values must credit the Materials Project per CC-BY-4.0 terms. The required citation and attribution template are in data/SCIENTIFIC_INTEGRITY.md (and reproduced in the callout at the top of this README).

Layout

data/           canonical JSON artifacts (rich.json, pourbaix results, lock file)
data/mp-cache/  raw MP API responses, checked in for reproducibility
schemas/        JSON Schema definitions for all published artifacts
scripts/        Python ingestion + computation pipeline
docs/           plans, consumer contract, methodology
ci/             schema validation + slug-coverage enforcement

Getting involved

This repo is part of the Messai-io open-source ecosystem for microbial electrochemical systems. Issues and PRs welcome once v0.1.0-pilot lands.