Installation

Molenspin distributes pre-built wheels for Linux, macOS, and Windows. You can also build from source if you need a custom Rust feature flag or want to contribute.

From PyPI (recommended)

pip install molenspin

Wheels are available for Python 3.10, 3.11, and 3.12 on:

• Linux x86-64 (manylinux 2.28+)
• Linux aarch64
• macOS 12+ (x86-64 and arm64)
• Windows 10+ (x86-64)

If pip falls back to a source build, see the section below — you'll need a Rust toolchain installed.

With optional dependencies

# Matplotlib support for quick inline plots
pip install "molenspin[plot]"

# Full dev setup (tests, linters, maturin)
pip install "molenspin[dev]"

Verifying the install

python -c "import molenspin; print(molenspin.__version__)"
# 0.4.1

Building from source

You need:

• Rust stable ≥ 1.76 — install via rustup.rs
• maturin — the PyO3 build backend: pip install maturin

git clone https://github.com/k-bekker/molenspin
cd molenspin
maturin develop --release

The --release flag is important; without it the Rust code runs in debug mode and is about 20× slower.

Running the tests

pip install "molenspin[dev]"
pytest tests/ -q

The test suite takes about 8 seconds on a modern laptop. It includes unit tests for the constraint solver, integration tests for known analytical solutions (simple pendulum, planetary gear sets), and regression tests for SVG output.

Docker

There's no official image, but a minimal Dockerfile looks like:

FROM python:3.12-slim
RUN pip install molenspin
WORKDIR /work
ENTRYPOINT ["python"]

If you want to build from source inside Docker, use python:3.12 (not slim) and add curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y before the pip install.

Upgrading

pip install --upgrade molenspin

Check the changelog before upgrading across minor versions — the constraint API had a breaking change in 0.3.0 and again in 0.4.0.