voly 0.0.166__tar.gz → 0.0.167__tar.gz

{voly-0.0.166/src/voly.egg-info → voly-0.0.167}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voly
-Version: 0.0.166
+Version: 0.0.167
 Summary: Options & volatility research package
 Author-email: Manu de Cara <manu.de.cara@gmail.com>
 License: MIT

{voly-0.0.166 → voly-0.0.167}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voly"
-version = "0.0.166"
+version = "0.0.167"
 description = "Options & volatility research package"
 readme = "README.md"
 authors = [
@@ -60,7 +60,7 @@ line_length = 100
 multi_line_output = 3
 
 [tool.mypy]
-python_version = "0.0.166"
+python_version = "0.0.167"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{voly-0.0.166 → voly-0.0.167}/src/voly/client.py

@@ -165,29 +165,24 @@ class VolyClient:
 
     @staticmethod
     def fit_model(option_chain: pd.DataFrame,
-                  model_name: str = 'svi',
-                  initial_params: Optional[List[float]] = None,
-                  param_bounds: Optional[Tuple] = None) -> Dict[str, Any]:
+                  domain_params: Tuple[float, float, int] = (-2, 2, 500)
+                  ) -> Dict[str, Any]:
         """
         Fit a volatility model to market data.
 
         Parameters:
         - option_chain: DataFrame with option market data
-        - model_name: Name of model to fit (default: 'svi')
-        - initial_params: Optional initial parameters for optimization
-        - param_bounds: Optional parameter bounds for optimization
+        - domain_params: Tuple of (min, max, num_points) for the moneyness grid
 
         Returns:
-        - Tuple of (fit_results, fit_performance)
+        - Dataframe with fit_results
         """
-        logger.info(f"Fitting {model_name.upper()} model to market data")
+        logger.info(f"Fitting model to market data.")
 
         # Fit the model
         fit_results = fit_model(
             option_chain=option_chain,
-            model_name=model_name,
-            initial_params=initial_params,
-            param_bounds=param_bounds
+            domain_params=domain_params
         )
 
         return fit_results

{voly-0.0.166 → voly-0.0.167}/src/voly/core/charts.py

@@ -139,7 +139,7 @@ def plot_raw_parameters(fit_results: pd.DataFrame) -> go.Figure:
     - Plotly figure
     """
     # Select parameters to plot
-    param_names = ['a', 'b', 'sigma', 'rho', 'm']
+    param_names = ['a', 'b', 'm', 'rho', 'sigma']
 
     # Create subplots
     fig = make_subplots(

{voly-0.0.166 → voly-0.0.167}/src/voly/core/data.py

@@ -259,7 +259,7 @@ def process_order_book_depth(option_chain, max_depth=5):
         s = row['underlying_price']
         k = row['strikes']
         t = row['t']
-        r = row['interest_rate'] if 'interest_rate' in row else 0.0
+        r = row['r'] if 'r' in row else 0.0
         option_type = 'C' if row['option_type'] == 'call' else 'P'
 
         # Process bid side

voly-0.0.167/src/voly/core/fit.py

@@ -0,0 +1,427 @@
+"""
+Model fitting and calibration module for the Voly package.
+
+This module handles fitting volatility models to market data and
+calculating fitting statistics.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import List, Tuple, Dict, Optional, Union, Any
+from scipy.optimize import least_squares
+from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
+from voly.utils.logger import logger, catch_exception
+from voly.formulas import get_domain
+from voly.exceptions import VolyError
+from voly.models import SVIModel
+import warnings
+
+warnings.filterwarnings("ignore")
+
+
+@catch_exception
+def fit_model(option_chain: pd.DataFrame,
+              domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000)) -> pd.DataFrame:
+    """
+    Fit Voly's volatility model to market data.
+
+    Parameters:
+    - option_chain: DataFrame with market data
+    - domain_params : Tuple[float, float, int]
+        (min_log_moneyness, max_log_moneyness, num_points)
+
+    Returns:
+    - DataFrame with all fit results and performance metrics as columns, maturity_names as index
+    """
+
+    # Define column names and their data types
+    column_dtypes = {
+        's': float,
+        't': float,
+        'r': float,
+        'maturity_date': 'datetime64[ns]',
+        'a': float,
+        'b': float,
+        'm': float,
+        'rho': float,
+        'sigma': float,
+        'nu': float,
+        'psi': float,
+        'p': float,
+        'c': float,
+        'nu_tilde': float,
+        'log_min_strike': float,
+        'usd_min_strike': float,
+        'fit_success': bool,
+        'butterfly_arbitrage_free': bool,
+        'calendar_arbitrage_free': bool,
+        'loss': float,
+        'rmse': float,
+        'mae': float,
+        'r2': float,
+        'max_error': float,
+        'n_points': int
+    }
+
+    # Get unique maturities and sort them
+    unique_ts = sorted(option_chain['t'].unique())
+    maturity_names = [option_chain[option_chain['t'] == t]['maturity_name'].iloc[0] for t in unique_ts]
+
+    # Store results in a dictionary first
+    results_data = {col: [] for col in column_dtypes.keys()}
+
+    # ANSI color codes for terminal output
+    GREEN, RED, RESET = '\033[32m', '\033[31m', '\033[0m'
+
+    s = option_chain['index_price'].iloc[-1]
+
+    # Dictionary to track fit results by maturity for arbitrage checks
+    fit_params_dict = {}
+
+    # First pass: Fit each maturity
+    for t in unique_ts:
+        # Get data for this maturity
+        maturity_data = option_chain[option_chain['t'] == t]
+        maturity_name = maturity_data['maturity_name'].iloc[0]
+        maturity_date = maturity_data['maturity_date'].iloc[0]
+
+        logger.info(f"Optimizing for {maturity_name}...")
+
+        # Extract data for fitting
+        k = maturity_data['log_moneyness'].values
+        iv = maturity_data['mark_iv'].values
+        vega = maturity_data['vega'].values if 'vega' in maturity_data else np.ones_like(iv)
+
+        # Apply mask to filter out invalid data
+        mask = ~np.isnan(iv) & ~np.isnan(k) & (iv > 0)
+        k_masked, iv_masked, vega_masked = k[mask], iv[mask], vega[mask]
+
+        # Check if we have enough valid points
+        if len(k_masked) <= 5:
+            logger.warning(f"Not enough valid data points for {maturity_name}, skipping.")
+            params = [np.nan] * 5
+            loss = np.inf
+        else:
+            # Calculate total implied variance (w = iv² * t)
+            w = (iv_masked ** 2) * t
+
+            # Fit using the improved SVI method
+            params, loss = SVIModel.fit(tiv=w, vega=vega_masked, k=k_masked, tau=t)
+
+        # Store the parameters for this maturity
+        fit_params_dict[maturity_date] = (t, params)
+
+        # Extract parameters (will be nan if fit failed)
+        a, b, m, rho, sigma = params
+
+        # Calculate statistics
+        fit_success = not np.isnan(a)
+        butterfly_arbitrage_free = True
+        calendar_arbitrage_free = True  # Will check later
+
+        # Initialize default metrics
+        rmse = mae = r2 = max_error = np.nan
+        nu = psi = p = c = nu_tilde = np.nan
+        log_min_strike = usd_min_strike = np.nan
+        a_scaled = b_scaled = np.nan
+
+        if fit_success:
+            # Scale a and b by t
+            a_scaled, b_scaled = a * t, b * t
+
+            # Calculate Jump-Wing parameters
+            nu, psi, p, c, nu_tilde = SVIModel.raw_to_jw_params(a_scaled, b_scaled, m, rho, sigma, t)
+
+            # Calculate model predictions for statistics
+            w_model = np.array([SVIModel.svi(x, a_scaled, b_scaled, m, rho, sigma) for x in k_masked])
+            iv_model = np.sqrt(w_model / t)
+            iv_market = iv_masked
+
+            # Calculate statistics
+            rmse = np.sqrt(mean_squared_error(iv_market, iv_model))
+            mae = mean_absolute_error(iv_market, iv_model)
+            r2 = r2_score(iv_market, iv_model)
+            max_error = np.max(np.abs(iv_market - iv_model))
+
+            # Calculate minimum strike
+            log_min_strike = SVIModel.svi_min_strike(sigma, rho, m)
+            usd_min_strike = s * np.exp(-log_min_strike)  # Convert from log_moneyness to strike
+
+            # Check butterfly arbitrage
+            k_range = np.linspace(min(k_masked), max(k_masked), domain_params[2])
+            for k_val in k_range:
+                wk = SVIModel.svi(k_val, a_scaled, b_scaled, m, rho, sigma)
+                wp = SVIModel.svi_d(k_val, a_scaled, b_scaled, m, rho, sigma)
+                wpp = SVIModel.svi_dd(k_val, a_scaled, b_scaled, m, rho, sigma)
+                g = (1 - (k_val * wp) / (2 * wk)) ** 2 - (wp ** 2) / 4 * (1 / wk + 1 / 4) + wpp / 2
+                if g < 0:
+                    butterfly_arbitrage_free = False
+                    break
+
+        r = maturity_data['r'].iloc[0] if 'r' in maturity_data.columns else 0
+
+        # Store values in the results dictionary with proper types
+        results_data['s'].append(float(s))
+        results_data['t'].append(float(t))
+        results_data['r'].append(float(r))
+        results_data['maturity_date'].append(maturity_date)
+        results_data['a'].append(float(a_scaled) if fit_success else np.nan)
+        results_data['b'].append(float(b_scaled) if fit_success else np.nan)
+        results_data['sigma'].append(float(sigma) if fit_success else np.nan)
+        results_data['m'].append(float(m) if fit_success else np.nan)
+        results_data['rho'].append(float(rho) if fit_success else np.nan)
+        results_data['nu'].append(float(nu))
+        results_data['psi'].append(float(psi))
+        results_data['p'].append(float(p))
+        results_data['c'].append(float(c))
+        results_data['nu_tilde'].append(float(nu_tilde))
+        results_data['log_min_strike'].append(float(log_min_strike))
+        results_data['usd_min_strike'].append(float(usd_min_strike))
+        results_data['fit_success'].append(bool(fit_success))
+        results_data['butterfly_arbitrage_free'].append(bool(butterfly_arbitrage_free))
+        results_data['calendar_arbitrage_free'].append(bool(True))  # Will update in second pass
+        results_data['loss'].append(float(loss))
+        results_data['rmse'].append(float(rmse))
+        results_data['mae'].append(float(mae))
+        results_data['r2'].append(float(r2))
+        results_data['max_error'].append(float(max_error))
+        results_data['n_points'].append(int(len(k_masked)))
+
+        # Log result
+        status = f'{GREEN}SUCCESS{RESET}' if fit_success else f'{RED}FAILED{RESET}'
+        logger.info(f'Optimization for {maturity_name}: {status}')
+        logger.info('-------------------------------------')
+
+    # Create DataFrame with proper types
+    results_df = pd.DataFrame(results_data, index=maturity_names)
+
+    # Convert columns to appropriate types
+    for col, dtype in column_dtypes.items():
+        if col in results_df.columns:
+            try:
+                results_df[col] = results_df[col].astype(dtype)
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Could not convert column {col} to {dtype}: {e}")
+
+    # Second pass: Check and correct for calendar arbitrage
+    logger.info("Checking for calendar arbitrage...")
+    sorted_maturities = sorted(fit_params_dict.keys())
+    k_grid = np.linspace(domain_params[0], domain_params[1], domain_params[2])  # Grid for arbitrage checking
+
+    # Check calendar arbitrage before correction
+    calendar_arbitrage_free = True
+    for i in range(len(sorted_maturities) - 1):
+        mat1, mat2 = sorted_maturities[i], sorted_maturities[i + 1]
+        t1, params1 = fit_params_dict[mat1]
+        t2, params2 = fit_params_dict[mat2]
+        a1, b1, sigma1, rho1, m1 = params1
+        a2, b2, sigma2, rho2, m2 = params2
+
+        if np.isnan(a1) or np.isnan(a2):
+            continue
+
+        # Check arbitrage on a grid of points
+        for k_val in k_grid:
+            w1 = SVIModel.svi(k_val, a1 * t1, b1 * t1, m1, rho1, sigma1)
+            w2 = SVIModel.svi(k_val, a2 * t2, b2 * t2, m2, rho2, sigma2)
+            if w2 < w1 - 1e-6:
+                calendar_arbitrage_free = False
+                logger.warning(
+                    f"Calendar arbitrage detected between {sorted_maturities[i]} and {sorted_maturities[i + 1]}")
+                break
+
+    # Update results with calendar arbitrage status
+    for i, maturity_name in enumerate(maturity_names):
+        idx = results_df.index[i]
+        results_df.at[idx, 'calendar_arbitrage_free'] = calendar_arbitrage_free
+
+    # Correct calendar arbitrage if needed
+    if not calendar_arbitrage_free:
+        logger.info("Correcting calendar arbitrage...")
+        for i in range(1, len(sorted_maturities)):
+            mat1 = sorted_maturities[i - 1]
+            mat2 = sorted_maturities[i]
+            t1, params1 = fit_params_dict[mat1]
+            t2, params2 = fit_params_dict[mat2]
+
+            if np.isnan(params1[0]) or np.isnan(params2[0]):
+                continue
+
+            # Find the index in maturity_names that corresponds to mat2
+            maturity_idx = None
+            for j, maturity_name in enumerate(maturity_names):
+                if results_df.iloc[j]['maturity_date'] == mat2:
+                    maturity_idx = j
+                    break
+
+            if maturity_idx is None:
+                continue
+
+            # Get data for correction
+            idx = results_df.index[maturity_idx]
+            maturity_data = option_chain[option_chain['maturity_name'] == idx]
+            k = maturity_data['log_moneyness'].values
+            iv = maturity_data['mark_iv'].values
+            vega = maturity_data['vega'].values if 'vega' in maturity_data else np.ones_like(iv)
+
+            # Apply mask to filter out invalid data
+            mask = ~np.isnan(iv) & ~np.isnan(k) & (iv > 0)
+            k_masked, iv_masked, vega_masked = k[mask], iv[mask], vega[mask]
+
+            if len(k_masked) <= 5:
+                continue
+
+            # Calculate total implied variance
+            w = (iv_masked ** 2) * t2
+
+            # Apply calendar arbitrage correction
+            new_params = SVIModel.correct_calendar_arbitrage(
+                params=params2, t=t2, tiv=w, vega=vega_masked, k=k_masked,
+                prev_params=params1, prev_t=t1, k_grid=k_grid
+            )
+
+            # Update the parameters dictionary
+            fit_params_dict[mat2] = (t2, new_params)
+
+            # Extract corrected parameters
+            a, b, m, rho, sigma = new_params
+
+            # Calculate scaled parameters and Jump-Wing parameters
+            a_scaled, b_scaled = a * t2, b * t2
+            nu, psi, p, c, nu_tilde = SVIModel.raw_to_jw_params(a_scaled, b_scaled, m, rho, sigma, t2)
+
+            # Calculate model predictions for statistics
+            w_model = np.array([SVIModel.svi(x, a_scaled, b_scaled, m, rho, sigma) for x in k_masked])
+            iv_model = np.sqrt(w_model / t2)
+            iv_market = iv_masked
+
+            # Calculate statistics
+            rmse = np.sqrt(mean_squared_error(iv_market, iv_model))
+            mae = mean_absolute_error(iv_market, iv_model)
+            r2 = r2_score(iv_market, iv_model)
+            max_error = np.max(np.abs(iv_market - iv_model))
+
+            # Calculate minimum strike
+            log_min_strike = SVIModel.svi_min_strike(sigma, rho, m)
+            usd_min_strike = s * np.exp(-log_min_strike)
+
+            # Check butterfly arbitrage
+            butterfly_arbitrage_free = True
+            k_range = np.linspace(min(k_masked), max(k_masked), domain_params[2])
+            for k_val in k_range:
+                wk = SVIModel.svi(k_val, a_scaled, b_scaled, m, rho, sigma)
+                wp = SVIModel.svi_d(k_val, a_scaled, b_scaled, m, rho, sigma)
+                wpp = SVIModel.svi_dd(k_val, a_scaled, b_scaled, m, rho, sigma)
+                g = (1 - (k_val * wp) / (2 * wk)) ** 2 - (wp ** 2) / 4 * (1 / wk + 1 / 4) + wpp / 2
+                if g < 0:
+                    butterfly_arbitrage_free = False
+                    break
+
+            # Update results in the DataFrame
+            results_df.at[idx, 'a'] = float(a_scaled)
+            results_df.at[idx, 'b'] = float(b_scaled)
+            results_df.at[idx, 'm'] = float(m)
+            results_df.at[idx, 'rho'] = float(rho)
+            results_df.at[idx, 'sigma'] = float(sigma)
+            results_df.at[idx, 'nu'] = float(nu)
+            results_df.at[idx, 'psi'] = float(psi)
+            results_df.at[idx, 'p'] = float(p)
+            results_df.at[idx, 'c'] = float(c)
+            results_df.at[idx, 'nu_tilde'] = float(nu_tilde)
+            results_df.at[idx, 'log_min_strike'] = float(log_min_strike)
+            results_df.at[idx, 'usd_min_strike'] = float(usd_min_strike)
+            results_df.at[idx, 'butterfly_arbitrage_free'] = bool(butterfly_arbitrage_free)
+            results_df.at[idx, 'rmse'] = float(rmse)
+            results_df.at[idx, 'mae'] = float(mae)
+            results_df.at[idx, 'r2'] = float(r2)
+            results_df.at[idx, 'max_error'] = float(max_error)
+
+            logger.info(
+                f"SVI parameters for {idx}: a={a_scaled:.4f}, b={b_scaled:.4f}, sigma={sigma:.4f}, rho={rho:.4f}, m={m:.4f}")
+
+        # Check calendar arbitrage after correction
+        calendar_arbitrage_free = True
+        for i in range(len(sorted_maturities) - 1):
+            mat1, mat2 = sorted_maturities[i], sorted_maturities[i + 1]
+            t1, params1 = fit_params_dict[mat1]
+            t2, params2 = fit_params_dict[mat2]
+            a1, b1, sigma1, rho1, m1 = params1
+            a2, b2, sigma2, rho2, m2 = params2
+
+            if np.isnan(a1) or np.isnan(a2):
+                continue
+
+            # Check arbitrage on a grid of points
+            for k_val in k_grid:
+                w1 = SVIModel.svi(k_val, a1 * t1, b1 * t1, m1, rho1, sigma1)
+                w2 = SVIModel.svi(k_val, a2 * t2, b2 * t2, m2, rho2, sigma2)
+                if w2 < w1 - 1e-6:
+                    calendar_arbitrage_free = False
+                    logger.warning(f"Calendar arbitrage still detected between {mat1} and {mat2} after correction")
+                    break
+
+        # Update results with final calendar arbitrage status
+        for i, maturity_name in enumerate(maturity_names):
+            maturity_date = results_df.iloc[i]['maturity_date']
+            idx = results_df.index[i]
+            results_df.at[idx, 'calendar_arbitrage_free'] = calendar_arbitrage_free
+
+    logger.info("Model fitting complete.")
+    return results_df
+
+
+@catch_exception
+def get_iv_surface(model_results: pd.DataFrame,
+                   domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
+                   return_domain: str = 'log_moneyness') -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]:
+    """
+    Generate implied volatility surface using optimized SVI parameters.
+
+    Works with both regular fit_results and interpolated_results dataframes.
+
+    Parameters:
+    - model_results: DataFrame from fit_model() or interpolate_model(). Maturity names or DTM as Index
+    - domain_params: Tuple of (min, max, num_points) for the log-moneyness array
+    - return_domain: Domain for x-axis values ('log_moneyness', 'moneyness', 'returns', 'strikes', 'delta')
+
+    Returns:
+    - Tuple of (iv_surface, x_surface)
+      iv_surface: Dictionary mapping maturity/dtm names to IV arrays
+      x_surface: Dictionary mapping maturity/dtm names to requested x domain arrays
+    """
+    # Check if required columns are present
+    required_columns = ['a', 'b', 'm', 'rho', 'sigma', 't']
+    missing_columns = [col for col in required_columns if col not in model_results.columns]
+    if missing_columns:
+        raise VolyError(f"Required columns missing in model_results: {missing_columns}")
+
+    # Generate implied volatility surface in log-moneyness domain
+    LM = np.linspace(domain_params[0], domain_params[1], domain_params[2])
+
+    iv_surface = {}
+    x_surface = {}
+
+    # Process each maturity/dtm
+    for i in model_results.index:
+        # Calculate SVI total implied variance and convert to IV
+        params = [
+            model_results.loc[i, 'a'],
+            model_results.loc[i, 'b'],
+            model_results.loc[i, 'm'],
+            model_results.loc[i, 'rho'],
+            model_results.loc[i, 'sigma']
+        ]
+        s = model_results.loc[i, 's']
+        r = model_results.loc[i, 'r']
+        t = model_results.loc[i, 't']
+
+        # Calculate implied volatility
+        w = np.array([SVIModel.svi(x, *params) for x in LM])
+        o = np.sqrt(w / t)
+        iv_surface[i] = o
+
+        # Calculate x domain for this maturity/dtm
+        x = get_domain(domain_params, s, r, o, t, return_domain)
+        x_surface[i] = x
+
+    return iv_surface, x_surface

voly-0.0.167/src/voly/models.py

@@ -0,0 +1,217 @@
+"""
+Volatility models for the Voly package.
+"""
+
+import numpy as np
+from numpy.linalg import solve
+from scipy.optimize import minimize
+from typing import Tuple, Dict, List, Optional, Union
+
+
+class SVIModel:
+    """
+    Stochastic Volatility Inspired (SVI) model.
+
+    This class provides methods for calculating implied volatility using the
+    SVI parameterization, as well as its derivatives and related functions.
+    """
+
+    # Parameter names for reference
+    PARAM_NAMES = ['a', 'b', 'm', 'rho', 'sigma']
+    JW_PARAM_NAMES = ['nu', 'psi', 'p', 'c', 'nu_tilde']
+
+    # Parameter descriptions for documentation
+    PARAM_DESCRIPTIONS = {
+        'a': 'Base level of total implied variance',
+        'b': 'Volatility skewness/smile modulation (controls wing slopes)',
+        'sigma': 'Convexity control of the volatility smile (reduces ATM curvature)',
+        'rho': 'Skewness/slope of the volatility smile (-1 to 1, rotates smile)',
+        'm': 'Horizontal shift of the smile peak',
+        'nu': 'ATM variance (level of ATM volatility)',
+        'psi': 'ATM volatility skew (affects the gradient of the curve at ATM point)',
+        'p': 'Slope of put wing (left side of curve)',
+        'c': 'Slope of call wing (right side of curve)',
+        'nu_tilde': 'Minimum implied total variance',
+    }
+
+    @staticmethod
+    def svi_raw(k, a, b, m, rho, sigma):
+        assert b >= 0, 'b must be non-negative'
+        assert abs(rho) <= 1, '|rho| must be <= 1'
+        assert sigma >= 0, 'sigma must be non-negative'
+        assert a + b * sigma * sqrt(1 - rho ** 2) >= 0, 'a + b*sigma*sqrt(1-rho^2) must be non-negative'
+        return a + b * (rho * (k - m) + sqrt((k - m) ** 2 + sigma ** 2))
+
+    @staticmethod
+    def svi(LM: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
+        return a + b * (rho * (LM - m) + np.sqrt((LM - m) ** 2 + sigma ** 2))
+
+    @staticmethod
+    def raw_to_jw_params(a: float, b: float, m: float, rho: float, sigma: float, t: float) -> Tuple[
+        float, float, float, float, float]:
+        nu = (a + b * ((-rho) * m + np.sqrt(m ** 2 + sigma ** 2))) / t
+        psi = (1 / np.sqrt(nu * t)) * (b / 2) * (rho - (m / np.sqrt(m ** 2 + sigma ** 2)))
+        p = (1 / np.sqrt(nu * t)) * b * (1 - rho)
+        c = (1 / np.sqrt(nu * t)) * b * (1 + rho)
+        nu_tilde = (1 / t) * (a + b * sigma * np.sqrt(1 - rho ** 2))
+        return nu, psi, p, c, nu_tilde
+
+    @classmethod
+    def calibration(cls, tiv, vega, k, m, sigma):
+        """
+        Calibrate SVI parameters using a more stable approach.
+
+        Parameters:
+        - tiv: Total implied variance values
+        - vega: Option vega values (for weighting)
+        - k: Log-moneyness values
+        - m: Horizontal shift parameter
+        - sigma: Convexity parameter
+
+        Returns:
+        - c, d, a: Calibrated parameters
+        - loss: Calibration loss value
+        """
+        sigma = max(sigma, 0.001)
+        vega = vega / vega.max() if vega.max() > 0 else np.ones_like(vega)
+        y = (k - m) / sigma
+        w = vega.mean()
+        y1 = (vega * y).mean()
+        y2 = (vega * y * y).mean()
+        y3 = (vega * np.sqrt(y * y + 1)).mean()
+        y4 = (vega * y * np.sqrt(y * y + 1)).mean()
+        y5 = (vega * (y * y + 1)).mean()
+        vy2 = (vega * tiv * np.sqrt(y * y + 1)).mean()
+        vy = (vega * tiv * y).mean()
+        v = (vega * tiv).mean()
+
+        matrix = [[y5, y4, y3], [y4, y2, y1], [y3, y1, w]]
+        vector = [vy2, vy, v]
+        c, d, a = solve(np.array(matrix), np.array(vector))
+
+        c = np.clip(c, 0, 4 * sigma)
+        a = max(a, 1e-6)
+        d = np.clip(d, -min(c, 4 * sigma - c), min(c, 4 * sigma - c))
+
+        loss = cls.loss(tiv, vega, y, c, d, a)
+        return c, d, a, loss
+
+    @staticmethod
+    def loss(tiv, vega, y, c, d, a):
+        """Calculate weighted loss for SVI calibration."""
+        diff = tiv - (a + d * y + c * np.sqrt(y * y + 1))
+        return (vega * diff * diff).mean()
+
+    @classmethod
+    def fit(cls, tiv, vega, k, tau=1.0):
+        """
+        Fit SVI model to market data using a more stable two-step approach.
+
+        Parameters:
+        - tiv: Total implied variance values
+        - vega: Option vega values (for weighting)
+        - k: Log-moneyness values
+        - tau: Time to expiry in years
+
+        Returns:
+        - params: [a, b, m, rho, sigma] parameters
+        - loss: Fitting loss value
+        """
+        if len(k) <= 5:
+            return [np.nan] * 5, np.inf
+
+        vega = vega / vega.max() if vega.max() > 0 else np.ones_like(vega)
+        m_init = np.mean(k)
+        sigma_init = max(0.1, np.std(k) * 0.1)
+
+        def score(params):
+            sigma, m = params
+            c, d, a_calib, loss = cls.calibration(tiv, vega, k, m, sigma)
+            return loss
+
+        result = minimize(score, [sigma_init, m_init], bounds=[(0.001, None), (None, None)],
+                          tol=1e-16, method="Nelder-Mead", options={'maxfun': 5000})
+
+        sigma, m = result.x
+        c, d, a_calib, loss = cls.calibration(tiv, vega, k, m, sigma)
+        a_calib = max(a_calib, 1e-6)
+
+        if c != 0:
+            a_svi = a_calib / tau
+            rho_svi = d / c
+            b_svi = c / (sigma * tau)
+        else:
+            a_svi = a_calib / tau
+            rho_svi = b_svi = 0
+
+        return [a_svi, b_svi, m, rho_svi, sigma], loss
+
+    @classmethod
+    def correct_calendar_arbitrage(cls, params, t, tiv, vega, k, prev_params, prev_t, domain_params):
+        """
+        Correct calendar arbitrage by ensuring the current SVI surface stays above the previous one.
+
+        Parameters:
+        - params: Current SVI parameters [a, b, sigma, rho, m]
+        - t: Current time to expiry
+        - tiv: Current total implied variance values
+        - vega: Current vega values
+        - k: Current log-moneyness values
+        - prev_params: Previous SVI parameters
+        - prev_t: Previous time to expiry
+        - k_grid: Grid of log-moneyness values for arbitrage checking
+
+        Returns:
+        - New arbitrage-free parameters
+        """
+
+        if np.any(np.isnan(params)) or np.any(np.isnan(prev_params)):
+            return params
+
+        a_init, b_init, sigma_init, rho_init, m_init = params
+        a_prev, b_prev, sigma_prev, rho_prev, m_prev = prev_params
+        k_constraint = np.unique(np.concatenate([k, np.linspace(min(k), max(k), domain_params[2])]))
+
+        def objective(x):
+            a, b, sigma, rho, m = x
+            w_model = cls.svi(k, a * t, b * t, sigma, rho, m)
+            fit_loss = ((w_model - tiv) ** 2 * vega).mean()
+            param_deviation = sum(((x[i] - params[i]) / max(abs(params[i]), 1e-6)) ** 2
+                                  for i in range(len(params)))
+            return fit_loss + 0.01 * param_deviation
+
+        def calendar_constraint(x):
+            a, b, sigma, rho, m = x
+            w_current = cls.svi(k_constraint, a * t, b * t, sigma, rho, m)
+            w_prev = cls.svi(k_constraint, a_prev * prev_t, b_prev * prev_t, sigma_prev, rho_prev, m_prev)
+            return w_current - w_prev
+
+        bounds = [
+            (max(a_init * 0.8, 1e-6), a_init * 1.2),
+            (max(b_init * 0.8, 0), b_init * 1.2),
+            (max(sigma_init * 0.8, 1e-6), sigma_init * 1.2),
+            (max(rho_init - 0.05, -1), min(rho_init + 0.05, 1)),
+            (m_init - 0.05, m_init + 0.05)
+        ]
+
+        constraints = [
+            {'type': 'ineq', 'fun': calendar_constraint},
+            {'type': 'ineq', 'fun': lambda x: x[0] + x[1] * x[2] * np.sqrt(1 - x[3] ** 2)}
+        ]
+
+        result = minimize(
+            objective, [a_init, b_init, sigma_init, rho_init, m_init],
+            bounds=bounds, constraints=constraints, method='SLSQP',
+            options={'disp': False, 'maxiter': 1000, 'ftol': 1e-8}
+        )
+
+        if result.success:
+            return result.x
+
+        return params
+
+
+# Models dictionary for easy access
+MODELS = {
+    'svi': SVIModel,
+}

{voly-0.0.166 → voly-0.0.167/src/voly.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voly
-Version: 0.0.166
+Version: 0.0.167
 Summary: Options & volatility research package
 Author-email: Manu de Cara <manu.de.cara@gmail.com>
 License: MIT

voly-0.0.166/src/voly/core/fit.py

@@ -1,241 +0,0 @@
-"""
-Model fitting and calibration module for the Voly package.
-
-This module handles fitting volatility models to market data and
-calculating fitting statistics.
-"""
-
-import numpy as np
-import pandas as pd
-from typing import List, Tuple, Dict, Optional, Union, Any
-from scipy.optimize import least_squares
-from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
-from voly.utils.logger import logger, catch_exception
-from voly.formulas import get_domain
-from voly.exceptions import VolyError
-from voly.models import SVIModel
-import warnings
-
-warnings.filterwarnings("ignore")
-
-
-@catch_exception
-def calculate_residuals(params: List[float], t: float, option_chain: pd.DataFrame,
-                        model: Any = SVIModel) -> np.ndarray:
-    """Calculate residuals between market and model implied volatilities."""
-    maturity_data = option_chain[option_chain['t'] == t]
-    w = np.array([model.svi(x, *params) for x in maturity_data['log_moneyness']])
-    iv_actual = maturity_data['mark_iv'].values
-    return iv_actual - np.sqrt(w / t)
-
-
-@catch_exception
-def fit_model(option_chain: pd.DataFrame,
-              model_name: str = 'svi',
-              initial_params: Optional[List[float]] = None,
-              param_bounds: Optional[Tuple] = None) -> pd.DataFrame:
-    """
-    Fit a volatility model to market data.
-
-    Parameters:
-    - option_chain: DataFrame with market data
-    - model_name: Type of model to fit (default: 'svi')
-    - initial_params: Optional initial parameters for optimization (default: model's defaults)
-    - param_bounds: Optional parameter bounds for optimization (default: model's defaults)
-
-    Returns:
-    - DataFrame with all fit results and performance metrics as columns, maturity_names as index
-    """
-    if model_name.lower() != 'svi':
-        raise VolyError(f"Model type '{model_name}' is not supported. Currently only 'svi' is available.")
-
-    # Use defaults if not provided
-    initial_params = initial_params or SVIModel.DEFAULT_INITIAL_PARAMS
-    param_bounds = param_bounds or SVIModel.DEFAULT_PARAM_BOUNDS
-
-    # Define column names and their data types
-    column_dtypes = {
-        's': float,
-        'u': float,
-        't': float,
-        'r': float,
-        'oi': float,
-        'volume': float,
-        'maturity_date': 'datetime64[ns]',
-        'a': float,
-        'b': float,
-        'sigma': float,
-        'rho': float,
-        'm': float,
-        'nu': float,
-        'psi': float,
-        'p': float,
-        'c': float,
-        'nu_tilde': float,
-        'fit_success': bool,
-        'cost': float,
-        'optimality': float,
-        'rmse': float,
-        'mae': float,
-        'r2': float,
-        'max_error': float,
-        'n_points': int
-    }
-
-    # Get unique maturities and sort them
-    unique_ts = sorted(option_chain['t'].unique())
-    maturity_names = [option_chain[option_chain['t'] == t]['maturity_name'].iloc[0] for t in unique_ts]
-
-    # Store results in a dictionary first
-    results_data = {col: [] for col in column_dtypes.keys()}
-
-    # ANSI color codes for terminal output
-    GREEN, RED, RESET = '\033[32m', '\033[31m', '\033[0m'
-
-    s = option_chain['index_price'].iloc[-1]
-
-    for t in unique_ts:
-        # Get data for this maturity
-        maturity_data = option_chain[option_chain['t'] == t]
-        maturity_name = maturity_data['maturity_name'].iloc[0]
-
-        logger.info(f"Optimizing for {maturity_name}...")
-
-        # Optimize SVI parameters
-        try:
-            result = least_squares(
-                calculate_residuals,
-                initial_params,
-                args=(t, option_chain, SVIModel),
-                bounds=param_bounds,
-                max_nfev=1000
-            )
-        except Exception as e:
-            raise VolyError(f"Optimization failed for {maturity_name}: {str(e)}")
-
-        # Extract raw parameters
-        a, b, sigma, rho, m = result.x
-
-        # Calculate model predictions for statistics
-        w = np.array([SVIModel.svi(x, *result.x) for x in maturity_data['log_moneyness']])
-        iv_model = np.sqrt(w / t)
-        iv_market = maturity_data['mark_iv'].values
-
-        # Calculate statistics
-        rmse = np.sqrt(mean_squared_error(iv_market, iv_model))
-        mae = mean_absolute_error(iv_market, iv_model)
-        r2 = r2_score(iv_market, iv_model)
-        max_error = np.max(np.abs(iv_market - iv_model))
-
-        # Get or calculate additional required data
-        u = maturity_data['underlying_price'].iloc[0]
-
-        # Aggregate open interest and volume
-        oi = maturity_data['open_interest'].sum() if 'open_interest' in maturity_data.columns else 0
-        volume = maturity_data['volume'].sum() if 'volume' in maturity_data.columns else 0
-        r = maturity_data['interest_rate'].iloc[0] if 'interest_rate' in maturity_data.columns else 0
-
-        # Calculate Jump-Wing parameters
-        nu, psi, p, c, nu_tilde = SVIModel.raw_to_jw_params(a, b, sigma, rho, m, t)
-
-        # Store values in the results dictionary with proper types
-        results_data['s'].append(float(s))
-        results_data['u'].append(float(u))
-        results_data['t'].append(float(t))
-        results_data['r'].append(float(r))
-        results_data['oi'].append(float(oi))
-        results_data['volume'].append(float(volume))
-        results_data['maturity_date'].append(maturity_data['maturity_date'].iloc[0])
-        results_data['a'].append(float(a))
-        results_data['b'].append(float(b))
-        results_data['sigma'].append(float(sigma))
-        results_data['m'].append(float(m))
-        results_data['rho'].append(float(rho))
-        results_data['nu'].append(float(nu))
-        results_data['psi'].append(float(psi))
-        results_data['p'].append(float(p))
-        results_data['c'].append(float(c))
-        results_data['nu_tilde'].append(float(nu_tilde))
-        results_data['fit_success'].append(bool(result.success))
-        results_data['cost'].append(float(result.cost))
-        results_data['optimality'].append(float(result.optimality))
-        results_data['rmse'].append(float(rmse))
-        results_data['mae'].append(float(mae))
-        results_data['r2'].append(float(r2))
-        results_data['max_error'].append(float(max_error))
-        results_data['n_points'].append(int(len(maturity_data)))
-
-        # Log result
-        status = f'{GREEN}SUCCESS{RESET}' if result.success else f'{RED}FAILED{RESET}'
-        logger.info(f'Optimization for {maturity_name}: {status}')
-        logger.info('-------------------------------------')
-
-    # Create DataFrame with proper types
-    results_df = pd.DataFrame(results_data, index=maturity_names)
-
-    # Convert columns to appropriate types
-    for col, dtype in column_dtypes.items():
-        if col in results_df.columns:
-            try:
-                results_df[col] = results_df[col].astype(dtype)
-            except (ValueError, TypeError) as e:
-                logger.warning(f"Could not convert column {col} to {dtype}: {e}")
-
-    return results_df
-
-
-@catch_exception
-def get_iv_surface(model_results: pd.DataFrame,
-                   domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
-                   return_domain: str = 'log_moneyness') -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]:
-    """
-    Generate implied volatility surface using optimized SVI parameters.
-
-    Works with both regular fit_results and interpolated_results dataframes.
-
-    Parameters:
-    - model_results: DataFrame from fit_model() or interpolate_model(). Maturity names or DTM as Index
-    - domain_params: Tuple of (min, max, num_points) for the log-moneyness array
-    - return_domain: Domain for x-axis values ('log_moneyness', 'moneyness', 'returns', 'strikes', 'delta')
-
-    Returns:
-    - Tuple of (iv_surface, x_surface)
-      iv_surface: Dictionary mapping maturity/dtm names to IV arrays
-      x_surface: Dictionary mapping maturity/dtm names to requested x domain arrays
-    """
-    # Check if required columns are present
-    required_columns = ['a', 'b', 'sigma', 'rho', 'm', 't']
-    missing_columns = [col for col in required_columns if col not in model_results.columns]
-    if missing_columns:
-        raise VolyError(f"Required columns missing in model_results: {missing_columns}")
-
-    # Generate implied volatility surface in log-moneyness domain
-    LM = np.linspace(domain_params[0], domain_params[1], domain_params[2])
-
-    iv_surface = {}
-    x_surface = {}
-
-    # Process each maturity/dtm
-    for i in model_results.index:
-        # Calculate SVI total implied variance and convert to IV
-        params = [
-            model_results.loc[i, 'a'],
-            model_results.loc[i, 'b'],
-            model_results.loc[i, 'sigma'],
-            model_results.loc[i, 'rho'],
-            model_results.loc[i, 'm']
-        ]
-        s = model_results.loc[i, 's']
-        r = model_results.loc[i, 'r']
-        t = model_results.loc[i, 't']
-
-        # Calculate implied volatility
-        w = np.array([SVIModel.svi(x, *params) for x in LM])
-        o = np.sqrt(w / t)
-        iv_surface[i] = o
-
-        # Calculate x domain for this maturity/dtm
-        x = get_domain(domain_params, s, r, o, t, return_domain)
-        x_surface[i] = x
-
-    return iv_surface, x_surface

voly-0.0.166/src/voly/models.py

@@ -1,81 +0,0 @@
-"""
-Volatility models for the Voly package.
-"""
-
-import numpy as np
-from typing import Tuple, Dict, List, Optional, Union
-
-
-class SVIModel:
-    """
-    Stochastic Volatility Inspired (SVI) model.
-
-    This class provides methods for calculating implied volatility using the
-    SVI parameterization, as well as its derivatives and related functions.
-    """
-
-    # Default initial parameters and bounds
-    DEFAULT_INITIAL_PARAMS = [0.04, 0.1, 0.2, -0.5, 0.01]
-    DEFAULT_PARAM_BOUNDS = ([-np.inf, 0, 0, -1, -np.inf], [np.inf, np.inf, np.inf, 1, np.inf])
-
-    # Parameter names for reference
-    PARAM_NAMES = ['a', 'b', 'sigma', 'rho', 'm']
-    JW_PARAM_NAMES = ['nu', 'psi', 'p', 'c', 'nu_tilde']
-
-    # Parameter descriptions for documentation
-    PARAM_DESCRIPTIONS = {
-        'a': 'Base level of total implied variance',
-        'b': 'Volatility skewness/smile modulation (controls wing slopes)',
-        'sigma': 'Convexity control of the volatility smile (reduces ATM curvature)',
-        'rho': 'Skewness/slope of the volatility smile (-1 to 1, rotates smile)',
-        'm': 'Horizontal shift of the smile peak',
-        'nu': 'ATM variance (level of ATM volatility)',
-        'psi': 'ATM volatility skew (affects the gradient of the curve at ATM point)',
-        'p': 'Slope of put wing (left side of curve)',
-        'c': 'Slope of call wing (right side of curve)',
-        'nu_tilde': 'Minimum implied total variance',
-    }
-
-    @staticmethod
-    def svi(LM: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
-        return a + b * (rho * (LM - m) + np.sqrt((LM - m) ** 2 + sigma ** 2))
-
-    @staticmethod
-    def svi_d(LM: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
-        return b * (rho + ((LM - m) / np.sqrt((LM - m) ** 2 + sigma ** 2)))
-
-    @staticmethod
-    def svi_dd(LM: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
-        return b * LM ** 2 / ((LM - m) ** 2 + sigma ** 2) ** 1.5
-
-    @staticmethod
-    def svi_min_strike(sigma: float, rho: float, m: float) -> float:
-        return m - ((sigma * rho) / np.sqrt(1 - rho ** 2))
-
-    @staticmethod
-    def raw_to_jw_params(a: float, b: float, sigma: float, rho: float, m: float, t: float) -> Tuple[float, float, float, float, float]:
-        nu = (a + b * ((-rho) * m + np.sqrt(m ** 2 + sigma ** 2))) / t
-        psi = (1 / np.sqrt(nu * t)) * (b / 2) * (rho - (m / np.sqrt(m ** 2 + sigma ** 2)))
-        p = (1 / np.sqrt(nu * t)) * b * (1 - rho)
-        c = (1 / np.sqrt(nu * t)) * b * (1 + rho)
-        nu_tilde = (1 / t) * (a + b * sigma * np.sqrt(1 - rho ** 2))
-        return nu, psi, p, c, nu_tilde
-
-    @staticmethod
-    def jw_to_raw_params(nu: float, psi: float, p: float, c: float, nu_tilde: float, t: float) -> Tuple[float, float, float, float, float]:
-        w = nu * t
-        b = (c + p) / 2
-        rho = (c - p) / (c + p)
-        beta = rho - ((2 * w * psi) / b)
-        alpha = np.sign(beta) * (np.sqrt((1 / (beta ** 2)) - 1))
-        m = (((nu ** 2) - (nu_tilde ** 2)) * t) / (
-                b * ((-rho) + (np.sign(alpha) * np.sqrt(1 + alpha ** 2)) - (alpha * np.sqrt(1 - rho ** 2))))
-        sigma = alpha * m
-        a = ((nu_tilde ** 2) * t) - (b * sigma * np.sqrt(1 - rho ** 2))
-        return a, b, sigma, rho, m
-
-
-# Models dictionary for easy access
-MODELS = {
-    'svi': SVIModel,
-}