Overview

site-information
Scope, evidence standards, and reading paths for the AffineDrift website

Overview

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

AffineDrift is a public technical website about control-affine mechanics, golf-swing models, and related questions in biomechanics and motor control. It brings together textbooks, research notes, critiques, and software resources. It does not present every interpretation as settled. Its job is to separate three things: established math, conclusions that depend on a model, and open hypotheses.

ImportantSuggested Reading Path
  1. Article Index lists everything published now.
  2. Drifter Manifesto is the core AffineDrift series.
  3. The Physics of Golf is the textbook on golf.
  4. The Geometry of Motion is the wider series on the math.
  5. Critiques and Responses covers scope limits, objections, and unresolved points.

Core Analytical Framing

The same equation appears again and again on this site. It is a control-affine ordinary differential equation:

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

Here \(x\) is the modeled state of the system. The term \(f(x)\) is what the system does when the control input is set to zero. The term \(G(x)u\) is the effect of the modeled input. This form is standard in nonlinear control theory. AffineDrift’s own contribution is to use it as a lens on golf-swing mechanics and related biomechanics questions.

On this site, drift means the part of the motion given by \(f(x)\). Control means the modeled input, \(G(x)u\). The split can be useful. But what it means depends on four choices: the coordinates, the multibody model, how constraints are treated, and how actuation is represented. The Mathematical Notation Reference is the official source for drift, control, the ZTCF family, ZVCF, DCR, DgCR, and the symbols.

NoteWhere This Framework Comes From

The control-affine form itself is standard material in nonlinear systems. The site’s use of the drift and input split, zero-torque counterfactuals, and related golf-specific readings is original AffineDrift synthesis. It is 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 sources.
  • A number is only as strong as the model, the parameters, and the method used to fit them.
  • Read claims about motor control, skill, or cause with caution. Trust them only if the page gives direct data, citations, or a clearly bounded derivation.
  • Exploratory pages stay up because they may still be useful. Read them as proposals or working notes, not as settled conclusions.

Main Content Areas

  • Drifter Manifesto: the main AffineDrift series on control-affine models of the golf swing.
  • The Physics of Golf: a textbook that applies the site’s mechanics to golf.
  • The Geometry of Motion: a wider series on the math and computing.
  • Tangent Hyperplanes: an exploratory series on tangent-space methods, with clear sources and scope notes.
  • Research Reviews: the hub for literature reviews. The current review pages are still incomplete.
  • Models: modeling and simulation resources across several software stacks.
  • UpstreamDrift: the site’s main modeling software, with a web UI, a REST API, and analysis tools (see the section below).

UpstreamDrift: The Software

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

At that revision, the web UI and the versioned REST API are available. Not every engine is supported to the same level:

  • Supported: MuJoCo, tested on every required pull request.
  • Extended: Drake and Pinocchio, tested by nightly or targeted checks.
  • Experimental: OpenSim and MyoSuite, outside the required release gate.

These are software support tiers. They are not proof that the engines give the same numbers. They are not proof of biomechanical validity or accuracy for any participant. They do not show the software is fit 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". That is the lowest version that will install. It is not a promise that every later version works. Python 3.11 and 3.12 are the tested interpreter minors at that revision. (A minor version is one like 3.12.) The metadata declaration does not establish support for untested interpreter minors such as Python 3.13.

# Clone the 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 work without a real engine, GOLF_USE_MOCK_ENGINE=1 selects the mock engine. Its output is synthetic. Do not present it 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 in the shape of 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 shows only the shape of a request. Whether it runs still depends on the engine you pick, the model setup, your environment, and valid inputs. Check the running server’s /docs endpoint for its exact OpenAPI contract.

Documentation & Troubleshooting

TipTroubleshooting

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

Scope and Limits

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

A few topics call for extra caution:

  • Which force caused what in a golf swing depends on the coordinates, the constraint models, and how internal forces are represented.
  • Numbers that compare drift and control depend on the model. Do not apply them beyond the assumptions used to derive them.
  • Shaft flexibility, soft-tissue mechanics, and neuromuscular control add more modeling uncertainty.
  • Impact is a hybrid event. Any framework for the swing before impact has to say clearly what it does and does not claim about the collision itself.

Reader Guidance

For the broadest introduction, start with the Article Index. Then read the Drifter Manifesto next to the matching critique pages.

For a golf textbook path, begin with The Physics of Golf.

For the math first, begin with The Geometry of Motion. Volume 0 and Volume I are the best places to start.

Citation

BibTeX citation: Download .bib
@online{untitled,
  author = {},
  title = {Overview},
  url = {https://affinedrift.com/pages/overview.html},
  langid = {en}
}
For attribution, please cite this work as:
“Overview.” n.d. https://affinedrift.com/pages/overview.html.