Contributing

Thank you for contributing to radpair. The project is a Python package for analytic simulation of cw-EPR spectra of singlet-born spin-correlated radical pairs.

Project Structure

The package uses a src layout. All package code lives under src/radpair:

core.py — entry points do_simulation and do_simulation_multicore.
classes.py — Matrix (tensor rotation) and Core (nuclei group) helper classes.
functions.py — math helpers (unit conversion, Pascal triangles, tensor rotation, grid generation).
_wrappers.py — decorators: timer, function_benchmark, multicore (splits field axis across CPU cores).

__init__.py is empty; there are no public re-exports. Import directly from submodules. The package depends on eprbase for grid.Grid, spectra.Spectra, and interpolation.Interpolator.

Development Setup

The project requires Python 3.13 or newer. The repository uses uv for dependency and environment management.

Clone the repository and change into its directory:

git clone https://github.com/florianquintes/radpair.git
cd radpair

Install the locked development environment from the repository root:

uv sync --dev

The package uses a src layout. Application code belongs under src/radpair and tests belong under tests.

Branches

Create a focused branch for each change and keep unrelated changes separate. The repository does not currently document a required branch naming scheme.

Pull Requests

Pull requests should explain the change and include the relevant validation results. Before opening a pull request, run the checks that apply to the change:

uv run ruff format --check .
uv run ruff check .
uv run pytest
uv build

If documentation is changed, also build the documentation as described in the Development page. Mention known baseline failures or warnings rather than presenting them as regressions.

Code Style

Follow the existing Python and reStructuredText style in the surrounding files. Keep importable Python modules under src/radpair and add tests under tests.

Ruff is the configured formatting and code-quality tool, using its default rules:

uv run ruff format --check .
uv run ruff check .

Docstrings should follow the numpydoc style with LaTeX math where applicable. Type annotations are required on all functions.

Documentation

Documentation source files are under docs/source. The Sphinx configuration reads the package version dynamically via importlib.metadata.version("radpair").

Build the documentation from the repository root:

uv run sphinx-build -b html docs/source docs/build/html

The generated HTML is written to docs/build/html. Add a title to every document included by the root index.rst so Sphinx can include it in the table of contents.