Biomechanical golf swing analysis across multiple physics engines, from two-degree-of-freedom pendulums to muscle-driven musculoskeletal models.
UpstreamDrift is a simulation and analysis platform for the golf swing. It runs the same model definitions through several physics engines, so a result can be checked against an independent implementation rather than taken on trust. It covers forward and inverse dynamics, inverse kinematics, trajectory optimization, motion-capture retargeting, and cross-engine comparison, with a web interface and a desktop application over the top.
- Audience: biomechanics researchers, robotics engineers, and golf instruction technologists.
- Platform: Windows, macOS, and Linux. Python 3.11 or 3.12.
- Status: actively developed. MuJoCo is the supported engine; other engines carry the support levels stated in Engine Support.
| Section | Purpose |
|---|---|
| Start Here | Choose a path for your first hour |
| Capabilities | What the platform can do |
| Installation | Get a working environment |
| Running the Platform | Entry points and what each one opens |
| Engine Support | Which engines are validated, and how far |
| Documentation | Guides, API reference, and architecture |
| Repository Layout | Where things live |
| Contributing | Development workflow |
| Citation | How to cite this work |
Pick the entry point that matches what you want to do.
| If you want to | Read |
|---|---|
| See one reproducible result end to end | Guided walkthrough |
| Install and launch the platform | Installation, below |
| Understand the whole system | Project map |
| Choose a physics engine for your problem | Engine selection guide |
| Go from video to tracked motion | Motion pipeline guide |
| Build a humanoid model | Character builder quickstart |
| Add support for a new engine | Adapter authoring guide |
| Browse everything | Documentation hub |
- Models spanning 2 to 28 degrees of freedom, including flexible-shaft formulations, up to musculoskeletal models with several hundred muscle actuators.
- Parametric humanoid generation with anthropometric scaling and URDF export.
- MATLAB Simscape Multibody models, maintained as research references rather than production artifacts.
- Inverse kinematics with nullspace optimization for redundant chains.
- Inverse dynamics with full torque computation and force decomposition.
- Kinematic force analysis separating Coriolis, centrifugal, and gravitational contributions.
- Trajectory optimization for comparing candidate swing objectives across speed, accuracy, and efficiency.
- Cross-engine validation running one model definition through several engines and reporting the deviation.
Impedance, admittance, hybrid force-position, and operational-space control; parallel-mechanism analysis of the two-handed grip; manipulability and singularity characterization; task-space control with redundancy resolution.
Load and retarget motion data in CSV, JSON, and C3D formats. Markerless tracking runs through OpenPose or MediaPipe. See the motion pipeline guide for the video-to-motion workflow.
Real-time three-dimensional rendering with multiple camera views and force-torque vector overlays; more than ten plot types including energy breakdowns, phase diagrams, and three-dimensional trajectories; CSV and JSON export for external analysis.
- Python 3.11 or 3.12.
- Git. The shared Tools layer (
theme,sidekick,chat,utils, ...) is a pinned submodule atvendor/ud-tools; the platform will not import without it. The repository does not use Git LFS. - MATLAB R2023a or later with Simulink and Simscape Multibody, only for the MATLAB models.
The supported combinations of Python version, operating system, engine tier, and hardware are recorded in the production readiness matrix.
git clone https://github.com/D-sorganization/UpstreamDrift.git
cd UpstreamDrift
git submodule update --init --recursive vendor/ud-tools
pip install -e ".[dev]"
python scripts/ci/verify_installation.pyOnly the vendor/ud-tools submodule is required. The three model submodules
(shared/models/opensim/opensim-models, shared/models/myosuite/myo_sim,
src/shared/tools/human-gazebo) are optional and only needed for the
experimental OpenSim/MyoSuite engines.
pyproject.toml is the canonical dependency source. A Conda wrapper is
generated from it:
conda env create -f environment.yml
conda activate upstream-driftEdit dependencies in pyproject.toml and run make sync-deps to regenerate
environment.yml.
For interface development without the physics engines:
pip install -e .
export GOLF_USE_MOCK_ENGINE=1If installation fails, see installation troubleshooting.
The Rust build works from a clean clone. The shared tools-core crate is
fetched from a pinned D-sorganization/Tools revision, so no sibling checkout is
required.
cargo build
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip maturin
cd rust_core/upstream-physics
python -m maturin develop --features python
python -c "import upstream_physics; print(upstream_physics.IntegratorConfig())"To develop against a local Tools checkout instead of the pinned revision, run
scripts/setup_tools_workspace.sh.
python launch_upstream_drift.pyThis starts the local API server on port 8000 and opens the web interface in your browser. The other entry points:
| Command | Opens |
|---|---|
python launch_upstream_drift.py |
Web interface, recommended |
python launch_upstream_drift.py --classic |
PyQt6 desktop application |
python launch_upstream_drift.py --api-only |
API server with no interface |
python launch_upstream_drift.py --engine <name> |
A single engine directly |
python -m src.tools.pose_studio |
Pose Studio, standalone |
upstream-drift is installed as a console script and accepts the same
arguments. The desktop application remains supported for users who prefer a
native window.
launch_golf_suite.py is a deprecated compatibility shim retained for existing
scripts. New work should use launch_upstream_drift.py.
Development tasks run through the Makefile:
make help # List available targets
make check # Run linters and tests
make format # Apply Ruff formattingSupport level determines what is validated in continuous integration, not what is implemented. Engines outside the supported tier work, but regressions in them are found later.
| Tier | Engines | Install profile | Validation |
|---|---|---|---|
| Supported | MuJoCo | pip install -e ".[dev]" |
Required on every pull request |
| Extended | Drake, Pinocchio | pip install -e ".[dev,all-engines]" |
Nightly cross-engine validation |
| Experimental | OpenSim, MyoSuite | pip install -e ".[dev,biomechanics]" |
Best-effort, local validation only |
| Engine | Strengths |
|---|---|
| MuJoCo | Contact-rich dynamics, ground and ball contact, motion capture workflow |
| Drake | Trajectory optimization, contact modeling, system analysis, URDF |
| Pinocchio | Fast rigid-body algorithms, analytical derivatives, PINK inverse kinematics |
| OpenSim | Biomechanics validation surface, experimental |
| MyoSuite | Muscle modeling surface, experimental |
The full contract is in support tiers; feature-level coverage is in engine capabilities.
The documentation hub is the entry point. Frequently used sections:
- Project map — every feature, module, and integration.
- User guide — installation, running simulations, using the interface.
- Engines — engine documentation and comparison.
- API reference — code interfaces and REST endpoints.
- Adapters — adding a physics engine.
- Architecture decisions — durable design records.
- Specification — the platform specification.
- Troubleshooting — installation, configuration, and cross-engine deviations.
- Development — architecture, contributing, and testing.
UpstreamDrift/
├── launch_upstream_drift.py Canonical entry point
├── src/
│ ├── launchers/ Launch applications
│ ├── engines/
│ │ ├── physics_engines/ MuJoCo, Drake, Pinocchio, OpenSim, MyoSuite
│ │ ├── Simscape_Multibody_Models/ MATLAB and Simulink models
│ │ └── pendulum_models/ Reduced-order models
│ ├── shared/ Code with more than one consumer
│ └── tools/ Standalone utilities, including Pose Studio
├── rust_core/ Rust physics kernels
├── apps/ Web interface
├── shared/ Model assets and vendored dependencies
├── docs/ Documentation
└── tests/ Test suite
Contributions are welcome. Start with the contributing guide, then the development guidelines and the testing guide.
Before adding code, read AGENTS.md. It maps the shared infrastructure and gives a discovery workflow that prevents reimplementing something the repository already provides.
Report vulnerabilities through SECURITY.md, not through public issues.
@software{upstream_drift,
title = {UpstreamDrift: A Unified Platform for Biomechanical Golf Swing Analysis},
author = {Dieter Olson},
year = {2026},
url = {https://github.com/D-sorganization/UpstreamDrift}
}Released under the MIT License. See LICENSE.
This project builds on MuJoCo for physics simulation, Drake for model-based design and control, Pinocchio for rigid-body dynamics, MyoSuite for musculoskeletal models, and OpenSim for biomechanical modeling.