Contributing

This repository is intended to be a research codebase that remains readable and extensible.

Development install

From the repo root (torus_voltage_solver/):

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e '.[test,docs]'

Run tests

pytest -q

Build docs locally

python -m sphinx -b html docs docs/_build/html -W

Benchmarks

Benchmarks live in benchmarks/ and are meant to be fast sanity checks rather than exhaustive performance reports:

python benchmarks/bench_forward_and_grad.py
python benchmarks/bench_fieldline.py

Code organization and extension points

If you want to add new research features, common extension points are:

  • New winding-surface geometry (replace/extend TorusSurface)

  • New current representations (new parameterization of \(\Phi\) or a different electrode kernel)

  • Faster Biot–Savart backends (FMM, batching, caching, GPU-friendly kernels)

  • New objective terms and constraints (e.g. coil power, smoothness, symmetry, manufacturing rules)

  • Better field-line diagnostics (surface-of-section, rotational transform, island detection)

Scientific contribution guidelines

  • Include units and sign conventions in new code and docs.

  • Add at least one validation test for any new physical model component.

  • When changing an algorithm, add a small regression test that would have caught common mistakes (e.g. wrong factor of \(2\pi\), wrong normalization, wrong current sign).