Contributing

Contribute to gp4c development.

Getting Started

Fork and clone the repository:

git clone https://github.com/yourusername/gp4c.git
cd gp4c

Install in development mode:

pip install -e ".[dev,viz]"

Development Workflow

1. Create a Feature Branch

git checkout -b feature/my-feature

2. Make Changes

Edit code in:

• gp4c/ - Python package
• gp4c/_sampler.c - C implementation
• gp4c/_core.pyx - Cython wrapper
• tests/ - Test suite

3. Rebuild After Changes

Rebuild Cython extension:

python setup.py build_ext --inplace

4. Run Tests

pytest tests/ -v

Run with coverage:

pytest tests/ --cov=gp4c --cov-report=html
open htmlcov/index.html

5. Format Code

Use black and isort:

black gp4c/ tests/
isort gp4c/ tests/

6. Commit Changes

git add .
git commit -m "Add feature X"

Follow conventional commit format:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• test: Tests
• refactor: Code restructuring

7. Push and Create PR

git push origin feature/my-feature

Create pull request on GitHub.

Code Guidelines

Python Style

• Follow PEP 8
• Use type hints
• Document functions with docstrings
• Maximum line length: 88 (black default)

Example:

def sample_prior(
    spec: SamplingSpec,
    sigma2: float = 1.0,
    ell: float = 1.0,
    n_samples: int = 1,
    seed: int = 42
) -> GPSamples:
    """
    Sample from joint GP.

    Parameters
    ----------
    spec : SamplingSpec
        Sampling specification
    sigma2 : float
        Kernel variance

    Returns
    -------
    GPSamples
        Sampled functions
    """

C Style

• Follow kernel style
• Comment non-obvious code
• Use descriptive variable names
• Check return values from GSL

Example:

/* Compute RBF kernel k(x, x') */
double k_ff(double x, double xp, double sigma2, double ell) {
    double diff = x - xp;
    double d2 = diff * diff;
    return sigma2 * exp(-d2 / (2.0 * ell * ell));
}

Tests

Add tests for new features:

def test_new_feature():
    """Test description."""
    # Arrange
    x = np.linspace(0, 5, 100)
    spec = SamplingSpec(x_f=x)

    # Act
    result = sample_prior(spec, ell=0.5, n_samples=5)

    # Assert
    assert result.f.shape == (5, 100)
    assert np.all(np.isfinite(result.f))

Documentation

Update documentation in docs/:

• Use Markdown
• Include code examples
• Add to mkdocs.yml navigation if new page
• Build locally:

mkdocs serve

View at http://127.0.0.1:8000

Project Structure

gp4c/
├── gp4c/                  # Python package
│   ├── __init__.py        # Public API
│   ├── _core.pyx          # Cython wrapper
│   ├── _sampler.c         # C implementation
│   ├── _sampler.h         # C header
│   └── types.py           # Type definitions
├── tests/                 # Test suite
├── examples/              # Example scripts
├── notebooks/             # Jupyter notebooks
├── docs/                  # Documentation
├── pyproject.toml         # Build configuration
├── setup.py               # Extension build
├── mkdocs.yml             # Docs configuration
└── README.md              # Short README

Adding New Kernels

To add a new kernel (e.g., Matérn):

1. Implement kernel functions in _sampler.c
2. Add Cython bindings in _core.pyx
3. Extend Python API in __init__.py
4. Add tests in tests/test_kernels.py
5. Document in docs/math/kernels.md

Performance Testing

Benchmark changes:

import time
import numpy as np
from gp4c import sample_prior, SamplingSpec

x = np.linspace(0, 5, 500)
spec = SamplingSpec(x_f=x, x_g=x)

start = time.time()
result = sample_prior(spec, ell=0.5, n_samples=10)
elapsed = time.time() - start

print(f"Time: {elapsed:.4f}s")

Issue Reporting

When reporting bugs:

1. Check existing issues first
2. Provide minimal reproducible example
3. Include versions and platform
4. Describe expected vs actual behavior

Template:

**Bug Description**
Brief description

**Reproduce**
```python
# Minimal code

Expected: X should happen Actual: Y happens

Environment: - gp4c version: X.Y.Z - NumPy version: X.Y.Z - Platform: macOS 12.0 / Ubuntu 22.04 / etc

## Feature Requests

When requesting features:

1. Describe use case
2. Explain why existing API doesn't work
3. Propose API design (optional)
4. Offer to implement (appreciated!)

## Citation

If you use gp4c in research, cite:

```bibtex
@software{gp4c,
  title = {gp4c: Fast Joint Gaussian Process Sampling with Derivatives},
  author = {Your Name},
  year = {2026},
  url = {https://github.com/yourusername/gp4c}
}

License

All contributions are under MIT License. By contributing, you agree to license your work under MIT.

Questions?

Open a GitHub issue or discussion.