optimiz-rs/docs/DEVELOPMENT.md

OptimizR Development Guide

Quick Start

Prerequisites

• Python 3.8+
• Rust 1.70+ (install from https://rustup.rs)
• Git

Setup

# Clone the repository
git clone https://github.com/ThotDjehuty/optimiz-r.git
cd optimiz-r

# Install development dependencies
pip install -e ".[dev]"
pip install maturin

# Build Rust extension
maturin develop --release

# Run tests
pytest tests/ -v

# Run example
python examples/hmm_regime_detection.py

Project Structure

optimiz-r/
├── src/                          # Rust source code
│   ├── lib.rs                   # Main library entry point
│   ├── hmm.rs                   # Hidden Markov Model
│   ├── mcmc.rs                  # MCMC sampling
│   ├── differential_evolution.rs # Differential Evolution
│   ├── grid_search.rs           # Grid Search
│   └── information_theory.rs    # MI and Entropy
│
├── python/optimizr/             # Python package
│   ├── __init__.py             # Package exports
│   ├── core.py                 # Core functions with fallbacks
│   └── hmm.py                  # HMM Python wrapper class
│
├── tests/                       # Python tests
│   └── test_optimizr.py        # Test suite
│
├── examples/                    # Example scripts
│   └── hmm_regime_detection.py # HMM example
│
├── docs/                        # Documentation
│   └── ...                     # API docs, theory, guides
│
├── Cargo.toml                  # Rust dependencies
├── pyproject.toml              # Python project config
├── Makefile                    # Common development tasks
└── README.md                   # Main documentation

Building

Development Build (faster, with debug symbols)

maturin develop

Release Build (optimized)

maturin develop --release

Build Wheel

maturin build --release --out dist/

Testing

Run all tests

make test-all

Python tests only

pytest tests/ -v

Rust tests only

cargo test

With coverage

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

Code Quality

Format code

make format

Lint code

make lint

Type checking

mypy python/optimizr/

Run all checks

make check

Common Commands

See all available commands:

make help

Common workflows:

make dev       # Setup dev environment
make build     # Build release version
make test      # Run tests
make lint      # Check code quality
make format    # Format code
make clean     # Remove build artifacts
make ci        # Run all CI checks locally

Algorithm Implementation Guide

Adding a New Algorithm

1. Create Rust module (src/new_algorithm.rs):

   ///! Algorithm Description
   
   use pyo3::prelude::*;
   
   #[pyfunction]
   pub fn my_algorithm(params: Vec<f64>) -> PyResult<f64> {
       // Implementation
       Ok(result)
   }
   

2. Register in src/lib.rs:

   mod new_algorithm;
   
   #[pymodule]
   fn _core(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
       m.add_function(wrap_pyfunction!(new_algorithm::my_algorithm, m)?)?;
       Ok(())
   }
   

3. Add Python wrapper (python/optimizr/core.py):

   def my_algorithm(params: np.ndarray) -> float:
       if RUST_AVAILABLE:
           return _rust_my_algorithm(params.tolist())
       else:
           return _my_algorithm_python(params)
   

4. Export in __init__.py:

   from optimizr.core import my_algorithm
   __all__ = [..., "my_algorithm"]
   

5. Add tests (tests/test_optimizr.py):

   def test_my_algorithm():
       result = my_algorithm(np.array([1.0, 2.0]))
       assert result > 0
   

6. Add documentation and examples

Benchmarking

Run Rust benchmarks:

cargo bench

Create benchmark:

// benches/benchmarks.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn benchmark_my_algo(c: &mut Criterion) {
    c.bench_function("my_algorithm", |b| {
        b.iter(|| {
            // Benchmark code
        });
    });
}

criterion_group!(benches, benchmark_my_algo);
criterion_main!(benches);

Publishing

Test on TestPyPI

maturin publish --repository testpypi

Publish to PyPI

maturin publish

Troubleshooting

Build fails with "rustc not found"

Install Rust: https://rustup.rs

Import error: "cannot import name '_core'"

Rebuild the extension: maturin develop --release

Tests fail with "module not found"

Install in editable mode: pip install -e .

Slow builds

Use development build: maturin develop (without --release)

Resources

• Rust Book
• PyO3 Guide
• Maturin Docs
• NumPy Docs

Getting Help

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions, share ideas
• Email: your.email@example.com