OpenSim Models

OpenSim musculoskeletal models for classical barbell exercises.

Exercises

Exercise	Module	Description
Back Squat	exercises.squat	High-bar back squat with barbell on trapezius
Bench Press	exercises.bench_press	Supine press with barbell gripped at chest
Deadlift	exercises.deadlift	Conventional deadlift from floor to lockout
Snatch	exercises.snatch	Wide-grip floor-to-overhead in one motion
Clean and Jerk	exercises.clean_and_jerk	Floor to shoulders (clean) + overhead (jerk)

Quick Start

pip install -e ".[dev]"
python3 -m pytest

Generate a model

from opensim_models.exercises.squat.squat_model import build_squat_model

xml = build_squat_model(body_mass=80, height=1.75, plate_mass_per_side=60)
with open("squat.osim", "w") as f:
    f.write(xml)

Architecture

See docs/architecture/C4.md for the authoritative Mermaid C4 architecture map and feature-to-component traceability matrix.

• shared/ — Reusable components (DRY)
  • barbell/ — Olympic barbell model (IWF/IPF spec)
  • body/ — Full-body musculoskeletal model (Winter 2009 anthropometrics)
  • contracts/ — Design-by-Contract preconditions and postconditions
  • utils/ — XML generation helpers and geometry/inertia calculations
• exercises/ — Exercise-specific model builders
  • Each exercise inherits from ExerciseModelBuilder (base class)
  • Customizes barbell attachment and initial pose

Testing

Agent-specific test commands for CI and local development:

# Run all unit tests (fast, no OpenSim required)
python3 -m pytest tests/unit/ -m unit -v

# Run integration tests (requires OpenSim package)
python3 -m pytest tests/integration/ -m integration -v

# Run parity/compliance tests across all exercises
python3 -m pytest tests/parity/ -v

# Run hypothesis property-based tests
python3 -m pytest tests/unit/test_hypothesis.py -v

# Run benchmark tests
python3 -m pytest tests/unit/test_benchmarks.py -v

# Run edge-case tests
python3 -m pytest tests/unit/test_edge_cases.py -v

# Run slow tests
python3 -m pytest tests/ -m slow -v

# Run with coverage
python3 -m pytest tests/ --cov=src --cov-report=html --cov-fail-under=80

# Run without parallel execution (for debugging)
python3 -m pytest tests/ -p no:xdist -v

Design Principles

• TDD — Tests written alongside models; CI enforces 80% coverage
• Design by Contract — All inputs validated via preconditions; outputs checked via postconditions
• DRY — Shared base class, shared barbell/body models, shared XML helpers
• Law of Demeter — Exercise builders interact only with public APIs of shared components

Used by UpstreamDrift

This package exposes a model_pack/v1 manifest (model_pack.yaml) and a biomech.model_pack entry point so that UpstreamDrift can discover and load OpenSim models without hard-coding paths. See umbrella issue UpstreamDrift#5179. The OpenSim dashboard tracked in UpstreamDrift#5181 depends on this integration.

Public API (under opensim_models.model_pack):

• manifest() — parsed model_pack.yaml as a dict.
• resolve() — absolute path to the exercises directory.
• list_exercises() — list of declared exercise IDs.

Launcher contract:

opensim-models --list-exercises
python -m opensim_models --exercise gait --export /tmp/gait.osim

License

MIT