UpstreamDrift: Educational Tool Integration Guide

Review of UpstreamDrift simulation platform capabilities and integration plan for the Geometry of Motion book series.

WarningAccess Restricted

UpstreamDrift is a private simulation platform. Access to the repository and simulation tools requires D-sorganization membership. This article documents the platform’s design and educational integration for authorized users and collaborators.

Overview

UpstreamDrift is a multi-physics simulation platform supporting the quantitative claims in Geometric Control of Nonlinear Systems book series. This article documents the platform’s capabilities and provides a guide for using it as an educational companion.

NoteRepository

UpstreamDrift is maintained at D-sorganization/UpstreamDrift. Access requires D-sorganization membership.

NoteStatus of the DCR / Contraction / Floquet Tooling

Some code blocks below (Drift-Control Ratio analyzer, contraction-rate verifier, Floquet multipliers, ABA-timing benchmark) describe a proposed reference API that is in development in UpstreamDrift. Implementation is tracked in the UpstreamDrift feature roadmap.

• When the tooling lands, replace the “proposed API” banners here with runnable examples and drop the (proposed) / (planned) labels.

Physics Engines Available

MuJoCo

Purpose: Fast GPU-accelerated rigid-body dynamics for golf swing simulations and RL training.

Key models: - 3-DOF simplified golf swing (shoulder + wrist + club) - Full-body musculoskeletal model (MyoSuite integration) - Double pendulum benchmark

Example usage:

import mujoco
import mujoco.viewer
import numpy as np

# Load golf swing model
model = mujoco.MjModel.from_xml_path("models/golf_3dof.xml")
data = mujoco.MjData(model)

# Run passive simulation (u=0)
mujoco.mj_resetData(model, data)
data.qpos[0] = np.radians(90)   # Shoulder at top of backswing
trajectories = []
for _ in range(500):
    mujoco.mj_step(model, data)
    trajectories.append(data.qpos.copy())

Drake

Purpose: Trajectory optimization and optimal control with formal guarantees.

Key capabilities: - Direct collocation for swing trajectories - LQR stabilization around nominal trajectories - Differential Dynamic Programming (DDP)

Example usage:

from pydrake.all import (DiagramBuilder, AddMultibodyPlantSceneGraph,
                          Parser, Simulator)

builder = DiagramBuilder()
plant, scene_graph = AddMultibodyPlantSceneGraph(builder, time_step=0.001)
Parser(plant).AddModelFromFile("models/golf_sdf/golf_arm.sdf")
plant.Finalize()
diagram = builder.Build()
simulator = Simulator(diagram)

Pinocchio

Purpose: Efficient \(O(n)\) rigid-body dynamics with Python bindings for control design.

Key capabilities: - Forward/inverse kinematics - Articulated Body Algorithm (ABA) for forward dynamics - Recursive Newton-Euler Algorithm (RNEA) for inverse dynamics - Jacobian computation for operational-space control

Example usage:

import pinocchio as pin
import numpy as np

# Load URDF model
model = pin.buildModelFromUrdf("models/golf_arm.urdf")
data = model.createData()

# Compute forward kinematics
q = np.zeros(model.nq)   # joint configuration
v = np.zeros(model.nv)   # joint velocities
pin.forwardKinematics(model, data, q, v)

# Compute Jacobian at end-effector
frame_id = model.getFrameId("club_head")
pin.computeFrameJacobian(model, data, q, frame_id)
J = pin.getFrameJacobian(model, data, frame_id, pin.LOCAL_WORLD_ALIGNED)
print(f"Club-head Jacobian shape: {J.shape}")  # (6, nv)

OpenSim

Purpose: Biomechanical modeling with muscle-driven dynamics (MTU models).

Key capabilities: - Musculoskeletal geometry - Muscle force-velocity-length relationships - Inverse dynamics with experimental motion capture data

MyoSuite

Purpose: Muscle-driven RL environments for biologically realistic motor control.

Key capabilities: - 200+ muscle DoF upper body model - OpenAI Gym-compatible interface - Integration with stable-baselines3 and SAC/TD3 algorithms

Example usage:

import myosuite
import gym

env = gym.make("myoChallengeBimanuaReachFixed-v0")
obs = env.reset()
for _ in range(100):
    action = env.action_space.sample()  # Random muscle activations
    obs, reward, done, info = env.step(action)
    if done:
        obs = env.reset()

Chapter-by-Chapter Integration Map

NoteGeometry of Motion — Forthcoming Textbook Series

The “Vol I”, “Vol II”, etc. references in this table point to chapters in Geometric Control of Nonlinear Systems — a book-length treatment of control-affine biomechanics currently in development. These volumes are not yet publicly available. The table is included to show the structural connections between the AffineDrift articles and the forthcoming textbook.

Book Chapter	UpstreamDrift Tool	Key Experiment
Vol 0, Ch 1 (Linear Algebra)	Pinocchio	Compute Jacobian, verify orthogonality of rotation matrix
Vol 0, Ch 3 (Rotations)	Pinocchio	Forward kinematics through rotation chain
Vol 0, Ch 6 (Recursive)	Pinocchio ABA	Forward dynamics \(O(n)\) timing benchmark
Vol I, Ch 1 (Foundations)	Any engine	Compute Fréchet derivative numerically
Vol I, Ch 4 (Contraction)	MuJoCo	Measure contraction rate from multiple initial conditions
Vol I, Ch 5 (Optimal Control)	Drake DDP	Solve swing trajectory optimization
Vol I, Ch 8 (Applications)	MuJoCo + Pinocchio	Compute drift-control ratio \(\rho(t)\) (proposed tooling — see note below)
Vol II, Ch 4 (Orbital Stability)	MuJoCo	Compute Floquet multipliers for passive swing (planned)
Vol II, Ch 6 (Trajectory Opt.)	Drake	Direct collocation golf swing
Vol III (RL & Policy)	MyoSuite	Train SAC agent on muscle-driven swing

Recommended Learning Path

NoteTested Tool Versions

The install commands below are tested against the following minimum versions (Python 3.12, Ubuntu 22.04+ / Windows 11 / macOS 13+). Newer minor releases are expected to work; older releases are not supported.

Tool	Minimum version	Install command
Pinocchio	>= 3.0.0	pip install "pinocchio>=3.0.0"
MuJoCo	>= 3.0.0	pip install "mujoco>=3.0.0"
Drake	>= 1.20.0	see Drake installation guide
MyoSuite	>= 2.0.0	pip install "myosuite>=2.0.0"
OpenSim	>= 4.5	see OpenSim install
Simulink / MATLAB	R2023b or later	MathWorks installer

Note: the package name for Pinocchio on PyPI is pinocchio (not pin — that is a separate unrelated package). The previous pip install pin instruction was incorrect for recent versions and is corrected throughout this page.

Beginner (Vol 0 Readers)

1. Install Pinocchio: pip install "pinocchio>=3.0.0"
2. Load the double pendulum URDF from models/pendulum_2dof.urdf
3. Verify that the rotation matrices along the chain are orthogonal
4. Compute the end-effector Jacobian and check its rank

Intermediate (Vol I Readers)

1. Install MuJoCo: pip install "mujoco>=3.0.0"
2. Load the 3-DOF golf swing model
3. Run passive simulation (zero control) and plot the drift trajectory
4. Add LQR stabilization and measure the contraction rate

Advanced (Vol II-III Readers)

1. Install Drake >= 1.20.0 (see Drake installation guide)
2. Set up the direct collocation problem for swing trajectory optimization
3. Compare the optimal trajectory against the passive trajectory
4. Implement a DDP iteration and visualize convergence

Research (Vol IV Readers)

1. Install MyoSuite: pip install "myosuite>=2.0.0"
2. Train a SAC agent on the golf swing task
3. Compare the learned latent policy against the geometric control law
4. Measure the effective dimensionality of the learned representation

Running Existing Benchmarks

WarningProposed Reference API — In Development

The drift-control-ratio and contraction-rate commands below (src.tools.compute_drift_control_ratio, src.tools.measure_contraction) are a proposed reference API illustrating how DCR and contraction rate could be computed with UpstreamDrift. They are in active development — see the UpstreamDrift feature roadmap for implementation status. The ABA-timing benchmark is also tracked there. Treat these as illustrative pseudocode until the implementation lands.

The intended (proposed) benchmark entry points are:

# PROPOSED (in development) — drift-control ratio computation
python3 -m src.tools.compute_drift_control_ratio --model golf_3dof --horizon 0.5

# PROPOSED (in development) — contraction rate measurement
python3 -m src.tools.measure_contraction --model pendulum_2dof --n_trials 50

# PROPOSED (in development) — forward dynamics timing benchmark
python3 -m src.engines.pinocchio.benchmarks.aba_timing --n_dof 7 --n_steps 1000

Installation

UpstreamDrift’s canonical install is an editable pip install (see the UpstreamDrift documentation). For current engine matrices, support tiers, and exact-commit provenance, consult the Programming Companion Engines Matrix.

# Clone UpstreamDrift and pull large model files via Git LFS
git clone https://github.com/D-sorganization/UpstreamDrift.git
cd UpstreamDrift
git lfs install && git lfs pull

# Editable install with dev extras (canonical)
pip install -e ".[dev]"

# Optional: Drake (requires separate installer)
# See https://drake.mit.edu/installation.html

# Verify the installation via CI entrypoint
python scripts/ci/verify_installation.py

# Or execute the governed installation verification workflow
python -m scripts.companion_workflows execute --workflow-id installation-verification

Choose the engine profile that matches your needs — UpstreamDrift groups engines into Supported (F0), Extended (F1), and Experimental (F2) tiers (Pinocchio/MuJoCo are core; MyoSuite/OpenSim are Experimental). For a UI-only exploration without the heavy engine dependencies, set GOLF_USE_MOCK_ENGINE=1.

Connection to Book Theorems

WarningProposed Reference API — In Development

The DriftControlAnalyzer and ContractionVerifier classes below are a proposed reference API showing how the Drift-Control Ratio and contraction rate could be exposed by UpstreamDrift. They are in active development — src.tools.compute_drift_control_ratio and src.tools.contraction_verifier are tracked in the UpstreamDrift feature roadmap; until they land, treat the snippets as illustrative pseudocode, not runnable code.

Drift-Control Ratio (Vol I, Ch 8)

The drift-control ratio \(\rho(t)\) would be computed from UpstreamDrift via the proposed analyzer (illustrative):

# PROPOSED API — illustrative reference
from src.tools.compute_drift_control_ratio import DriftControlAnalyzer

analyzer = DriftControlAnalyzer(model_path="models/golf_3dof.xml")
trajectory = analyzer.load_expert_trajectory("data/expert_swing.npz")
rho = analyzer.compute_ratio(trajectory)
print(f"Peak rho (impact phase): {max(rho):.2f}")
# Expert swings show rho > 10 during downswing (drift-dominated)

Contraction Rate Verification (Vol I, Ch 4)

# PROPOSED API — illustrative reference
from src.tools.contraction_verifier import ContractionVerifier

verifier = ContractionVerifier(model_path="models/pendulum_2dof.xml")
# Perturb from nominal and measure convergence
lambda_measured = verifier.estimate_contraction_rate(
    n_trials=50, perturbation_scale=0.1
)
print(f"Measured contraction rate: λ = {lambda_measured:.4f}")
# Should match the theoretical prediction from LQR eigenvalues