Development¶

Resources for contributors and developers working with Diffid.

Getting Started with Development¶

Quick Setup¶

# Clone the repository
git clone https://github.com/bradyplanden/diffid.git
cd diffid

# Create Python environment
uv sync

# Build Rust extension with Python bindings
uv run maturin develop

# Run tests
uv run pytest -v      # Python tests
cargo test            # Rust tests

Development Workflow¶

1. Make Changes¶

Edit Rust source in rust/src/ or Python bindings in python/.

2. Rebuild¶

uv run maturin develop  # For Python binding changes

3. Test¶

# Python tests
uv run pytest -v

# Rust tests
cargo test

# Both
cargo test && uv run pytest -v

4. Update Stubs¶

If you modified Python bindings:

uv run cargo run -p diffid-py --no-default-features --features stubgen --bin generate_stubs

5. Format and Lint¶

# Rust
cargo fmt
cargo clippy

# Python
uv run ruff check .
uv run ruff format .

Project Structure¶

diffid/
├── rust/                   # Rust core implementation
│   ├── src/
│   │   ├── builders/       # Problem builders
│   │   ├── optimisers/     # Optimisation algorithms
│   │   ├── sampler/        # MCMC and nested sampling
│   │   ├── cost/           # Cost metrics
│   │   └── problem/        # Problem types
│   ├── Cargo.toml
│   └── tests/              # Rust tests
├── python/                 # Python bindings
│   ├── src/diffid/
│   │   ├── __init__.py
│   │   └── _diffid.pyi   # Generated type stubs
│   └── diffid/           # PyO3 bindings source
├── examples/               # Example scripts
├── tests/                  # Python tests
├── docs/                   # Documentation (this site)
├── pyproject.toml          # Python package config
└── README.md

Key Technologies¶

• Rust: Core algorithms, high performance
• PyO3: Python bindings with minimal overhead
• Maturin: Build system for Rust Python extensions
• uv: Fast Python package management
• MkDocs Material: Documentation site

Testing Strategy¶

Unit Tests¶

Rust unit tests alongside code:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // ...
    }
}

Integration Tests¶

Python integration tests in tests/:

def test_optimisation():
    builder = diffid.ScalarBuilder().with_objective(func)
    # ...
    assert result.success

Continuous Integration¶

GitHub Actions runs: - Rust tests and clippy - Python tests on multiple versions - Type checking with mypy - Linting with ruff - Documentation builds

Documentation¶

Rust Docs¶

cargo doc --open --no-deps

Python Docs¶

Edit markdown files in docs/:

mkdocs serve  # Live preview
mkdocs build  # Build static site

Docstrings¶

Use NumPy-style docstrings:

def example(x, y):
    """
    Brief description.

    Parameters
    ----------
    x : float
        Description of x.
    y : float
        Description of y.

    Returns
    -------
    float
        Description of return value.
    """

Code Style¶

Rust¶

• Follow Rust API Guidelines
• Use cargo fmt (automatic formatting)
• Pass cargo clippy (linting)

Python¶

• Follow PEP 8
• Use type hints
• Format with ruff format

Performance Profiling¶

Rust¶

cargo install flamegraph
cargo flamegraph --example your_example

Python¶

uv pip install py-spy
py-spy record --native -- python examples/your_example.py

See Also¶

• Architecture - System design
• Contributing - Contribution guidelines
• API Reference - API documentation