# dervflow Examples

This directory contains example scripts demonstrating the key features of dervflow.

## Example Scripts

### 1. basic_pricing.py

Demonstrates basic option pricing functionality:

- Black-Scholes pricing for European options
- Binomial tree pricing for American options
- Monte Carlo simulation pricing
- Implied volatility calculation
- Greeks calculation
- Batch pricing for multiple options

**Run:**

```bash
python examples/basic_pricing.py
```

### 2. portfolio_optimization.py

Demonstrates portfolio optimization techniques:

- Mean-variance optimization
- Efficient frontier construction
- Risk parity allocation
- Portfolio constraints handling (box constraints, long-only)
- Comparison of different portfolio strategies

**Run:**

```bash
python examples/portfolio_optimization.py
```

**Output:**

- Console output with optimization results
- `efficient_frontier.png` - visualization of the efficient frontier (requires `matplotlib`)

### 3. risk_analysis.py

Demonstrates risk analytics and measurement:

- Greeks calculation for single options
- Greeks sensitivity analysis
- Portfolio Greeks aggregation
- Value at Risk (VaR) using multiple methods
- Conditional Value at Risk (CVaR)
- Maximum drawdown analysis
- Risk-adjusted performance metrics (Sharpe ratio, Sortino ratio)

**Run:**

```bash
python examples/risk_analysis.py
```

**Output:**

- Console output with risk metrics
- `drawdown_analysis.png` - visualization of drawdown analysis (requires `matplotlib`)

### 4. fixed_income_analysis.py

Demonstrates fixed-income analytics using the yield-curve module:

- Bootstrap a Treasury zero curve from coupon-bearing bonds
- Interpolate zero rates, forward rates, and discount factors
- Price a corporate bond from the curve and recover its yield to maturity
- Compute duration, convexity, DV01, and compare shock re-pricings

**Run:**

```bash
python examples/fixed_income_analysis.py
```

### 5. factor_model_allocation.py

End-to-end multi-factor portfolio construction workflow:

- Fit a cross-sectional factor model and inspect betas, alphas, and R²
- Derive factor-implied expected returns and portfolio factor exposures
- Solve for the maximum Sharpe ratio allocation with position limits
- Apply a Black-Litterman update combining market equilibrium with investor views

**Run:**

```bash
python examples/factor_model_allocation.py
```

### 6. market_risk_metrics.py

Comprehensive market risk measurement example:

- Simulate correlated asset returns and aggregate portfolio performance
- Estimate VaR/CVaR across historical, parametric, and Monte Carlo methods
- Measure maximum drawdown and risk-adjusted performance (Sortino ratio)
- Decompose total risk into asset contributions and diversification benefits

**Run:**

```bash
python examples/market_risk_metrics.py
```

## Requirements

All examples require:

- dervflow (installed via `pip install dervflow` or `maturin develop`)
- numpy
- matplotlib (for visualization examples)

Install dependencies:

```bash
pip install numpy

# Optional, for plots generated by certain examples
pip install matplotlib
```

## Additional Examples

For more advanced examples and tutorials, see the Jupyter notebooks in the `examples/notebooks/` directory:

- `01_option_pricing.ipynb` - Comprehensive option pricing examples
- `02_volatility_surface.ipynb` - Volatility surface construction and calibration
- `03_portfolio_optimization.ipynb` - Advanced portfolio optimization
- `04_yield_curves.ipynb` - Yield curve construction and bond analytics
- `05_monte_carlo.ipynb` - Monte Carlo simulation examples
- `06_risk_analysis.ipynb` - Comprehensive risk analysis

## Getting Help

For more information:

- GitHub: https://github.com/alphavelocity/dervflow
- Issues: https://github.com/alphavelocity/dervflow/issues
