optPricing 2.0.0__py3-none-any.whl

quantfin/models/bates.py

@@ -0,0 +1,192 @@
+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
+from quantfin.models.heston import HestonModel
+from quantfin.models.merton_jump import MertonJumpModel
+
+__doc__ = """
+Defines the Bates stochastic volatility with jumps model.
+"""
+
+
+class BatesModel(BaseModel):
+    """
+    Bates stochastic volatility jump-diffusion model.
+
+    This model combines the Heston stochastic volatility process with Merton's
+    log-normal jump-diffusion process, providing a rich framework for capturing
+    both volatility smiles and sudden market shocks.
+    """
+
+    name: str = "Bates"
+    supports_cf: bool = True
+    supports_sde: bool = True
+    has_jumps: bool = True
+    has_variance_process: bool = True
+    cf_kwargs = ("v0",)
+
+    default_params = {
+        "v0": 0.04,
+        "kappa": 2.0,
+        "theta": 0.04,
+        "rho": -0.7,
+        "vol_of_vol": 0.5,
+        "lambda": 0.5,
+        "mu_j": -0.1,
+        "sigma_j": 0.15,
+    }
+    param_defs = {**HestonModel.param_defs, **MertonJumpModel.param_defs}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the Bates 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 all Heston and Merton parameters."""
+        p = self.params
+        req = ["kappa", "theta", "rho", "vol_of_vol", "lambda", "mu_j", "sigma_j"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(
+            p, ["kappa", "theta", "vol_of_vol", "lambda", "sigma_j"], model=self.name
+        )
+        ParamValidator.bounded(p, "rho", -1.0, 1.0, model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, BatesModel):
+            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:
+        """
+        Bates characteristic function, a product of Heston and Merton CFs.
+
+        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"],
+        )
+        lambda_, mu_j, sigma_j = p["lambda"], p["mu_j"], p["sigma_j"]
+
+        # Risk-neutral compensator for the jump part
+        compensator = lambda_ * (np.exp(mu_j + 0.5 * sigma_j**2) - 1)
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            # Heston part (with drift adjusted for jump compensator)
+            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 - compensator) * 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))
+            )
+            heston_part = np.exp(C + D * v0 + 1j * u * np.log(spot))
+
+            # Merton jump part
+            jump_part = np.exp(
+                lambda_ * t * (np.exp(1j * u * mu_j - 0.5 * u**2 * sigma_j**2) - 1)
+            )
+
+            return heston_part * jump_part
+
+        return phi
+
+    def get_sde_stepper(self) -> Callable:
+        """Returns the SDE stepper function for the Bates model."""
+        p = self.params
+        kappa, theta, rho, vol_of_vol = (
+            p["kappa"],
+            p["theta"],
+            p["rho"],
+            p["vol_of_vol"],
+        )
+        lambda_, mu_j, sigma_j = p["lambda"], p["mu_j"], p["sigma_j"]
+        compensator = lambda_ * (np.exp(mu_j + 0.5 * sigma_j**2) - 1)
+
+        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,
+            jump_counts: np.ndarray,
+            rng: np.random.Generator,
+        ) -> tuple[np.ndarray, np.ndarray]:
+            v_t_pos = np.maximum(v_t, 0)
+            v_sqrt = np.sqrt(v_t_pos)
+            # Evolve variance
+            v_t_next = v_t + kappa * (theta - v_t_pos) * dt + vol_of_vol * v_sqrt * dw_v
+            # Evolve log-spot (Heston part + jump compensator)
+            s_drift = (r - q - 0.5 * v_t_pos - compensator) * dt
+            next_log_s = log_s_t + s_drift + v_sqrt * dw_s
+            # Add jumps
+            paths_with_jumps = np.where(jump_counts > 0)[0]
+            for path_idx in paths_with_jumps:
+                num_jumps = jump_counts[path_idx]
+                jump_size = np.sum(rng.normal(loc=mu_j, scale=sigma_j, size=num_jumps))
+                next_log_s[path_idx] += jump_size
+            return next_log_s, np.maximum(v_t_next, 0)
+
+        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

quantfin/models/blacks_approx.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+from quantfin.models.base import BaseModel, ParamValidator
+from quantfin.models.bsm import BSMModel
+
+__doc__ = """
+Defines Black's (1975) approximation for pricing an American call option
+on a stock paying discrete dividends.
+"""
+
+
+class BlacksApproxModel(BaseModel):
+    """
+    Black's approximation for an American call on a stock with discrete dividends.
+    """
+
+    name: str = "Black's Approximation"
+    has_closed_form: bool = True
+    cf_kwargs = BaseModel.cf_kwargs + ("discrete_dividends", "ex_div_times")
+
+    default_params = {"sigma": 0.30}
+
+    def __init__(self, params: dict[str, float]):
+        """
+        Initializes the Black's Approximation model.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary of model parameters. If None, `default_params` are used.
+            Must contain 'sigma'.
+        """
+        super().__init__(params)
+        self.bsm_solver = BSMModel(params={"sigma": self.params["sigma"]})
+
+    def _validate_params(self) -> None:
+        """Validate the 'sigma' parameter."""
+        ParamValidator.require(self.params, ["sigma"], model=self.name)
+        ParamValidator.positive(self.params, ["sigma"], model=self.name)
+
+    def _closed_form_impl(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        t: float,
+        call: bool = True,
+        discrete_dividends: np.ndarray,
+        ex_div_times: np.ndarray,
+        q: float | None = None,
+    ) -> float:
+        """
+        Calculates the price by comparing holding vs. exercising before each dividend.
+
+        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.
+        t : float
+            The time to maturity of the option, in years.
+        call : bool, optional
+            Must be True, as the model is for calls only. Defaults to True.
+        discrete_dividends : np.ndarray
+            An array of discrete dividend amounts.
+        ex_div_times : np.ndarray
+            An array of ex-dividend dates, in years.
+
+        Returns
+        -------
+        float
+            The approximated price of the American call option.
+
+        Raises
+        ------
+        NotImplementedError
+            If the option is a put.
+        ValueError
+            If `discrete_dividends` is empty.
+        """
+        if not call:
+            raise NotImplementedError(
+                "Black's Approximation is for American calls only."
+            )
+        if not hasattr(discrete_dividends, "__len__") or len(discrete_dividends) == 0:
+            raise ValueError(
+                "BlacksApproxModel requires non-empty 'discrete_dividends'."
+            )
+
+        # Value of holding until maturity T
+        pv_all_divs = sum(
+            D * math.exp(-r * tD)
+            for D, tD in zip(discrete_dividends, ex_div_times)
+            if tD < t
+        )
+        S_adj_T = spot - pv_all_divs
+        price_hold_to_maturity = self.bsm_solver.price_closed_form(
+            spot=S_adj_T, strike=strike, r=r, q=0, t=t, call=True
+        )
+
+        # Value of exercising just before each ex-dividend date
+        prices_early_exercise = []
+        for i, t_i in enumerate(ex_div_times):
+            if t_i >= t:
+                continue
+            pv_divs_before_i = sum(
+                discrete_dividends[j] * math.exp(-r * ex_div_times[j]) for j in range(i)
+            )
+            S_adj_i = spot - pv_divs_before_i
+            price_at_t_i = self.bsm_solver.price_closed_form(
+                spot=S_adj_i, strike=strike, r=r, q=0, t=t_i, call=True
+            )
+            prices_early_exercise.append(price_at_t_i)
+
+        max_early_price = max(prices_early_exercise) if prices_early_exercise else 0.0
+        return max(price_hold_to_maturity, max_early_price)
+
+    def _cf_impl(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _sde_impl(self) -> Any:
+        raise NotImplementedError
+
+    def _pde_impl(self) -> Any:
+        raise NotImplementedError

quantfin/models/bsm.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from scipy.stats import norm
+
+from quantfin.models.base import CF, BaseModel, ParamValidator, PDECoeffs
+
+__doc__ = """
+Defines the Black-Scholes-Merton (BSM) model for pricing European options.
+"""
+
+
+class BSMModel(BaseModel):
+    """
+    Black-Scholes-Merton (BSM) model for pricing European options.
+
+    This model assumes the underlying asset follows a geometric Brownian motion
+    with constant volatility and risk-free rate.
+    """
+
+    name: str = "Black-Scholes-Merton"
+    supports_cf: bool = True
+    supports_sde: bool = True
+    supports_pde: bool = True
+    has_closed_form: bool = True
+
+    default_params = {"sigma": 0.2}
+    param_defs = {
+        "sigma": {
+            "label": "Volatility",
+            "default": 0.2,
+            "min": 0.01,
+            "max": 2.0,
+            "step": 0.01,
+        }
+    }
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the BSM model.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary of model parameters. If None, `default_params` are used.
+            Must contain 'sigma'.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        """Validate the 'sigma' parameter."""
+        ParamValidator.require(self.params, ["sigma"], model=self.name)
+        ParamValidator.positive(self.params, ["sigma"], model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, BSMModel):
+            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,
+        r: float,
+        q: float,
+        t: float,
+        call: bool = True,
+    ) -> float:
+        """
+        Computes the Black-Scholes-Merton price in closed form.
+
+        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.
+        """
+        sigma = self.params["sigma"]
+        sqrt_t = np.sqrt(t)
+        d1 = (np.log(spot / strike) + (r - q + 0.5 * sigma**2) * t) / (sigma * sqrt_t)
+        d2 = d1 - sigma * sqrt_t
+
+        df_div = np.exp(-q * t)
+        df_rate = np.exp(-r * t)
+
+        if call:
+            price = spot * df_div * norm.cdf(d1) - strike * df_rate * norm.cdf(d2)
+        else:
+            price = strike * df_rate * norm.cdf(-d2) - spot * df_div * norm.cdf(-d1)
+        return price
+
+    def delta_analytic(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+        call: bool = True,
+    ) -> float:
+        """Analytic delta for the BSM model."""
+        sigma = self.params["sigma"]
+        d1 = (np.log(spot / strike) + (r - q + 0.5 * sigma**2) * t) / (
+            sigma * np.sqrt(t)
+        )
+        df_div = np.exp(-q * t)
+        return df_div * norm.cdf(d1) if call else -df_div * norm.cdf(-d1)
+
+    def gamma_analytic(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+    ) -> float:
+        """Analytic gamma for the BSM model."""
+        sigma = self.params["sigma"]
+        sqrt_t = np.sqrt(t)
+        d1 = (np.log(spot / strike) + (r - q + 0.5 * sigma**2) * t) / (sigma * sqrt_t)
+        df_div = np.exp(-q * t)
+        return df_div * norm.pdf(d1) / (spot * sigma * sqrt_t)
+
+    def vega_analytic(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+    ) -> float:
+        """Analytic vega for the BSM model."""
+        sigma = self.params["sigma"]
+        sqrt_t = np.sqrt(t)
+        d1 = (np.log(spot / strike) + (r - q + 0.5 * sigma**2) * t) / (sigma * sqrt_t)
+        return spot * np.exp(-q * t) * norm.pdf(d1) * sqrt_t
+
+    def theta_analytic(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+        call: bool = True,
+    ) -> float:
+        """Analytic theta for the BSM model."""
+        sigma = self.params["sigma"]
+        sqrt_t = np.sqrt(t)
+        d1 = (np.log(spot / strike) + (r - q + 0.5 * sigma**2) * t) / (sigma * sqrt_t)
+        d2 = d1 - sigma * sqrt_t
+        term1 = -spot * np.exp(-q * t) * norm.pdf(d1) * sigma / (2 * sqrt_t)
+        if call:
+            term2 = q * spot * np.exp(-q * t) * norm.cdf(d1)
+            term3 = -r * strike * np.exp(-r * t) * norm.cdf(d2)
+        else:
+            term2 = -q * spot * np.exp(-q * t) * norm.cdf(-d1)
+            term3 = r * strike * np.exp(-r * t) * norm.cdf(-d2)
+        return term1 + term2 + term3
+
+    def rho_analytic(
+        self,
+        *,
+        spot: float,
+        strike: float,
+        r: float,
+        q: float,
+        t: float,
+        call: bool = True,
+    ) -> float:
+        """Analytic rho for the BSM model."""
+        sigma = self.params["sigma"]
+        sqrt_t = np.sqrt(t)
+        d2 = (np.log(spot / strike) + (r - q - 0.5 * sigma**2) * t) / (sigma * sqrt_t)
+        df_rate = np.exp(-r * t)
+        return strike * t * df_rate * (norm.cdf(d2) if call else -norm.cdf(-d2))
+
+    def _cf_impl(
+        self,
+        *,
+        t: float,
+        spot: float,
+        r: float,
+        q: float,
+        **_,
+    ) -> CF:
+        """
+        Returns the characteristic function phi(u) 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.
+        """
+        sigma = self.params["sigma"]
+        drift = r - q - 0.5 * sigma**2
+
+        def phi(u: np.ndarray | complex) -> np.ndarray | complex:
+            mean_component = 1j * u * (np.log(spot) + drift * t)
+            variance_component = -0.5 * (u**2) * (sigma**2) * t
+            return np.exp(mean_component + variance_component)
+
+        return phi
+
+    def _sde_impl(self) -> Callable:
+        """Returns the Euler-Maruyama stepper for the BSM log-price process."""
+        sigma = self.params["sigma"]
+
+        def stepper(
+            log_s_t: np.ndarray, r: float, q: float, dt: float, dw_t: np.ndarray
+        ) -> np.ndarray:
+            drift = (r - q - 0.5 * sigma**2) * dt
+            diffusion = sigma * dw_t
+            return log_s_t + drift + diffusion
+
+        return stepper
+
+    def _pde_impl(self) -> PDECoeffs:
+        """Returns the Black-Scholes PDE coefficients."""
+        sigma = self.params["sigma"]
+
+        def coeffs(
+            S: np.ndarray, r: float, q: float
+        ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+            return sigma**2 * S**2, (r - q) * S, -r * np.ones_like(S)
+
+        return coeffs

quantfin/models/cev.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from quantfin.models.base import BaseModel, ParamValidator
+
+__doc__ = """
+Defines the Constant Elasticity of Variance (CEV) model.
+"""
+
+
+class CEVModel(BaseModel):
+    """Constant Elasticity of Variance (CEV) model."""
+
+    name: str = "CEV"
+    supports_sde: bool = True
+    has_exact_sampler: bool = True
+    default_params = {"sigma": 0.8, "gamma": 0.7}
+
+    def __init__(self, params: dict[str, float] | None = None):
+        """
+        Initializes the CEV model.
+
+        Parameters
+        ----------
+        params : dict[str, float] | None, optional
+            A dictionary of model parameters. If None, `default_params` are used.
+            Must contain 'sigma' and 'gamma'. Defaults to None.
+        """
+        super().__init__(params or self.default_params)
+
+    def _validate_params(self) -> None:
+        """Validates that 'sigma' and 'gamma' are present and positive."""
+        p = self.params
+        req = ["sigma", "gamma"]
+        ParamValidator.require(p, req, model=self.name)
+        ParamValidator.positive(p, ["sigma"], model=self.name)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CEVModel):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        return hash((self.__class__, tuple(sorted(self.params.items()))))
+
+    def sample_terminal_spot(
+        self,
+        S0: float,
+        r: float,
+        T: float,
+        size: int,
+    ) -> np.ndarray:
+        """
+        Exact simulation of the terminal spot price via Non-Central Chi-Squared.
+
+        This method provides a way to sample directly from the terminal
+        distribution of the CEV process, which is more efficient than
+        path-based simulation for pricing European options.
+
+        Parameters
+        ----------
+        S0 : float
+            The initial spot price of the asset.
+        r : float
+            The continuously compounded risk-free rate.
+        T : float
+            The time to maturity, in years.
+        size : int
+            The number of samples to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of simulated terminal spot prices.
+        """
+        from scipy.stats import ncx2
+
+        p = self.params
+        sigma, gamma = p["sigma"], p["gamma"]
+
+        # Handle the boundary case where gamma -> 1 (which is BSM)
+        if abs(1.0 - gamma) < 1e-6:
+            drift = (r - 0.5 * sigma**2) * T
+            diffusion = sigma * np.sqrt(T) * np.random.standard_normal(size)  # noqa: NPY002
+            return S0 * np.exp(drift + diffusion)
+
+        df = 2 + 2 / (1 - gamma)
+        k = 2 * r / (sigma**2 * (1 - gamma) * (np.exp(r * (1 - gamma) * T) - 1))
+        nc = k * S0 ** (2 * (1 - gamma)) * np.exp(-r * (1 - gamma) * T)
+
+        chi2_draws = ncx2.rvs(df=df, nc=nc, size=size)
+        ST = (chi2_draws / k) ** (1 / (2 * (1 - gamma)))
+        return ST
+
+    #  Abstract Method Implementations
+    def _sde_impl(self, **kwargs: Any) -> Any:
+        raise NotImplementedError("CEV uses a specialized exact sampler.")
+
+    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