Skip to content

Public API

Root-level exports

This page covers the main objects re-exported from option_pricing.

Use it to find the shared public types before diving into the dedicated pricer, curves, or volatility reference pages.

For pricing functions, use Pricers. This page stays focused on shared types, contracts, configuration objects, and common volatility exports.

Core types

These are the root-level typed containers used throughout the convenience API and as bridges into the richer market-context workflows.

OptionType

Bases: StrEnum

Option type enumeration.

Attributes:

Name Type Description
CALL

European or American call option.
PUT

European or American put option.

MarketData dataclass

Flat market data container.

Primarily a convenience structure for common Black-Scholes and binomial tree scenarios. For richer market structures (term structures, stochastic rates), use PricingContext instead.

Attributes:

Name Type Description
spot float

Spot price at valuation time.
rate float

Continuously-compounded domestic risk-free rate.
dividend_yield float

Continuously-compounded dividend yield (default: 0.0).

df 

df(T: float, t: float = 0.0) -> float

Discount factor from time t to T.

Parameters:

Name Type Description Default
T float

Maturity time.

 required
t float

Valuation time (default: 0.0).

 0.0

Returns:

Type Description
float

Discount factor P(0, T-t) = exp(-r * tau).

forward 

forward(T: float, t: float = 0.0) -> float

Forward price from time t for delivery at T.

Uses the cost-of-carry model: F(t,T) = S(t) * exp((r - q) * (T - t)).

Parameters:

Name Type Description Default
T float

Maturity time.

 required
t float

Valuation time (default: 0.0).

 0.0

Returns:

Type Description
float

Forward price.

fwd 

fwd(T: float, t: float = 0.0) -> float

Alias for forward.

to_context 

to_context() -> PricingContext

Convert to a PricingContext.

Returns:

Type Description
PricingContext

Curves-first market container with flat discount and forward curves.

OptionSpec dataclass

Specification of a vanilla option.

Attributes:

Name Type Description
kind OptionType

Option type (call or put).
strike float

Strike price.
expiry float

Expiry time in years.

In the legacy PricingInputs workflow this is interpreted as the absolute expiry T and the remaining time is computed as tau = expiry - t. With the default t=0, this is numerically equal to time-to-expiry.

PricingInputs dataclass

All inputs needed to price an option.

Generic over the option specification (vanilla, digital, etc.).

Attributes:

Name Type Description
spec SpecT

Option specification (OptionSpec or subclass).
market MarketData

Market data (MarketData).
sigma float

Implied volatility.
t float

Current valuation time (default: 0.0).
Notes

PricingInputs follows the legacy flat-input convention where spec.expiry is the absolute expiry T and tau = T - t.

S property 

S: float

Spot price from market data.

ctx property 

ctx: PricingContext

Pricing context derived from market data.

K property 

K: float

Strike price from option spec.

T property 

T: float

Absolute expiry time T from the option spec.

tau property 

tau: float

Remaining time to expiry tau = T - t.

df property 

df: float

Discount factor from current time to expiry.

F property 

F: float

Forward price for delivery at expiry.

Instrument layer

The instrument workflow is the recommended public path because the contract carries payoff and exercise semantics explicitly.

Lightweight instrument interfaces.

The library exposes both a "PricingInputs" API (flat, tutorial-friendly) and an instrument-based API for pricers that operate on terminal payoffs.

Only a small subset is required by the pricers in this repository: - an exercise style (European/American) - a time-to-expiry (tau) - a vectorizable payoff function of the terminal underlying price

ExerciseStyle

Bases: StrEnum

Exercise style for vanilla options.

Vanilla (call/put) instruments and payoffs.

This module provides two small building blocks:

  • VanillaPayoff: a vectorized terminal payoff (call/put)
  • VanillaOption: an instrument wrapper bundling expiry + exercise + payoff

VanillaPayoff dataclass

Callable, vectorized call/put payoff.

__call__ 

__call__(ST: float) -> float

__call__(ST: FloatArray) -> FloatArray

__call__(ST: float | FloatArray) -> float | FloatArray

Evaluate payoff at terminal price(s).

Parameters:

Name Type Description Default
ST float | FloatArray

Terminal price(s).

 required

Returns:

Type Description
float or FloatArray

Option payoff(s) at maturity.

VanillaOption dataclass

Vanilla option instrument.

Notes

expiry is interpreted as time to expiry (tau).

payoff property 

payoff: TerminalPayoff

Terminal payoff function.

Returns:

Type Description
TerminalPayoff

A callable VanillaPayoff object.

intrinsic_value 

intrinsic_value(spot: float) -> float

intrinsic_value(spot: FloatArray) -> FloatArray

intrinsic_value(spot: float | FloatArray) -> float | FloatArray

Intrinsic value at a given spot price.

Parameters:

Name Type Description Default
spot float | FloatArray

Current spot price(s).

 required

Returns:

Type Description
float or FloatArray

Intrinsic value(s) at current spot.

Market context and curves

These names are re-exported from the package root so callers can move from flat inputs to explicit market curves without changing namespaces.

  • PricingContext
  • DiscountCurve
  • ForwardCurve
  • FlatDiscountCurve
  • FlatCarryForwardCurve

See the dedicated Curves-first API page for the canonical class documentation.

Configuration and solver selection

These configuration types control Monte Carlo sampling and implied-vol inversion behavior without being tied to a single pricing style.

RandomConfig dataclass

Random number generator configuration.

Attributes:

Name Type Description
seed int

Seed value for reproducibility (default: 0).
rng_type RngType

RNG algorithm: 'pcg64', 'mt19937', or 'sobol' (default: 'pcg64').

MCConfig dataclass

Monte Carlo pricing configuration.

Attributes:

Name Type Description
n_paths int

Number of Monte Carlo paths (default: 100,000).
antithetic bool

Use antithetic variates for variance reduction (default: False).
random RandomConfig

Random number generator configuration (RandomConfig).
rng Generator | None

Optional pre-constructed numpy RandomGenerator. If None, one is created from the random config.

ImpliedVolConfig dataclass

Configuration for implied volatility (IV) solvers.

Controls root-finding algorithm, bounds, seeding strategy, and numerical tolerances.

Attributes:

Name Type Description
root_method RootMethod

Root-finding method from RootMethod (default: BRACKETED_NEWTON).
sigma_lo float

Lower volatility bound (default: 1e-8).
sigma_hi float

Upper volatility bound (default: 5.0).
bounds_eps float

Slack for bracket bounds (default: 1e-12).
seed_strategy SeedStrategy

Initial guess strategy from SeedStrategy (default: HEURISTIC).
numerics NumericsConfig

Numerical solver configuration (NumericsConfig).

RootMethod

Bases: StrEnum

Supported root-finding methods.

Notes

This enum is used to select a concrete solver from the internal registry (:data:ROOT_METHODS). Using an enum avoids "magic strings" and makes method selection type-safe.

Volatility objects

The package root keeps the common smile and surface objects close to the pricing API, while the broader volatility namespace carries the heavier calibration stack.

  • VolSurface
  • Smile

See the dedicated Volatility page for the canonical class documentation.

The broader volatility namespace option_pricing.vol also exposes the eSSVI toolbox, including:

  • ESSVIImpliedSurface
  • ESSVINodalSurface
  • ESSVISmoothedSurface
  • calibrate_essvi
  • project_essvi_nodes