UpstreamDrift Engine Protocol Reference
UpstreamDrift is the implementation authority for the control-affine decompositions AffineDrift motivates. This page records what the code does at one commit, not every narrative shortcut on this site. All UpstreamDrift evidence links below use 625a16e6897b88ab29fb5a64c65ecee820dd58f5 (re-checked 2026-11-11 for issue #5620).
For array layouts, frames, and quaternion order when moving state between engines, see the merged UpstreamDrift Conventions Reference (pages/upstreamdrift-conventions.qmd). AffineDrift’s programming catalog remains Engines and Runtime Support.
The PhysicsEngine Contract
The suite-wide entry point is the PhysicsEngine protocol. It composes SimulationInterface (load, step, state I/O) and DynamicsInterface (mass matrix, bias, Jacobians, drift/control).
State machine (from the interface docstring): UNINITIALIZED → load → INITIALIZED → reset/step/forward.
Core Method Table
| Responsibility | Method | Typical signature / return | Units / shapes |
|---|---|---|---|
| Load | load_from_path(path: str) |
None |
Path must exist; formats include .xml, .urdf, .sdf, .osim per docstring |
| Load | load_from_string(content, extension=None) |
None |
Model definition string |
| Time | reset() |
None |
t → 0, initial (q₀, v₀) |
| Time | step(dt: float \| None = None) |
None |
dt in seconds; None uses the model or engine default (see §Defaults) |
| Kinematics | forward() |
None |
Updates derived quantities without advancing t |
| State | get_state() |
(q, v) |
q: (n_q,), v: (n_v,) SI generalized coordinates / speeds |
| State | set_state(q, v) |
None |
Matching lengths; triggers forward in implementations |
| Control | set_control(u) |
None |
u: (n_u,) torques or actuator commands |
| Time query | get_time() |
float |
Seconds, ≥ 0 |
| Inertia | compute_mass_matrix() |
M |
(n_v, n_v), SPD |
| Bias | compute_bias_forces() |
h |
(n_v,) Coriolis, centrifugal, gravity |
| Gravity | compute_gravity_forces() |
g |
(n_v,) |
| Inverse dynamics | compute_inverse_dynamics(qacc) |
τ |
τ = M(qacc) + h |
| Jacobian | compute_jacobian(body_name) |
dict or None |
Keys linear, angular, spatial; spatial rows [angular; linear] per SPATIAL_JACOBIAN_ORDER |
| Drift | compute_drift_acceleration() |
a_drift |
(n_v,), rad/s² or m/s² |
| Control | compute_control_acceleration(tau) |
a_control |
(n_v,) |
| Counterfactual | compute_ztcf(q, v), compute_zvcf(q) |
accelerations | Legacy names: see §PhysicsEngine Counterfactual Names; compute_zvcf is not site ZVCF |
| Checkpoint | save_checkpoint / restore_checkpoint |
varies | Via Checkpointable on SimulationInterface |
| Features | get_capabilities() |
EngineCapabilities |
Optional UI/API feature gating |
Bias meaning: inverse dynamics implements τ = M(q̈) + h(q, v) where h is the bias from compute_bias_forces(). Drift and control split acceleration q̈, not torque directly.
Capability levels: get_capabilities() reports per-feature support (FULL, PARTIAL, NONE, …) in capabilities.py. The interface docstring states a design goal a_full ≈ a_drift + a_control, but implementations differ when constraints or contacts are active (§Drift vs control).
Minimal Usage Pattern
Every engine follows the same call pattern after install in an UpstreamDrift checkout:
# Pattern (UpstreamDrift repo root on PYTHONPATH); paths are repository-relative.
from pathlib import Path
engine = MyEngineClass() # MuJoCo, Drake, Pinocchio, Pendulum, OpenSim, MyoSuite, …
engine.load_from_path(str(Path("src/engines/physics_engines/mujoco/models/simple_pendulum.xml")))
engine.reset()
q, v = engine.get_state()
engine.set_state(q, v)
engine.forward()
a_drift = engine.compute_drift_acceleration()
a_ctrl = engine.compute_control_acceleration(tau=engine.compute_mass_matrix() @ (0.1 * v))Pendulum Engine (Lowest Dependency)
The analytical double-pendulum engine lives under pendulum_physics_engine.py. get_state() returns q = [θ₁, θ₂], v = [ω₁, ω₂] in radians and rad/s (get_state). Default step() size when dt is None: 0.01 s (step).
ode Simulation Backend (Club Double Pendulum)
For rollouts without loading a full PhysicsEngine, the ode backend in simulation_backends wraps the same golf parameters as MuJoCo/MJX:
from src.shared.python.simulation_backends import GolfModelParams, make_backend
params = GolfModelParams.default()
backend = make_backend("ode", params)
trace = backend.rollout(controls=None, horizon=200, dt=0.005) # always pass dt explicitlyModule map and backend choice table: simulation_backends/README.md.
CLI Rollout Harness
src/sim_run/engine_run.py loads a named engine, load_from_string, reset, then step(timestep) with an explicit timestep argument — mirroring the advice to never rely on implicit defaults for cross-engine studies.
What Is Inside Drift and Control?
The suite documents a Section F split: drift is “passive” acceleration with actuation cleared; control isolates the increment attributable to applied τ. The passive term is not the same physical sum in every engine.
| Engine | Drift implementation (code) | Control implementation | Active contact / equality in drift? | Superposition a_drift + a_control = a_full |
|---|---|---|---|---|
| MuJoCo | mj_forward with ctrl=0, external wrenches cleared; reads qacc (compute_affine_drift) |
a_full(τ) - a_drift via constrained forward (compute_control_acceleration) |
Yes when constraints/contacts active | No under active contacts/equalities (docstring at compute_control_acceleration) |
| Drake | -M⁻¹ bias from CalcInverseDynamics at qacc=0 (_passive_acceleration) |
M⁻¹ τ (compute_control_acceleration) |
No contact solver in this path | Holds for unconstrained plant context |
| Pinocchio | pin.aba(model, data, q, v, τ=0) (compute_drift_acceleration) |
M⁻¹ τ |
No built-in contact in ABA path | Unconstrained models |
| OpenSim | -M⁻¹ * compute_bias_forces() with muscles cleared (compute_drift_acceleration) |
M⁻¹ τ |
Muscle / passive forces in bias | Pointwise; ZTCF uses realizeAcceleration (_zero_control_udot) |
| MyoSuite | MuJoCo forward with ctrl=0 (_drift_control.py) |
M⁻¹ τ |
Same family as MuJoCo | Same caveats as MuJoCo |
| Pendulum | Analytical passive dynamics (compute_drift_acceleration) |
M⁻¹ τ |
N/A | Teaching models |
| Putting green | Rolling + slope drift (shared_engine.py) |
τ / m |
Rolling resistance in drift | Specialized 2-D ball model |
| Simscape adapter | Deferred stub | Deferred stub | N/A | Not available (adapter.py) |
| JaxSim | Not verified in this pass | Not verified in this pass | — | See UpstreamDrift docs/engines/jaxsim.md |
Constrained superposition: when welds, loops, or contacts participate in forward dynamics, use the constraint-aware helpers in constrained_ztcf_zvcf.py (covered by unit tests under tests/unit/simulation_backends/). The unconstrained M⁻¹ τ control term is not additive with MuJoCo drift under active constraints.
ZTCF / ZVCF: at a fixed state, UpstreamDrift defines ZTCF as the drift component and ZVCF as M⁻¹ τ with velocity and gravity terms zeroed; the split is exact pointwise but not additive over trajectories (simulation_backends/README.md).
PhysicsEngine Counterfactual Names Versus AffineDrift Notation
AffineDrift’s Notation Reference pins ZVCF to the pointwise control acceleration \(M^{-1}\tau\) (equivalently \(M^{-1}Bu\) at \(\dot q=0\) with gravity excluded from the control operand). UpstreamDrift’s PhysicsEngine protocol reuses older method names; they do not all match that contract.
| Reader goal | AffineDrift term | UpstreamDrift API at this commit | Caution |
|---|---|---|---|
| Pointwise drift at fixed state | ZTCF (drift) | compute_ztcf(q, v) or compute_drift_acceleration() |
Must match engine’s passive definition (table above) |
| Pointwise control acceleration | ZVCF (\(M^{-1}\tau\)) | compute_control_acceleration(tau) |
Preferred when \(\tau\) is explicit |
| Same ZVCF in simulation backends | ZVCF (\(M^{-1}\tau\)) | simulation_backends/ztcf_zvcf.py |
Canonical module for the NOTATION definition |
| Zero-velocity bias acceleration | zero-velocity baseline (not ZVCF) | compute_zvcf(q) |
Returns \(q̈\) with \(\dot q=0\) and \(u=0\) — do not call ZVCF on this site |
Calling compute_zvcf(q) and labeling the result “ZVCF” will not reconstruct \(\ddot q \approx a_{\mathrm{ZTCF}}+a_{\mathrm{ZVCF}}\) under AffineDrift notation.
Integrator and Timestep Defaults
Always pass dt explicitly when comparing engines or publishing trajectories. Defaults differ:
| Source | Default step | Integrator notes | Evidence |
|---|---|---|---|
| Suite constant | 0.001 s | DEFAULT_TIME_STEP |
core/constants.py |
| MuJoCo golf / myo models | 0.002 s, RK4 | Per-model <option timestep="…" integrator="RK4"/> |
e.g. golfer.xml |
| MuJoCo simple pendulum | 0.01 s | Default MuJoCo integrator | simple_pendulum.xml |
| Pinocchio engine | Uses suite DEFAULT_TIME_STEP for stepping; integrator="rk4" default, semi_implicit optional |
PinocchioPhysicsEngine.__init__ |
|
| OpenSim engine | _time_step = 0.01 s |
Simbody manager step | opensim_physics_engine.py |
| Pendulum engine | 0.01 s if step(dt=None) |
Analytical RK inside dynamics | pendulum_physics_engine.step |
| Drake | Discrete plant per model | Set at URDF/SDF load | Model-dependent |
ode / mujoco backends |
Caller-supplied dt only |
No implicit default in rollout |
README.md usage |
Contact Parameters and Models
Qualitative differences and test tolerances are documented in docs/conventions/contact_models.md (MuJoCo soft contact penetration tol 5e-3 m, Drake rigid/compliant 1e-3 m, Pinocchio constraint-based).
Representative MuJoCo MJCF defaults in golf model generators:
condim="3"andfriction="0.9 0.005 0.0001"on default geoms (models_advanced.py,urdf_parser.py).
Ground contact for soft-feet biomechanics models often uses condim="3" with friction="0.9 0.8 0" on foot contact spheres in bundled MyoSuite golf MJCF (golfer_myobody_driver.xml).
Pinocchio has no turnkey contact drift path in the ABA wrapper above; contact-heavy studies should prefer MuJoCo (or Drake hydroelastic / point contact, per contact_models.md).
Choosing an Engine
UpstreamDrift maintains a capability matrix and selection guide in-repo:
- Feature × engine table:
docs/engines/engine_capabilities.md - Decision prose:
docs/engines/engine_selection_guide.md - Model ledger (which models exist per engine):
src/engines/model_inventory.py
Condensed decision hints from those documents and this commit’s code:
| Need | Practical direction at this commit | Why |
|---|---|---|
| Soft contact, muscles, grip welds | MuJoCo (+ MyoSuite for bundled muscle MJCF) | Contact in drift path; Hill muscles MuJoCo-only per selection guide |
| Trajectory optimization, hydroelastic contact planning | Drake | Selection guide prioritizes Drake trajopt / contact planning |
| Lightweight rigid-body ID / Jacobians, no contact | Pinocchio | Fast ABA drift; contact not in default drift path |
| Hill-type musculoskeletal forward sim | OpenSim (experimental tier) | Muscle bias in compute_bias_forces; ZTCF uses Simbody acceleration stage |
| Teaching / double-pendulum parity | Pendulum engine or ode backend |
Symbolic or analytical reference |
| Differentiable batched rollouts | mjx backend |
See backend table in simulation_backends/README.md |
| GPU throughput sweeps | mjwarp backend |
Batched rollouts; not faster for a single 2-DoF rollout |
| Drift/control on Simscape Multibody | Not available | Adapter returns deferred stubs |
| Counterfactuals on JaxSim | Verify against current manifest | Capability taxonomy lists partial contact / counterfactual gaps |
AffineDrift’s companion Engines and Runtime Support lists provider support tiers only; this page is the code-grounded supplement.
Cross-Engine Validation
The validator class CrossEngineValidator implements Guideline P3 metric tolerances and severity ramps:
| Metric key | Tolerance | Lines |
|---|---|---|
position |
1e-6 m | TOLERANCES |
velocity |
1e-5 m/s | same |
acceleration |
1e-4 m/s² | same |
torque |
1e-3 N·m | same |
jacobian |
1e-8 | same |
state_round_trip |
1e-9 | same |
end_effector |
5e-3 m | same |
Severity: warning at 80% of tolerance, error at 10×, blocker at 100× (WARNING_THRESHOLD et al.).
Representative conformance checks include state round-trip, forward kinematics, inverse/forward dynamics consistency, mass properties, and differential cross-engine reference (methods near lines 284–403 in the same module).
User-facing compare command for golf double-pendulum backends:
python -m src.shared.python.simulation_backends.compare_cli \
--engines ode,mujoco \
--horizon 200 \
--dt 0.005 \
--output reports/ode_vs_mujoco.mdDocumented in simulation_backends/README.md § Cross-engine reports. Registered divergences can be attached via the comparison service (comparison.py in the same package).
Simulation Backends (ode, mujoco, mjwarp, mjx)
These backends implement SimulationBackend for the shared GolfModelParams club model — orthogonal to full humanoid PhysicsEngine loads but the lowest-friction path to reproduce double-pendulum ZTCF/ZVCF analysis:
| Backend | Device | Batched | Differentiable | Exposes M, bias |
|---|---|---|---|---|
ode |
CPU | no | no | yes |
mujoco |
CPU | no | no | yes |
mjwarp |
CUDA | yes | no | no |
mjx |
JAX | yes | yes | no |
Factory entry point: make_backend(name, params, **kwargs). Pointwise ZTCF/ZVCF on canonical-v2 trajectories: ztcf_zvcf.py (see README § Pointwise ZTCF/ZVCF).
Lower-body and putting-green specialized engines are documented under UpstreamDrift docs/engines/ and the putting-green shared_engine.py implementation; unverified in this pass: full lower-body SPEC.md walk-through.
Citation
@online{untitled,
author = {},
title = {UpstreamDrift {Engine} {Protocol} {Reference}},
url = {https://affinedrift.com/pages/upstreamdrift-engine-protocol.html},
langid = {en}
}