optPricing 2.0.0__py3-none-any.whl

quantfin/models/hyperbolic.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from scipy.special import kv
+from scipy.stats import genhyperbolic
+
+from quantfin.models.base import CF, BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Hyperbolic pure-jump Lévy model.
+"""
+
+
+class HyperbolicModel(BaseModel):
+    """Hyperbolic pure-jump Lévy model."""
+
+    name: str = "Hyperbolic"
+    supports_cf: bool = True
+    is_pure_levy: bool = True
+    default_params = {"alpha": 15.0, "beta": -5.0, "delta": 0.5, "mu": 0.0}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the Hyperbolic model.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary of model parameters. If None, `default_params` are used.
+            Defaults to None.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        p = self.params
+        req = ["alpha", "beta", "delta", "mu"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["alpha", "delta"], model=self.name)
+        if not (abs(p["beta"]) < p["alpha"]):
+            raise ValueError("Hyperbolic params must satisfy |beta| < alpha.")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, HyperbolicModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    def _cf_impl(
+        self,
+        *,
+        t: float,
+        spot: float,
+        r: float,
+        q: float,
+        **_: Any,
+    ) -> CF:
+        """
+        Risk-neutral characteristic function for the log-spot price log(S_t).
+
+        This is the risk-neutral characteristic function, which includes the
+        drift adjustment.
+
+        Parameters
+        ----------
+        t : float
+            The time to maturity of the option, in years.
+        spot : float
+            The current price of the underlying asset.
+        r : float
+            The continuously compounded risk-free rate.
+        q : float
+            The continuously compounded dividend yield.
+
+        Returns
+        -------
+        CF
+            The characteristic function.
+        """
+        p = self.params
+        alpha, beta, delta, mu = p["alpha"], p["beta"], p["delta"], p["mu"]
+        compensator = np.log(self.raw_cf(t=1.0)(-1j))  # E[exp(X_1)] = phi_raw(-i)
+        drift = r - q - compensator
+
+        def phi(u: np.ndarray | complex):
+            return self.raw_cf(t=t)(u) * np.exp(1j * u * (np.log(spot) + drift * t))
+
+        return phi
+
+    def raw_cf(self, *, t: float) -> Callable:
+        """
+        Returns the CF of the raw Hyperbolic process, without drift or spot.
+
+        This function represents the characteristic function of the process
+        before the risk-neutral drift adjustment is applied.
+
+        Parameters
+        ----------
+        t : float
+            The time horizon.
+
+        Returns
+        -------
+        Callable
+            The raw characteristic function.
+        """
+        p = self.params
+        alpha, beta, delta, mu = p["alpha"], p["beta"], p["delta"], p["mu"]
+        gamma_0 = np.sqrt(alpha**2 - beta**2)
+
+        def phi_raw(u: np.ndarray | complex) -> np.ndarray | complex:
+            gamma_u = np.sqrt(alpha**2 - (beta + 1j * u) ** 2)
+            term1 = np.exp(1j * u * mu * t)
+            term2 = (gamma_0 / gamma_u) ** t * (
+                kv(1, delta * t * gamma_u) / kv(1, delta * t * gamma_0)
+            )
+            return term1 * term2
+
+        return phi_raw
+
+    def sample_terminal_log_return(
+        self,
+        T: float,
+        size: int,
+        rng: np.random.Generator,
+    ) -> np.ndarray:
+        """
+        Generates exact samples of the terminal log-return for the Hyperbolic process.
+
+        This uses the `scipy.stats.genhyperbolic` distribution, which is the
+        exact distribution of the process at a given time horizon.
+
+        Parameters
+        ----------
+        T : float
+            The time to maturity, in years.
+        size : int
+            The number of samples to generate.
+        rng : np.random.Generator
+            A random number generator instance for reproducibility.
+
+        Returns
+        -------
+        np.ndarray
+            An array of simulated terminal log-returns.
+        """
+        p = self.params
+        return genhyperbolic.rvs(
+            p=1.0,
+            a=p["alpha"],
+            b=p["beta"],
+            loc=p["mu"] * T,
+            scale=p["delta"] * T,
+            size=size,
+            random_state=rng,
+        )
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _pde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _closed_form_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

quantfin/models/kou.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from quantfin.models.base import CF, BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Kou double-exponential jump-diffusion model.
+"""
+
+
+class KouModel(BaseModel):
+    """Kou double-exponential jump-diffusion model."""
+
+    name: str = "Kou Double-Exponential Jump"
+    supports_cf: bool = True
+    supports_sde: bool = True
+    has_jumps: bool = True
+
+    default_params = {
+        "sigma": 0.15,
+        "lambda": 1.0,
+        "p_up": 0.6,
+        "eta1": 10.0,
+        "eta2": 5.0,
+    }
+    param_defs = {
+        "sigma": {
+            "label": "Volatility",
+            "default": 0.15,
+            "min": 0.01,
+            "max": 1.0,
+            "step": 0.01,
+        },
+        "lambda": {
+            "label": "Jump Intensity",
+            "default": 1.0,
+            "min": 0.0,
+            "max": 10.0,
+            "step": 0.1,
+        },
+        "p_up": {
+            "label": "Up Prob",
+            "default": 0.6,
+            "min": 0.0,
+            "max": 1.0,
+            "step": 0.05,
+        },
+        "eta1": {
+            "label": "Up Size",
+            "default": 10.0,
+            "min": 0.1,
+            "max": 50.0,
+            "step": 0.5,
+        },
+        "eta2": {
+            "label": "Down Size",
+            "default": 5.0,
+            "min": 0.1,
+            "max": 50.0,
+            "step": 0.5,
+        },
+    }
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the Kou Double-Exponential Jump model.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary of model parameters. If None, `default_params` are used.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        """Validate the models parameter."""
+        p = self.params
+        req = ["sigma", "lambda", "p_up", "eta1", "eta2"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["sigma", "lambda", "eta1", "eta2"], model=self.name)
+        ParamValidator.bounded(p, "p_up", 0.0, 1.0, model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, KouModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    def _cf_impl(self, *, t: float, spot: float, r: float, q: float, **_: Any) -> CF:
+        """
+        Kou characteristic function for the log-spot price log(S_t).
+
+        Parameters
+        ----------
+        t : float
+            The time to maturity of the option, in years.
+        spot : float
+            The current price of the underlying asset.
+        r : float
+            The continuously compounded risk-free rate.
+        q : float
+            The continuously compounded dividend yield.
+
+        Returns
+        -------
+        CF
+            The characteristic function.
+        """
+        p = self.params
+        sigma, lambda_, p_up, eta1, eta2 = (
+            p["sigma"],
+            p["lambda"],
+            p["p_up"],
+            p["eta1"],
+            p["eta2"],
+        )
+
+        compensator = lambda_ * (p_up / (eta1 - 1) - (1 - p_up) / (eta2 + 1))
+        drift = r - q - 0.5 * sigma**2 - compensator
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            # BSM component
+            bsm_part = 1j * u * (np.log(spot) + drift * t) - 0.5 * u**2 * sigma**2 * t
+            # Jump component formulation
+            jump_part = (
+                lambda_
+                * t
+                * (p_up / (eta1 - 1j * u) + (1 - p_up) / (eta2 + 1j * u) - 1)
+            )
+
+            return np.exp(bsm_part + jump_part)
+
+        return phi
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError("Kou uses a specialized kernel.")
+
+    def _pde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _closed_form_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

quantfin/models/merton_jump.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from scipy.special import factorial
+
+from quantfin.models.base import CF, BaseModel, ParamValidator
+from quantfin.models.bsm import BSMModel
+
+__doc__ = """
+Defines the Merton jump-diffusion model.
+"""
+
+
+class MertonJumpModel(BaseModel):
+    """
+    Merton Jump-Diffusion model, implemented as a Poisson-weighted sum of BSM prices.
+    """
+
+    name: str = "Merton Jump-Diffusion"
+    supports_cf: bool = True
+    has_closed_form: bool = True
+    supports_sde: bool = True
+    has_jumps: bool = True
+
+    default_params = {
+        "sigma": 0.2,
+        "lambda": 0.5,
+        "mu_j": -0.1,
+        "sigma_j": 0.15,
+        "max_sum_terms": 100,
+    }
+    param_defs = {
+        "sigma": {
+            "label": "Volatility",
+            "default": 0.2,
+            "min": 0.01,
+            "max": 1.0,
+            "step": 0.01,
+        },
+        "lambda": {
+            "label": "Jump Intensity",
+            "default": 0.5,
+            "min": 0.0,
+            "max": 5.0,
+            "step": 0.1,
+        },
+        "mu_j": {
+            "label": "Mean Jump",
+            "default": -0.1,
+            "min": -1.0,
+            "max": 1.0,
+            "step": 0.05,
+        },
+        "sigma_j": {
+            "label": "Jump Vol",
+            "default": 0.15,
+            "min": 0.01,
+            "max": 1.0,
+            "step": 0.01,
+        },
+    }
+
+    def __init__(self, params: dict[str, float]):
+        """
+        Initializes the Merton Jump-Diffusion model.
+        Uses BSMModel instance for the core diffusion
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            A dictionary of model parameters.
+        """
+        super().__init__(params)
+        self.bsm_solver = BSMModel(params={"sigma": self.params["sigma"]})
+
+    def _validate_params(self) -> None:
+        """Validates parameters for diffusion and jump components."""
+        p = self.params
+        req = ["lambda", "mu_j", "sigma_j", "sigma", "max_sum_terms"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(
+            p, ["lambda", "sigma_j", "sigma", "max_sum_terms"], model=self.name
+        )
+
+    def _closed_form_impl(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+        call: bool = True,
+    ) -> float:
+        """
+        Merton's closed-form solution as a sum of BSM prices.
+
+        Parameters
+        ----------
+        spot : float
+            The current price of the underlying asset.
+        strike : float
+            The strike price of the option.
+        r : float
+            The continuously compounded risk-free rate.
+        q : float
+            The continuously compounded dividend yield.
+        t : float
+            The time to maturity of the option, in years.
+        call : bool, optional
+            True for a call option, False for a put. Defaults to True.
+
+        Returns
+        -------
+        float
+            The price of the European option.
+        """
+        lambda_ = self.params["lambda"]
+        mu_j = self.params["mu_j"]
+        sigma_j = self.params["sigma_j"]
+        max_sum_terms = int(self.params["max_sum_terms"])
+
+        k = math.exp(mu_j + 0.5 * sigma_j**2) - 1
+        lambda_prime = lambda_ * (1 + k)
+        y_mul = lambda_prime * t
+
+        interval = np.arange(max_sum_terms)
+        weights = np.exp(-y_mul) * (y_mul**interval) / factorial(interval)
+
+        r_n = r - lambda_ * k + (interval * (mu_j + 0.5 * sigma_j**2)) / t
+        sigma_n_sq = self.params["sigma"] ** 2 + (interval * sigma_j**2) / t
+        sigma_n = np.sqrt(np.maximum(sigma_n_sq, 1e-12))
+
+        total_price = 0.0
+        for i in range(max_sum_terms):
+            # Terminate sum early if weights become negligible
+            if weights[i] < 1e-12 and i > lambda_prime * t:
+                break
+
+            temp_bsm_solver = self.bsm_solver.with_params(sigma=sigma_n[i])
+
+            price_term = temp_bsm_solver.price_closed_form(
+                spot=spot, strike=strike, r=r_n[i], q=q, t=t, call=call
+            )
+            total_price += weights[i] * price_term
+
+        return total_price
+
+    def _cf_impl(
+        self,
+        *,
+        t: float,
+        spot: float,
+        r: float,
+        q: float,
+        **_: Any,
+    ) -> CF:
+        """
+        Merton characteristic function for the log-spot price log(S_t).
+
+        Parameters
+        ----------
+        t : float
+            The time to maturity of the option, in years.
+        spot : float
+            The current price of the underlying asset.
+        r : float
+            The continuously compounded risk-free rate.
+        q : float
+            The continuously compounded dividend yield.
+
+        Returns
+        -------
+        CF
+            The characteristic function.
+        """
+        p = self.params
+        sigma, lambda_, mu_j, sigma_j = p["sigma"], p["lambda"], p["mu_j"], p["sigma_j"]
+        drift = r - q - 0.5 * sigma**2
+        compensator = lambda_ * (np.exp(mu_j + 0.5 * sigma_j**2) - 1)
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            bsm_part = (
+                1j * u * (np.log(spot) + (drift - compensator) * t)
+                - 0.5 * u**2 * sigma**2 * t
+            )
+            jump_part = (
+                lambda_ * t * (np.exp(1j * u * mu_j - 0.5 * u**2 * sigma_j**2) - 1)
+            )
+            return np.exp(bsm_part + jump_part)
+
+        return phi
+
+    def _sde_impl(self):
+        p = self.params
+        sigma, mu_j, sigma_j, lambda_ = p["sigma"], p["mu_j"], p["sigma_j"], p["lambda"]
+        compensator = lambda_ * (np.exp(mu_j + 0.5 * sigma_j**2) - 1)
+
+        def stepper(
+            log_s_t: np.ndarray,
+            r: float,
+            q: float,
+            dt: float,
+            dw_t: np.ndarray,
+            jump_counts: np.ndarray,
+            rng: np.random.Generator,
+        ) -> np.ndarray:
+            drift_term = (r - q - 0.5 * sigma**2 - compensator) * dt
+            next_log_s = log_s_t + drift_term + sigma * dw_t
+            paths_with_jumps = np.where(jump_counts > 0)[0]
+            for path_idx in paths_with_jumps:
+                num_jumps_on_path = jump_counts[path_idx]
+                total_jump_size = np.sum(
+                    rng.normal(loc=mu_j, scale=sigma_j, size=num_jumps_on_path)
+                )
+                next_log_s[path_idx] += total_jump_size
+            return next_log_s
+
+        return stepper
+
+    def _pde_impl(self) -> Any:
+        raise NotImplementedError(f"{self.name} PDE not implemented")