optPricing 2.0.0__py3-none-any.whl

quantfin/calibration/calibrator.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize, minimize_scalar
+
+from quantfin.atoms import Option, OptionType, Rate, Stock
+from quantfin.models import BaseModel
+
+from .technique_selector import select_fastest_technique
+
+__doc__ = """
+Defines the main Calibrator class used to fit financial models to market data.
+"""
+
+
+class Calibrator:
+    """
+    A generic class for calibrating financial models to market data.
+
+    This class orchestrates the process of finding the model parameters that
+    minimize the difference between model prices and observed market prices.
+    """
+
+    def __init__(
+        self,
+        model: BaseModel,
+        market_data: pd.DataFrame,
+        stock: Stock,
+        rate: Rate,
+    ):
+        """
+        Initializes the Calibrator.
+
+        Parameters
+        ----------
+        model : BaseModel
+            The financial model to be calibrated (e.g., HestonModel).
+        market_data : pd.DataFrame
+            A DataFrame containing market prices of options. Must include
+            'strike', 'maturity', 'optionType', and 'marketPrice' columns.
+        stock : Stock
+            The underlying asset's properties.
+        rate : Rate
+            The risk-free rate structure.
+        """
+        self.model = model
+        self.market_data = market_data
+        self.stock = stock
+        self.rate = rate
+        self.technique = select_fastest_technique(model)
+        _class_name = self.technique.__class__.__name__
+        print(f"Calibrator using '{_class_name}' for model '{model.name}'.")
+
+    def _objective_function(
+        self,
+        params_to_fit_values: np.ndarray,
+        params_to_fit_names: list[str],
+        frozen_params: dict[str, float],
+    ) -> float:
+        """The objective function to be minimized, calculating total squared error."""
+        current_params = {
+            **frozen_params,
+            **dict(zip(params_to_fit_names, params_to_fit_values)),
+        }
+        print(
+            f"  Trying params: { {k: f'{v:.4f}' for k, v in current_params.items()} }",
+            end="",
+        )
+        try:
+            temp_model = self.model.with_params(**current_params)
+        except ValueError as e:
+            print(f" -> Invalid params ({e}), returning large error.")
+            return 1e12
+
+        # Vectorized pricing for speed
+        # assumes the technique supports vectorized pricing.
+        # For now, fall back to iterating, but this is where future optimization lies.
+        total_error = 0.0
+        for _, row in self.market_data.iterrows():
+            option = Option(
+                strike=row["strike"],
+                maturity=row["maturity"],
+                option_type=OptionType.CALL
+                if row["optionType"] == "call"
+                else OptionType.PUT,
+            )
+            model_price = self.technique.price(
+                option, self.stock, temp_model, self.rate, **current_params
+            ).price
+            total_error += (model_price - row["marketPrice"]) ** 2
+
+        print(f"  --> Total Error: {total_error:.4f}")
+        return total_error
+
+    def fit(
+        self,
+        initial_guess: dict[str, float],
+        bounds: dict[str, tuple],
+        frozen_params: dict[str, float] = None,
+    ) -> dict[str, float]:
+        """
+        Performs the calibration using an optimization algorithm.
+
+        This method uses `scipy.optimize.minimize` (or `minimize_scalar` for
+        a single parameter) to find the optimal set of parameters that
+        minimizes the objective function.
+
+        Parameters
+        ----------
+        initial_guess : dict[str, float]
+            A dictionary of initial guesses for the parameters to be fitted.
+        bounds : dict[str, tuple]
+            A dictionary mapping parameter names to their (min, max) bounds.
+        frozen_params : dict[str, float] | None, optional
+            A dictionary of parameters to hold constant during the optimization.
+            Defaults to None.
+
+        Returns
+        -------
+        dict[str, float]
+            A dictionary containing the full set of calibrated and frozen parameters.
+        """
+        frozen_params = frozen_params or {}
+        params_to_fit_names = [p for p in initial_guess if p not in frozen_params]
+        print(f"Fitting parameters: {params_to_fit_names}")
+        if not params_to_fit_names:
+            return frozen_params
+
+        fit_bounds = [bounds.get(p) for p in params_to_fit_names]
+        initial_values = [initial_guess[p] for p in params_to_fit_names]
+
+        if len(params_to_fit_names) == 1:
+            # scalar minimizer for one parameter
+            res = minimize_scalar(
+                lambda x: self._objective_function(
+                    np.array([x]), params_to_fit_names, frozen_params
+                ),
+                bounds=fit_bounds[0],
+                method="bounded",
+            )
+            final_params = {**frozen_params, params_to_fit_names[0]: res.x}
+            print(f"Scalar optimization finished. Final loss: {res.fun:.6f}")
+        else:
+            # gradient-based optimizer for multiple parameters
+            res = minimize(
+                fun=self._objective_function,
+                x0=initial_values,
+                args=(params_to_fit_names, frozen_params),
+                method="L-BFGS-B",
+                bounds=fit_bounds,
+            )
+            final_params = {**frozen_params, **dict(zip(params_to_fit_names, res.x))}
+            print(f"Multivariate optimization finished. Final loss: {res.fun:.6f}")
+        return final_params

quantfin/calibration/fit_jump_parameters.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+__doc__ = """
+Provides a utility function to estimate jump parameters from historical data.
+"""
+
+
+def fit_jump_params_from_history(
+    log_returns: pd.Series,
+    threshold_stds: float = 3.0,
+) -> dict:
+    """
+    Estimates jump parameters and diffusion volatility from historical returns.
+
+    This function separates historical log returns into a "diffusion" component
+    (normal daily movements) and a "jump" component (extreme movements) based
+    on a standard deviation threshold. It then calculates the annualized
+    parameters for a jump-diffusion model like Merton's.
+
+    Parameters
+    ----------
+    log_returns : pd.Series
+        A pandas Series of daily log returns.
+    threshold_stds : float, optional
+        The number of standard deviations to use as a threshold for identifying
+        jumps, by default 3.0.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the estimated parameters: 'sigma', 'lambda',
+        'mu_j', and 'sigma_j'.
+    """
+    print("Fitting jump parameters from historical returns...")
+
+    std_dev = log_returns.std()
+    jump_threshold = threshold_stds * std_dev
+
+    diffusion_returns = log_returns[abs(log_returns) < jump_threshold]
+    jump_returns = log_returns[abs(log_returns) >= jump_threshold]
+
+    # Annualize daily std dev by multiplying by sqrt(252 trading days)
+    sigma_est = diffusion_returns.std() * np.sqrt(252)
+
+    if len(jump_returns) > 2:
+        lambda_est = len(jump_returns) / len(log_returns) * 252
+        mu_j_est = jump_returns.mean()
+        sigma_j_est = jump_returns.std()
+    else:
+        lambda_est, mu_j_est, sigma_j_est = 0.1, 0.0, 0.0
+        print("  -> Warning: Not enough jumps detected. Using default jump parameters.")
+
+    # Use the key 'sigma' to match the parameter name in the Merton/Kou models.
+    fitted_params = {
+        "sigma": sigma_est,
+        "lambda": lambda_est,
+        "mu_j": mu_j_est,
+        "sigma_j": sigma_j_est,
+    }
+
+    formatted = ", ".join(f"{k}: {v:.4f}" for k, v in fitted_params.items())
+    print(f"  -> Estimated Historical Params: {{{formatted}}}")
+    return fitted_params

quantfin/calibration/fit_market_params.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize
+
+__doc__ = """
+Provides utility functions to fit market-implied parameters like the
+risk-free rate and dividend yield from option prices using put-call parity.
+"""
+
+
+def find_atm_options(
+    calls: pd.DataFrame,
+    puts: pd.DataFrame,
+    spot: float,
+) -> pd.DataFrame:
+    """
+    Finds the closest at-the-money (ATM) call-put pair for each expiry.
+
+    Parameters
+    ----------
+    calls : pd.DataFrame
+        A DataFrame of call options.
+    puts : pd.DataFrame
+        A DataFrame of put options.
+    spot : float
+        The current spot price of the underlying.
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame containing the merged ATM call-put pairs.
+    """
+    merged = pd.merge(
+        calls, puts, on=["strike", "maturity"], suffixes=("_call", "_put"), how="inner"
+    )
+    if merged.empty:
+        return pd.DataFrame()
+    merged["moneyness_dist"] = abs(merged["strike"] - spot)
+    atm_indices = merged.groupby("maturity")["moneyness_dist"].idxmin()
+    return merged.loc[atm_indices]
+
+
+def fit_rate_and_dividend(
+    calls: pd.DataFrame,
+    puts: pd.DataFrame,
+    spot: float,
+    r_fixed: float | None = None,
+    q_fixed: float | None = None,
+) -> tuple[float, float]:
+    """
+    Fits the risk-free rate (r) and dividend yield (q) from put-call parity.
+
+    This function uses the prices of at-the-money (ATM) call-put pairs to
+    solve for the `r` and `q` that minimize the parity pricing error.
+    Parameters can be held fixed or fitted.
+
+    Parameters
+    ----------
+    calls : pd.DataFrame
+        A DataFrame of call options with 'strike', 'maturity', 'marketPrice'.
+    puts : pd.DataFrame
+        A DataFrame of put options with 'strike', 'maturity', 'marketPrice'.
+    spot : float
+        The current spot price of the underlying.
+    r_fixed : float | None, optional
+        If provided, the risk-free rate is held fixed at this value.
+        Defaults to None.
+    q_fixed : float | None, optional
+        If provided, the dividend yield is held fixed at this value.
+        Defaults to None.
+
+    Returns
+    -------
+    tuple[float, float]
+        A tuple containing the estimated (or fixed) risk-free rate and dividend yield.
+    """
+    atm_pairs = find_atm_options(calls, puts, spot)
+    if atm_pairs.empty:
+        print("Warning: No ATM pairs found. Using default r=0.05, q=0.0.")
+        return 0.05, 0.0
+
+    free_param_indices, initial_guess, bounds = [], [], []
+    if r_fixed is None:
+        free_param_indices.append(0)
+        initial_guess.append(0.05)
+        bounds.append((0.0, 0.15))
+    if q_fixed is None:
+        free_param_indices.append(1)
+        initial_guess.append(0.01)
+        bounds.append((0.0, 0.10))
+
+    if not free_param_indices:
+        return r_fixed, q_fixed
+
+    def parity_error(x: np.ndarray) -> float:
+        r = r_fixed if 0 not in free_param_indices else x[free_param_indices.index(0)]
+        q = q_fixed if 1 not in free_param_indices else x[free_param_indices.index(1)]
+        parity_rhs = spot * np.exp(-q * atm_pairs["maturity"]) - atm_pairs[
+            "strike"
+        ] * np.exp(-r * atm_pairs["maturity"])
+        parity_lhs = atm_pairs["marketPrice_call"] - atm_pairs["marketPrice_put"]
+        return np.sum((parity_lhs - parity_rhs) ** 2)
+
+    solution = minimize(
+        fun=parity_error, x0=initial_guess, bounds=bounds, method="L-BFGS-B"
+    )
+    r_est = (
+        r_fixed
+        if 0 not in free_param_indices
+        else solution.x[free_param_indices.index(0)]
+    )
+    q_est = (
+        q_fixed
+        if 1 not in free_param_indices
+        else solution.x[free_param_indices.index(1)]
+    )
+    print(f"Fitted market params -> r: {r_est:.4f}, q: {q_est:.4f}")
+    return float(r_est), float(q_est)

quantfin/calibration/iv_surface.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from quantfin.atoms import Option, OptionType, Rate, Stock
+from quantfin.models import BaseModel
+from quantfin.techniques.base import BaseTechnique
+
+from .vectorized_bsm_iv import BSMIVSolver
+
+__doc__ = """
+Defines the VolatilitySurface class, used to compute and store implied
+volatility surfaces from both market and model prices.
+"""
+
+
+class VolatilitySurface:
+    """
+    A class to compute and hold market and model-implied volatility surfaces.
+
+    This class takes a DataFrame of option market data and provides methods
+    to calculate the Black-Scholes implied volatility (IV) for each option,
+    either from its market price or from a price generated by a financial model.
+    """
+
+    def __init__(self, option_data: pd.DataFrame):
+        """
+        Initializes the VolatilitySurface.
+
+        Parameters
+        ----------
+        option_data : pd.DataFrame
+            A DataFrame containing market prices of options. Must include
+            'strike', 'maturity', 'marketPrice', 'optionType', and 'expiry' columns.
+
+        Raises
+        ------
+        ValueError
+            If any of the required columns are missing from `option_data`.
+        """
+        required_cols = ["strike", "maturity", "marketPrice", "optionType", "expiry"]
+        if not all(col in option_data.columns for col in required_cols):
+            msg = (
+                "Input option_data is missing one "
+                f"of the required columns: {required_cols}"
+            )
+            raise ValueError(msg)
+
+        self.data = option_data[required_cols].copy()
+        self.surface: pd.DataFrame | None = None
+        self.iv_solver = BSMIVSolver()
+
+    def _calculate_ivs(
+        self,
+        stock: Stock,
+        rate: Rate,
+        prices_to_invert: pd.Series,
+    ) -> np.ndarray:
+        """Calculates IVs using the fast, vectorized BSM solver."""
+        ivs = self.iv_solver.solve(prices_to_invert.values, self.data, stock, rate)
+        return ivs
+
+    def calculate_market_iv(
+        self,
+        stock: Stock,
+        rate: Rate,
+    ) -> VolatilitySurface:
+        """
+        Calculates the market implied volatility surface from market prices.
+
+        This method inverts the Black-Scholes formula for each option's market
+        price to find the corresponding implied volatility. The results are
+        stored in the `self.surface` DataFrame.
+
+        Parameters
+        ----------
+        stock : Stock
+            The underlying asset's properties.
+        rate : Rate
+            The risk-free rate structure.
+
+        Returns
+        -------
+        VolatilitySurface
+            The same instance of the class, allowing for method chaining.
+        """
+        print("Calculating market implied volatility surface...")
+        market_ivs = self._calculate_ivs(stock, rate, self.data["marketPrice"])
+        self.surface = self.data.copy()
+        self.surface["iv"] = market_ivs
+        self.surface.dropna(inplace=True)
+        self.surface = self.surface[
+            (self.surface["iv"] > 1e-4) & (self.surface["iv"] < 2.0)
+        ]
+        return self
+
+    def calculate_model_iv(
+        self,
+        stock: Stock,
+        rate: Rate,
+        model: BaseModel,
+        technique: BaseTechnique,
+    ) -> VolatilitySurface:
+        """
+        Calculates a model's implied volatility surface.
+
+        This method first prices every option in the dataset using the provided
+        model and technique. It then inverts the Black-Scholes formula for each
+        of these model prices to generate the model-implied volatility surface.
+
+        Parameters
+        ----------
+        stock : Stock
+            The underlying asset's properties.
+        rate : Rate
+            The risk-free rate structure.
+        model : BaseModel
+            The financial model to generate prices from.
+        technique : BaseTechnique
+            The pricing technique to use with the model.
+
+        Returns
+        -------
+        VolatilitySurface
+            The same instance of the class, allowing for method chaining.
+        """
+        print(f"Calculating {model.name} implied volatility surface...")
+
+        model_prices = np.array(
+            [
+                technique.price(
+                    Option(
+                        strike=row.strike,
+                        maturity=row.maturity,
+                        option_type=OptionType.CALL
+                        if row.optionType == "call"
+                        else OptionType.PUT,
+                    ),
+                    stock,
+                    model,
+                    rate,
+                    **model.params,
+                ).price
+                for _, row in self.data.iterrows()
+            ]
+        )
+
+        model_ivs = self._calculate_ivs(
+            stock, rate, pd.Series(model_prices, index=self.data.index)
+        )
+        self.surface = self.data.copy()
+        self.surface["iv"] = model_ivs
+        self.surface.dropna(inplace=True)
+        return self

quantfin/calibration/technique_selector.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from quantfin.models.base import BaseModel
+from quantfin.techniques.closed_form import ClosedFormTechnique
+from quantfin.techniques.fft import FFTTechnique
+from quantfin.techniques.monte_carlo import MonteCarloTechnique
+
+__doc__ = """
+Provides a utility function to select the most efficient pricing technique
+for a given financial model based on its supported features.
+"""
+
+
+def select_fastest_technique(model: BaseModel):
+    """
+    Selects the fastest available pricing technique for a given model.
+
+    The function checks the capabilities of the model in a specific order of
+    preference, which generally corresponds to computational speed.
+
+    The order of preference is:
+    1. Closed-Form
+    2. Fast Fourier Transform (FFT)
+    3. Monte Carlo
+
+    Parameters
+    ----------
+    model : BaseModel
+        The financial model for which to select a technique.
+
+    Returns
+    -------
+    BaseTechnique
+        An instance of the fastest suitable pricing technique.
+
+    Raises
+    ------
+    TypeError
+        If no suitable pricing technique can be found for the model.
+    """
+    if model.has_closed_form:
+        return ClosedFormTechnique()
+    if model.supports_cf:
+        return FFTTechnique(n=12)
+    if model.supports_sde:
+        return MonteCarloTechnique(n_paths=5000, n_steps=50, antithetic=True)
+    raise TypeError(f"No suitable pricing technique found for model '{model.name}'")

quantfin/calibration/vectorized_bsm_iv.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.stats import norm
+
+from quantfin.atoms import Rate, Stock
+
+__doc__ = """
+Defines a high-performance, vectorized solver for Black-Scholes-Merton
+implied volatility.
+"""
+
+
+class BSMIVSolver:
+    """
+    High-performance, vectorized Newton-Raphson solver for BSM implied volatility.
+
+    This solver is designed to calculate the implied volatility for a large
+    number of options simultaneously, leveraging NumPy for vectorized operations.
+    """
+
+    def __init__(
+        self,
+        max_iter: int = 20,
+        tolerance: float = 1e-6,
+    ):
+        """
+        Initializes the BSM implied volatility solver.
+
+        Parameters
+        ----------
+        max_iter : int, optional
+            The maximum number of iterations for the Newton-Raphson method,
+            by default 20.
+        tolerance : float, optional
+            The error tolerance to determine convergence, by default 1e-6.
+        """
+        self.max_iter = max_iter
+        self.tolerance = tolerance
+
+    def solve(
+        self,
+        target_prices: np.ndarray,
+        options: pd.DataFrame,
+        stock: Stock,
+        rate: Rate,
+    ) -> np.ndarray:
+        """
+        Calculates implied volatility for an array of options.
+
+        Parameters
+        ----------
+        target_prices : np.ndarray
+            An array of market prices for which to find the implied volatility.
+        options : pd.DataFrame
+            A DataFrame of option contracts, must include 'strike', 'maturity',
+            and 'optionType' columns.
+        stock : Stock
+            The underlying asset's properties.
+        rate : Rate
+            The risk-free rate structure.
+
+        Returns
+        -------
+        np.ndarray
+            An array of calculated implied volatilities corresponding to the
+            target prices.
+        """
+        S, q = stock.spot, stock.dividend
+        K, T = options["strike"].values, options["maturity"].values
+        r = rate.get_rate(T)  # Use get_rate for term structure
+        is_call = options["optionType"].values == "call"
+        iv = np.full_like(target_prices, 0.20)
+
+        for _ in range(self.max_iter):
+            with np.errstate(all="ignore"):
+                sqrt_T = np.sqrt(T)
+                d1 = (np.log(S / K) + (r - q + 0.5 * iv**2) * T) / (iv * sqrt_T)
+                d2 = d1 - iv * sqrt_T
+                vega = S * np.exp(-q * T) * sqrt_T * norm.pdf(d1)
+                call_prices = S * np.exp(-q * T) * norm.cdf(d1) - K * np.exp(
+                    -r * T
+                ) * norm.cdf(d2)
+                put_prices = K * np.exp(-r * T) * norm.cdf(-d2) - S * np.exp(
+                    -q * T
+                ) * norm.cdf(-d1)
+            model_prices = np.where(is_call, call_prices, put_prices)
+            error = model_prices - target_prices
+            if np.all(np.abs(error) < self.tolerance):
+                break
+            iv = iv - error / np.maximum(vega, 1e-8)
+        return iv