Section 10Simulation Runtime
Mechanics System requirements
Defines the Rust-native rigid and articulated mechanics contract, contact behavior, dynamic-analysis queries, diagnostics, and future mechanics backends.
Section relationships
| ID | Name | Priority | Requirement | Verification |
|---|---|---|---|---|
| MECH-001 | Double-precision baseline | MVP | The default engineering mechanics path SHALL support 64-bit floating-point state and parameters. | Test |
| MECH-002 | Rust-native default backend | MVP | The portable distribution SHALL provide a Rust-native mechanics backend that passes the MVP mechanics conformance and qualification suites. | Demonstration |
| MECH-003 | Body modes | MVP | The default backend SHALL support dynamic, static, and kinematic rigid bodies. | Test |
| MECH-004 | Mass properties | MVP | Mechanics SHALL use explicit mass, center of mass, and positive-definite inertia tensor for dynamic bodies. | Test |
| MECH-005 | External wrench | MVP | A device or environment model SHALL be able to apply force and torque to a body at a specified frame and point. | Test |
| MECH-006 | Collision primitives | MVP | The default backend SHALL support box, sphere, capsule, and cylinder collision shapes. | Test |
| MECH-007 | Convex collision | MVP | The default backend SHALL support convex collision geometry. | Test |
| MECH-008 | Static mesh collision | MVP | The default backend SHALL support documented static triangle-mesh and terrain collision use. | Test |
| MECH-009 | Continuous collision detection | MVP | Bodies explicitly configured for continuous collision detection SHALL use it for the backend's documented velocity, shape, and timestep envelope. | Test |
| MECH-010 | Fixed joint | MVP | Mechanics SHALL support a fixed relative constraint between two bodies or a body and world. | Test |
| MECH-011 | Revolute joint | MVP | Mechanics SHALL support a one-axis revolute joint with limits, viscous damping, and drive input. | Test |
| MECH-012 | Continuous joint | MVP | Mechanics SHALL support an unlimited one-axis rotational joint. | Test |
| MECH-013 | Prismatic joint | MVP | Mechanics SHALL support a one-axis translational joint with limits, viscous damping, and drive input. | Test |
| MECH-014 | Ball joint | Beta | Mechanics SHALL support a three-axis rotational joint with documented limit behavior. | Test |
| MECH-015 | Articulated tree | MVP | The default backend SHALL simulate a tree-structured articulated robot. | Test |
| MECH-016 | Closed-loop mechanism | Beta | At least one mechanics backend SHALL support documented closed kinematic loops or loop-closing constraints. | Test |
| MECH-017 | Joint state | MVP | Mechanics SHALL expose joint position, velocity, applied command, limits, and available reaction information. | Test |
| MECH-018 | Joint drive | MVP | The default backend SHALL support documented position, velocity, and effort joint-drive modes with explicit command and effort limits. | Test |
| MECH-019 | Contact generation | MVP | Mechanics SHALL expose contact point, normal, penetration or separation measure, involved shapes, and available impulse or force estimate. | Test |
| MECH-020 | Surface friction | MVP | Contact response SHALL use explicit surface or material-pair friction parameters and a documented combination rule. | Test |
| MECH-021 | Restitution | MVP | Contact response SHALL support a documented coefficient-of-restitution model and combination rule. | Test |
| MECH-022 | Wet-friction contact update | MVP | The default mechanics contract SHALL accept committed material-pair friction updates derived from surface wetness at documented scheduling boundaries. | Test |
| MECH-023 | Compliant contact | Beta | At least one engineering profile SHALL support a calibrated compliant-contact model for documented applications. | Analysis |
| MECH-024 | Advanced friction | Future | An engineering backend MAY support separate static and dynamic friction, Stribeck behavior, anisotropy, rolling resistance, and torsional resistance. | Analysis |
| MECH-025 | Collision filtering | MVP | A model SHALL be able to enable or suppress collision by explicit groups and pair rules. | Test |
| MECH-026 | Scene queries | MVP | The mechanics contract SHALL support ray casts, shape casts, and overlap queries required by sensors and tools. | Test |
| MECH-027 | Contact events | MVP | The mechanics backend SHALL produce deterministic contact-begin, current-contact, and contact-end observations under a documented policy. | Test |
| MECH-028 | Solver convergence diagnostics | MVP | Each default-backend step SHALL expose actual iteration counts, at least one documented convergence or constraint-error residual, joint error, maximum penetration, active-constraint count, iteration-limit hits, stabilization settings, and the applied unconverged-step warning or failure policy. | Test |
| MECH-029 | Energy diagnostics | MVP | The default mechanics backend SHALL expose kinetic and potential energy diagnostics sufficient for the approved analytical and reference-rover benchmarks. | Analysis |
| MECH-030 | Backend snapshot contract | MVP | The selected default mechanics backend SHALL participate in complete kernel checkpoint and restore. | Test |
| MECH-031 | Mechanics capability report | MVP | A backend SHALL report supported shapes, joints, contacts, precision, determinism, snapshot, and diagnostic capabilities. | Inspection |
| MECH-032 | Second-backend conformance | Beta | Any second production mechanics backend SHALL pass the shared mechanics capability and benchmark suite before release. | Analysis |
| MECH-033 | Deformable body backend | Future | BeforeMetal MAY support beams, shells, cables, or volumetric deformables through a capability-scoped backend. | Analysis |
| MECH-034 | Granular and soil backend | Future | BeforeMetal MAY support granular media and deformable terrain through a capability-scoped backend. | Analysis |
| MECH-035 | Structural failure | Future | BeforeMetal MAY support calibrated yield, damage, breakage, fatigue, and fracture models with explicit validity limits. | Analysis |
| MECH-036 | Derived mass properties | MVP | BeforeMetal SHALL derive mass, center of mass, and inertia from supported closed geometry and assigned density when requested, while retaining any explicit user override. | Analysis |
| MECH-037 | Compound rigid body | MVP | A rigid body SHALL support multiple collision shapes and their local transforms without requiring artificial fixed joints. | Test |
| MECH-038 | Force contribution diagnostics | Beta | A user SHALL be able to inspect supported force and torque contributions by source, including gravity, contact, devices, and environment loads. | Analysis |
| MECH-039 | General contact modification | Beta | At least one Engineering-profile mechanics backend SHALL expose capability-checked contact modification based on material, direction, temperature, speed, pressure, or other committed state. | Test |
| MECH-040 | Evidence-declared wheel-terrain model | MVP | The reference rover SHALL use a documented wheel-terrain model covering longitudinal and lateral slip, rolling resistance, normal load, speed, wetness, parameter and evidence provenance, qualification status, and validity limits for the accepted mission envelope. | Analysis |
| MECH-041 | Dynamic-analysis coordinate contract | Beta | Every mechanics analysis request and result SHALL identify its source compiled scenario, committed state, and virtual time; ordered generalized position, tangent-velocity, acceleration, and force coordinates; canonical entity and degree-of-freedom mappings; units; frames or bases; and sign convention. | Test |
| MECH-042 | Generalized mass matrix | Beta | At least one portable General Robotics Beta mechanics profile SHALL expose a backend-neutral generalized mass-matrix query for a declared state and declared constraint and contact treatment using the MECH-041 coordinate contract. | Analysis |
| MECH-043 | Bias and gravity decomposition | Beta | At least one portable General Robotics Beta mechanics profile SHALL separately expose velocity-dependent inertial-bias and gravity generalized-force terms under a declared equation convention and SHALL identify whether passive, actuator, contact, constraint, and external-load terms are excluded or reported separately. | Analysis |
| MECH-044 | Generalized-force mapping | Beta | At least one portable General Robotics Beta mechanics profile SHALL map named body wrenches and joint loads to generalized forces and SHALL report included device, environment, contact, and constraint contributions separately by source where supported. | Analysis |
| MECH-045 | Inverse dynamics | Beta | At least one portable General Robotics Beta mechanics profile SHALL compute required generalized effort from a declared state, requested generalized acceleration, and supported external loads and SHALL report equation convention, contact and constraint treatment, residual and status, and unavailable contributions. | Analysis |
Change rationale (MECH-040): A calibrated model remains permitted, but requiring project-specific calibration would reintroduce a physical-test dependency. The reference model now discloses whatever analytical, published, manufacturer, community, independent, or optional empirical evidence supports its parameters.
Change rationale (MECH-041–MECH-045): Simulation execution alone does not expose the engineering quantities needed for model analysis, controls design, and system identification. The coordinate, mass, force-decomposition, force-projection, and inverse-dynamics obligations are independently falsifiable and therefore remain separate. At least one portable qualified profile must implement them, while alternate backends retain honest capability declarations rather than universal parity.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.