Development

Development Setup

  1. Clone the repository:

git clone https://github.com/CMBSciPol/zeropybench.git
cd zeropybench

  1. Install in development mode:

The dependency groups cuda12 and cuda13 can be used to quickly install JAX with cuda support:

pip install --group dev --group cuda13 -e .
or
uv sync --group cuda13

  1. Install pre-commit (or equivalently prek):

pipx --user install pre-commit
or
uv tool install pre-commit

The pre-commit hooks need to be installed (see more details in the section Code Quality). After doing so, they will be run at each commit.

pre-commit install

Running Tests

The project uses pytest for testing:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run notebook tests
pytest docs/source/user-guide/

# Run specific test file
pytest tests/test_jax.py

The test suite includes:

  • Unit tests: Individual function testing

  • JAX tests: JAX-specific benchmarking tests

  • Functional tests: The documentation notebooks

Code Quality

The project uses several pre-commit hooks for code quality. They include

  • ruff (linting and formatting)

  • mypy (type checking)

  • and others

The pre-commit will be run against the files that are part of a Git commit. To run against all files (modified but not added or already committed):

pre-commit run --all-files

Documentation

Build documentation locally: The dependencies required to build the documentation have already been installed through uv sync. If you prefer using pip, this extra step is required:

pip install --group docs .

Then, the HTML documentation is built and inspected by:

cd docs
make html
firefox build/html/index.html

The documentation uses:

  • Sphinx: Documentation generator

  • MyST: Markdown support in Sphinx

  • Furo: Clean, responsive theme

  • nbsphinx: Jupyter notebook support

Project Structure

zeropybench/
├── src/zeropybench/         # Main package
│   ├── __init__.py             # Public API exports
│   ├── _benchmark.py           # Benchmark class
│   ├── _io.py                  # Read / write utilities
│   ├── _jax.py                 # JAX code transformation utilities
│   ├── _plot.py                # Plotting utilities
│   └── _units.py               # Unit conversion utilities
├── tests/                   # Unit test suite
├── docs/                    # Documentation
│   └── source/
│       ├── _static/            # Logo and CSS file
│       ├── user-guide/         # User guide and notebook examples
│       ├── developer-guide.md  # This file
│       └── reference-guide.md  # API reference
├── .github/                 # CI/CD workflows
├── .pre-commit-config.yaml  # Pre-commit hook configuration
└── pyproject.toml           # Project configuration

Contributing

  1. Fork the repository

  2. Install pre-commit

  3. Create a feature branch: git switch -c feature-name

  4. Make your changes

  5. Add tests for new functionality

  6. Add documentation for new functionality

  7. Ensure all tests pass: pytest

  8. Submit a pull request

Release Process

Releases are automated through GitHub Actions:

  1. Create a new tag: git tag v1.x.x

  2. Push the tag: git push origin v1.x.x

  3. Create a GitHub release

  4. The CI will automatically build and publish to PyPI