Product definition
Defines BeforeMetal's purpose, users, reference robots, canonical vocabulary, fidelity profiles, and execution modes.
Section relationships
BeforeMetal is a Rust-native robotics design, simulation, and experiment platform. It allows a roboticist to describe a robot, world, controller, and experiment; compile that description into an explicit fidelity model; execute it reproducibly; and compare results with stated uncertainty and available validation evidence or its explicit absence.
BeforeMetal is not a promise of perfect reality. It is an engineering decision-support system that lets roboticists build and run simulations while keeping model validity limits and supporting evidence visible.
The Portable MVP does not require BeforeMetal or its users to own, fabricate, instrument, or physically test a robot. Analytical references, published experiments, manufacturer data, community datasets, independent reference results, and optional project-specific measurements MAY strengthen a named model's evidence status, but their source class and limitations remain explicit.
Primary users
- Robotics systems engineer — compares hardware, mass, geometry, gearing, batteries, sensors, and payloads.
- Controls engineer — develops and verifies deterministic controllers and actuator behavior.
- ML engineer — trains or evaluates policies across reproducible randomized environments.
- Verification engineer — builds regression suites, uncertainty sweeps, failure cases, and evidence packages.
- Simulation model author — creates reusable robot, device, material, sensor, and environment models.
Reference systems
- Primary reference robot: a versioned, distributable small outdoor wheeled-rover model and reference scenario; an associated physical rover is optional.
- Architecture portability robot: six-degree-of-freedom manipulator.
- Future aerodynamic reference robot: multirotor aircraft.
Canonical vocabulary
These names are normative and deliberately distinguish concepts that are often blurred together.
| Term | Meaning |
|---|---|
| Project | The portable, versioned workspace containing model definitions, assets, scenarios, experiments, and references to results. |
| Canonical Model | BeforeMetal's backend-independent, unit-aware, frame-aware representation of robot and world definitions. |
| Asset | An immutable or revisioned source or derived artifact such as a mesh, texture, controller, dataset, or imported model file. |
| Robot | A modeled physical system composed of bodies, joints, materials, devices, sensors, and controller interfaces. |
| World | The spatial setting containing terrain, objects, fields, atmosphere, weather, and global conventions. |
| Scenario | A reusable pairing of robot, world, initial state, mission, and supported disturbances; it does not select a sweep or create results. |
| Experiment | A versioned plan that selects a scenario, parameters or distributions, controllers, fidelity, seeds, metrics, stop conditions, and execution policy. |
| Compiled Scenario | The immutable, capability-checked execution description produced from an experiment before a run. |
| World Instance | One live mutable execution state created from a compiled scenario. |
| Run | One attempted execution of one compiled scenario with one realized parameter set and seed, whether completed, failed, or cancelled. |
| Batch | A finite set of runs generated by a sweep, repetitions, sampling plan, or explicit run list. |
| Entity | A stable-identity object in the canonical model or committed simulation state. |
| Component | Typed state and behavior attached to or referenced by an entity. |
| Port | A typed, directed connection point with declared units, frame, timing, causality, and cardinality where applicable. |
| Model | A declared mathematical or behavioral approximation with parameters, assumptions, validity limits, and evidence. |
| Solver | An algorithm that advances or resolves the state of a model. |
| Backend | A replaceable implementation of a BeforeMetal subsystem contract, such as a mechanics solver implementation. |
| Adapter | A boundary that maps an external format, protocol, process, device, or solver to canonical BeforeMetal contracts. |
| Sidecar | An adapter or external tool executed in a separately supervised operating-system process. |
| Extension | User- or third-party-supplied behavior attached only through a declared Extension Host capability. |
| Capability | A stable, machine-readable statement of supported behavior, limits, fidelity, and required resources. |
| Fidelity Profile | A named selection of models, solver settings, approximations, and evidence expectations. |
| Fidelity Card | The pre-run or completed-run record of the fidelity actually requested and used, including limitations and out-of-envelope conditions. |
| Calibration | Estimation of model parameters using designated observations. |
| Validation | Comparison of predictions with independent evidence for named observables and operating conditions; the evidence source class is explicit, and physical evidence is optional. |
| Verification | Evidence that equations, algorithms, schemas, and implementations behave as specified. |
| Metric | A versioned, unit-bearing calculation over run state, events, or results. |
| Trace | Timestamped recorded state, signal, event, or diagnostic data from a run. |
| Checkpoint | A restorable state artifact whose completeness and compatibility are explicitly declared. |
| Input Re-execution | A new execution driven by recorded causal inputs and compared with the original under a declared criterion. |
| Checkpoint Resume | Continued execution from a compatible checkpoint after all stateful participants restore their declared state. |
| Recorded-State Playback | Visualization or analysis of stored states without rerunning any solver. |
| Portable product | The default installation and workflow that remains useful without optional engineering integrations. |
| Pure-Rust default | First-party runtime logic and mandatory simulation dependencies are Rust; ordinary operating-system APIs and drivers are not reimplemented, and foreign engineering runtimes are not required. |
The initial fidelity profiles are also named:
| Fidelity profile | Intended use |
|---|---|
| Preview | Low-cost interactive inspection and early design iteration; every reduced model remains disclosed. |
| Engineering | The default design-comparison profile; each capability must meet the profile's declared minimum evidence status, which MAY permit an explicitly unqualified model when its limitations are surfaced. |
| Validation | A study-specific profile with stricter convergence, recording, uncertainty, and evidence requirements; it does not imply universal truth. |
Execution policy is orthogonal to fidelity. The initial execution modes are Deterministic, Throughput, Interactive, and Real-Time; a run manifest records both its fidelity profile and execution mode.
Change rationale (product definition, v0.2): ADR-0001 clarifies that the reference rover is a distributable digital system and that Portable MVP use does not depend on a physical counterpart. Independent and physical evidence remain supported, but every evidence source is classified and no stronger claim is inherited than that evidence can justify.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.