The UpstreamDrift Method Inventory
Evidence snapshot: UpstreamDrift commit d7c7d07add0d7407a5a3376d5fe4a97aee9112a0. This chapter is a source and evidence inventory, not a claim that every method has been trained or physically qualified. Links below pin code and documentation to that immutable commit. No network retrieval or test execution was performed for this chapter.
The phrase “match dynamics to kinematic data” hides several inverse problems with different unknowns. A motion-capture sequence may constrain joint angles, marker positions, club pose, or only a projected silhouette. A forward model maps a specified initial state, parameters, controls, contacts and environment to a trajectory. Matching asks which unknowns make that trajectory agree with measurements. Depending on what is unknown, the problem may be trajectory tracking, control reconstruction, parameter identification, shape calibration, or a combination. A solver can return a low residual while choosing a physically wrong combination of these variables. This chapter inventories the actual UpstreamDrift methods by these distinctions.
1. Classical Parameter Fitting Through a Forward Simulator
The foundational Simscape path parameterizes each actuated joint with a seven-coefficient polynomial and repeatedly executes the native model. The orchestration entry point is fit_swing_full_pipeline. It resolves a target, applies options, dispatches to a solver, renders diagnostics and writes a fit report. The forward oracle is simulate_with_coefficients. Cost terms are shared instead of embedded in each optimizer; see COST_FUNCTION_SPEC.md.
The optimizer choices span local smooth optimization (fit_swing_fmincon), randomized local starts (fit_swing_multistart), global derivative-free exploration (fit_swing_surrogateopt) and global-to-local hybrid search (fit_swing_hybrid). Each is executable under option1_direct_optimization. Synthetic recovery tests are present, including fmincon tests and multistart tests. Synthetic observability and optimizer wiring tests are valuable but do not answer whether the SLX model, its marker map, mass properties or ground contacts represent a recorded person.
The coefficient vector is convenient because it makes a simulator call a deterministic function of a compact vector. It is also numerically fragile: powers of physical seconds have very different scales, high-order monomial coefficients can be strongly correlated, and a fixed coefficient box does not imply a bound on the actual torque curve unless time interval and basis are fixed. The tour matching guide records the native polynomial A*t^6 + ... + G, while shared Python uses ascending powers; conversion must happen at the engine boundary. A more stable parameterization uses normalized time and a basis with better conditioning, while preserving a tested native conversion and interval torque bound.
Cross-engine implementations include OpenSim’s fit_swing_opensim, Drake’s bounded SLSQP fitter and a Drake AutoDiff pathway. OpenSim’s fitter consumes the shared cost; Drake includes both float simulation and an analytic AutoDiff integration route. The code and test paths are in the audit report. Their default coefficient bounds and regularizers are not yet identical: OpenSim uses a relatively narrow symmetric bound and a coefficient-norm default when torque logs are absent, while Drake/Simscape document wider per-power envelopes, and the autodiff path has its own degree-scaled bound convention. These are scientific differences because optimization outcome depends on parameter scale and regularization. A cross-engine parity result is meaningful only after model identity, coefficient order, time normalization, units, initial state, outputs and objective are identical.
2. Kinematic Fitting and Constrained Inverse Kinematics
Kinematic fitting solves pose variables against marker or body targets, often using forward kinematics, without asking whether a torque-driven model would produce those poses. The Simscape shared tools include skeleton FK and a pose seed fitter, and the OpenSim pathway includes document IK and address-pose fitting. These tools are appropriate for model registration, initial-state construction and geometric residual analysis. They are not substitutes for dynamic matching.
The more recent club-only package distinguishes measured, derived and unobserved components through an observation contract, carries time/resampling provenance and supports sign-invariant SO(3) error. A measured club orientation and a derived orientation are not equivalent evidence; an unobserved twist should remain masked rather than set to zero. Constrained IK adds backend capability declarations and posture branches. Starting guesses can be retrieved or seeded, then body candidates can be generated under plausibility priors. The package explicitly retains ambiguity because club motion alone cannot uniquely determine internal whole-body posture. This is methodologically sound: a single inverse solution is not “the golfer’s motion” absent additional observations and priors.
The club-only path adds null-space analysis for grip closure and alternative offsets. These are useful tools for understanding the family of kinematic solutions that produce a similar end-effector constraint. Their role is proposal generation; candidates still need observation scoring, plausibility checks and, for a dynamics claim, torque/control recovery plus an independent forward trajectory. The club_only turnover says its software-contract work packages completed while the epic remained open on native Fit/G1 gates. This nuance should be preserved in any textbook description.
3. Direct Control Recovery and Tracking
There are two broad approaches to dynamic matching. In shooting or single shooting, optimize a control sequence and integrate from one initial state; gradients or finite differences pass through the simulator. In direct collocation or multiple shooting, optimize state and control nodes together, enforce defects between nodes, and then validate with a separate integration. Direct transcription can handle constraints and long horizons more robustly, but its optimizer nodes are not by themselves a realized motion: the cold replay is authoritative.
OpenSim’s full-swing tracking module defines explicit event, trajectory, tracking-receipt, replay-receipt and qualification-result records. It validates model hashes, capture completeness, control naming, grip closure, continuity and coordinate limits. Moco tracking can produce a dynamically constrained tracking solution; a separate open-loop replay checks whether the proposed control from the actual initial state reproduces the path. A marker-scoring lane without model marker predictions is explicitly documented as incapable of qualifying a fit. This design prevents a solver objective or status flag from becoming an unsupported matching claim.
Simscape tour-average work provides a concrete direct-node continuation workflow. It first calibrates geometry and initial state, then optimizes controls over progressively longer capture prefixes. Prefix extension must preserve earlier samples and reintegrate from the same initial state; state resets at windows would leak measured trajectory information into the simulation. A candidate can be stitched from windows only if continuity and the actual native control path are verified. The native qualification protocol specifies independent replay at tighter tolerances and reports per-marker/per-phase errors, actuator limits and missing force/penetration evidence. The 2026-10-05 snapshot includes a two-window 0.85-second uninterrupted replay that passes four gates but fails the terminal full-marker RMS gate; it is an informative partial success, not whole-capture acceptance.
The same distinction applies to feedback-assisted tracking. A controller that continuously corrects state error may track well even if its underlying model and open-loop torques are poor. Report tracking-controller mode and independent replay separately. The Simscape Human experiments document fixed supported holds with feedback and prescribed neck support, yet explicitly leave full-swing forward dynamics unqualified. The reference contains failed force/pose gates as well as successes, preserving evidence instead of selecting only visually appealing frames.
4. Learned Forward and Inverse Models
The current shared Python code has a real neural method portfolio. The trajectory-level forward model in surrogate/model.py maps torque coefficients to butt/grip and clubhead paths, orientation and auxiliary joints. FiLM modulation conditions a temporal backbone on the control vector. Its trainer, train_surrogate, is implemented. fit_swing_via_surrogate differentiates through the learned model to propose controls. Because a surrogate can be exploited in regions where its gradients do not represent native mechanics, validation includes trust-region, directional derivative and contact-boundary checks, followed by native evaluation.
Separate compact-corpus and per-step models handle different data organizations and tasks. Compact sequence models predict a whole trajectory and have their own target/coefficient normalization. Per-step surrogate training predicts state dynamics from structured inputs and the sequence optimizer adds orientation, work and smoothness terms. They should not be collapsed into one “neural matcher” in a review: target representation, supervision and native use differ.
Inverse models estimate controls from a trajectory. The full-trial CVAE uses a conditional prior and posterior with coefficient decoder and bounded outputs. It acknowledges the many-to-one mapping by sampling candidate coefficient vectors. The deterministic inverse regressor is faster but tends toward conditional mean solutions when labels are multi-modal; historical source notes a plateau near mean predictions, a claim NM-00 quarantines pending original curves. A per-timestep inverse dynamics network maps (q, qd, qdd) to generalized torque. That is a local force inference conditioned on state derivatives and a given model/labeling scheme; it is not automatically a whole-trajectory control solution or independent causal system identification. Masked proposals address incomplete observations and preserve proposal diversity.
The purpose of all these networks should be to amortize candidate generation or provide gradients, not to replace physics. Strong deployment architecture is “learned proposal → bounded native polish → independent replay → physical acceptance,” with classical fallback under fixed budget. The current NM-07 receipt is diagnostic and specifically records that some earlier ablations used hard-coded literals; NM-10 speed estimates are diagnostic/unmeasured. Do not repeat their numerical values as measured results.
5. Model Dimensions and Identification
The repo contains anthropometric scaling, segment scaling and dimension configuration structures. These can build a subject-scaled model or choose among registered topologies. That is not the same as learning dimensions from motion. A dimension-learning method jointly varies geometry with control or torque and may let one compensate for another: a longer segment can mimic different joint motion; an offset can absorb camera calibration error; mass, inertia, actuator gains and torque scale can trade off in the dynamics. If all are free, a lower residual may indicate compensation rather than improved anatomy.
A rigorous adaptive model should use a small structured dimension vector with informative anthropometric priors and hard mechanical constraints. Fit camera registration and marker attachments first, then dimensions against calibration observations, then hold geometry fixed for dynamic control fitting. If alternating refinement is needed, constrain each block, log sensitivity matrices, and report which directions are identifiable. Include positive lengths/inertias, mass consistency, topology constraints and model complexity penalties. A parameter with a flat profile likelihood or small Jacobian singular value is prior-dominated, not learned. Evaluate dimensions against withheld markers, views or phases and compare them with anthropometric measurements where available.
6. Evidence Levels and Practical Reading
For every method, distinguish source implementation, unit tests, synthetic recovery, learned artifact training, native candidate simulation, independent open-loop replay, and physical qualification. UpstreamDrift has meaningful code in each category, but they are not interchangeable. Existing unit tests validate shapes, costs, failure handling and sometimes synthetic recovery. The artifact audit quarantines known absent checkpoint paths and unsupported training claims. Neural roadmap receipts explicitly limit many results to synthetic fixtures and software contracts. At the same time, Simscape has real R2025b dynamic replay evidence for a partial horizon with a clearly failed gate, and extensive experimental receipts for failed Human holds and unqualified full-swing matching. These candid partial results are more valuable than a fabricated pass: they tell the next method what to solve.
The strongest overall workflow is therefore not a single algorithm. It is a layered system: calibrate observations and frames; use IK/retrieval to generate a valid initial state; assess observability; choose a fixed or explicitly adaptive model; fit controls with bounded, scaled variables and transparent objectives; preserve diverse proposals; replay through the exact native forward solver without state injection; audit contact, continuity and actuator behavior; evaluate held-out data; and publish provenance and rejected attempts. The method should return a candidate plus uncertainties and evidence status, not a bare residual or a single claim of a “matched” human.
Citation
@online{untitled,
author = {},
url = {https://affinedrift.com/articles/forward_dynamics_matching/02_upstream_inventory.html},
langid = {en}
}