optimiz-rs/docs/source/quickstart.md

# Quick Start Guide

## 1. Verify Installation

```bash
python -c "import optimizr; print(optimizr.__version__)"
```

You should see `0.3.0` (or newer). If the Rust backend is missing, reinstall with `pip install .` from the project root to build the extension module.

## 2. First Optimization (Differential Evolution)

```python
import numpy as np
from optimizr import differential_evolution

def rosenbrock(x: np.ndarray) -> float:
    return sum(100.0 * (x[1:] - x[:-1]**2)**2 + (1 - x[:-1])**2)

best_x, best_fx = differential_evolution(
    objective_fn=rosenbrock,
    bounds=[(-5, 5)] * 5,
    strategy="best1",
    adaptive=True,
    maxiter=500,
)

print(f"Best value: {best_fx:.6f}")
print(f"Best point: {best_x}")
```

## 3. Hidden Markov Model (Regime Detection)

```python
import numpy as np
from optimizr import HMM

returns = np.concatenate([
    np.random.normal(0.01, 0.02, 400),
    np.random.normal(-0.01, 0.03, 400),
])

model = HMM(n_states=2).fit(returns, n_iterations=80)
states = model.predict(returns)
print(np.bincount(states))
```

## 4. MCMC Sampling (Bayesian Inference)

```python
import numpy as np
from optimizr import mcmc_sample

def log_likelihood(params, data):
    mu, sigma = params
    residuals = (data - mu) / sigma
    return -0.5 * np.sum(residuals**2) - len(data) * np.log(sigma)

data = np.random.randn(500) + 1.5
samples = mcmc_sample(
    log_likelihood_fn=log_likelihood,
    data=data,
    initial_params=np.array([0.0, 1.0]),
    param_bounds=[(-5, 5), (0.1, 5.0)],
    n_samples=5000,
    burn_in=500,
)

print(samples.mean(axis=0))
```

## 5. Mean Field Games (1D)

```python
from optimizr import MFGConfig, solve_mfg_1d_rust

config = MFGConfig(
    nx=64,
    nt=40,
    x_min=-3.0,
    x_max=3.0,
    T=1.0,
    epsilon=0.1,
    kappa=1.0,
)

solution = solve_mfg_1d_rust(config)
print(f"Converged: {solution.converged}")
```

## Next Steps

- See [Getting Started](getting-started.md) for environment setup and verification.
- Browse [Examples](examples.md) for code snippets per optimizer.
- Deep dive into algorithms in [Algorithms](algorithms/differential_evolution.md).

## Notebook status and reproducibility

- Audit (2025-01-04): 6/7 notebooks execute cleanly; `03_optimal_control_tutorial.ipynb` is theory-only by design.
- Fully validated: `01_hmm_tutorial`, `02_mcmc_tutorial`, `04_real_world_applications`, `05_performance_benchmarks`, `mean_field_games_tutorial`.
- Differential Evolution tutorial works with current API; enable `track_history=True` to capture convergence curves during runs.