optimiz-rs/CONTRIBUTING.md

Contributing to OptimizR

Thank you for your interest in contributing to OptimizR! This document provides guidelines and instructions for contributing.

Development Setup

1. Clone the repository

   git clone https://github.com/yourusername/optimiz-r.git
   cd optimiz-r
   

2. Install Rust (if not already installed)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

3. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

4. Install development dependencies

   pip install -e ".[dev]"
   pip install maturin
   

5. Build Rust extension

   maturin develop
   

Development Workflow

Making Changes

1. Create a new branch for your feature:

   git checkout -b feature/your-feature-name
   

2. Make your changes in appropriate files:

   • Rust code: src/*.rs
   • Python code: python/optimizr/*.py
   • Tests: tests/test_*.py
   • Documentation: docs/*.md, README.md

3. Rebuild after Rust changes:

   maturin develop
   

Code Quality

1. Format code

   # Python
   black python/
   
   # Rust
   cargo fmt
   

2. Lint code

   # Python
   ruff check python/
   
   # Rust
   cargo clippy -- -D warnings
   

3. Type checking

   mypy python/optimizr/
   

Testing

1. Run Python tests

   pytest tests/ -v
   

2. Run Rust tests

   cargo test
   

3. Run with coverage

   pytest tests/ --cov=optimizr --cov-report=html
   

4. Run benchmarks

   cargo bench
   

Contribution Guidelines

Code Style

• Python: Follow PEP 8, use type hints, docstrings in NumPy style
• Rust: Follow Rust conventions, document public APIs with /// comments
• Line length: 100 characters for both Python and Rust
• Imports: Group and sort imports (use isort for Python)

Documentation

• Document all public APIs with examples
• Update README.md if adding major features
• Add docstrings to Python functions
• Add doc comments (///) to Rust functions
• Include mathematical background for algorithms

Commit Messages

Use conventional commit format:

type(scope): brief description

Detailed explanation if needed.

Fixes #issue_number

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(hmm): add support for multivariate emissions
fix(mcmc): correct acceptance probability calculation
docs(readme): update installation instructions

Pull Request Process

1. Before submitting:

   • Ensure all tests pass
   • Add tests for new functionality
   • Update documentation
   • Run code formatters and linters
   • Squash minor commits if appropriate

2. PR Description should include:

   • What changes were made and why
   • Link to related issues
   • Any breaking changes
   • Testing performed

3. Review process:

   • Maintainers will review within 1-2 weeks
   • Address review comments
   • Once approved, maintainer will merge

Areas for Contribution

High Priority

• Additional optimization algorithms (PSO, CMA-ES, Simulated Annealing)
• More HMM variants (discrete emissions, semi-Markov, etc.)
• GPU acceleration via CUDA
• Improved documentation and examples
• Performance benchmarks

Medium Priority

• Additional probability distributions
• Parallel execution support
• More information theory metrics
• Visualization utilities
• R language bindings

Documentation

• Tutorial notebooks
• API reference improvements
• Algorithm explanations
• Performance comparisons
• Use case examples

Questions?

• Open an issue for bugs or feature requests
• Start a discussion for questions
• Email maintainers for sensitive matters

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for making OptimizR better! 🚀