Development Guide

This guide covers how to contribute to FastQuat development.

Setting up Development Environment

Clone the repository:

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

Install in development mode:
```
pip install -e ".[dev]"
```
Install pre-commit hooks (optional but recommended):
```
pre-commit install
```

Running Tests

FastQuat uses pytest for testing:

# Run all tests
pytest

# Run with coverage
pytest --cov=fastquat

# Run specific test file
pytest tests/test_rotation.py

# Run tests with JIT compilation
pytest -k "jit"

Code Style

We use ruff for code formatting and linting:

# Format code
ruff format

# Check for linting issues
ruff check

# Fix linting issues automatically
ruff check --fix

Project Structure

fastquat/
├── src/fastquat/           # Main package
│   ├── __init__.py
│   └── quaternion.py       # Core Quaternion class
├── tests/                  # Test suite
│   ├── test_base.py        # Basic operations
│   ├── test_math.py        # Mathematical operations
│   ├── test_rotation.py    # Rotation and SLERP tests
│   └── test_tensor.py      # Tensor operations
├── docs/                   # Documentation
├── benchmarks/             # Performance benchmarks
└── pyproject.toml          # Project configuration

Adding New Features

When adding new features:

Write tests first: Add tests in the appropriate test file
Follow existing patterns: Look at existing code for style and structure
Add documentation: Update docstrings and add examples
Consider JAX compatibility: Ensure your code works with JIT, vmap, and grad
Benchmark performance: Add benchmarks for performance-critical code

Contributing Guidelines

Fork the repository and create a feature branch
Write comprehensive tests for new functionality
Update documentation including docstrings and examples
Run the test suite to ensure nothing is broken
Submit a pull request with a clear description

Performance Considerations

FastQuat is designed for high performance. When contributing:

Avoid Python loops: Use JAX operations that can be vectorized
Consider memory layout: Operations should work efficiently with batched data
Profile your code: Use JAX profiling tools to identify bottlenecks
Test with JIT: Ensure your code compiles and runs efficiently under JIT

Example: Adding a New Method

Here’s how to add a new method to the Quaternion class:

def new_method(self, parameter: Array) -> Quaternion:
    """Brief description of what the method does.

    Args:
        parameter: Description of the parameter

    Returns:
        Description of the return value
    """
    # Implementation using JAX operations
    result = jnp.some_operation(self.wxyz, parameter)
    return Quaternion.from_array(result)

Then add tests:

@pytest.mark.parametrize('do_jit', [False, True])
def test_new_method(do_jit):
    """Test the new method."""
    def test_fn(q, param):
        return q.new_method(param)

    if do_jit:
        test_fn = jax.jit(test_fn)

    # Test implementation
    q = Quaternion.ones()
    result = test_fn(q, parameter)
    assert jnp.allclose(result.wxyz, expected_result)

Documentation

Documentation is built using Sphinx with MyST parser for Markdown support. To build locally:

cd docs
make html

The documentation will be available in docs/build/html/.

Release Process

Update version number in pyproject.toml
Update CHANGELOG.md with new features and fixes
Create a git tag: git tag v0.2.0
Push to GitHub: git push --tags
Create a GitHub release
The CI will automatically build and upload to PyPI

Getting Help

GitHub Issues: Report bugs or request features
Discussions: Ask questions or discuss ideas
Email: Contact the maintainers directly

We welcome contributions of all kinds!