abaquant.derivatives.models.black_scholes

Import path: abaquant.derivatives.models.black_scholes

Domain: Derivative pricing, simulation, calibration, diagnostics, and strategy analysis.

Purpose

Black–Scholes–Merton analytical option pricing model.

When to use it

This module implements or supports one derivative model. Read the parameter constraints, pricing measure, numerical method, and limiting cases before comparing outputs across models.

Public objects

  • class: BlackScholesMertonModel — Analytical Black–Scholes–Merton model for European vanilla options. * BlackScholesMertonModel.call_price — Return the model price of a European call option. * BlackScholesMertonModel.put_price — Return the model price of a European put option. * BlackScholesMertonModel.greeks — Return the model sensitivities implemented by this model. * BlackScholesMertonModel.implied_vol — Return the Black–Scholes–Merton implied volatility associated with the model price. * BlackScholesMertonModel.vol_smile_surface — Evaluate the model-implied volatility across strike and maturity grids. * BlackScholesMertonModel.visualize — Return a backend-native visualization of this option-pricing model.

  • function: bsm_d1_d2_summary — Compute the result defined by ‘’bsm_d1_d2_summary’’ under this module’s documented convention.

Detailed reference

Black–Scholes–Merton analytical option pricing model.

Purpose

The module implements European call and put prices, standard Greeks, implied-volatility inversion, and simple smile diagnostics under constant lognormal volatility.

Conventions

Maturity is in years. Rates and continuous dividend yield are continuously compounded decimal annual rates. Volatility is annualized decimal volatility.

References

[ 1 ] Black, F., and M. Scholes (1973), “The Pricing of Options and Corporate Liabilities”; Merton, R. C. (1973), “Theory of Rational Option Pricing”.

class abaquant.derivatives.models.black_scholes.BlackScholesMertonModel(spot_price, strike_price, maturity_years, risk_free_rate, volatility, dividend_yield=0.0)

Bases: OptionDiagnosticsMixin

Analytical Black–Scholes–Merton model for European vanilla options.

Parameters:

  • spot_price (float or array-like) – Current underlying asset price in currency units.

  • strike_price (float or array-like) – Option exercise price in the same currency units as spot_price.

  • maturity_years (float or array-like) – Remaining time to expiry, measured in years.

  • risk_free_rate (float or array-like) – Continuously compounded annual risk-free rate in decimal units.

  • volatility (float or array-like) – Annualized lognormal volatility in decimal units.

  • dividend_yield (float or array-like, default=0.0) – Continuously compounded annual dividend or carry yield in decimal units.

spot_price, strike_price, maturity_years, risk_free_rate, volatility, dividend_yield

Canonical descriptive model inputs. Legacy textbook-symbol attributes such as S and sigma remain available for backward compatibility.

Initialize the Black–Scholes–Merton model state.

Parameters:

  • spot_price (float or array-like) – Current underlying asset price in currency units.

  • strike_price (float or array-like) – Option exercise price in the same currency units as spot_price.

  • maturity_years (float or array-like) – Remaining time to expiry, measured in years.

  • risk_free_rate (float or array-like) – Continuously compounded annual risk-free rate in decimal units.

  • volatility (float or array-like) – Annualized lognormal volatility in decimal units.

  • dividend_yield (float or array-like, default=0.0) – Continuously compounded annual dividend or carry yield in decimal units.

call_price()

Return the model price of a European call option.

Returns:

Computed call price in the units implied by the documented inputs.

Return type:

float

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.

put_price()

Return the model price of a European put option.

Returns:

Computed put price in the units implied by the documented inputs.

Return type:

float

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.

greeks()

Return the model sensitivities implemented by this model.

Returns:

Result of the greeks workflow.

Return type:

object

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.

implied_vol(market_price, option_type='call', tol=1e-6, max_iter=200)

Return the Black–Scholes–Merton implied volatility associated with the model price.

Parameters:

  • market_price (float or array-like) – Observed option premium in the same currency units as spot and strike.

  • option_type (str, default='call') – Option type label, normally "call" or "put".

  • tol (float, default=1e-06) – Numerical convergence tolerance.

  • max_iter (int, default=200) – Maximum numerical-optimizer or root-finder iterations.

Returns:

Result of the implied vol workflow.

Return type:

object

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.

vol_smile_surface(strikes, maturities)

Evaluate the model-implied volatility across strike and maturity grids.

Parameters:

  • strikes (float or array-like) – Strike-price grid in the same currency units as the underlying or forward.

  • maturities (float or array-like) – Maturity grid in years for a volatility-surface calculation.

Returns:

Tabular result with the index, column schema, units, and missing-value treatment defined by the module convention.

Return type:

pandas.DataFrame

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.

visualize(*, option_type='call', chart='payoff', backend=None, theme=None, save_path=None, filename=None, lower_spot_multiple=0.5, upper_spot_multiple=1.5, grid_size=101, lower_volatility_multiple=0.5, upper_volatility_multiple=1.5, volatility_grid_size=31, greek_scale='raw')

Return a backend-native visualization of this option-pricing model.

Parameters:

  • option_type ({"call", "put"}, default="call") – Vanilla option type used for payoff, price-profile, smile, or tree plots.

  • chart (str, default="payoff") – Visual diagnostic to create. Supported charts include payoff, price profile, extrinsic value, Greek curves, selected surfaces, volatility smile, and lattice tree when the model exposes a tree.

  • backend ({"matplotlib", "plotly"}, default="matplotlib") – Optional plotting backend. The returned figure is not shown automatically.

  • lower_spot_multiple (float, default=0.5, 1.5) – Price-grid bounds as multiples of the strike price.

  • upper_spot_multiple (float, default=0.5, 1.5) – Price-grid bounds as multiples of the strike price.

  • grid_size (int, default=101) – Number of spot-grid points for non-tree plots.

  • lower_volatility_multiple (float, default=0.5, 1.5) – Volatility-grid bounds expressed as multiples of the model’s base volatility.

  • upper_volatility_multiple (float, default=0.5, 1.5) – Volatility-grid bounds expressed as multiples of the model’s base volatility.

  • volatility_grid_size (int, default=31) – Number of volatility-grid points for surface plots.

  • greek_scale ({"raw", "standardized"}, default="raw") – Scaling mode for the multi-Greek curve chart.

Returns:

Figure object created without mutating model state.

Return type:

matplotlib.figure.Figure or plotly.graph_objects.Figure

abaquant.derivatives.models.black_scholes.bsm_d1_d2_summary(S, K, T, r, sigma, q=0.0)

Compute the result defined by bsm_d1_d2_summary under this module’s documented convention.

Parameters:

  • S (float) – Current underlying spot price in currency units.

  • K (float) – Option strike price in the same currency units as the underlying.

  • T (float) – Time to maturity in years.

  • r (float) – Continuously compounded risk-free annual rate in decimal units.

  • sigma (float) – Annualized lognormal volatility in decimal units; for example, 0.20 denotes 20%.

  • q (float, default=0.0) – Continuous dividend or carry yield in decimal annual units.

Returns:

Named d1 and d2 diagnostics for the stated Black–Scholes–Merton inputs.

Return type:

dict[str, float]

Notes

Model inputs are interpreted according to the module-level rate, maturity, and volatility conventions. Numerical outputs depend on the validity of those assumptions.