OptionStratLib v0.6.0: Financial Options Library

Table of Contents

1. Introduction
2. Features
3. Project Structure
4. Core Components
5. Strategies Classification
6. Setup Instructions
7. Library Usage
8. Usage Examples
9. Testing
10. Contribution and Contact

Introduction

OptionStratLib is a comprehensive Rust library for options trading and strategy development across multiple asset classes. This versatile toolkit enables traders, quants, and developers to model, analyze, and visualize options strategies with a robust, type-safe approach. The library focuses on precision with decimal-based calculations, extensive test coverage, and a modular architecture.

Features

1. Valuation Models:

• Black-Scholes model for European options pricing
• Binomial tree model for American and European options
• Monte Carlo simulations for complex pricing scenarios
• Telegraph process model for advanced stochastic modeling

2. Greeks Calculation:

• Delta, gamma, theta, vega, and rho calculations
• Custom Greeks implementation with adjustable parameters
• Greeks visualization for risk analysis
• Sensitivity analysis tools

3. Option Types:

• European and American options
• Calls and puts with customizable parameters
• Support for exotic options (Asian, Barrier, Binary, etc.)
• Comprehensive validation and error handling

4. Volatility Models:

• Constant volatility implementation
• EWMA (Exponentially Weighted Moving Average)
• GARCH implementation for volatility forecasting
• Heston stochastic volatility model
• Volatility surface interpolation techniques

5. Option Chain Management:

• Chain construction and analysis tools
• Strike price generation algorithms
• Chain data import/export (CSV/JSON)
• Filtering and selection tools

6. Trading Strategies:

• Bull Call/Put Spreads
• Bear Call/Put Spreads
• Butterfly Spreads (Long/Short)
• Iron Condor/Butterfly
• Straddles and Strangles
• Covered Calls and Protective Puts
• Strategy optimization framework
• Custom strategy development tools

7. Risk Management:

• SPAN margin calculation
• Position tracking and management
• Break-even analysis
• Profit/Loss calculations at various price points
• Risk profiles and visualizations

8. Simulation Tools:

• Random Walk simulation
• Telegraph process implementation
• Monte Carlo methods for scenario analysis
• Custom simulation frameworks for strategy testing
• Parametrized simulations with adjustable inputs

9. Visualization:

• Strategy payoff diagrams
• Greeks visualization
• Binomial trees
• Risk profiles
• Interactive charts (powered by plotly.rs)
• Robust generation of various plot types (scatter, surface) for different data representations
• Comprehensive test coverage for visualization components, ensuring reliability

10. Data Management:

• CSV/JSON import/export functionality
• Option chain data handling and processing
• Historical data analysis tools
• Price series management and manipulation
• Efficient decimal-based storage

11. Geometry and Curve Tools:

• Curve interpolation techniques
• Surface construction and analysis
• 3D visualization of option surfaces
• Custom geometric operations

12. Backtesting (In Development):

• Historical strategy performance evaluation
• Parameter optimization
• Performance metrics calculation

13. Performance Metrics (In Development):

• Sharpe ratio, Sortino ratio
• Maximum drawdown analysis
• Win/loss ratio calculations
• Return distributions

Project Structure

The project is organized into the following key modules:

1. Model (model/):

• option.rs: Core option structures and methods
• position.rs: Position management
• expiration.rs: Expiration date handling
• positive.rs: Non-negative number type implementation
• types.rs: Common enums and types

2. Pricing Models (pricing/):

• binomial_model.rs: Binomial tree implementation
• black_scholes_model.rs: Black-Scholes pricing
• monte_carlo.rs: Monte Carlo simulations
• telegraph.rs: Telegraph process model
• payoff.rs: Payoff function implementations

3. Greeks (greeks/):

• Base trait definition for Greeks calculations
• Implementation for different option models
• Sensitivity analysis tools

4. Volatility (volatility/):

• constant.rs: Constant volatility model
• ewma.rs: EWMA implementation
• garch.rs: GARCH model
• heston.rs: Heston model
• surface.rs: Volatility surface handling
• traits.rs: Common interfaces for volatility models

5. Strategies (strategies/):

• base.rs: Strategy base traits and interfaces
• Individual strategy implementations:
• bear_put_spread.rs, bull_call_spread.rs, etc.
• build/: Strategy construction tools
• custom.rs: Custom strategy framework
• probabilities/: Probability analysis for strategies

6. Risk Management (risk/):

• span.rs: SPAN margin calculation
• margin.rs: Margin requirements computation
• position.rs: Position risk metrics

7. Simulation (simulation/):

• random_walk.rs: Random walk implementations
• telegraph.rs: Telegraph process modeling
• monte_carlo.rs: Monte Carlo simulation tools
• steps/: Step generation for simulations
• params.rs: Simulation parameters

8. Visualization (visualization/):

• plotly.rs: Plotly integration for interactive charts
• Graph trait implementations
• Utility functions for visualization

9. Geometrics (geometrics/):

• construction/: Tools for building geometric structures
• interpolation/: Interpolation techniques
• analysis/: Analysis tools for curves and surfaces
• visualization/: Visualization of geometric structures

10. Error Handling (error/):

• Comprehensive error types for each module
• Error propagation and handling utilities

Core Components

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()
}

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 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
}

class Side {
<<enumeration>>
Long
Short
}

class Graph {
<<interface>>
+graph_data()
+graph_config()
+to_plot()
+write_html()
+write_png()
+write_svg()
+write_jpeg()
}

class Greeks {
<<interface>>
+delta()
+gamma()
+theta()
+vega()
+rho()
+calculate_all_greeks()
}

Options --|> Greeks : implements
Options --|> Graph : implements
Position o-- Options : contains
Options *-- OptionStyle : has
Options *-- OptionType : has
Options *-- Side : has
Options *-- ExpirationDate : has
Options *-- Positive : uses

Loading

Strategies and Methods

classDiagram
class Strategy {
+name: String
+strategy_type: StrategyType
+description: String
+legs: Vec~Position~
+new()
+validate()
+add_leg()
}

class Strategies {
<<interface>>
+get_volume()
+get_net_premium_received()
+get_max_profit()
+get_max_loss()
+get_profit_ratio()
+get_profit_area()
+get_break_even_points()
+get_fees()
+get_title()
+get_profit_loss_at_price()
+get_positions()
+get_options()
}

class BullCallSpread {
+underlying_symbol: String
+underlying_price: Positive
+long_call: Position
+short_call: Position
+new()
+validate()
}

class BearPutSpread {
+underlying_symbol: String
+underlying_price: Positive
+long_put: Position
+short_put: Position
+new()
+validate()
}

class LongCall {
+underlying_symbol: String
+underlying_price: Positive
+long_call: Position
+new()
+validate()
}

class LongPut {
+underlying_symbol: String
+underlying_price: Positive
+long_put: Position
+new()
+validate()
}

class ShortCall {
+underlying_symbol: String
+underlying_price: Positive
+short_call: Position
+new()
+validate()
}

class ShortPut {
+underlying_symbol: String
+underlying_price: Positive
+short_put: Position
+new()
+validate()
}

class IronCondor {
+underlying_symbol: String
+underlying_price: Positive
+long_put: Position
+short_put: Position
+short_call: Position
+long_call: Position
+new()
+validate()
}

class BasicAble {
<<interface>>
+get_underlying_symbol()
+get_underlying_price()
+one_option()
}

class BreakEvenable {
<<interface>>
+get_break_even_points()
+get_profit_loss_zones()
}

class Validable {
<<interface>>
+validate()
}

class Optimizable {
<<interface>>
+get_best_ratio()
+get_best_profit()
+get_best_loss()
+get_best_premium()
+find_optimal()
}

Strategy ..|> Strategies : implements
BullCallSpread ..|> Strategies : implements
BearPutSpread ..|> Strategies : implements
LongCall ..|> Strategies : implements
LongPut ..|> Strategies : implements
ShortCall ..|> Strategies : implements
ShortPut ..|> Strategies : implements
IronCondor ..|> Strategies : implements

Strategies ..> BasicAble : requires
Strategies ..> BreakEvenable : requires
Strategies ..> Validable : requires
Optimizable ..> Validable : requires
Optimizable ..> Strategies : requires

Loading

Strategies Classification

classDiagram
class StrategyType {
<<enumeration>>
Custom
BullCallSpread
BearPutSpread
LongCall
LongPut
ShortCall
ShortPut
CallButterfly
LongButterflySpread
ShortButterflySpread
IronButterfly
IronCondor
Straddle
LongStraddle
ShortStraddle
Strangle
LongStrangle
ShortStrangle
CoveredCall
ProtectivePut
PoorMansCoveredCall
Collar
}

class DirectionalBias {
<<enumeration>>
Bullish
Bearish
Neutral
}

class VolatilityOutlook {
<<enumeration>>
High
Low
Neutral
}

class ComplexityLevel {
<<enumeration>>
Basic
Intermediate
Advanced
}

class RiskProfile {
<<enumeration>>
DefinedRisk
UndefinedRisk
LimitedProfit
UnlimitedProfit
}

DirectionalBias <-- StrategyType : categorized by
VolatilityOutlook <-- StrategyType : categorized by
ComplexityLevel <-- StrategyType : categorized by
RiskProfile <-- StrategyType : categorized by

class BullishStrategies {
BullCallSpread
LongCall
CoveredCall
PoorMansCoveredCall
}

class BearishStrategies {
BearPutSpread
LongPut
ShortCall
}

class NeutralStrategies {
IronCondor
IronButterfly
ButterflySpread
Straddle
Strangle
}

class HighVolatilityStrategies {
LongStraddle
LongStrangle
LongCall
LongPut
}

class LowVolatilityStrategies {
ShortStraddle
ShortStrangle
IronCondor
ButterflySpread
CoveredCall
}

DirectionalBias <.. BullishStrategies : implements
DirectionalBias <.. BearishStrategies : implements
DirectionalBias <.. NeutralStrategies : implements
VolatilityOutlook <.. HighVolatilityStrategies : implements
VolatilityOutlook <.. LowVolatilityStrategies : implements

Loading

Setup Instructions

Prerequisites

• Rust 1.65 or higher
• Cargo

Installation

Add OptionStratLib to your Cargo.toml:

[dependencies]
optionstratlib = "0.5.1"

Or use cargo to add it to your project:

cargo add optionstratlib

Optional Features

The library includes several optional features that can be enabled:

[dependencies]
optionstratlib = { version = "0.5.1", features = ["plotly", "kaleido", "full"] }

• plotly: Enables visualization using plotly.rs
• kaleido: Enables saving static images (requires plotly)
• full: Enables all features

Building from Source

Clone the repository and build using Cargo:

git clone https://github.com/joaquinbejar/OptionStratLib.git
cd OptionStratLib
cargo build --release

Run tests:

cargo test --all-features

Generate documentation:

cargo doc --open

Library Usage

Basic Usage

use optionstratlib::{Options, OptionStyle, OptionType, Side, ExpirationDate};
use optionstratlib::pos;
use rust_decimal_macros::dec;
use tracing::info;
use optionstratlib::greeks::Greeks;

// Create a basic European call option
let option = Options::new(
OptionType::European,
Side::Long,
"AAPL".to_string(),
pos!(100.0),            // strike_price
ExpirationDate::Days(pos!(30.0)),
pos!(0.2),              // implied_volatility
pos!(1.0),              // quantity
pos!(105.0),            // underlying_price
dec!(0.05),             // risk_free_rate
OptionStyle::Call,
pos!(0.02),             // dividend_yield
None,                   // exotic_params
);

// Calculate option price using Black-Scholes
let price = option.calculate_price_black_scholes().unwrap();
info!("Option price: {}", price);

// Calculate Greeks
let delta = option.delta().unwrap();
let gamma = option.gamma().unwrap();
let theta = option.theta().unwrap();
info!("Delta: {}, Gamma: {}, Theta: {}", delta, gamma, theta);

Working with Strategies

use optionstratlib::{Positive, ExpirationDate, pos};
use optionstratlib::strategies::Strategies;
use optionstratlib::strategies::bull_call_spread::BullCallSpread;
use optionstratlib::visualization::Graph;
use rust_decimal_macros::dec;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    use tracing::info;
use optionstratlib::strategies::base::BreakEvenable;
    use optionstratlib::strategies::BasicAble;
    let underlying_price = pos!(5781.88);

    // Create a Bull Call Spread strategy
    let strategy = BullCallSpread::new("SP500".to_string(), underlying_price, pos!(5750.0), pos!(5820.0), ExpirationDate::Days(pos!(2.0)), pos!(0.18), dec!(0.01), pos!(0.78), pos!(0.78), pos!(0.73), pos!(0.73), Default::default(), Default::default(), Default::default(), Default::default());

    // Get information about the strategy
    info!("Title: {}", strategy.get_title());
    info!("Break Even Points: {:?}", strategy.get_break_even_points()?);
    info!("Net Premium Received: ${:.2}", strategy.get_net_premium_received()?);
    info!("Max Profit: ${:.2}", strategy.get_max_profit().unwrap_or(Positive::ZERO));
    info!("Max Loss: ${:0.2}", strategy.get_max_loss().unwrap_or(Positive::ZERO));
    info!("Total Fees: ${:.2}", strategy.get_fees()?);
    info!("Profit Area: {:.2}%", strategy.get_profit_area()?);
    info!("Profit Ratio: {:.2}%", strategy.get_profit_ratio()?);

    // Generate visualization and save to HTML file
    #[cfg(feature = "static_export")]
    {
        let file_path = "Draws/Strategy/bull_call_spread_profit_loss_chart.html".as_ref();
        strategy.write_html(file_path)?;
    }

    Ok(())
}

Visualization Example

use optionstratlib::visualization::{Graph, GraphData, Series2D, TraceMode, GraphConfig};
use optionstratlib::error::GraphError;
use std::path::PathBuf;
use rust_decimal_macros::dec;

struct SimpleChart {
    series: Series2D
}

impl Graph for SimpleChart {
    fn graph_data(&self) -> GraphData {
        GraphData::Series(self.series.clone())
    }

    fn graph_config(&self) -> GraphConfig {
        use optionstratlib::visualization::{ColorScheme, LineStyle};
GraphConfig {
            title: "Interactive Chart Example".into(),
            width: 800,
            height: 600,
            x_label: Some("X Axis".into()),
            y_label: Some("Y Axis".into()),
            z_label: None,
            line_style: LineStyle::Solid,
            color_scheme: ColorScheme::Viridis,
            legend: Some(vec!["My Data".to_string()]),
            show_legend: true,
        }
    }
}

fn main() -> Result<(), GraphError> {
    let series = Series2D {
        x: vec![dec!(1.0), dec!(2.0), dec!(3.0)],
        y: vec![dec!(4.0), dec!(5.0), dec!(6.0)],
        name: "Series 1".to_string(),
        mode: TraceMode::Lines,
        line_color: Some("#1f77b4".to_string()),
        line_width: Some(2.0),
    };

    #[cfg(feature = "static_export")]
    {
        let chart = SimpleChart { series };
        let filename: PathBuf = PathBuf::from("interactive_chart.html");
        chart.write_html(&filename)?;
    }

    Ok(())
}

Testing

To run the test suite:

make test

For running tests with specific features:

cargo test --features "plotly kaleido"

To generate a test coverage report:

make coverage

Contribution and Contact

We welcome contributions to this project! If you would like to contribute, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and ensure that the project still builds and all tests pass.
4. Commit your changes and push your branch to your forked repository.
5. Submit a pull request to the main repository.

If you have any questions, issues, or would like to provide feedback, please feel free to contact the project maintainer:

Joaquín Béjar García

• Email: jb@taunais.com
• GitHub: joaquinbejar

We appreciate your interest and look forward to your contributions!

✍️ License

Licensed under MIT license