tmepass000/matter-os

MATTER OS (prototype 0.1.0)

A standalone, local-first, evidence-first research environment for generating, screening, simulating and grading candidate atomic, molecular and material structures. It is a Python modular monolith built from MATTER OS Master Specification v1.0.

Core rule: unrestricted hypothesis generation; constrained, reproducible, evidence-driven claims. The software reports the strongest evidence it actually holds (M0 to M3). M4 (experimentally confirmed) needs real laboratory evidence and is never assigned by simulation.

What works (short version)

• Unified representation (composition, typed graph, geometry/cell/symmetry, conditions, lineage) with XYZ/CIF/SDF round-trip.
• Reversible, lineage-tracked transformations; seeded random, guided, evolutionary and adaptive search; Pareto ranking with an exploration reserve.
• Six real solver adapters behind one contract: ASE EMT, Lennard-Jones, Langevin MD, harmonic stat-mech, PySCF HF and DFT. Nine more engines (xtb/tblite, QE, CP2K, Psi4, LAMMPS, GROMACS, OpenMM, field, FEM) are labelled stubs that return NOT_SUPPORTED.
• Isolated job runner: separate worker processes, CPU limit, RAM watchdog, wall-time limit, cancel, checkpoint/resume, retries, crash recovery.
• Immutable, checksummed and HMAC-signed run records; provenance on every datum; project archives that rebuild inputs, configs, versions and results.
• Uncertainty records (5 components), novelty relative to searched sources, M0-M3 gates with traces, a governed knowledge graph (proposed, provisional, verified, contradicted, deprecated).
• 13 named rule-based agents plus dynamic agents, task contracts, tool allowlists, memory, messages, debate, evaluation; the LLM interface is a labelled stub.
• FastAPI exposing every section-14 operation, plus a single-page dashboard with an offline 3D structure viewer.
• Benchmarks reproduced: EMT Cu lattice constant, LJ13 and LJ38 global minima, H2 RHF/STO-3G.

Full detail and honest gaps: docs/STATUS_MATRIX.md.

Install

cd matter-os
pip install -e ".[all]"        # numpy scipy ase pydantic fastapi uvicorn pyyaml spglib psutil + rdkit pyscf pytest httpx

Optional extras: chem (RDKit, needed for SDF and the graph grammar) and quantum (PySCF). Without them the related features return UNSUPPORTED_METHOD.

Run

python -m matter_os.demo                 # end-to-end: goal -> generate -> screen -> simulate -> grade -> report (~65 s on 2 CPUs)
python -m matter_os.demo --quick         # cluster mission only (~10 s)
python -m pytest                         # 89 tests (~30 s)
uvicorn apps.api:create_app --factory --port 8000    # API + dashboard at http://127.0.0.1:8000/ (OpenAPI at /docs)
python scripts/run_benchmarks.py         # reproduce registered benchmarks
python scripts/active_learning_benchmark.py         # Phase-6 measurement (AL vs random)

Runtime data goes to $MATTER_OS_HOME/var/ (default: the repo root). The demo writes reports, a JSON summary and a project archive to var/demo_output/.

Layout (spec section 16)

configs/        app, resource policy, solver registry, evidence gates
docs/           architecture, methods, API, status matrix, ADRs, changelog, resources, benchmarks
apps/           FastAPI server (api.py) and dashboard (dashboard/index.html)
core/           schemas, units, elements, representation, constraints, lineage, provenance, io, errors
discovery/      generators, transformations, search, optimization, archives, active learning, candidate service
simulation/     contract, registry, router, adapters/, convergence, benchmarks, service
agents/         coordinator + runtime, 12 specialists, dynamic agents, memory, messaging, debate, evaluation, meta, LLM stub
orchestration/  missions, scheduler, jobs (queue + runner), queues, checkpoints, resources, failures
knowledge/      graph, governance, provenance, ingestion, service
evidence/       uncertainty, novelty, maturity, replication, reports, service
storage/        SQLite db + migrations, repositories, artifact store, archives/snapshots, indexes
visualization/  viewer payloads, dashboard data, static/viewer.js
matter_os/      app container, config loader, CLI, demo
tests/          unit, integration, scientific, reproducibility, security
examples/       small scripts using the Python API
scripts/        benchmark runners

Honest limitations

• Accuracy is method-limited: EMT and LJ are model potentials; HF/STO-3G is a minimal-basis method. Every claim says which method produced it.
• "Independent replication" with the same engine counts as M3 evidence under the configured gates. The claim records the limitation "same engine; not an independent code".
• Novelty is relative to the bundled ASE reference set and the project's own candidates only.
• Active learning is implemented but showed no measured improvement over random selection in our test.
• The dashboard was served and API-tested but not visually inspected (no headless browser available here).
• Process-level isolation only (no containers or seccomp). Signatures are local HMAC integrity checks, not PKI.

License

MATTER OS code: MIT. Third-party components keep their own licenses; see LICENSES_AND_ATTRIBUTION.md.