quantark 0.1.0__py3-none-any.whl

quantark/asset/equity/engine/analytical/single_sharkfin_option_analytical_engine.py

@@ -0,0 +1,229 @@
+"""
+Analytical pricing engine for single sharkfin options.
+
+The payoff is decomposed into:
+- a no-rebate knock-out vanilla option,
+- a one-touch cash leg for the knock-out rebate, and
+- a no-touch cash leg for the no-hit rebate.
+
+Discrete monitoring is handled by the underlying barrier and one-touch
+analytical engines using the Broadie-Glasserman-Kou barrier shift.
+"""
+
+from typing import Optional
+
+from quantark.asset.equity.engine.base_engine import BaseEngine
+from quantark.asset.equity.product.base_equity_product import BaseEquityProduct
+from quantark.asset.equity.product.option import (
+    BarrierOption,
+    OneTouchOption,
+    SingleSharkfinOption,
+)
+from quantark.asset.equity.param import EngineParams
+from quantark.priceenv import PricingEnvironment
+from quantark.util.enum import BarrierDirection, BarrierType, ObservationType, TouchType
+from quantark.util.enum.engine_enums import EngineType
+from quantark.util.exceptions import PricingError, ValidationError
+from quantark.util.numerical import validate_non_negative, validate_positive
+
+from .barrier_analytical_engine import BarrierAnalyticalEngine
+from .one_touch_analytical_engine import OneTouchAnalyticalEngine
+
+
+class SingleSharkfinOptionAnalyticalEngine(BaseEngine):
+    """
+    Closed-form analytical engine for SingleSharkfinOption.
+
+    Supports expiry-only and continuous monitoring exactly under Black-Scholes
+    assumptions. Discrete monitoring uses the standard BGK continuity correction
+    implemented by the composed barrier and one-touch engines, so daily
+    observation schedules are approximated by shifting the barrier away from spot.
+    """
+
+    engine_type = EngineType.ANALYTICAL
+
+    MIN_MATURITY = 1e-10
+    MAX_MATURITY = 50.0
+    MIN_VOL = 0.001
+    MAX_VOL = 5.0
+
+    def __init__(self, params: Optional[EngineParams] = None):
+        super().__init__(params)
+        self._barrier_engine = BarrierAnalyticalEngine(params)
+        self._one_touch_engine = OneTouchAnalyticalEngine(params)
+
+    def price(
+        self, product: BaseEquityProduct, pricing_env: PricingEnvironment
+    ) -> float:
+        """
+        Price a single sharkfin option analytically.
+
+        Args:
+            product: SingleSharkfinOption instance.
+            pricing_env: Market data environment.
+
+        Returns:
+            Present value scaled by product.contract_multiplier.
+
+        Raises:
+            PricingError: If product type or observation mode is unsupported.
+            ValidationError: If pricing inputs are invalid.
+        """
+        if not isinstance(product, SingleSharkfinOption):
+            raise PricingError(
+                "SingleSharkfinOptionAnalyticalEngine only supports "
+                f"SingleSharkfinOption, got {type(product).__name__}"
+            )
+
+        spot = pricing_env.spot
+        maturity = product.get_maturity(pricing_env)
+        rate = pricing_env.get_rate(maturity)
+        div = pricing_env.get_div_yield(maturity)
+        vol = pricing_env.get_vol(product.strike, maturity)
+
+        self._validate_inputs(
+            spot=spot,
+            strike=product.strike,
+            barrier=product.barrier,
+            maturity=maturity,
+            rate=rate,
+            div=div,
+            vol=vol,
+            participation_rate=product.participation_rate,
+            knock_out_rebate=product.knock_out_rebate,
+            no_hit_rebate=product.no_hit_rebate,
+            contract_multiplier=product.contract_multiplier,
+        )
+
+        if maturity < self.MIN_MATURITY:
+            return product.get_payoff(spot)
+
+        if product.observation_type not in (
+            ObservationType.EXPIRY,
+            ObservationType.CONTINUOUS,
+            ObservationType.DISCRETE,
+        ):
+            raise PricingError(
+                f"Unsupported observation type: {product.observation_type}"
+            )
+
+        ko_option_value = self._price_no_rebate_knock_out(product, pricing_env)
+        knock_out_rebate_value = self._price_touch_leg(
+            product=product,
+            pricing_env=pricing_env,
+            rebate=product.knock_out_rebate,
+            touch_type=TouchType.ONE_TOUCH,
+        )
+        no_hit_rebate_value = self._price_touch_leg(
+            product=product,
+            pricing_env=pricing_env,
+            rebate=product.no_hit_rebate,
+            touch_type=TouchType.NO_TOUCH,
+        )
+
+        value = (
+            product.participation_rate * ko_option_value
+            + knock_out_rebate_value
+            + no_hit_rebate_value
+        )
+        return max(value, 0.0) * product.contract_multiplier
+
+    def _price_no_rebate_knock_out(
+        self, product: SingleSharkfinOption, pricing_env: PricingEnvironment
+    ) -> float:
+        """Value the capped sharkfin participation leg as a knock-out option."""
+        barrier_option = BarrierOption(
+            strike=product.strike,
+            option_type=product.option_type,
+            barrier=product.barrier,
+            barrier_type=self._barrier_type(product),
+            maturity=product.maturity,
+            exercise_date=product.exercise_date,
+            settlement_date=product.settlement_date,
+            rebate=0.0,
+            participation_rate=1.0,
+            pay_at_hit=False,
+            observation_type=product.observation_type,
+            observation_dates=product.observation_dates,
+            observation_schedule=product.observation_schedule,
+            contract_multiplier=1.0,
+        )
+        return self._barrier_engine.price(barrier_option, pricing_env)
+
+    def _price_touch_leg(
+        self,
+        product: SingleSharkfinOption,
+        pricing_env: PricingEnvironment,
+        rebate: float,
+        touch_type: TouchType,
+    ) -> float:
+        """Value a fixed cash leg conditional on touch or no-touch."""
+        if rebate <= 0.0:
+            return 0.0
+
+        touch_option = OneTouchOption(
+            barrier=product.barrier,
+            barrier_direction=self._barrier_direction(product),
+            maturity=product.maturity,
+            exercise_date=product.exercise_date,
+            settlement_date=product.settlement_date,
+            rebate=rebate,
+            payment_at_hit=(
+                product.pay_at_hit if touch_type == TouchType.ONE_TOUCH else False
+            ),
+            touch_type=touch_type,
+            observation_type=product.observation_type,
+            observation_dates=product.observation_dates,
+            observation_schedule=product.observation_schedule,
+        )
+        return self._one_touch_engine.price(touch_option, pricing_env)
+
+    def _barrier_type(self, product: SingleSharkfinOption) -> BarrierType:
+        """Map sharkfin orientation to a knock-out barrier type."""
+        return BarrierType.UP_OUT if product.is_call() else BarrierType.DOWN_OUT
+
+    def _barrier_direction(self, product: SingleSharkfinOption) -> BarrierDirection:
+        """Map sharkfin orientation to a one-touch barrier direction."""
+        return BarrierDirection.UP if product.is_call() else BarrierDirection.DOWN
+
+    def _validate_inputs(
+        self,
+        spot: float,
+        strike: float,
+        barrier: float,
+        maturity: float,
+        rate: float,
+        div: float,
+        vol: float,
+        participation_rate: float,
+        knock_out_rebate: float,
+        no_hit_rebate: float,
+        contract_multiplier: float,
+    ) -> None:
+        """Validate market and product inputs for analytical pricing."""
+        validate_positive(spot, "spot")
+        validate_positive(strike, "strike")
+        validate_positive(barrier, "barrier")
+        validate_non_negative(maturity, "maturity")
+        validate_positive(vol, "volatility")
+        validate_non_negative(participation_rate, "participation_rate")
+        validate_non_negative(knock_out_rebate, "knock_out_rebate")
+        validate_non_negative(no_hit_rebate, "no_hit_rebate")
+        validate_positive(contract_multiplier, "contract_multiplier")
+
+        if vol < self.MIN_VOL or vol > self.MAX_VOL:
+            raise ValidationError(
+                f"Volatility {vol} outside supported range "
+                f"[{self.MIN_VOL}, {self.MAX_VOL}]"
+            )
+        if maturity > self.MAX_MATURITY:
+            raise ValidationError(
+                f"Maturity too long for analytical sharkfin pricing: {maturity}"
+            )
+        if div < 0:
+            raise ValidationError(f"Dividend yield must be non-negative, got {div}")
+        if abs(rate) > 1.0:
+            raise ValidationError(f"Risk-free rate outside reasonable bounds: {rate}")
+
+    def __repr__(self):
+        return "SingleSharkfinOptionAnalyticalEngine()"

quantark/asset/equity/engine/base_engine.py

@@ -0,0 +1,137 @@
+"""
+Base class for pricing engines.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional
+from quantark.asset.equity.product.base_equity_product import BaseEquityProduct
+from quantark.priceenv import PricingEnvironment
+from quantark.asset.equity.param import EngineParams
+from quantark.asset.equity.engine.event_stats import AutocallableEventStats
+from quantark.util.enum.engine_enums import EngineType
+
+
+class BaseEngine(ABC):
+    """
+    Abstract base class for all pricing engines.
+
+    Engines are responsible for computing prices and Greeks for derivatives.
+
+    Attributes:
+        engine_type: The type category of this engine (ANALYTICAL, MONTE_CARLO, PDE, etc.)
+    """
+
+    engine_type: EngineType = EngineType.ANALYTICAL
+
+    def __init__(self, params: Optional[EngineParams] = None):
+        """
+        Initialize the engine.
+
+        Args:
+            params: Engine configuration parameters
+        """
+        self.params = params if params is not None else EngineParams()
+
+    @abstractmethod
+    def price(
+        self, product: BaseEquityProduct, pricing_env: PricingEnvironment
+    ) -> float:
+        """
+        Calculate the price of the product.
+
+        Args:
+            product: The derivative product to price
+            pricing_env: Pricing environment with market data
+
+        Returns:
+            Product price
+        """
+        pass
+
+    def price_with_events(
+        self,
+        product: BaseEquityProduct,
+        pricing_env: PricingEnvironment,
+        emit_distribution: bool = True,
+    ) -> "PricingResult":
+        """
+        Return product NPV and an event distribution for cash-leg valuation.
+
+        Engines that already implement calculate_event_stats are adapted to the
+        generalized EventDistribution. Engines without event stats fall back to
+        a maturity-only distribution, which is sufficient for deterministic and
+        full-schedule cash legs.
+        """
+        from quantark.cashleg.event_distribution import EventDistribution, PricingResult
+
+        if emit_distribution:
+            stats = self.calculate_event_stats(product, pricing_env)
+            if stats is not None:
+                return PricingResult(
+                    npv=float(stats.pv),
+                    event_distribution=EventDistribution.from_autocallable_stats(stats),
+                )
+
+        npv = self.price(product, pricing_env)
+        return PricingResult(
+            npv=npv,
+            event_distribution=EventDistribution.trivial(product.get_maturity(pricing_env)),
+        )
+
+    def calculate_greeks(
+        self, product: BaseEquityProduct, pricing_env: PricingEnvironment
+    ) -> Dict[str, float]:
+        """
+        Calculate Greeks using finite difference method.
+
+        This default implementation uses bump-and-reprice.
+        Subclasses can override to provide analytical Greeks.
+
+        Args:
+            product: The derivative product
+            pricing_env: Pricing environment with market data
+
+        Returns:
+            Dictionary of Greeks
+        """
+        from copy import deepcopy
+
+        base_price = self.price(product, pricing_env)
+        greeks = {"price": base_price}
+
+        # Delta: dV/dS
+        env_up = deepcopy(pricing_env)
+        env_up.spot_quote.spot *= 1 + self.params.bump_size
+        price_up = self.price(product, env_up)
+
+        env_down = deepcopy(pricing_env)
+        env_down.spot_quote.spot *= 1 - self.params.bump_size
+        price_down = self.price(product, env_down)
+
+        delta = (price_up - price_down) / (2 * pricing_env.spot * self.params.bump_size)
+        greeks["delta"] = delta
+
+        # Gamma: d²V/dS²
+        gamma = (price_up - 2 * base_price + price_down) / (
+            pricing_env.spot * self.params.bump_size
+        ) ** 2
+        greeks["gamma"] = gamma
+
+        return greeks
+
+    def calculate_event_stats(
+        self, product: BaseEquityProduct, pricing_env: PricingEnvironment
+    ) -> Optional[AutocallableEventStats]:
+        """
+        Optionally provide per-observation event stats and cashflow decomposition.
+
+        Engines MAY override this method to provide per-observation probabilities and
+        expected discounted cashflows for autocallable products. This enables faster
+        reporting (especially for QUAD/PDE engines) compared to Monte Carlo analyzers.
+
+        Default behavior: return None (not supported).
+        """
+        return None
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}()"

quantark/asset/equity/engine/event_stats.py

@@ -0,0 +1,85 @@
+"""
+Engine-level event stats and cashflow decomposition types.
+
+These types define an optional API that engines MAY implement to provide
+per-observation event probabilities and expected discounted cashflows for
+autocallable products (Snowball-first).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class AutocallableEventStats:
+    """
+    Event probabilities and expected discounted cashflows.
+
+    Attributes:
+        pv: Present value produced by the engine for the given product/env.
+        ko_times: KO observation times (year fractions from valuation date).
+        ko_probability: Probability of KO occurring at each observation time.
+        survival_probability: Probability of surviving (not KO'd) up to each observation.
+        expected_discounted_ko_cashflow: Expected discounted KO redemption cashflow at each observation.
+        ki_probability: Probability that KI occurred at least once before maturity (if applicable).
+        expected_discounted_maturity_cashflow: Expected discounted maturity cashflow (conditional on no KO).
+        reconciliation_error: pv minus sum(expected discounted cashflows) if computed, else 0.0.
+        ki_times: KI observation/monitoring times where event probabilities are available.
+        ki_event_probability: Probability of first KI occurring at each KI time.
+        ki_survival_probability: Probability of surviving without KI up to each KI time.
+    """
+
+    pv: float
+    ko_times: np.ndarray
+    ko_probability: np.ndarray
+    survival_probability: np.ndarray
+    expected_discounted_ko_cashflow: np.ndarray
+    ki_probability: float
+    expected_discounted_maturity_cashflow: float
+    reconciliation_error: float = 0.0
+    ki_times: np.ndarray = field(default_factory=lambda: np.array([]))
+    ki_event_probability: np.ndarray = field(default_factory=lambda: np.array([]))
+    ki_survival_probability: np.ndarray = field(default_factory=lambda: np.array([]))
+
+
+@dataclass(frozen=True)
+class PhoenixEventStats(AutocallableEventStats):
+    """
+    Event stats for Phoenix options including coupon diagnostics.
+
+    Attributes:
+        coupon_probability: Coupon trigger probability at each observation time.
+        expected_discounted_coupon_cashflow: Expected discounted coupon cashflow per observation.
+    """
+
+    coupon_probability: np.ndarray = field(default_factory=lambda: np.array([]))
+    expected_discounted_coupon_cashflow: np.ndarray = field(
+        default_factory=lambda: np.array([])
+    )
+
+
+@dataclass(frozen=True)
+class KOResetEventStats(AutocallableEventStats):
+    """
+    Event stats for KO-reset snowball options.
+
+    Attributes:
+        pre_ko_times: Pre-KI KO observation times (absolute).
+        pre_ko_probability: KO probability per pre-KI observation.
+        post_ko_times: Post-KI KO observation times (absolute or offsets for REBASED).
+        post_ko_probability: KO probability per post-KI observation (or offset).
+        pre_ko_probability_total: Total probability of pre-KI KO.
+        post_ko_probability_total: Total probability of post-KI KO.
+        expected_discounted_post_ko_cashflow: Total expected discounted KO cashflow after KI.
+    """
+
+    pre_ko_times: np.ndarray = field(default_factory=lambda: np.array([]))
+    pre_ko_probability: np.ndarray = field(default_factory=lambda: np.array([]))
+    post_ko_times: np.ndarray = field(default_factory=lambda: np.array([]))
+    post_ko_probability: np.ndarray = field(default_factory=lambda: np.array([]))
+    pre_ko_probability_total: float = 0.0
+    post_ko_probability_total: float = 0.0
+    expected_discounted_post_ko_cashflow: float = 0.0

quantark/asset/equity/engine/mc/__init__.py

@@ -0,0 +1,31 @@
+"""
+Monte Carlo pricing engines for equity derivatives.
+"""
+
+from .euro_mc_engine import EuropeanMCEngine
+from .american_option_mc_engine import AmericanOptionMCEngine, AmericanMCResult
+from .snowball_mc_engine import SnowballMCEngine
+from .phoenix_mc_engine import PhoenixMCEngine, PhoenixMCResult
+from .asian_option_mc_engine import AsianOptionMCEngine, AsianMCResult
+from .digital_option_mc_engine import DigitalOptionMCEngine
+from .barrier_option_mc_engine import BarrierOptionMCEngine
+from .single_sharkfin_option_mc_engine import SingleSharkfinOptionMCEngine
+from .double_sharkfin_option_mc_engine import DoubleSharkfinOptionMCEngine
+from .range_accrual_mc_engine import RangeAccrualMCEngine, RangeAccrualMCResult
+
+__all__ = [
+    "EuropeanMCEngine",
+    "AmericanOptionMCEngine",
+    "AmericanMCResult",
+    "SnowballMCEngine",
+    "PhoenixMCEngine",
+    "PhoenixMCResult",
+    "AsianOptionMCEngine",
+    "AsianMCResult",
+    "DigitalOptionMCEngine",
+    "BarrierOptionMCEngine",
+    "SingleSharkfinOptionMCEngine",
+    "DoubleSharkfinOptionMCEngine",
+    "RangeAccrualMCEngine",
+    "RangeAccrualMCResult",
+]