optPricing 2.0.0__py3-none-any.whl

quantfin/models/nig.py

@@ -0,0 +1,180 @@
+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 Normal Inverse Gaussian (NIG) model, a pure-jump Lévy process.
+"""
+
+
+class NIGModel(BaseModel):
+    """Normal Inverse Gaussian (NIG) model, a pure-jump Lévy process."""
+
+    name: str = "Normal Inverse Gaussian"
+    supports_cf: bool = True
+    is_pure_levy: bool = True
+
+    default_params = {"alpha": 15.0, "beta": -5.0, "delta": 0.5}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the NIG 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 = ["alpha", "beta", "delta"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["alpha", "delta"], model=self.name)
+        if not (abs(p["beta"]) < p["alpha"]):
+            raise ValueError("NIG params must satisfy |beta| < alpha.")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, NIGModel):
+            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 = p["alpha"], p["beta"], p["delta"]
+        compensator = delta * (
+            np.sqrt(alpha**2 - (beta + 1) ** 2) - np.sqrt(alpha**2 - beta**2)
+        )
+        drift = r - q + compensator
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            term1 = 1j * u * (np.log(spot) + drift * t)
+            term2 = (
+                delta
+                * t
+                * (
+                    np.sqrt(alpha**2 - beta**2)
+                    - np.sqrt(alpha**2 - (beta + 1j * u) ** 2)
+                )
+            )
+            return np.exp(term1 + term2)
+
+        return phi
+
+    def raw_cf(self, *, t: float) -> Callable:
+        """
+        Returns the CF of the raw NIG 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 = p["alpha"], p["beta"], p["delta"]
+
+        def phi_raw(u: np.ndarray | complex) -> np.ndarray | complex:
+            term = (
+                delta
+                * t
+                * (
+                    np.sqrt(alpha**2 - beta**2)
+                    - np.sqrt(alpha**2 - (beta + 1j * u) ** 2)
+                )
+            )
+            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 NIG process.
+
+        This leverages the representation of the NIG process as a Brownian
+        motion with drift, time-changed by an Inverse Gaussian process.
+
+        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.
+        """
+        from scipy.stats import invgauss
+
+        p = self.params
+        alpha, beta, delta = p["alpha"], p["beta"], p["delta"]
+        mu_ig = delta * T / np.sqrt(alpha**2 - beta**2)
+        ig_time = invgauss.rvs(mu=mu_ig, size=size, random_state=rng)
+        bm_drift = beta * ig_time
+        bm_diffusion = np.sqrt(ig_time) * rng.standard_normal(size=size)
+        return bm_drift + bm_diffusion
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError("NIG 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/perpetual_put.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines a model for pricing a perpetual American put option.
+"""
+
+
+class PerpetualPutModel(BaseModel):
+    """
+    Provides a closed-form price for a perpetual American put option.
+
+    A perpetual option has no expiry date. This model assumes the holder will
+    exercise optimally. The risk-free rate and volatility are considered
+    intrinsic parameters of the model itself.
+    """
+
+    name: str = "Perpetual Put"
+    has_closed_form: bool = True
+
+    default_params = {"sigma": 0.20, "rate": 0.08}
+
+    def __init__(self, params: dict[str, float]) -> None:
+        """
+        Initializes the model with its parameters.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary requiring 'sigma' and 'rate'. If None, `default_params`
+            are used.
+        """
+        super().__init__(params=params)
+
+    def _validate_params(self) -> None:
+        """Validates that 'sigma' and 'rate' are present and positive."""
+        ParamValidator.require(self.params, ["sigma", "rate"], model=self.name)
+        ParamValidator.positive(self.params, ["sigma", "rate"], model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, PerpetualPutModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    def _closed_form_impl(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        q: float,
+        **_: Any,
+    ) -> float:
+        """
+        Calculates the price of a perpetual American put.
+
+        Note: This model uses the 'rate' from its own parameters (`self.params`),
+        ignoring the risk-free rate passed in from the pricing technique. This
+        is a specific design choice for this model. The `t` and `call`
+        parameters are also ignored as they are not applicable.
+
+        Parameters
+        ----------
+        spot : float
+            The current price of the underlying asset.
+        strike : float
+            The strike price of the option.
+        q : float
+            The continuously compounded dividend yield of the asset.
+
+        Returns
+        -------
+        float
+            The price of the perpetual American put.
+        """
+        # uses its own intrinsic rate, not the one from the Rate object.
+        r = self.params["rate"]
+        sigma = self.params["sigma"]
+        vol_sq = sigma**2
+
+        # negative root of the characteristic quadratic equation
+        b = r - q - 0.5 * vol_sq
+        gamma = (-b - math.sqrt(b**2 + 2 * r * vol_sq)) / vol_sq
+
+        # Calculate the optimal exercise boundary (S*)
+        s_star = strike * gamma / (gamma - 1.0)
+
+        if spot <= s_star:
+            # If it is optimal to exercise, the value is the intrinsic value.
+            return strike - spot
+        else:
+            # Otherwise, the value is given by the standard formula.
+            return (strike - s_star) * (spot / s_star) ** gamma
+
+    #  Abstract Method Implementations
+    def _cf_impl(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        raise NotImplementedError(
+            f"{self.name} does not support a characteristic function."
+        )
+
+    def _sde_impl(self) -> Any:
+        raise NotImplementedError(f"{self.name} does not support SDE sampling.")
+
+    def _pde_impl(self) -> Any:
+        raise NotImplementedError(f"{self.name} does not support PDE solving.")

quantfin/models/sabr.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Stochastic Alpha, Beta, Rho (SABR) model.
+"""
+
+
+class SABRModel(BaseModel):
+    """
+    Stochastic Alpha, Beta, Rho (SABR) model from Hagan et al. (2002).
+    """
+
+    name: str = "SABR"
+    supports_sde: bool = True
+    has_variance_process: bool = True
+    is_sabr: bool = True
+    default_params = {"alpha": 0.5, "beta": 0.8, "rho": -0.6}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the SABR 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 that 'alpha', 'beta', and 'rho' are present and positive."""
+        p = self.params
+        req = ["alpha", "beta", "rho"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["alpha"], model=self.name)
+        ParamValidator.bounded(p, "beta", 0.0, 1.0, model=self.name)
+        ParamValidator.bounded(p, "rho", -1.0, 1.0, model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SABRModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError(
+            "SABR uses a specialized kernel, not a generic stepper."
+        )
+
+    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/sabr_jump.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines the SABR model with an added log-normal jump component.
+"""
+
+
+class SABRJumpModel(BaseModel):
+    """SABR model with an added log-normal jump component on the spot process."""
+
+    name: str = "SABR with Jumps"
+    supports_sde: bool = True
+    has_variance_process: bool = True
+    has_jumps: bool = True
+    is_sabr: bool = True
+
+    default_params = {
+        "alpha": 0.5,
+        "beta": 0.8,
+        "rho": -0.6,
+        "lambda": 0.4,
+        "mu_j": -0.1,
+        "sigma_j": 0.15,
+    }
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the SABR with Jumps 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", "rho", "lambda", "mu_j", "sigma_j"]
+        ParamValidator.require(p, req, model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SABRJumpModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError(
+            "SABR uses a specialized kernel, not a generic stepper."
+        )
+
+    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/vasicek.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Vasicek (1977) mean-reverting interest rate model.
+"""
+
+
+class VasicekModel(BaseModel):
+    """
+    Vasicek mean-reverting short rate model.
+    dr_t = kappa * (theta - r_t) * dt + sigma * dW_t
+    """
+
+    name: str = "Vasicek"
+    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 Vasicek 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 that 'kappa', 'theta', and 'sigma' are present and positive."""
+        p = self.params
+        req = ["kappa", "theta", "sigma"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["kappa", "theta", "sigma"], model=self.name)
+
+    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"]
+
+        B = (1 / kappa) * (1 - math.exp(-kappa * T))
+        A_log = (theta - sigma**2 / (2 * kappa**2)) * (B - T) - (
+            sigma**2 / (4 * kappa)
+        ) * B**2
+
+        price = math.exp(A_log - 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/vg.py

@@ -0,0 +1,178 @@
+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 Variance Gamma (VG) model, a pure-jump Lévy process.
+"""
+
+
+class VarianceGammaModel(BaseModel):
+    """Variance Gamma (VG) model, a pure-jump Lévy process."""
+
+    name: str = "Variance Gamma"
+    supports_cf: bool = True
+    is_pure_levy: bool = True
+
+    default_params = {"sigma": 0.2, "nu": 0.1, "theta": -0.14}
+    param_defs = {
+        "sigma": {
+            "label": "Volatility",
+            "default": 0.2,
+            "min": 0.01,
+            "max": 2.0,
+            "step": 0.01,
+        },
+        "nu": {
+            "label": "Variance Rate",
+            "default": 0.1,
+            "min": 0.001,
+            "max": 2.0,
+            "step": 0.01,
+        },
+        "theta": {
+            "label": "Drift",
+            "default": -0.14,
+            "min": -2.0,
+            "max": 2.0,
+            "step": 0.05,
+        },
+    }
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the Variance Gamma (VG) model.
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            A dictionary of model parameters.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        p = self.params
+        req = ["sigma", "nu", "theta"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["sigma", "nu"], model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, VarianceGammaModel):
+            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:
+        """
+        Variance Gamma 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 - 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 raw characteristic function of the VG process itself.
+
+        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
+        sigma, nu, theta = p["sigma"], p["nu"], p["theta"]
+
+        def phi_raw(u: np.ndarray | complex) -> np.ndarray | complex:
+            return (1 - 1j * u * theta * nu + 0.5 * u**2 * sigma**2 * nu) ** (-t / nu)
+
+        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 VG process.
+
+        This leverages the representation of the VG process as a Brownian
+        motion with drift, time-changed by a Gamma process.
+
+        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
+        sigma, nu, theta = p["sigma"], p["nu"], p["theta"]
+        gamma_time = rng.gamma(shape=T / nu, scale=nu, size=size)
+        bm_drift = theta * gamma_time
+        bm_diffusion = sigma * np.sqrt(gamma_time) * rng.standard_normal(size=size)
+        return bm_drift + bm_diffusion
+
+    #  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/parity/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+__doc__ = """
+The `parity` package provides models and utilities based on put-call parity.
+"""
+
+from .implied_rate import ImpliedRateModel
+from .parity_model import ParityModel
+
+__all__ = [
+    "ParityModel",
+    "ImpliedRateModel",
+]