optPricing 2.0.0__py3-none-any.whl

quantfin/models/cgmy.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from scipy.special import gamma as gamma_func
+
+from quantfin.models.base import CF, BaseModel, ParamValidator
+
+__doc__ = """
+Defines the CGMY (Carr, Geman, Madan, Yor, 2002) pure-jump Lévy model.
+"""
+
+
+class CGMYModel(BaseModel):
+    """
+    CGMY (Carr, Geman, Madan, Yor, 2002) pure-jump Lévy model.
+
+    This is a flexible four-parameter model that can capture skewness and kurtosis.
+    It has a known characteristic function for all valid parameters. Monte Carlo
+    simulation is supported for the special case Y=1 (Variance Gamma process).
+    """
+
+    name: str = "CGMY"
+    supports_cf: bool = True
+    is_pure_levy: bool = True
+
+    default_params = {"C": 0.02, "G": 5.0, "M": 5.0, "Y": 1.2}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the CGMY 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:
+        """Validates the C, G, M, and Y parameters."""
+        p = self.params
+        req = ["C", "G", "M", "Y"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["C", "G", "M"], model=self.name)
+        if not (p["Y"] < 2):
+            raise ValueError(
+                "CGMY parameter Y must be less than 2 for finite variance."
+            )
+        if p["Y"] <= 0 and p["C"] != 0:
+            print("Warning: CGMY with Y<=0 and C!=0 can have infinite moments.")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CGMYModel):
+            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.
+        """
+        compensator = np.log(self.raw_cf(t=1.0)(-1j))
+        drift = r - q - np.real(compensator)
+
+        def phi(u: np.ndarray | complex) -> 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 CGMY 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
+        C, G, M, Y = p["C"], p["G"], p["M"], p["Y"]
+
+        def phi_raw(u: np.ndarray | complex) -> np.ndarray | complex:
+            term = (
+                C
+                * t
+                * gamma_func(-Y)
+                * ((M - 1j * u) ** Y - M**Y + (G + 1j * u) ** Y - G**Y)
+            )
+            return np.exp(term)
+
+        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 CGMY process.
+
+        NOTE: This is only implemented for the special case Y=1, where the
+        process is a difference of two time-changed Brownian motions.
+
+        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.
+
+        Raises
+        ------
+        NotImplementedError
+            If the model parameter Y is not equal to 1.
+        """
+        p = self.params
+        C, G, M, Y = p["C"], p["G"], p["M"], p["Y"]
+
+        if not np.isclose(Y, 1.0):
+            raise NotImplementedError(
+                "Monte Carlo sampling for CGMY is only implemented for Y=1."
+            )
+
+        # For Y=1, CGMY is a scaled difference of two Gamma processes.
+        # This is equivalent to a Variance Gamma process.
+        # Can sample this by time-changing a Brownian motion.
+        g_up = rng.gamma(shape=C * T, scale=1 / M, size=size)
+        g_down = rng.gamma(shape=C * T, scale=1 / G, size=size)
+
+        return g_up - g_down
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError("CGMY is a pure Lévy process, use terminal sampling.")
+
+    def _pde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _closed_form_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

quantfin/models/cir.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Cox-Ingersoll-Ross (1985) mean-reverting interest rate model.
+"""
+
+
+class CIRModel(BaseModel):
+    """
+    Cox-Ingersoll-Ross (1985) mean-reverting short rate model.
+    dr_t = kappa * (theta - r_t) * dt + sigma * sqrt(r_t) * dW_t
+    """
+
+    name: str = "Cox-Ingersoll-Ross"
+    has_closed_form: bool = True
+    default_params = {"kappa": 0.86, "theta": 0.09, "sigma": 0.02}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the CIR 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:
+        p = self.params
+        req = ["kappa", "theta", "sigma"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["kappa", "theta", "sigma"], model=self.name)
+        if 2 * p["kappa"] * p["theta"] < p["sigma"] ** 2:
+            print("Warning: CIR parameters do not satisfy the Feller condition.")
+
+    def _closed_form_impl(
+        self,
+        *,
+        spot: float,
+        t: float,
+        **_: Any,
+    ) -> float:
+        """
+        Calculates the price of a Zero-Coupon Bond.
+
+        Note: Re-interprets 'spot' as the initial short rate r0 and 't' as
+        the bond's maturity T. Ignores other option-specific parameters.
+
+        Parameters
+        ----------
+        spot : float
+            The initial short rate, r0.
+        t : float
+            The maturity of the bond, in years.
+
+        Returns
+        -------
+        float
+            The price of the zero-coupon bond.
+        """
+        r0, T = spot, t
+        p = self.params
+        kappa, theta, sigma = p["kappa"], p["theta"], p["sigma"]
+
+        gamma = math.sqrt(kappa**2 + 2 * sigma**2)
+        exp_gamma_T = math.exp(gamma * T)
+
+        den = (gamma + kappa) * (exp_gamma_T - 1) + 2 * gamma
+        B = 2 * (exp_gamma_T - 1) / den
+        A_log_base = (2 * gamma * math.exp((kappa + gamma) * T / 2)) / den
+        A_log_power = (2 * kappa * theta) / sigma**2
+
+        price = (A_log_base**A_log_power) * math.exp(-B * r0)
+        return price
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _cf_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _pde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

quantfin/models/dupire_local.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+from quantfin.models.base import BaseModel
+
+
+class DupireLocalVolModel(BaseModel):
+    """Dupire Local Volatility model."""
+
+    name: str = "Dupire Local Volatility"
+    supports_sde: bool = True
+    is_local_vol: bool = True
+
+    default_params = {"vol_surface": lambda T, K: 0.2}
+
+    def __init__(self, params: dict[str, Any] | None = None):
+        """
+        Initializes the Dupire Local Volatility model.
+
+        The key parameter for this model is 'vol_surface', a callable function
+        that takes maturity (T) and strike (K) and returns the local volatility.
+
+        Parameters
+        ----------
+        params : dict[str, Any] | None, optional
+            A dictionary of model parameters. If None, a default constant
+            volatility surface is used. Defaults to None.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        if "vol_surface" not in self.params or not callable(self.params["vol_surface"]):
+            raise ValueError(
+                "Dupire model requires a callable 'vol_surface' in its parameters."
+            )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, DupireLocalVolModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    def __repr__(self) -> str:
+        """Custom representation to handle the vol_surface function."""
+        # Get the name of the function if possible, otherwise show its type
+        vol_surface_repr = getattr(
+            self.params["vol_surface"],
+            "__name__",
+            str(type(self.params["vol_surface"])),
+        )
+        return f"{self.__class__.__name__}(vol_surface={vol_surface_repr})"
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError("Dupire uses a specialized kernel.")
+
+    def _cf_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/heston.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from quantfin.models.base import CF, BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Heston stochastic volatility model.
+"""
+
+
+class HestonModel(BaseModel):
+    """
+    Heston stochastic volatility model.
+
+    This model describes the evolution of an asset's price where the volatility
+    itself is a random process, following a Cox-Ingersoll-Ross (CIR) process.
+    It is widely used as it can capture volatility smiles and skews.
+    """
+
+    name: str = "Heston"
+    supports_cf: bool = True
+    supports_sde: bool = True
+    has_variance_process: bool = True
+    cf_kwargs = ("v0",)  # v0 is required for pricing, passed from kwargs
+
+    default_params = {
+        "v0": 0.04,
+        "kappa": 2.0,
+        "theta": 0.04,
+        "rho": -0.7,
+        "vol_of_vol": 0.5,
+    }
+    param_defs = {
+        "v0": {
+            "label": "Initial Variance (v0)",
+            "default": 0.04,
+            "min": 0.001,
+            "max": 0.5,
+            "step": 0.01,
+        },
+        "kappa": {
+            "label": "Mean Reversion (κ)",
+            "default": 2.0,
+            "min": 0.1,
+            "max": 10.0,
+            "step": 0.1,
+        },
+        "theta": {
+            "label": "Long-Term Var (θ)",
+            "default": 0.04,
+            "min": 0.01,
+            "max": 0.5,
+            "step": 0.01,
+        },
+        "rho": {
+            "label": "Correlation (ρ)",
+            "default": -0.7,
+            "min": -0.99,
+            "max": 0.99,
+            "step": 0.05,
+        },
+        "vol_of_vol": {
+            "label": "Vol of Vol (ξ)",
+            "default": 0.5,
+            "min": 0.1,
+            "max": 1.5,
+            "step": 0.05,
+        },
+    }
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the Heston 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:
+        """Validates parameters for mean-reversion, correlation, etc."""
+        p = self.params
+        req = ["kappa", "theta", "rho", "vol_of_vol"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["kappa", "theta", "vol_of_vol"], model=self.name)
+        ParamValidator.bounded(p, "rho", -1.0, 1.0, model=self.name)
+        if 2 * p["kappa"] * p["theta"] < p["vol_of_vol"] ** 2:
+            print(
+                f"Warning: Params for {self.name} do not satisfy the Feller condition."
+            )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, HestonModel):
+            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,
+        v0: float,
+        **_: Any,
+    ) -> CF:
+        """
+        Heston 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.
+        v0 : float
+            The initial variance of the asset's returns.
+
+        Returns
+        -------
+        CF
+            The characteristic function.
+        """
+        p = self.params
+        kappa, theta, rho, vol_of_vol = (
+            p["kappa"],
+            p["theta"],
+            p["rho"],
+            p["vol_of_vol"],
+        )
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            d = np.sqrt(
+                (rho * vol_of_vol * u * 1j - kappa) ** 2
+                - (vol_of_vol**2) * (-u * 1j - u**2)
+            )
+            g = (kappa - rho * vol_of_vol * u * 1j - d) / (
+                kappa - rho * vol_of_vol * u * 1j + d
+            )
+            C = (r - q) * u * 1j * t + (kappa * theta / vol_of_vol**2) * (
+                (kappa - rho * vol_of_vol * u * 1j - d) * t
+                - 2 * np.log((1 - g * np.exp(-d * t)) / (1 - g))
+            )
+            D = ((kappa - rho * vol_of_vol * u * 1j - d) / vol_of_vol**2) * (
+                (1 - np.exp(-d * t)) / (1 - g * np.exp(-d * t))
+            )
+            return np.exp(C + D * v0 + 1j * u * np.log(spot))
+
+        return phi
+
+    def get_sde_stepper(self) -> Callable:
+        """
+        Returns the SDE stepper function for the Heston model.
+
+        This is not used by the JIT-compiled kernel but is kept for potential
+        future use with non-compiled or more complex simulation loops.
+        """
+        p = self.params
+        kappa, theta, rho, vol_of_vol = (
+            p["kappa"],
+            p["theta"],
+            p["rho"],
+            p["vol_of_vol"],
+        )
+
+        def stepper(
+            log_s_t: np.ndarray,
+            v_t: np.ndarray,
+            r: float,
+            q: float,
+            dt: float,
+            dw_s: np.ndarray,
+            dw_v: np.ndarray,
+        ) -> tuple[np.ndarray, np.ndarray]:
+            v_t_pos = np.maximum(v_t, 0)
+            v_sqrt = np.sqrt(v_t_pos)
+            log_s_t_next = log_s_t + (r - q - 0.5 * v_t_pos) * dt + v_sqrt * dw_s
+            v_t_next = v_t + kappa * (theta - v_t_pos) * dt + vol_of_vol * v_sqrt * dw_v
+            return log_s_t_next, np.maximum(v_t_next, 0)  # Reflection scheme
+
+        return stepper
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Callable:
+        return self.get_sde_stepper()
+
+    def _pde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _closed_form_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError