This guide walks through the full authoring cycle: creating a .matr program, compiling it into a Molebyte artifact, validating it in the Material Twin, and submitting it to Material Cloud for governed execution. Matter defines intent. Material Cloud governs operation. The two are designed to work together, but the boundary between them is strict by design.
step 1
Create a project and author .matr source
A Matter project is a directory containing one or more .matr files. Each file defines a matter program: a self-contained unit of logic that describes material definitions, protocol steps, constraints, and expected outcomes. Projects can contain multiple programs that compose into larger workflows.
// hello.matr — a minimal matter program
material HelloSubstrate {
substrate: "sim-default"
concentration: 1.0 mM
}
protocol Synthesize {
step mix {
input: HelloSubstrate
duration: 30s
temperature: 25°C
}
}
constraints {
yield >= 0.85
purity >= 0.95
}
governance {
tier: T0
consequence: "simulation-only"
}This program defines a single material, a one-step protocol, yield and purity constraints, and a governance annotation marking it as simulation-only (T0, the lowest consequence tier). Every .matr program must declare its governance tier explicitly.
step 2
Compile source into a versioned Molebyte
Compilation transforms .matr source into a Molebyte: the deployable artifact format for the Matterforma platform. A Molebyte carries the compiled protocol execution plan, all metadata, substrate bindings, constraint thresholds, and governance annotations in a single versioned, immutable package.
$ mf compile hello.matr
✓ Parsed hello.matr
✓ Resolved substrate bindings
✓ Generated Protocol Execution Plan
✓ Attached governance annotations (T0)
✓ Molebyte written: hello.molebyte (v1.0.0, sha256:a3f8...)
The compiler validates syntax, resolves substrate references, generates the Protocol Execution Plan (PEP), and packages everything into the Molebyte. If constraints are unsatisfiable or governance annotations are missing, compilation fails with actionable diagnostics.
step 3
Validate in the Material Twin
Before any Molebyte reaches physical substrates, it must pass through the Material Twin. The Material Twin executes the Protocol Execution Plan against a digital twin of the target substrate and validates that all declared constraints are satisfiable. Simulation produces signals, confidence bounds, and a pass/fail determination.
$ mf simulate hello.molebyte
Material Twin simulation against substrate: sim-default
Step [mix]: duration=30s, temp=25°C
Yield estimate: 0.91 ± 0.03
Purity estimate: 0.97 ± 0.01
✓ All constraints satisfied
✓ Governance tier T0: no approval required
✓ Simulation passed — artifact eligible for execution
The Material Twin is not optional. It is the primary safety mechanism in the Matter authoring model. Programs that fail simulation cannot be submitted to Material Cloud for execution. Programs that pass carry their simulation results as provenance metadata in the Molebyte.
step 4
Submit to Material Cloud for policy-bound execution
Submission is the handoff from Matter Studio (authoring) to Material Cloud (governance and execution). When a Molebyte is submitted, FORMA evaluates it against organizational policy: consequence tier, approval requirements, execution profile eligibility, and facility availability. If all checks pass, the Molebyte enters the execution queue.
$ mf submit hello.molebyte --profile default
✓ Policy check passed (T0, no approval required)
✓ Execution profile: default
✓ Pool: sim-default (available)
✓ Run ID: run_a3f8e2...
✓ Status: queued → executing → complete
Signals available: mf signals run_a3f8e2
After execution, signals are available for review. Signals are structured outputs, not logs: they include outcome distributions, confidence bounds, cost accounting, and provenance. The full cycle from .matr source to observable signals is the core workflow of the Matterforma platform.
