OptionStratLib

OptionStratLib is a comprehensive Rust library for options trading and strategy development. It provides a modular, type-safe toolkit for modeling, analyzing, and visualizing options strategies across multiple asset classes.

Key capabilities include:

• Pricing Models: Black-Scholes, Binomial Trees, Monte Carlo, Telegraph Process, and support for 14 exotic option types.
• Greeks: Full suite including Delta, Gamma, Theta, Vega, Rho, Vanna, Vomma, Veta, Charm, and Color.
• Volatility: Implied volatility (Newton-Raphson), surface construction, and historical estimation.
• Strategy Support: 25+ strategies including Spreads, Butterflies, Iron Condors, Volatility plays, and Income strategies (e.g., Covered Calls).
• Risk Management: Break-even analysis, P&L calculations, and delta neutrality analysis.
• Simulation & Backtesting: Monte Carlo simulations and a comprehensive backtesting engine.
• Visualization: Payoff diagrams, Greeks, and 3D volatility surfaces (via plotly.rs).

OptionStratLib uses a strict, type-safe approach to financial arithmetic to prevent silent errors like overflows or non-finite values.

Decimal Arithmetic

All monetary-path calculations use rust_decimal. To prevent silent wraparound, the library routes through specific kernels in model::decimal:

• d_add, d_sub, d_mul, d_div, d_sum, d_sum_iter.
• Arithmetic errors surface as DecimalError::Overflow { operation, lhs, rhs }.

Non-Finite Guards

To prevent f64 issues (like NaN or Inf) from corrupting calculations, boundaries between f64 and Decimal are wrapped with finite_decimal(..). This surfaces domain-specific errors instead of defaulting to zero:

• PricingError::NonFinite { context, value }
• GreeksError::NonFinite
• VolatilityError::NonFinite
• SimulationError::NonFinite

Type-Safe Constraints

• Positive: Monetary values, strikes, and volatilities use a Positive newtype. Inverted strikes or out-of-range values return a StrategyError rather than panicking.
• NonZeroUsize: Simulation steps (e.g., in monte_carlo_option_pricing) require std::num::NonZeroUsize. Use the nz!(N) macro for literal call sites.

The library supports multiple pricing models depending on the option type and style:

• black_scholes: Used for European options.
• black_76: Used for forward-priced options.
• garman_kohlhagen: Used for FX / Currency options.
• barone_adesi_whaley: Used for American options.
• binomial_model: Used for American and Bermuda options.
• monte_carlo: Used for path-dependent options (e.g., Asian, Lookback, Barrier).

Standard options are categorized into European, American, and Bermuda. Path-dependent options include Asian, Lookback, and Barrier. Multi-asset options include Rainbow and Spread. Special payoffs include Binary, Power, Quanto, and Compound.

flowchart TB
    subgraph Standard["Standard Options"]
        EU[European]
        AM[American]
        BE[Bermuda]
    end

subgraph PathDependent["Path-Dependent"]
        AS[Asian]
        LB[Lookback]
        BA[Barrier]
        CL[Cliquet]
    end

subgraph MultiAsset["Multi-Asset"]
        RB[Rainbow]
        SP[Spread]
        EX[Exchange]
    end

subgraph Special["Special Payoffs"]
        BI[Binary]
        PW[Power]
        QU[Quanto]
        CO[Compound]
        CH[Chooser]
    end

subgraph Forward["Forward-Priced"]
        FUT[Future]
        FWD[Forward]
    end

subgraph FX["FX / Currency"]
        FX_S[FX Spot]
    end
BS[black_scholes] --> EU
    BS --> PathDependent
    BS --> MultiAsset
    BS --> Special
    B76[black_76] --> Forward
    GK[garman_kohlhagen] --> FX
    BAW[barone_adesi_whaley] --> AM
    BIN[binomial_model] --> AM
    BIN --> BE
    MC[monte_carlo] --> PathDependent

The library is organized into several functional modules:

model/ (Core Data Structures)

Handles the fundamental types for trading:

• option.rs: Option structures with pricing and Greeks.
• position.rs: Position management and P&L tracking.
• leg/: Multi-instrument support including SpotPosition, PerpetualPosition (crypto), and FuturePosition.
• positive.rs: Type-safe Positive numbers for strikes and volatilities.

pricing/ (Pricing Engines)

• Standard Models: black_scholes_model.rs, binomial_model.rs, monte_carlo.rs.
• Specialized Models: black_76.rs (futures), garman_kohlhagen.rs (FX), telegraph.rs (jump-diffusion).
• Exotic Options: Dedicated modules for Asian, Barrier, Binary, Lookback, Compound, Chooser, Cliquet, Rainbow, Spread, Quanto, Exchange, and Power options.

strategies/ (Trading Implementations)

Provides ready-to-use strategy implementations and analysis tools:

• Implementations: Single legs, Spreads (Bull/Bear), Butterflies, Iron Condors/Butterflies, Straddles/Strangles, and Protection (Collars/Protective Puts).
• Analysis: probabilities/ for outcome analysis and delta_neutral/ for adjustment tools.

volatility/ (Volatility Modeling)

• utils.rs: Implied volatility via Newton-Raphson.
• traits.rs: Interfaces for volatility models and surface construction.

The library uses a highly modular trait system to provide consistent capabilities across different types of trading strategies. If you are building custom strategies, implementing these traits allows them to integrate with the library's analysis and visualization tools.

Key traits include:

• Strategable: The master trait that combines all other capabilities.
• BasicAble: Provides access to underlying price, symbol, expiration, and title.
• Positionable: Allows managing positions via get_positions(), add_position(), and modify_position().
• Strategies: Provides financial totals like get_net_premium_received(), get_max_profit(), get_max_loss(), and get_total_cost().
• BreakEvenable: Enables calculation of break-even points via get_break_even_points().
• Profit: Provides P&L calculation at specific price points via get_point_at_price() and calculate_profit_at().
• Greeks: Provides risk sensitivities like delta(), gamma(), theta(), and vega().
• DeltaNeutrality: Provides get_delta() and suggest_delta_adjustments() for hedging.
• Graph: Enables visualization via to_plot() and file exports like write_html(), write_png(), etc.

classDiagram
    class Strategable {
        <<trait>>
        Master trait combining all capabilities
    }

class BasicAble {
        <<trait>>
        +get_underlying_price()
        +get_underlying_symbol()
        +get_expiration()
        +get_title()
    }

class Positionable {
        <<trait>>
        +get_positions()
        +add_position()
        +modify_position()
    }

class Strategies {
        <<trait>>
        +get_net_premium_received()
        +get_max_profit()
        +get_max_loss()
        +get_total_cost()
    }

class BreakEvenable {
        <<trait>>
        +get_break_even_points()
        +calculate_break_even()
    }

class Profit {
        <<trait>>
        +get_point_at_price()
        +calculate_profit_at()
    }

class Greeks {
        <<trait>>
        +delta()
        +gamma()
        +theta()
        +vega()
    }

class DeltaNeutrality {
        <<trait>>
        +get_delta()
        +suggest_delta_adjustments()
    }

class Graph {
        <<trait>>
        +to_plot()
        +write_html()
        +write_png()
    }

Strategable --|> BasicAble
Strategable --|> Positionable
Strategable --|> Strategies
Strategable --|> BreakEvenable
Strategable --|> Profit
Strategable --|> Greeks
Strategable --|> DeltaNeutrality
Strategable --|> Graph

OptionStratLib uses a hierarchical model to represent financial instruments and holdings:

• Options: The fundamental unit representing an option contract. It includes properties like option_type (e.g., European, American), side (Long/Short), strike_price, expiration_date, implied_volatility, and underlying_price. It implements Greeks and Graph traits.
• Position: Represents a holding that contains an Options object. It tracks position_cost, entry_date, and fees to calculate net_cost(), unrealized_pnl(), and pnl_at_expiration().
• Leg: An enumeration used to compose complex strategies. A Leg can be an Option(Position), a Spot(SpotPosition), a Future(FuturePosition), or a Perpetual(PerpetualPosition). This allows for strategies like Covered Calls that combine spot and option legs.
• SpotPosition: Represents a non-derivative holding (like a stock). It tracks symbol, quantity, cost_basis, and side, providing methods like market_value() and break_even_price().

classDiagram
class Options {
+option_type: OptionType
+side: Side
+underlying_symbol: String
+strike_price: Positive
+expiration_date: ExpirationDate
+implied_volatility: Positive
+quantity: Positive
+underlying_price: Positive
+risk_free_rate: Decimal
+option_style: OptionStyle
+dividend_yield: Positive
+exotic_params: Option~ExoticParams~
+calculate_price_black_scholes()
+calculate_price_binomial()
+time_to_expiration()
+is_long()
+is_short()
+validate()
+to_plot()
+calculate_implied_volatility()
+delta()
+gamma()
+theta()
+vega()
+rho()
+vanna()
+vomma()
+veta()
+charm()
+color()
}

class Position {
+option: Options
+position_cost: Positive
+entry_date: DateTime<Utc>
+open_fee: Positive
+close_fee: Positive
+net_cost()
+net_premium_received()
+unrealized_pnl()
+pnl_at_expiration()
+validate()
}

class Leg {
<<enumeration>>
Option(Position)
Spot(SpotPosition)
Future(FuturePosition)
Perpetual(PerpetualPosition)
+is_option()
+is_spot()
+is_linear()
+delta()
+pnl_at_price()
}

class SpotPosition {
+symbol: String
+quantity: Positive
+cost_basis: Positive
+side: Side
+date: DateTime<Utc>
+open_fee: Positive
+close_fee: Positive
+pnl_at_price()
+delta()
+market_value()
+break_even_price()
}

class ExpirationDate {
+Days(Positive)
+Date(NaiveDate)
+get_years()
+get_date()
+get_date_string()
+from_string()
}

class Positive {
+value: Decimal
+ZERO: Positive
+ONE: Positive
+format_fixed_places()
+round_to_nice_number()
+is_positive()
}

class OptionStyle {
<<enumeration>>
Call
Put
}

class OptionType {
<<enumeration>>
European
American
Bermuda
Asian
Barrier
Binary
Lookback
Compound
Chooser
Cliquet
Rainbow
Spread
Quanto
Exchange
Power
}

class Side {
<<enumeration>>
Long
Short
}

Options --|> Greeks : implements
Options --|> Graph : implements
Position o-- Options : contains
Leg o-- Position : Option variant
Leg o-- SpotVariant : Spot variant
SpotPosition *-- Side : has
SpotPosition *-- Positive : uses
Options *-- OptionStyle : has
Options *-- OptionType : has
Options *-- Side : has
Options *-- ExpirationDate : has
Options *-- Positive : uses