Merge pull request #278 from joaquinbejar/feat/issue-243-cliquet-option

feat: issue #243 cliquet option pricing

Author: joaquinbejar

.windsurf/issues/237-asian-option-pricing.md

@@ -0,0 +1,77 @@
+# Issue #237: Asian Option Pricing Model
+
+## Overview
+
+Asian options are path-dependent options where the payoff depends on the average price of the underlying asset over a specified period. This implementation will support both geometric and arithmetic averaging, with fixed and floating strike variants.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Asian { averaging_type: AsianAveragingType }` exists
+- Ensure `AsianAveragingType` enum has Arithmetic and Geometric variants
+- Add any missing fields for fixed/floating strike distinction
+
+### Phase 2: Geometric Average Asian Option (Closed-Form)
+- Implement `geometric_asian_black_scholes()` in new `src/pricing/asian.rs`
+- Use adjusted Black-Scholes formula:
+  - Adjusted volatility: `σ_adj = σ / √3`
+  - Adjusted rate: `r_adj = (r + σ²/6) / 2` for the cost-of-carry adjustment
+- Support both call and put options
+
+### Phase 3: Arithmetic Average Asian Option
+- Implement Turnbull-Wakeman approximation for closed-form pricing
+- Match first two moments of arithmetic average to lognormal distribution
+- Fallback to Monte Carlo for higher accuracy if needed
+
+### Phase 4: Fixed vs Floating Strike
+- Fixed strike: payoff = max(Average - K, 0) for calls
+- Floating strike: payoff = max(S_T - Average, 0) for calls
+- Handle both variants in pricing functions
+
+### Phase 5: Integration
+- Route `OptionType::Asian` to new pricing functions in `black_scholes_model.rs`
+- Integrate with unified pricing API
+
+### Phase 6: Greeks
+- Use numerical Greeks from existing `src/greeks/numerical.rs` module
+- Route Asian options to numerical implementations in `equations.rs`
+
+### Phase 7: Testing
+- Test geometric average closed-form against known values
+- Test arithmetic approximation accuracy
+- Verify put-call parity relationships
+- Edge cases: zero volatility, zero time, extreme averaging periods
+
+### Phase 8: Documentation
+- Add docstrings and examples
+- Document formula sources and limitations
+
+## Technical Notes
+
+### Geometric Average Closed-Form
+For a geometric average Asian call:
+```
+C = S * e^((b_adj - r) * T) * N(d1) - K * e^(-r * T) * N(d2)
+```
+where:
+- `σ_adj = σ / √3`
+- `b_adj = 0.5 * (r - q - σ²/6)`
+
+### Turnbull-Wakeman Approximation
+Matches moments of the arithmetic average to a lognormal distribution.
+
+## Dependencies
+
+- Existing Black-Scholes infrastructure
+- Numerical Greeks module
+
+## Files to Modify/Create
+
+- `src/pricing/asian.rs` - NEW: Asian option pricing functions
+- `src/pricing/mod.rs` - Export new module
+- `src/pricing/black_scholes_model.rs` - Route Asian to new functions
+- `src/greeks/equations.rs` - Route to numerical Greeks
+
+## Estimated Effort
+
+8-12 hours

.windsurf/issues/239-binary-option-pricing.md

@@ -0,0 +1,61 @@
+# Issue #239: Binary Option Pricing Model
+
+## Overview
+
+Binary options (also called digital options) have a fixed payout if the option expires in-the-money, regardless of how far in-the-money it is. This implementation will support cash-or-nothing and asset-or-nothing variants.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Binary { binary_type: BinaryPayoffType }` exists
+- Check `BinaryPayoffType` enum for CashOrNothing and AssetOrNothing variants
+- Ensure the data model captures the payout amount (Q) for cash-or-nothing
+
+### Phase 2: Cash-or-Nothing Binary Options
+- Implement `cash_or_nothing_call()`: `C = Q * e^(-rT) * N(d2)`
+- Implement `cash_or_nothing_put()`: `P = Q * e^(-rT) * N(-d2)`
+- Q = fixed cash payout amount
+
+### Phase 3: Asset-or-Nothing Binary Options
+- Implement `asset_or_nothing_call()`: `C = S * e^(-qT) * N(d1)`
+- Implement `asset_or_nothing_put()`: `P = S * e^(-qT) * N(-d1)`
+
+### Phase 4: Integration
+- Create `src/pricing/binary.rs` with all pricing functions
+- Route `OptionType::Binary` in `black_scholes_model.rs`
+- Export from `mod.rs`
+
+### Phase 5: Greeks (Numerical)
+- Use numerical Greeks from existing `src/greeks/numerical.rs`
+- Note: Delta is discontinuous at strike, Gamma very large near expiration
+
+### Phase 6: Testing
+- Test cash-or-nothing and asset-or-nothing variants
+- Test call/put symmetry where applicable
+- Test edge cases: ATM, deep ITM/OTM, zero time
+
+### Phase 7: Documentation
+- Add docstrings explaining binary option behavior
+- Note discontinuous Delta at strike
+
+## Technical Notes
+
+### Cash-or-Nothing
+- **Call**: Pays Q if S_T > K
+- **Put**: Pays Q if S_T < K
+- Formula: `C = Q * e^(-rT) * N(d2)` where d2 is standard BS d2
+
+### Asset-or-Nothing
+- **Call**: Pays S_T if S_T > K
+- **Put**: Pays S_T if S_T < K
+- Formula: `C = S * e^(-qT) * N(d1)` where d1 is standard BS d1
+
+## Files to Modify/Create
+
+- `src/pricing/binary.rs` - NEW: Binary option pricing functions
+- `src/pricing/mod.rs` - Export new module
+- `src/pricing/black_scholes_model.rs` - Route Binary to new functions
+
+## Estimated Effort
+
+4-6 hours

.windsurf/issues/240-lookback-option-pricing.md

@@ -0,0 +1,71 @@
+# Issue #240: Lookback Option Pricing Model
+
+## Overview
+
+Lookback options are path-dependent options with payoffs that depend on the maximum or minimum price of the underlying asset during the option's life. This implementation uses the Goldman-Sosin-Gatto (1979) closed-form solutions.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Lookback { lookback_type: LookbackType }` exists
+- Check `LookbackType` enum for FixedStrike and FloatingStrike variants
+- Ensure the data model captures the observed min/max prices
+
+### Phase 2: Floating Strike Lookback Options
+- **Call**: buyer pays minimum price (S_min), always exercised
+  - Formula: Standard Black-Scholes + premium for lookback feature
+- **Put**: buyer receives maximum price (S_max), always exercised
+  - Uses Goldman-Sosin-Gatto closed-form
+
+### Phase 3: Fixed Strike Lookback Options
+- **Call**: Payoff = max(S_max - K, 0)
+- **Put**: Payoff = max(K - S_min, 0)
+- Uses Conze-Viswanathan formulas
+
+### Phase 4: Goldman-Sosin-Gatto Formulas
+For floating strike lookback call (new contract):
+```
+C = S*N(a1) - S*e^(-rT)*(sigma^2/(2r))*N(-a1) 
+    - S*e^(-rT)*N(a2) + S*(sigma^2/(2r))*N(a3)
+```
+Where a1, a2, a3 are adjusted d-values.
+
+### Phase 5: Integration
+- Create `src/pricing/lookback.rs` with all pricing functions
+- Route `OptionType::Lookback` in `black_scholes_model.rs`
+- Export from `mod.rs`
+
+### Phase 6: Greeks
+- Use numerical Greeks from existing `src/greeks/numerical.rs`
+
+### Phase 7: Testing
+- Test floating and fixed strike variants
+- Test call/put pricing
+- Test edge cases: ATM, deep ITM/OTM, zero time
+
+### Phase 8: Documentation
+- Add docstrings explaining lookback behavior
+- Document the path-dependent nature
+
+## Technical Notes
+
+### Floating Strike Lookback
+- Call: `C = S*N(a1) - S_min*e^(-rT)*N(a2) + Y(lambda=1)`
+- Put: `P = S_max*e^(-rT)*N(b1) - S*N(b2) + Y(lambda=-1)`
+
+### Fixed Strike Lookback  
+- Uses standard BS formulas with S_max or S_min instead of S
+
+### Key Parameters
+- For new contracts: S_min = S_max = S (current price)
+- For seasoned contracts: actual observed min/max prices
+
+## Files to Modify/Create
+
+- `src/pricing/lookback.rs` - NEW: Lookback option pricing functions
+- `src/pricing/mod.rs` - Export new module
+- `src/pricing/black_scholes_model.rs` - Route Lookback to new functions
+
+## Estimated Effort
+
+8-12 hours

.windsurf/issues/241-compound-option-pricing.md

@@ -0,0 +1,67 @@
+# Issue #241: Compound Option Pricing Model
+
+## Overview
+
+Compound options are options on options. They have two layers: an outer option (compound) and an inner option (underlying). The holder of a compound option can exercise at T1 to receive (or sell) the underlying option that expires at T2.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Compound { compound_type: CompoundType }` exists
+- Check `CompoundType` enum for the four variants:
+  - CallOnCall, CallOnPut, PutOnCall, PutOnPut
+- Ensure data model captures both strikes (K1, K2) and expiries (T1, T2)
+
+### Phase 2: Bivariate Normal Distribution
+- Implement bivariate CDF approximation (Drezner-Wesolowsky)
+- Required for Geske (1979) compound option formulas
+- Create helper function: `bivariate_normal_cdf(a, b, rho)`
+
+### Phase 3: Critical Value Calculation
+- Find critical underlying price S* where compound option is ATM at T1
+- Solve: f(S*) = 0 where f is the underlying option value minus K1
+- Use Newton-Raphson or bisection method
+
+### Phase 4: Compound Option Pricing (Geske 1979)
+- **Call-on-Call**: Right to buy a call option
+- **Call-on-Put**: Right to buy a put option  
+- **Put-on-Call**: Right to sell a call option
+- **Put-on-Put**: Right to sell a put option
+
+### Phase 5: Integration
+- Create `src/pricing/compound.rs` with all pricing functions
+- Route `OptionType::Compound` in `black_scholes_model.rs`
+- Export from `mod.rs`
+
+### Phase 6: Greeks
+- Use numerical Greeks from existing module
+
+### Phase 7: Testing
+- Test all four compound types
+- Test edge cases: T1 ≈ T2, deep ITM/OTM
+
+## Technical Notes
+
+### Geske Formula Key Components
+- Two cumulative normal distributions N(d1), N(d2)
+- One bivariate normal distribution M(a, b, rho)
+- Correlation rho = sqrt(T1/T2)
+
+### Parameters
+- S: current underlying price
+- K1: strike of compound option
+- K2: strike of underlying option  
+- T1: time to compound expiry
+- T2: time to underlying expiry (T2 > T1)
+- r: risk-free rate
+- σ: volatility
+
+## Files to Modify/Create
+
+- `src/pricing/compound.rs` - NEW: Compound option pricing functions
+- `src/pricing/mod.rs` - Export new module
+- `src/pricing/black_scholes_model.rs` - Route Compound to new functions
+
+## Estimated Effort
+
+8-12 hours

.windsurf/issues/242-chooser-option-pricing.md

@@ -0,0 +1,54 @@
+# Issue #242: Chooser Option Pricing Model
+
+## Overview
+
+Chooser options allow the holder to choose at a specified date (choice date) whether the option becomes a call or a put. Uses Rubinstein (1991) decomposition.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Chooser { choice_date: f64 }` exists
+- Ensure choice_date is captured as time until choice
+
+### Phase 2: Simple Chooser (Rubinstein 1991)
+- Same strike K and expiration T for both call and put
+- Choice date t < T
+- Formula: Chooser = Call(K, T) + Put(K, t) * e^(-(r-q)(T-t))
+- Alternative: C + Se^(-q*t)*N(-y2) - Ke^(-r*t)*N(-y1 + sigma*sqrt(t))
+
+### Phase 3: Complex Chooser (Optional)
+- Different strikes and/or expirations for call vs put
+- More complex valuation
+
+### Phase 4: Integration
+- Create `src/pricing/chooser.rs`
+- Route `OptionType::Chooser` in `black_scholes_model.rs`
+- Export from `mod.rs`
+
+### Phase 5: Testing
+- Test simple chooser pricing
+- Test edge cases: choice_date = 0, choice_date = T
+- Test call/put parity relationships
+
+## Technical Notes
+
+### Simple Chooser Formula
+```
+V = S*e^(-qT)*N(d1) - K*e^(-rT)*N(d2) 
+    + K*e^(-rT)*N(-y2) - S*e^(-qT)*N(-y1)
+```
+Where:
+- d1, d2 are standard BS d-values for T
+- y1 = [ln(S/K) + (b + σ²/2)t] / (σ√t)
+- y2 = y1 - σ√t
+- t = choice date, T = expiration
+
+## Files to Modify/Create
+
+- `src/pricing/chooser.rs` - NEW
+- `src/pricing/mod.rs` - Export
+- `src/pricing/black_scholes_model.rs` - Route
+
+## Estimated Effort
+
+6-8 hours

.windsurf/issues/243-cliquet-option-pricing.md

@@ -0,0 +1,56 @@
+# Issue #243: Cliquet Option Pricing Model
+
+## Overview
+
+Cliquet options (ratchet options) reset their strike periodically, locking in gains. The payoff is the sum of capped/floored returns over each period.
+
+## Implementation Phases
+
+### Phase 1: Core Data Model Verification
+- Verify `OptionType::Cliquet { reset_dates: Vec<f64> }` exists
+- Ensure reset_dates captures the periodic reset schedule
+
+### Phase 2: Forward-Starting Option Approach
+- Treat each period as an independent forward-starting option
+- Price each period's contribution and sum them
+- Apply local caps/floors to each period's return
+
+### Phase 3: Cliquet Pricing Formula
+- For each period i with return R_i = (S_i - S_{i-1}) / S_{i-1}
+- Capped return: min(max(R_i, floor), cap)
+- Total value: Sum of discounted capped returns
+
+### Phase 4: Integration
+- Create `src/pricing/cliquet.rs`
+- Route `OptionType::Cliquet` in `black_scholes_model.rs`
+- Export from `mod.rs`
+
+### Phase 5: Testing
+- Test with various reset frequencies
+- Test caps and floors
+- Test edge cases
+
+## Technical Notes
+
+### Payoff Structure
+- Total Payoff = Σ max(min(R_i, cap), floor)
+- R_i = return in period i
+
+### Pricing Approach
+- Analytical: Sum of forward-starting call/put spreads
+- Each period contributes: BS_call(K=1, T_i) - BS_call(K=1+cap, T_i)
+
+### Default Parameters
+- Local cap: 10% per period
+- Local floor: 0% per period
+- Global cap/floor: Not implemented in first version
+
+## Files to Modify/Create
+
+- `src/pricing/cliquet.rs` - NEW
+- `src/pricing/mod.rs` - Export
+- `src/pricing/black_scholes_model.rs` - Route
+
+## Estimated Effort
+
+10-14 hours