Contributing

How to contribute to Optyx development
Published

February 8, 2026

1 Welcome Contributors! πŸŽ‰

Thank you for your interest in contributing to Optyx! This guide will help you get started with development.

2 Development Setup

2.1 Prerequisites

  • Python 3.12 or higher
  • uv package manager (recommended)
  • Git

2.2 Clone and Install

# Clone the repository
git clone https://github.com/daggbt/optyx.git
cd optyx

# Create virtual environment and install dependencies
uv sync

# Verify installation
uv run python -c "import optyx; print(optyx.__version__)"

2.3 Set Up Pre-commit Hooks

We use pre-commit hooks to automatically check code quality before commits:

# Install the git hooks (pre-commit is already installed with uv sync)
uv run pre-commit install

# (Optional) Run hooks on all files
uv run pre-commit run --all-files

Now ruff (linting & formatting) and pyright (type checking) will run automatically on staged files before each commit.

2.4 Alternative: pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

3 Project Structure

optyx/
β”œβ”€β”€ src/optyx/           # Source code
β”‚   β”œβ”€β”€ core/
β”‚   β”‚   β”œβ”€β”€ expressions.py   # Variable, Constant, operators
β”‚   β”‚   β”œβ”€β”€ functions.py     # Mathematical functions (sin, cos, exp, etc.)
β”‚   β”‚   β”œβ”€β”€ compiler.py      # Expression β†’ NumPy/SciPy compilation
β”‚   β”‚   β”œβ”€β”€ autodiff.py      # Symbolic differentiation
β”‚   β”‚   └── verification.py  # Gradient verification utilities
β”‚   └── __init__.py          # Public API exports
β”œβ”€β”€ tests/               # Test suite
β”œβ”€β”€ docs/                # Quarto documentation
β”œβ”€β”€ examples/            # Runnable example scripts
└── pyproject.toml       # Project configuration

4 Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=optyx --cov-report=html

# Run specific test file
uv run pytest tests/test_expressions.py

# Run tests matching a pattern
uv run pytest -k "test_gradient"

5 Code Style

5.1 Formatting

We use Ruff for formatting and linting:

# Format code
uv run ruff format src tests

# Check for issues
uv run ruff check src tests

# Auto-fix issues
uv run ruff check --fix src tests

5.2 Type Checking

We use pyright for static type checking:

uv run pyright src

5.3 Docstrings

All public APIs must have NumPy-style docstrings:

def compute_jacobian(
    expressions: list[Expression],
    variables: list[Variable],
) -> list[list[Expression]]:
    """
    Compute the Jacobian matrix of expressions with respect to variables.

    Parameters
    ----------
    expressions : list[Expression]
        List of expressions to differentiate.
    variables : list[Variable]
        List of variables to differentiate with respect to.

    Returns
    -------
    list[list[Expression]]
        Jacobian matrix where J[i][j] = βˆ‚expressions[i]/βˆ‚variables[j].

    Examples
    --------
    >>> x, y = Variable("x"), Variable("y")
    >>> exprs = [x**2 + y, x * y]
    >>> J = compute_jacobian(exprs, [x, y])
    """

6 Pull Request Process

6.1 1. Create a Branch

# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

6.2 2. Make Changes

  • Write code following our style guide
  • Add tests for new functionality
  • Update documentation if needed

6.3 3. Test Locally

# Run the full test suite
uv run pytest

# Check formatting
uv run ruff format --check src tests

# Check linting
uv run ruff check src tests

# Check types
uv run pyright src

Note: If you’ve set up pre-commit hooks, these checks run automatically on commit. You can also run them manually with pre-commit run --all-files.

6.4 4. Commit and Push

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add support for matrix operations"

# Push to your fork
git push origin feature/your-feature-name

6.5 5. Open Pull Request

  • Go to GitHub
  • Click β€œNew Pull Request”
  • Select your branch
  • Fill in the PR template
  • Request review

7 Commit Message Guidelines

We follow Conventional Commits:

Type Description
feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting, no code change
refactor: Code restructuring
test: Adding tests
chore: Maintenance tasks

Examples:

feat: add symbolic matrix multiplication
fix: correct gradient computation for division
docs: add tutorial for constraint handling
test: add edge cases for autodiff

8 Areas for Contribution

8.1 Current Priorities

  1. Documentation & Examples
    • More real-world application examples (finance, logistics, engineering, ML)
    • Tutorial enhancements and walkthroughs
    • API reference improvements with usage patterns
  2. Developer Experience
    • Better error messages and diagnostic output
    • Debugging utilities for gradient verification
    • Enhanced IDE support and type hints
  3. Performance & Benchmarking
    • Benchmark suite against other optimization libraries
    • Performance profiling and optimization
    • Expression simplification algorithms
    • Compilation and caching strategies
  4. Test Coverage
    • Edge cases and boundary conditions
    • Numerical stability tests
    • Cross-platform compatibility

8.2 Future Features (v1.2+)

  • Advanced Backends: JAX integration for GPU acceleration and JIT compilation, custom solver backends (Gurobi, CPLEX, MOSEK)
  • Optimization Intelligence: Convex optimization detection, problem classification and solver recommendation
  • Scalability: Sparse matrix support for large-scale problems, distributed computing capabilities
  • Ecosystem Integration: PyTorch/TensorFlow integration examples, scikit-learn pipeline compatibility, pandas DataFrame workflows

9 Documentation

9.1 Preview Docs Locally

# Install Quarto: https://quarto.org/docs/get-started/
cd docs
quarto preview

9.2 Writing Documentation

  • Use Quarto Markdown (.qmd files)
  • Include executable Python code blocks
  • Add LaTeX for mathematical notation

10 Getting Help

  • GitHub Issues: Bug reports and feature requests
  • Discussions: Questions and community support

11 Code of Conduct

Please be respectful and constructive in all interactions. We’re building a welcoming community for everyone interested in symbolic optimization.

Thank you for contributing to Optyx! πŸš€