Motion-Matching Runtime Reference
Evidence snapshot: UpstreamDrift commit d7c7d07add0d7407a5a3376d5fe4a97aee9112a0. Numerical thresholds below are transcribed from acceptance.py (AcceptanceGates, lines 79–132). Where a prose handoff disagrees with that module, the code wins until MS-100 versions the contract.
Earlier chapters develop forward matching theory and historical receipts. This reference states the programme a user actually runs: horizons, gates, the two-window native fit, the ground-support pipeline, the shared contact law, control layouts, gradient backends by lane, and the vocabulary of receipts and lanes.
1. Horizons G1, G2, and G3
The evaluator defines three horizons in Horizon:
| Horizon | Time span (driver) | Role |
|---|---|---|
| G1 | 0–0.85 s | Top of backswing / early transition dynamic milestone |
| G2 | Through ~1.20 s (impact band) | Ground-support dynamic replay with floating root |
| G3 | Full capture (driver 1.814 s / iron 1.827 s) | Professional release and dual-club coverage |
Minimum durations enforced on receipts: G1 \(\ge 0.85\) s, G2 \(\ge 1.20\) s, G3 \(\ge 1.80\) s (g1_min_duration_s, g2_min_duration_s, g3_min_duration_s).
Entry point: evaluate (line 1349) returns an AcceptanceVerdict for a receipt dict at the chosen horizon.
2. Acceptance Gates and Thresholds
AcceptanceGates holds frozen SI thresholds. Kinematic RMSE gates use metres unless noted.
2.1 Kinematic RMSE by Horizon
| Gate field | G1 | G2 | G3 (driver) | G3 (iron) |
|---|---|---|---|---|
whole_marker_rmse_m |
0.025 | 0.040 | 0.060 | 0.095 |
early_marker_rmse_m |
0.012 | 0.015 | 0.020 | 0.020 |
terminal_marker_rmse_m |
0.035 | 0.050 | 0.080 | 0.080 |
club_marker_rmse_m |
0.060 | 0.075 | 0.100 | 0.100 |
pelvis_yaw_rmse_rad |
0.05236 (~3°) | 0.08727 (~5°) | 0.10472 (~6°) | 0.10472 (~6°) |
When a receipt reports pelvis_yaw_error_pct instead of radians, G1 compares against 5.0 % (g1_pelvis_yaw_error_pct).
2.3 Metric Definitions
Standard receipt metrics are computed in tour_metrics.py:
- Whole: RMS over all valid tracked markers and times.
- Early: RMS for \(t \le 0.60\) s (
early_cutoff_sdefault). - Terminal: RMS over the last 10 % of capture frames (
terminal_ratiodefault 0.10), full-marker set (head cluster disclosed separately under MS-61). - Club cluster: RMS over markers in the club segment (Marker_2 / Marker_3 family) across the trial.
- Pelvis yaw: RMS of waist-marker heading error in the transverse plane.
The two-window optimiser’s internal scoring uses a last-frame terminal residual with weight \(25^2\) in the objective (see §3); gates still compare the receipt’s stored terminal_marker_rmse_m, which may come from compute_shared_metrics or replay qualification.
2.4 Gate Statuses and Verdict Rule
Each gate has status: passed, failed, missing, not_applicable, or disclosed (GateStatus).
is_verdict_accepted returns true only when:
- At least one gate passed, and
- Every gate is in
{passed, disclosed, not_applicable}— nofailedormissing.
As of the matched swing programme status on the pinned commit, no committed evidence/matched/* receipt on main passes G1; headline candidates (Simscape run-102, Pinocchio Crocoddyl, MuJoCo tracking) are explicitly REJECTED with documented reasons.
3. Two-Window Native Optimisation (Run 102)
The canonical bounded trial is documented under two_window_fit_9967_102. Implementation: multi_shooting_fit.py, two_window_fit.py.
Decision variables: 81 increments in a 27-dimensional native control chart (config.json chart.dimension: 27). Bernstein degree 6 with only controls from index first_control: 4 onward free (B4–B6 increments per coordinate), boxed at \(\pm 3.0\) N or N·m relative to the parent candidate.
Windows: \([0, 0.6]\) s and \([0.6, 0.85]\) s with one 27-D shooting node at the boundary (shared_boundary_policy: once).
Objective (marker terms, from compute_marker_metrics):
\[ J = \sum \|e\|^2 + w_{\mathrm{term}}^2 \sum \|e_{\mathrm{last}}\|^2 + (\alpha \,\Delta u_{\mathrm{yaw}})^2 + J_{\mathrm{effort}} \]
Defaults in run-102 config: \(w_{\mathrm{term}} = 25\), pelvis-yaw weight \(\alpha = 40\), effort penalty weight \(0.01\) (reference force 100 N, torque 20 N·m).
Pelvis-yaw term: compute_marker_metrics defaults pelvis_yaw_weight = 40.0 on the last frame waist-marker residual (not the same construction as the G1 receipt gate).
Constraints: Projected continuity equalities at the window join with scaled defect tolerance \(10^{-4}\) (defect_tolerance_scaled in config) and equality tolerance \(10^{-7}\) (equality_tolerance).
Solver: SLSQP with analytic ODE sensitivities (solver: slsqp); primal integrator rtol \(10^{-11}\), atol \(10^{-13}\); sensitivity rtol \(10^{-10}\).
3.1 Run-102 Config Keys (Pinned Evidence)
| Key | Value (run 102) | Role |
|---|---|---|
windows |
[0, 0.6], [0.6, 0.85] s |
Shooting segments |
chart.dimension |
27 | Native control coordinates |
first_control |
4 | Free Bernstein indices B4–B6 (81 increments) |
control_box / theta_lower/theta_upper |
\(\pm 3.0\) | Increment bounds relative to parent |
shared_boundary_policy |
once |
Single 27-D node at \(t=0.6\) s |
terminal_weight |
25.0 | Objective weight on last-frame marker error |
effort_penalty.weight |
0.01 | Effort term scale |
primal.rtol |
\(10^{-11}\) | Forward integration relative tolerance |
Recorded result (handoff, not acceptance): whole 20.267 mm, early 9.995 mm, terminal 40.303 mm (fails G1 35 mm gate), club cluster 8.389 mm, pelvis-yaw error 0.610 % — see 03_historical_lessons.
4. Ground-Support Pipeline
CLI entry: pipeline/cli.py (build_parser, line 168). Constants: pipeline/constants.py.
4.1 Stages
Typical --out run:
- Address / calibration — static seeds, hip calibration, leg bounds, calibrated address (
solve_address_stage,record_calibrated_address). - IK — full-body inverse kinematics on the capture (
pipelineIK modules); producesik.marker_rms_min the receipt. - Reference smoothing — zero-phase low-pass on the IK track at
REFERENCE_CUTOFF_HZ = 12.0Hz before dynamics. - Dynamics replay — computed-torque tracking of the smoothed reference with unactuated floating root (
pipeline/dynamics.py, line 227). Reporteddynamics.marker_rms_mis feedback-tracked, not open-loop torque replay. - Optional filters —
--shooting-fit,--zmp-filter,--centroidal-filterrefine or qualify the tracked trajectory. - Receipt —
receipt.jsonaggregates address, IK, dynamics, controller metadata, and gate evaluation.
4.2 Computed-Torque Controller
From pipeline/constants.py and tracking_controller.py:
- Natural frequency
OMEGA_RAD_S = 30rad/s (critical-style PD gains from \(\omega\) and damping). - Balance gains
BALANCE = (60, 15)on horizontal CoM regulation. - Tracking backend
--tracking {kkt, mj-inverse, wrench-qp}(default KKT computed torque). - Trajectory optimiser option
--trajectory-optimiser mjx-knotsfor the JAX knot path.
4.3 Selected CLI Flags
| Flag | Effect |
|---|---|
--static-seeds |
Validated upper/lower attachment calibration before IK |
--shooting-fit |
Optional shooting refinement on the tracked lane |
--zmp-filter |
ZMP / support-polygon feasibility filter on the finish |
--centroidal-filter |
Centroidal feasibility v2 after ZMP filter |
--preload-feet |
Preload contact before dynamics (documented per lane) |
Read receipt.json fields under address, ik, dynamics, contact_audit, and top-level gates after evaluate.
6. Control Layout: A..G and Bernstein
Canonical Python layout (polynomial_torque.py): seven columns per joint, lowest power first \([A,B,C,D,E,F,G]\) for \(\tau(t) = A + Bt + \cdots + Gt^6\).
Simscape native layout (constrained_sextic.py): descending powers \([A,B,C,D,E,F,G]\) for \(\tau(t) = At^6 + Bt^5 + \cdots + G\).
Conversion on normalized time \(s = t/T_{\mathrm{full}}\):
\[ p_j = \mathrm{simscape}_{6-j}\, T_{\mathrm{full}}^{\,j}, \qquad A = p_6 / T_{\mathrm{full}}^6,\ \ldots,\ G = p_0 \]
Bernstein controls for shooting fits use piecewise_polynomial.py and prefix_fit.py; validate_theta enforces layout at API boundaries. Passing coefficients in the wrong order produces a silently wrong swing.
6.1 Typical Increment and Node Bounds (Run 102)
| Quantity | Config key | Run-102 value |
|---|---|---|
| Control increment box | control_box, theta_lower/theta_upper |
\(\pm 3.0\) N or N·m |
| Node chart radius | chart.radius |
0.5 (native units) |
| Node chart bound | node_bound_chart |
0.075 |
| Box scaling factor | box_factor |
6.5 |
7. Gradient and Sensitivity Backends by Lane
| Lane / task | Primary gradient source | Upstream anchor |
|---|---|---|
| Simscape / Pinocchio native two-window | Analytic ODE sensitivities + SLSQP | multi_shooting_fit.py, run-102 config |
| Ground-support shooting fit | Discrete RK4 sensitivities | full_body_step.py |
| MJX knot optimiser | JAX / MJX autodiff | mjx_knot_optimiser.py |
| Pipeline IK / Bernstein least squares | SciPy TRF / LM finite differences | pipeline IK modules |
| Crocoddyl native fit | Pinocchio analytic RNEA / ABA | optimization/crocoddyl_backend.py |
| Drake AutoDiff fit | Drake AutoDiff integration | fit_swing_autodiff.py |
This table supplements the generic discussion in 10_gradients; it does not certify every path on every engine.
8. Engine and Lane Status (Pinned Commit)
Summarised from the programme README §3 status matrix (2026-09-18 hand-written reset). All listed G1 candidates are REJECTED under acceptance.py.
| Engine | Best G1-horizon whole RMS (quoted) | Verdict / blocker |
|---|---|---|
| Simscape | 20.3 mm (run-102, 0–0.85 s) | REJECTED: terminal 40.3 mm \(>\) 35 mm gate |
| Pinocchio | 46.8 mm (Crocoddyl RK45 candidate) | REJECTED: early / terminal / yaw / penetration |
| MuJoCo | 74.6 mm tracking variant | REJECTED; replay path exists for cross-engine checks |
| Drake | IK ~176 mm (FB-4) | No accepted G1; needs shared fitter on plant |
| OpenSim | Moco rungs at calibration floor | No accepted G1 |
| MyoSuite | Kinematic replay only | Experimental; provider rejects runs when prerequisites are missing |
Lanes include native, drake_native_fit, crocoddyl_native_fit, ground_support, matched, and engine-specific tags recorded on each receipt’s lane field (ledger.py).
9. Programme Vocabulary
The site glossary defines motion-matching terms of art. Anchors cited from UpstreamDrift modules:
| Topic | Site glossary anchors | Upstream module / field |
|---|---|---|
| Horizons & gates | G1–G3 horizon, acceptance gate, acceptance verdict, gate status | acceptance.Horizon, acceptance.evaluate |
| Kinematic metrics | Whole / early / terminal / club-cluster RMSE, early cutoff, terminal weight | tour_metrics.py, two_window_fit.compute_marker_metrics |
| Programme objects | Receipt, lane, ledger, candidate, factor | receipt.json, ledger.py, candidate.py |
| Replay modes | Open-loop replay, stabilized replay, computed-torque tracking | pipeline/dynamics.py, AcceptanceGates.max_stabilized_marker_rmse_m |
| Optimisation | Two-window fit, node chart, Bernstein increment, shooting node | multi_shooting_fit.py, config.json run 102 |
| Contact / support | Weight fraction, support-polygon fraction, collocation defect | acceptance.py, contact_audit receipt section |
Null-space convention vocabulary (INVARIANT, FAMILY_DEPENDENT, closure scales) is covered in After One Solution: Null-Space Exploration; issue #5622 defers that slice to a follow-up conventions pass.
Further Reading
- Lessons From Historical Fits — Run-102 numbers and failure interpretation.
- Constraints, Contact, and Hybrid Events — Event-time sensitivity and hybrid formulations.
- Software Architecture and Test Contracts — Test hooks named in upstream receipts.
Citation
@online{untitled,
author = {},
url = {https://affinedrift.com/articles/forward_dynamics_matching/27_runtime_reference.html},
langid = {en}
}