Option#

Option#

class hestonpy.option.Option.Option(flag: Literal['call', 'put'], strike: float, time_to_maturity: float)[source]#

Represents a vanilla European option contract.

This is a pure contract specification — it carries no market data (spot, rate) and no model. Those live in OptionsBook.

flag#

Type of the option.

Type:

Literal[‘call’, ‘put’]

strike#

Strike price.

Type:

float

time_to_maturity#

Time to maturity in years.

Type:

float

Example

>>> opt = Option(flag='call', strike=100.0, time_to_maturity=1.0)

Position#

class hestonpy.option.OptionsBook.Position(option: Option, quantity: float, entry_price: float | None = None)[source]#

A position in the options book: a contract, a signed quantity, and an optional entry price.

option#

The option contract.

Type:

Option

quantity#

Signed quantity — positive = long, negative = short.

Type:

float

entry_price#

Price at which the position was opened. Used for P&L.

Type:

float | None

OptionsBook#

class hestonpy.option.OptionsBook.OptionsBook(spot: float, r: float, underlying: str = '')[source]#

Manages a book of European vanilla options on a single underlying.

Market context (spot, risk-free rate) is held at the book level and shared across all positions. Pricing and greeks delegate to the existing BlackScholes and Heston model classes.

Greeks are always computed analytically via Black-Scholes. Pricing can use either Black-Scholes or Heston, specified at call time.

Parameters:

  • spot (float) – Current spot price of the underlying.

  • r (float) – Risk-free interest rate (annualised).

  • underlying (str) – Optional label for the underlying (e.g. ‘AAPL’).

Example

>>> book = OptionsBook(spot=100.0, r=0.05, underlying='SPX')
>>> book.add('call', strike=105.0, time_to_maturity=0.5, quantity=1)
>>> book.add('put',  strike=95.0,  time_to_maturity=0.5, quantity=-2)
>>> print(book)
>>> print(book.summary('blackScholes', vol=0.2, params=[0.05]))
add(flag: Literal['call', 'put'], strike: float, time_to_maturity: float, quantity: float, entry_price: float | None = None) → None[source]#

Add a new position to the book.

Parameters:

  • flag – ‘call’ or ‘put’.

  • strike – Strike price.

  • time_to_maturity – Time to maturity in years.

  • quantity – Signed quantity (+N = long, -N = short).

  • entry_price – Optional entry price for P&L tracking.

greeks(vol: float) → dict[str, float][source]#

Aggregate Black-Scholes greeks of the book.

Delta, Gamma and Vega are computed analytically from the BS closed-form formulas, regardless of which model is used for pricing. This is the standard market convention.

Parameters:

vol – Implied volatility to use for greek computation.

Returns:

dict with keys ‘delta’, ‘gamma’, ‘vega’.

pnl(flag_model: Literal['heston', 'blackScholes'], vol: float, params: list) → float[source]#

Total P&L of the book vs entry prices.

Positions without an entry_price are excluded from the calculation.

Returns:

Sum of quantity × (current_price - entry_price).

Return type:

float

price(flag_model: Literal['heston', 'blackScholes'], vol: float, params: list) → float[source]#

Total mark-to-market value of the book.

Returns:

Sum of (quantity × price) across all positions.

Return type:

float

remove(index: int) → None[source]#

Remove the position at the given index.

summary(flag_model: Literal['heston', 'blackScholes'], vol: float, params: list) → DataFrame[source]#

Returns a DataFrame with one row per position, plus a TOTAL row.

Columns: flag, strike, TTM, qty, price, MtM, PnL, delta, gamma, vega.

Parameters:

  • flag_model – ‘blackScholes’ or ‘heston’.

  • vol – Volatility used for both pricing and greek computation.

  • params – Model parameters (see _price_option).

update_spot(new_spot: float) → None[source]#

Update the spot price (re-marks the book to the new level).