Overview

Scope, evidence standards, and reading paths for the AffineDrift website

AffineDrift is a public technical website about control-affine mechanics, golf-swing modeling, and related questions in biomechanics and motor control. The site combines textbooks, research notes, critiques, and implementation resources. Its purpose is not to present every interpretation as settled; it is to distinguish established mathematical structure from model-dependent inference and open hypotheses.

Core Analytical Framing

The recurring mathematical form on the site is the control-affine ordinary differential equation

\[\dot{x} = f(x) + G(x)u.\]

In this notation, \(x\) denotes the modeled state, \(f(x)\) collects state-dependent dynamics that remain when the applied control input is set to zero, and \(G(x)u\) represents the contribution of the modeled input. That ODE form is standard in nonlinear control theory. AffineDrift’s site-specific contribution is to use it as an organizing lens for golf-swing mechanics and related biomechanical questions.

On this site, drift refers to the state-dependent dynamics represented by \(f(x)\), and control refers to the modeled input contribution \(G(x)u\). That distinction can be analytically useful, but its interpretation depends on the chosen coordinates, the multibody model, the treatment of constraints, and the level at which actuation is represented. The Mathematical Notation Reference is the normative source for drift, control, the ZTCF family, ZVCF, DCR, DgCR, and symbol conventions.

Provenance

The control-affine formulation itself is standard nonlinear-systems material. The site’s use of drift/input decomposition, zero-torque counterfactuals, and related golf-specific interpretations is original AffineDrift synthesis built on top of that standard machinery.

What Counts as Evidence Here

Equations and derivations are strongest when they follow directly from stated model assumptions and cited source material.
Quantitative claims are only as strong as the model, parameter set, and identification procedure behind them.
Interpretive claims about motor control, skill, or causation should be read cautiously unless the page provides direct data, citations, or a clearly delimited derivation.
Exploratory pages are retained where they may still be useful, but they should be read as proposals or working notes rather than settled conclusions.

Main Content Areas

Drifter Manifesto: canonical AffineDrift series on control-affine modeling of the golf swing.
The Physics of Golf: textbook-scale golf application of the site’s mechanics framework.
The Geometry of Motion: broader mathematical and computational series.
Tangent Hyperplanes: exploratory tangent-space series with explicit provenance and scope notes.
Research Reviews: literature-review hub; the current review pages are still incomplete.
Models: modeling and simulation resources across several software stacks.
UpstreamDrift: the site’s primary modeling software — web UI, REST API, and analysis tools (see the section below).

UpstreamDrift: The Software

UpstreamDrift is the separate runtime and computational repository that AffineDrift accompanies. The statements below are an UpstreamDrift authority snapshot pinned to protected commit 8cc236c6879e7535bb6bd15aecbe3396fb6dbb36, reviewed on 2026-08-29. The upstream repository remains the live authority.

At that revision, the web UI and versioned REST API are available. Engine support is not uniform:

Supported: MuJoCo, exercised by required pull-request CI.
Extended: Drake and Pinocchio, exercised by nightly or targeted validation.
Experimental: OpenSim and MyoSuite, outside the required release gate.

These are software support tiers, not proof of cross-engine numerical equality, biomechanical validity, participant-level accuracy, or fitness for coaching or clinical use. See the pinned support-tier contract and the Models page for the AffineDrift link map.

Quick Start

The pinned package metadata declares requires-python = ">=3.11", which is an installation lower bound rather than an open-ended compatibility qualification. Python 3.11 and 3.12 are the tested interpreter minors at that revision. The metadata declaration does not establish support for untested interpreter minors such as Python 3.13.

# Clone the protected public repository
git clone https://github.com/D-sorganization/UpstreamDrift.git
cd UpstreamDrift

# Editable development install using tested Python 3.11 or 3.12
python -m pip install -e ".[dev]"

# Verify the install, then launch the default web UI
python scripts/ci/verify_installation.py
upstream-drift

For UI development without a real engine, GOLF_USE_MOCK_ENGINE=1 selects the mock engine; its output is synthetic and must not be presented as a physics result. Full pinned instructions: UpstreamDrift Getting Started.

A Real API Example

Once the API is running on its default local port, the pinned v1 simulation route accepts a request shaped by UpstreamDrift’s SimulationRequest model:

import requests

# Submit a simulation to the running UpstreamDrift API
resp = requests.post(
    "http://localhost:8000/api/v1/simulate",
    json={"engine_type": "mujoco", "duration": 0.5},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

This example establishes request shape only; successful execution still depends on the selected engine, model configuration, environment, and input validity. Inspect the running server’s /docs endpoint for its exact OpenAPI contract.

Documentation & Troubleshooting

Troubleshooting

If installation fails, see the pinned installation troubleshooting guide. For UI-only work, GOLF_USE_MOCK_ENGINE=1 is experimental synthetic mode, not a scientific simulation.

Scope and Limits

The site is strongest when it explains how a particular model behaves and what follows from that model’s equations. It is weaker whenever a page jumps from model structure to broad claims about human intent, coaching, or biological mechanism without direct supporting evidence.

Several recurring topics deserve that caution:

Golf-swing force attribution depends on coordinate choices, constraint models, and how internal forces are represented.
Quantitative drift/control comparisons are model-dependent and should not be generalized beyond the assumptions used to derive them.
Shaft flexibility, soft-tissue mechanics, and neuromuscular control introduce additional layers of modeling uncertainty.
Impact is a hybrid event; any pre-impact framework has to state clearly what it does and does not claim about the collision itself.

Reader Guidance

If you want the broadest introduction, start with the Article Index, then read the Drifter Manifesto alongside the relevant critique pages.

If you want a golf-specific textbook path, begin with The Physics of Golf.

If you want the mathematical foundations first, begin with The Geometry of Motion, especially Volume 0 and Volume I.