abaquant.derivatives.strategies

Import path: abaquant.derivatives.strategies

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

Purpose

Composable option-strategy objects and expiration payoff profiles.

When to use it

Use this package when valuing contingent claims, calculating Greeks, building option strategies, simulating stochastic processes, or fitting models to market observations.

Public objects

  • function: option_payoff_leg — Evaluate one legacy option leg’s net expiration profit.

  • class: OptionStrategyLeg — One line item in a static option strategy. * OptionStrategyLeg.option — Create one call or put leg. * OptionStrategyLeg.underlying — Create one underlying asset leg. * OptionStrategyLeg.display_label — Return the label used in strategy profiles and charts. * OptionStrategyLeg.gross_payoff — Evaluate the terminal payoff before inception cash flows. * OptionStrategyLeg.net_inception_cost — Return the initial net cash cost of the leg. * OptionStrategyLeg.profit — Evaluate terminal net profit after inception cash flows. * OptionStrategyLeg.terminal_slope — Return the profit slope as the terminal price tends to infinity.

  • class: OptionStrategy — Composable static option strategy with payoff and risk diagnostics. * OptionStrategy.legs — Return the strategy legs as an immutable tuple. * OptionStrategy.add_leg — Append a validated leg and return ‘’self’’ for chaining. * OptionStrategy.buy_call — Add a long call leg and return the strategy. * OptionStrategy.sell_call — Add a short call leg and return the strategy. * OptionStrategy.buy_put — Add a long put leg and return the strategy. * OptionStrategy.sell_put — Add a short put leg and return the strategy. * OptionStrategy.buy_underlying — Add a long underlying leg and return the strategy. * OptionStrategy.sell_underlying — Add a short underlying leg and return the strategy. * OptionStrategy.bull_call_spread — Create a long bull call spread. * OptionStrategy.protective_put — Create a protective put from a long underlying and long put. * OptionStrategy.straddle — Create a long straddle using one call and one put at one strike. * OptionStrategy.strangle — Create a long strangle using an out-of-the-money put and call. * OptionStrategy.iron_condor — Create a long-wing iron condor with four option legs. * OptionStrategy.butterfly — Create a symmetric or asymmetric long butterfly. * OptionStrategy.net_inception_cost — Return total net cash paid at inception. * OptionStrategy.gross_payoff — Evaluate strategy payoff before premiums and entry costs. * OptionStrategy.profit — Evaluate terminal net profit after inception cash flows. * OptionStrategy.payoff — Evaluate the strategy expiration payoff or profit. * OptionStrategy.profile — Return a payoff table over terminal underlying prices. * OptionStrategy.max_profit — Return maximum expiration profit, or ‘’np.inf’’ if unbounded above. * OptionStrategy.max_loss — Return minimum expiration profit, or ‘’-np.inf’’ if unbounded below. * OptionStrategy.break_even_points — Return terminal prices where net profit is approximately zero. * OptionStrategy.as_dict — Return a plain-Python summary of the strategy and diagnostics. * OptionStrategy.visualize — Visualize the strategy payoff or component profile.

  • function: strategy_profile — Evaluate a legacy dictionary-based static strategy profile.

Detailed reference

Composable option-strategy objects and expiration payoff profiles.

Purpose

The module defines static option strategies built from long and short call, put, and underlying legs. Strategies can be evaluated at a single terminal underlying price, expanded into payoff tables, inspected for maximum profit, maximum loss, and break-even points, and visualized through the optional AbaQuant visualization layer.

Conventions

A positive position denotes a long leg and a negative position denotes a short leg. Premiums are quoted as positive currency amounts per contract. By default, strategy payoff methods report net expiration profit after option premiums and underlying entry costs. Use gross_payoff to exclude inception cash flows.

Scope and limitations

Strategies are static expiration profiles. They do not model early exercise, dynamic hedging, funding, margin, bid–ask slippage, taxes, assignment timing, or path-dependent risk.

class abaquant.derivatives.strategies.OptionStrategy(legs=None, *, name=None)

Bases: object

Composable static option strategy with payoff and risk diagnostics.

Notes

Builder methods mutate the strategy and return self so scripts can use either imperative or chained construction. The analytics are deterministic expiration calculations and do not require a market-data provider.

Parameters:
property legs: tuple[OptionStrategyLeg, ...]

Return the strategy legs as an immutable tuple.

add_leg(leg)

Append a validated leg and return self for chaining.

Parameters:

leg (OptionStrategyLeg) – Strategy leg to append.

Returns:

This strategy after mutation.

Return type:

OptionStrategy

buy_call(*, strike, premium, quantity=1.0)

Add a long call leg and return the strategy.

Parameters:

  • strike (float)

  • premium (float)

  • quantity (float)

Return type:

OptionStrategy

sell_call(*, strike, premium, quantity=1.0)

Add a short call leg and return the strategy.

Parameters:

  • strike (float)

  • premium (float)

  • quantity (float)

Return type:

OptionStrategy

buy_put(*, strike, premium, quantity=1.0)

Add a long put leg and return the strategy.

Parameters:

  • strike (float)

  • premium (float)

  • quantity (float)

Return type:

OptionStrategy

sell_put(*, strike, premium, quantity=1.0)

Add a short put leg and return the strategy.

Parameters:

  • strike (float)

  • premium (float)

  • quantity (float)

Return type:

OptionStrategy

buy_underlying(*, entry_price, quantity=1.0)

Add a long underlying leg and return the strategy.

Parameters:

  • entry_price (float)

  • quantity (float)

Return type:

OptionStrategy

sell_underlying(*, entry_price, quantity=1.0)

Add a short underlying leg and return the strategy.

Parameters:

  • entry_price (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod bull_call_spread(*, lower_strike, upper_strike, lower_premium, upper_premium, quantity=1.0)

Create a long bull call spread.

The strategy buys the lower-strike call and sells the higher-strike call with the same quantity.

Parameters:

  • lower_strike (float)

  • upper_strike (float)

  • lower_premium (float)

  • upper_premium (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod protective_put(*, underlying_entry_price, put_strike, put_premium, quantity=1.0)

Create a protective put from a long underlying and long put.

Parameters:

  • underlying_entry_price (float)

  • put_strike (float)

  • put_premium (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod straddle(*, strike, call_premium, put_premium, quantity=1.0)

Create a long straddle using one call and one put at one strike.

Parameters:

  • strike (float)

  • call_premium (float)

  • put_premium (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod strangle(*, put_strike, call_strike, put_premium, call_premium, quantity=1.0)

Create a long strangle using an out-of-the-money put and call.

Parameters:

  • put_strike (float)

  • call_strike (float)

  • put_premium (float)

  • call_premium (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod iron_condor(*, lower_put_strike, short_put_strike, short_call_strike, upper_call_strike, lower_put_premium, short_put_premium, short_call_premium, upper_call_premium, quantity=1.0)

Create a long-wing iron condor with four option legs.

Parameters:

  • lower_put_strike (float)

  • short_put_strike (float)

  • short_call_strike (float)

  • upper_call_strike (float)

  • lower_put_premium (float)

  • short_put_premium (float)

  • short_call_premium (float)

  • upper_call_premium (float)

  • quantity (float)

Return type:

OptionStrategy

classmethod butterfly(*, lower_strike, middle_strike, upper_strike, lower_premium, middle_premium, upper_premium, option_type='call', quantity=1.0)

Create a symmetric or asymmetric long butterfly.

The strategy buys the lower and upper strikes and sells twice the middle strike using either calls or puts.

Parameters:

  • lower_strike (float)

  • middle_strike (float)

  • upper_strike (float)

  • lower_premium (float)

  • middle_premium (float)

  • upper_premium (float)

  • option_type (Literal['call', 'put'])

  • quantity (float)

Return type:

OptionStrategy

net_inception_cost()

Return total net cash paid at inception.

Return type:

float

gross_payoff(spot_price)

Evaluate strategy payoff before premiums and entry costs.

Parameters:

spot_price (float | Sequence[float] | ndarray)

Return type:

float | ndarray

profit(spot_price)

Evaluate terminal net profit after inception cash flows.

Parameters:

spot_price (float | Sequence[float] | ndarray)

Return type:

float | ndarray

payoff(spot_price, *, include_premium=True)

Evaluate the strategy expiration payoff or profit.

Parameters:

  • spot_price (float or array-like) – Terminal underlying price or price grid.

  • include_premium (bool, default=True) – When True, return net profit after option premiums and underlying entry costs. When False, return gross terminal payoff only.

Returns:

Net profit or gross terminal payoff according to include_premium.

Return type:

float or numpy.ndarray

profile(*, spot_prices=None, spot_min=None, spot_max=None, points=501, include_leg_columns=True)

Return a payoff table over terminal underlying prices.

Parameters:

  • spot_prices (array-like, optional) – Explicit terminal price grid. When supplied, spot_min, spot_max, and points are ignored.

  • spot_min (float, optional) – Bounds for a generated terminal-price grid.

  • spot_max (float, optional) – Bounds for a generated terminal-price grid.

  • points (int, default=501) – Number of grid points when spot_prices is omitted.

  • include_leg_columns (bool, default=True) – Include per-leg profit columns in addition to aggregate columns.

Returns:

Table with spot_price, gross_payoff, net_profit, and optional per-leg profit columns.

Return type:

pandas.DataFrame

max_profit()

Return maximum expiration profit, or np.inf if unbounded above.

Return type:

float

max_loss()

Return minimum expiration profit, or -np.inf if unbounded below.

Return type:

float

break_even_points(*, tolerance=1e-10)

Return terminal prices where net profit is approximately zero.

Parameters:

tolerance (float, default=1e-10) – Numerical tolerance used for duplicate removal and exact-zero detection.

Returns:

Sorted break-even terminal prices. The list may be empty when a strategy has no non-negative-price break-even point.

Return type:

list[float]

as_dict()

Return a plain-Python summary of the strategy and diagnostics.

Return type:

dict[str, object]

visualize(*, chart='payoff', backend=None, theme=None, save_path=None, filename=None, spot_min=None, spot_max=None, points=501)

Visualize the strategy payoff or component profile.

Parameters:

  • chart ({"payoff", "components"}, default="payoff") – "payoff" plots aggregate net profit. "components" plots aggregate net profit and each leg’s contribution.

  • backend ({"matplotlib", "plotly"}, optional) – Visualization backend override.

  • theme (VisualizationTheme, optional) – Per-call theme override.

  • save_path (str or pathlib.Path, optional) – Explicit export path.

  • filename (str, optional) – Filename relative to the active theme save directory.

  • spot_min (float, optional) – Terminal-price grid bounds.

  • spot_max (float, optional) – Terminal-price grid bounds.

  • points (int, default=501) – Number of grid points.

Returns:

Backend-native figure object.

Return type:

matplotlib.figure.Figure or plotly.graph_objects.Figure

class abaquant.derivatives.strategies.OptionStrategyLeg(kind, position, quantity=1.0, strike=None, premium=0.0, entry_price=None, label=None)

Bases: object

One line item in a static option strategy.

Parameters:

  • kind ({"call", "put", "underlying"}) – Type of financial exposure represented by the leg.

  • position (float) – Signed direction of the exposure. Positive values are long exposures; negative values are short exposures.

  • quantity (float, default=1.0) – Number of contracts or underlying units represented by the leg.

  • strike (float, optional) – Strike price for option legs. Must be None for an underlying leg.

  • premium (float, default=0.0) – Option premium per contract in currency units. Must be non-negative.

  • entry_price (float, optional) – Underlying entry price per unit for stock-like legs.

  • label (str, optional) – Human-readable label used in payoff tables and plots. A default label is generated when omitted.

classmethod option(*, option_type, position, strike, premium, quantity=1.0, label=None)

Create one call or put leg.

Parameters:

  • option_type ({"call", "put"}) – Vanilla option family.

  • position (float) – Positive for long exposure and negative for short exposure.

  • strike (float) – Option strike price.

  • premium (float) – Premium per contract in currency units.

  • quantity (float, default=1.0) – Contract count.

  • label (str, optional) – Custom display label.

Returns:

Validated option leg.

Return type:

OptionStrategyLeg

classmethod underlying(*, position, entry_price, quantity=1.0, label=None)

Create one underlying asset leg.

Parameters:

  • position (float) – Positive for long underlying exposure and negative for short underlying exposure.

  • entry_price (float) – Initial purchase or sale price per underlying unit.

  • quantity (float, default=1.0) – Number of underlying units.

  • label (str, optional) – Custom display label.

Returns:

Validated underlying leg.

Return type:

OptionStrategyLeg

display_label()

Return the label used in strategy profiles and charts.

Return type:

str

gross_payoff(spot_price)

Evaluate the terminal payoff before inception cash flows.

Parameters:

spot_price (float or array-like) – Terminal underlying price or price grid.

Returns:

Signed terminal payoff before premiums or underlying entry costs.

Return type:

float or numpy.ndarray

net_inception_cost()

Return the initial net cash cost of the leg.

Positive values represent net cash paid at inception. Negative values represent net cash received at inception.

Return type:

float

profit(spot_price)

Evaluate terminal net profit after inception cash flows.

Parameters:

spot_price (float or array-like) – Terminal underlying price or price grid.

Returns:

Terminal payoff minus the net inception cost.

Return type:

float or numpy.ndarray

terminal_slope()

Return the profit slope as the terminal price tends to infinity.

Return type:

float

abaquant.derivatives.strategies.option_payoff_leg(option_type, position, terminal_prices, strike, premium)

Evaluate one legacy option leg’s net expiration profit.

Parameters:

  • option_type (str) – Option type label, either "call" or "put".

  • position (int) – Position side. 1 represents a long option and -1 represents a short option.

  • terminal_prices (numpy.ndarray) – Terminal underlying-price grid in currency units.

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

  • premium (float) – Positive premium paid by a long option holder and received by a short option writer.

Returns:

Net expiration profit for the option leg, including premium.

Return type:

numpy.ndarray

abaquant.derivatives.strategies.strategy_profile(spot, legs, points=500)

Evaluate a legacy dictionary-based static strategy profile.

Parameters:

  • spot (float) – Current underlying or asset spot price used to build a terminal-price grid from 0.5 * spot to 1.5 * spot.

  • legs (list[dict]) – Sequence of option-leg specifications with option_type, position, strike, and premium keys.

  • points (int, default=500) – Number of terminal-price grid points.

Returns:

Payoff table preserving the historical S_T, per-leg, and Net Payoff column names while using the validated leg payoff calculation internally.

Return type:

pandas.DataFrame