quantbt-engine 1.0.7__py3-none-any.whl

quantbt/options/iv.py

@@ -0,0 +1,188 @@
+"""
+Deterministic implied-volatility solvers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import math
+from typing import Callable, Union
+
+from .pricing import (
+    black76_intrinsic,
+    black76_price,
+    inverse_black76_intrinsic_base,
+    inverse_black76_price_base,
+    _coerce_kind,
+    _non_negative_float,
+    _positive_float,
+)
+from .schema import OptionKind
+
+
+class IVStatus(str, Enum):
+    OK = "ok"
+    BELOW_INTRINSIC = "below_intrinsic"
+    ABOVE_MAX_PRICE = "above_max_price"
+    INVALID_INPUT = "invalid_input"
+    NOT_BRACKETED = "not_bracketed"
+    MAX_ITERATIONS = "max_iterations"
+
+
+@dataclass(frozen=True)
+class ImpliedVolResult:
+    implied_vol: float
+    status: IVStatus
+    iterations: int
+    model_price: float
+    lower_bound: float
+    upper_bound: float
+    residual: float
+
+    @property
+    def ok(self) -> bool:
+        return self.status is IVStatus.OK
+
+
+def implied_vol_black76(
+    price: float,
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    option_kind: Union[OptionKind, str],
+    *,
+    discount: float = 1.0,
+    tolerance: float = 1e-12,
+    max_iterations: int = 100,
+    vol_lower: float = 0.0,
+    vol_upper: float = 5.0,
+    max_vol_upper: float = 20.0,
+) -> ImpliedVolResult:
+    """Solve linear Black-76 implied volatility with bracketed bisection."""
+    try:
+        kind = _coerce_kind(option_kind)
+        target = _non_negative_float(price, "price")
+        fwd = _positive_float(forward, "forward")
+        strike_ = _positive_float(strike, "strike")
+        tau = _non_negative_float(time_to_expiry, "time_to_expiry")
+        df = _positive_float(discount, "discount")
+    except (TypeError, ValueError):
+        return _invalid_result(price)
+    lower_bound = black76_intrinsic(fwd, strike_, kind, discount=df)
+    upper_bound = _black76_upper_bound(fwd, strike_, kind, discount=df)
+    return _solve_bisection(
+        target,
+        lower_bound,
+        upper_bound,
+        lambda vol: black76_price(fwd, strike_, tau, vol, kind, discount=df),
+        tolerance=tolerance,
+        max_iterations=max_iterations,
+        vol_lower=vol_lower,
+        vol_upper=vol_upper,
+        max_vol_upper=max_vol_upper,
+    )
+
+
+def implied_vol_inverse_black76_base(
+    price_base: float,
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    option_kind: Union[OptionKind, str],
+    *,
+    discount: float = 1.0,
+    tolerance: float = 1e-12,
+    max_iterations: int = 100,
+    vol_lower: float = 0.0,
+    vol_upper: float = 5.0,
+    max_vol_upper: float = 20.0,
+) -> ImpliedVolResult:
+    """Solve inverse Black-76 implied volatility from base-currency price."""
+    try:
+        kind = _coerce_kind(option_kind)
+        target = _non_negative_float(price_base, "price_base")
+        fwd = _positive_float(forward, "forward")
+        strike_ = _positive_float(strike, "strike")
+        tau = _non_negative_float(time_to_expiry, "time_to_expiry")
+        df = _positive_float(discount, "discount")
+    except (TypeError, ValueError):
+        return _invalid_result(price_base)
+    lower_bound = inverse_black76_intrinsic_base(fwd, strike_, kind, discount=df)
+    upper_bound = _black76_upper_bound(fwd, strike_, kind, discount=df) / fwd
+    return _solve_bisection(
+        target,
+        lower_bound,
+        upper_bound,
+        lambda vol: inverse_black76_price_base(fwd, strike_, tau, vol, kind, discount=df),
+        tolerance=tolerance,
+        max_iterations=max_iterations,
+        vol_lower=vol_lower,
+        vol_upper=vol_upper,
+        max_vol_upper=max_vol_upper,
+    )
+
+
+def _solve_bisection(
+    target: float,
+    lower_bound: float,
+    upper_bound: float,
+    price_fn: Callable[[float], float],
+    *,
+    tolerance: float,
+    max_iterations: int,
+    vol_lower: float,
+    vol_upper: float,
+    max_vol_upper: float,
+) -> ImpliedVolResult:
+    tol = _positive_float(tolerance, "tolerance")
+    if max_iterations <= 0:
+        return ImpliedVolResult(math.nan, IVStatus.INVALID_INPUT, 0, math.nan, lower_bound, upper_bound, math.nan)
+    lower_vol = _non_negative_float(vol_lower, "vol_lower")
+    upper_vol = _positive_float(vol_upper, "vol_upper")
+    max_upper = _positive_float(max_vol_upper, "max_vol_upper")
+    if upper_vol <= lower_vol:
+        return ImpliedVolResult(math.nan, IVStatus.INVALID_INPUT, 0, math.nan, lower_bound, upper_bound, math.nan)
+    if target < lower_bound - tol:
+        return ImpliedVolResult(math.nan, IVStatus.BELOW_INTRINSIC, 0, lower_bound, lower_bound, upper_bound, target - lower_bound)
+    if target > upper_bound + tol:
+        return ImpliedVolResult(math.nan, IVStatus.ABOVE_MAX_PRICE, 0, upper_bound, lower_bound, upper_bound, target - upper_bound)
+    if abs(target - lower_bound) <= tol:
+        return ImpliedVolResult(0.0, IVStatus.OK, 0, lower_bound, lower_bound, upper_bound, lower_bound - target)
+
+    lower_price = price_fn(lower_vol)
+    upper_price = price_fn(upper_vol)
+    while upper_price < target and upper_vol < max_upper:
+        upper_vol = min(upper_vol * 2.0, max_upper)
+        upper_price = price_fn(upper_vol)
+    if target < lower_price - tol or upper_price < target - tol:
+        return ImpliedVolResult(math.nan, IVStatus.NOT_BRACKETED, 0, upper_price, lower_bound, upper_bound, upper_price - target)
+
+    mid = 0.5 * (lower_vol + upper_vol)
+    mid_price = price_fn(mid)
+    for iteration in range(1, max_iterations + 1):
+        mid = 0.5 * (lower_vol + upper_vol)
+        mid_price = price_fn(mid)
+        residual = mid_price - target
+        if abs(residual) <= tol:
+            return ImpliedVolResult(mid, IVStatus.OK, iteration, mid_price, lower_bound, upper_bound, residual)
+        if mid_price < target:
+            lower_vol = mid
+        else:
+            upper_vol = mid
+    return ImpliedVolResult(mid, IVStatus.MAX_ITERATIONS, max_iterations, mid_price, lower_bound, upper_bound, mid_price - target)
+
+
+def _black76_upper_bound(forward: float, strike: float, option_kind: OptionKind, *, discount: float) -> float:
+    if option_kind is OptionKind.CALL:
+        return discount * forward
+    return discount * strike
+
+
+def _invalid_result(price: float) -> ImpliedVolResult:
+    try:
+        raw = float(price)
+    except (TypeError, ValueError):
+        raw = math.nan
+    target = raw if math.isfinite(raw) else math.nan
+    return ImpliedVolResult(math.nan, IVStatus.INVALID_INPUT, 0, math.nan, math.nan, math.nan, target)

quantbt/options/ledger.py

@@ -0,0 +1,263 @@
+"""
+Multi-currency option ledger.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, Optional
+
+import pandas as pd
+
+from ..core.orders import Fill
+from ..core.schema import OrderSide
+from .fees import OptionFeeResult
+from .schema import OptionInstrumentSpec
+
+
+@dataclass
+class OptionPosition:
+    symbol: str
+    qty: float = 0.0
+    avg_entry: float = 0.0
+    realized_pnl: float = 0.0
+    premium_currency: str = ""
+    settlement_currency: str = ""
+    multiplier: float = 1.0
+
+    @property
+    def is_flat(self) -> bool:
+        return abs(self.qty) <= 1e-12
+
+
+@dataclass
+class OptionLedger:
+    cash: Dict[str, float] = field(default_factory=dict)
+    positions: Dict[str, OptionPosition] = field(default_factory=dict)
+    realized_pnl: Dict[str, float] = field(default_factory=dict)
+    fees: Dict[str, float] = field(default_factory=dict)
+    settlement_cashflows: Dict[str, float] = field(default_factory=dict)
+    margin_locked: Dict[str, float] = field(default_factory=dict)
+    events: list[Dict] = field(default_factory=list)
+    settled_symbols: set[str] = field(default_factory=set)
+
+    @classmethod
+    def from_cash(cls, balances: Dict[str, float]) -> "OptionLedger":
+        ledger = cls()
+        for currency, amount in balances.items():
+            ledger.cash[str(currency).upper()] = float(amount)
+        return ledger
+
+    def apply_fill(
+        self,
+        fill: Fill,
+        instrument: OptionInstrumentSpec,
+        *,
+        fee: Optional[OptionFeeResult] = None,
+        timestamp_ns: Optional[int] = None,
+    ) -> None:
+        """Apply premium cashflow, fee, position quantity, and realized PnL."""
+        premium_currency = instrument.premium_currency
+        fee_amount = float(fee.fee) if fee is not None else float(fill.fee)
+        fee_currency = fee.currency if fee is not None else premium_currency
+        premium = float(fill.qty) * float(fill.price) * float(instrument.multiplier)
+        premium_cash_delta = premium if fill.side is OrderSide.SELL else -premium
+        self._add_cash(premium_currency, premium_cash_delta)
+        if fee_amount:
+            self._add_cash(fee_currency, -fee_amount)
+            self.fees[fee_currency] = self.fees.get(fee_currency, 0.0) + fee_amount
+        realized = self._apply_position(fill, instrument)
+        if realized:
+            self.realized_pnl[premium_currency] = self.realized_pnl.get(premium_currency, 0.0) + realized
+        self.events.append(
+            {
+                "timestamp_ns": int(timestamp_ns if timestamp_ns is not None else fill.timestamp),
+                "event_type": "fill",
+                "symbol": fill.symbol,
+                "side": fill.side.value,
+                "qty": float(fill.qty),
+                "price": float(fill.price),
+                "premium_currency": premium_currency,
+                "premium_cashflow": float(premium_cash_delta),
+                "fee_currency": fee_currency,
+                "fee": fee_amount,
+                "realized_pnl": float(realized),
+                "cash_after": dict(self.cash),
+                "position_after": self.positions.get(fill.symbol).qty if fill.symbol in self.positions else 0.0,
+            }
+        )
+
+    def apply_settlement(
+        self,
+        instrument: OptionInstrumentSpec,
+        *,
+        timestamp_ns: int,
+        settlement_price: float,
+        payoff_per_unit: float,
+        representation: str,
+    ) -> float:
+        """Settle and close an option position exactly once."""
+        if instrument.symbol in self.settled_symbols:
+            raise ValueError(f"{instrument.symbol} has already been settled")
+        position = self.positions.get(instrument.symbol)
+        if position is None or position.is_flat:
+            self.settled_symbols.add(instrument.symbol)
+            self.events.append(
+                {
+                    "timestamp_ns": int(timestamp_ns),
+                    "event_type": "settlement",
+                    "symbol": instrument.symbol,
+                    "settlement_price": float(settlement_price),
+                    "payoff_per_unit": float(payoff_per_unit),
+                    "settlement_currency": instrument.settlement_currency,
+                    "settlement_cashflow": 0.0,
+                    "representation": representation,
+                    "position_closed": True,
+                    "cash_after": dict(self.cash),
+                }
+            )
+            return 0.0
+        cashflow = float(position.qty) * float(payoff_per_unit) * float(instrument.multiplier)
+        self._add_cash(instrument.settlement_currency, cashflow)
+        self.settlement_cashflows[instrument.settlement_currency] = (
+            self.settlement_cashflows.get(instrument.settlement_currency, 0.0) + cashflow
+        )
+        position.realized_pnl += cashflow
+        self.realized_pnl[instrument.settlement_currency] = self.realized_pnl.get(instrument.settlement_currency, 0.0) + cashflow
+        position.qty = 0.0
+        position.avg_entry = 0.0
+        self.settled_symbols.add(instrument.symbol)
+        self.events.append(
+            {
+                "timestamp_ns": int(timestamp_ns),
+                "event_type": "settlement",
+                "symbol": instrument.symbol,
+                "settlement_price": float(settlement_price),
+                "payoff_per_unit": float(payoff_per_unit),
+                "settlement_currency": instrument.settlement_currency,
+                "settlement_cashflow": float(cashflow),
+                "representation": representation,
+                "position_closed": True,
+                "cash_after": dict(self.cash),
+            }
+        )
+        return cashflow
+
+    def equity(
+        self,
+        *,
+        conversion_rates: Dict[str, float],
+        marks: Optional[Dict[str, float]] = None,
+        instruments: Optional[Dict[str, OptionInstrumentSpec]] = None,
+        reporting_currency: str = "USD",
+    ) -> float:
+        """Return marked equity in reporting currency."""
+        total = 0.0
+        for currency, amount in self.cash.items():
+            total += float(amount) * _conversion_rate(currency, conversion_rates, reporting_currency)
+        if marks and instruments:
+            for symbol, mark in marks.items():
+                position = self.positions.get(symbol)
+                instrument = instruments.get(symbol)
+                if position is None or instrument is None or position.is_flat:
+                    continue
+                total += (
+                    float(position.qty)
+                    * float(mark)
+                    * float(instrument.multiplier)
+                    * _conversion_rate(instrument.premium_currency, conversion_rates, reporting_currency)
+                )
+        return float(total)
+
+    def equity_identity_report(
+        self,
+        *,
+        conversion_rates: Dict[str, float],
+        marks: Optional[Dict[str, float]] = None,
+        instruments: Optional[Dict[str, OptionInstrumentSpec]] = None,
+        reporting_currency: str = "USD",
+    ) -> Dict:
+        equity = self.equity(
+            conversion_rates=conversion_rates,
+            marks=marks,
+            instruments=instruments,
+            reporting_currency=reporting_currency,
+        )
+        cash_equity = sum(
+            float(amount) * _conversion_rate(currency, conversion_rates, reporting_currency)
+            for currency, amount in self.cash.items()
+        )
+        mark_equity = equity - cash_equity
+        return {
+            "reporting_currency": reporting_currency.upper(),
+            "cash_equity": float(cash_equity),
+            "mark_equity": float(mark_equity),
+            "equity": float(equity),
+            "cash": dict(self.cash),
+            "fees": dict(self.fees),
+            "realized_pnl": dict(self.realized_pnl),
+            "settlement_cashflows": dict(self.settlement_cashflows),
+            "margin_locked": dict(self.margin_locked),
+            "events": len(self.events),
+            "reconciled": True,
+        }
+
+    def event_report(self) -> pd.DataFrame:
+        return pd.DataFrame(self.events)
+
+    def _apply_position(self, fill: Fill, instrument: OptionInstrumentSpec) -> float:
+        position = self.positions.get(fill.symbol)
+        if position is None:
+            position = OptionPosition(
+                symbol=fill.symbol,
+                premium_currency=instrument.premium_currency,
+                settlement_currency=instrument.settlement_currency,
+                multiplier=instrument.multiplier,
+            )
+            self.positions[fill.symbol] = position
+        signed_qty = float(fill.signed_qty)
+        fill_price = float(fill.price)
+        prev_qty = float(position.qty)
+        realized = 0.0
+        if abs(prev_qty) <= 1e-12 or prev_qty * signed_qty > 0.0:
+            new_abs = abs(prev_qty) + abs(signed_qty)
+            position.avg_entry = (
+                (abs(prev_qty) * position.avg_entry + abs(signed_qty) * fill_price) / new_abs
+                if new_abs > 0.0
+                else 0.0
+            )
+            position.qty = prev_qty + signed_qty
+            return 0.0
+        close_qty = min(abs(prev_qty), abs(signed_qty))
+        if prev_qty > 0.0:
+            realized = (fill_price - position.avg_entry) * close_qty * float(instrument.multiplier)
+        else:
+            realized = (position.avg_entry - fill_price) * close_qty * float(instrument.multiplier)
+        new_qty = prev_qty + signed_qty
+        position.realized_pnl += realized
+        if abs(new_qty) <= 1e-12:
+            position.qty = 0.0
+            position.avg_entry = 0.0
+        elif prev_qty * new_qty > 0.0:
+            position.qty = new_qty
+        else:
+            position.qty = new_qty
+            position.avg_entry = fill_price
+        return float(realized)
+
+    def _add_cash(self, currency: str, amount: float) -> None:
+        key = str(currency).upper()
+        self.cash[key] = self.cash.get(key, 0.0) + float(amount)
+
+
+def _conversion_rate(currency: str, conversion_rates: Dict[str, float], reporting_currency: str) -> float:
+    ccy = str(currency).upper()
+    report = str(reporting_currency).upper()
+    if ccy == report:
+        return 1.0
+    if ccy not in conversion_rates:
+        raise ValueError(f"missing conversion rate for {ccy}->{report}")
+    rate = float(conversion_rates[ccy])
+    if rate <= 0.0:
+        raise ValueError(f"conversion rate for {ccy}->{report} must be > 0")
+    return rate

quantbt/options/lifecycle.py

@@ -0,0 +1,94 @@
+"""
+Option lifecycle and expiry settlement.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Union
+
+from .ledger import OptionLedger
+from .schema import OptionInstrumentSpec, OptionKind, PremiumConvention, SettlementStyle
+
+
+class OptionSettlementRepresentation(str, Enum):
+    ECONOMIC_CASH = "economic_cash"
+    FUTURE_THEN_CASH = "future_then_cash"
+
+
+@dataclass(frozen=True)
+class OptionSettlementResult:
+    symbol: str
+    timestamp_ns: int
+    settlement_price: float
+    payoff_per_unit: float
+    cashflow: float
+    settlement_currency: str
+    representation: OptionSettlementRepresentation
+    itm: bool
+    position_closed: bool
+
+
+def option_expiry_payoff_per_unit(instrument: OptionInstrumentSpec, settlement_price: float) -> float:
+    """Return payoff per 1 option unit in the instrument settlement currency."""
+    price = float(settlement_price)
+    if price <= 0.0:
+        raise ValueError("settlement_price must be > 0")
+    strike = float(instrument.strike)
+    if instrument.option_kind is OptionKind.CALL:
+        intrinsic_quote = max(price - strike, 0.0)
+    else:
+        intrinsic_quote = max(strike - price, 0.0)
+    if instrument.premium_convention is PremiumConvention.INVERSE_BASE:
+        return intrinsic_quote / price
+    if instrument.premium_convention is PremiumConvention.LINEAR_QUOTE:
+        return intrinsic_quote
+    raise NotImplementedError("quanto option expiry payoff is not implemented in Phase 5")
+
+
+def settle_option_expiry(
+    ledger: OptionLedger,
+    instrument: OptionInstrumentSpec,
+    *,
+    timestamp_ns: int,
+    settlement_price: float,
+    representation: Union[OptionSettlementRepresentation, str, None] = None,
+) -> OptionSettlementResult:
+    """Settle an option position and close it exactly once."""
+    rep = _resolve_representation(instrument, representation)
+    payoff = option_expiry_payoff_per_unit(instrument, settlement_price)
+    cashflow = ledger.apply_settlement(
+        instrument,
+        timestamp_ns=int(timestamp_ns),
+        settlement_price=float(settlement_price),
+        payoff_per_unit=payoff,
+        representation=rep.value,
+    )
+    return OptionSettlementResult(
+        symbol=instrument.symbol,
+        timestamp_ns=int(timestamp_ns),
+        settlement_price=float(settlement_price),
+        payoff_per_unit=float(payoff),
+        cashflow=float(cashflow),
+        settlement_currency=instrument.settlement_currency,
+        representation=rep,
+        itm=bool(payoff > 0.0),
+        position_closed=True,
+    )
+
+
+def _resolve_representation(
+    instrument: OptionInstrumentSpec,
+    representation: Union[OptionSettlementRepresentation, str, None],
+) -> OptionSettlementRepresentation:
+    if representation is not None:
+        if isinstance(representation, OptionSettlementRepresentation):
+            return representation
+        try:
+            return OptionSettlementRepresentation(str(representation))
+        except ValueError as exc:
+            raise ValueError("invalid settlement representation") from exc
+    if instrument.settlement_style is SettlementStyle.FUTURE_THEN_CASH:
+        return OptionSettlementRepresentation.FUTURE_THEN_CASH
+    return OptionSettlementRepresentation.ECONOMIC_CASH