quantark 0.1.0__py3-none-any.whl

quantark/param/rrf/rate_curve.py

@@ -0,0 +1,436 @@
+"""
+Risk-free rate curve representations.
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List, Tuple
+import math
+from quantark.util.exceptions import ValidationError
+
+
+class RateCurve(ABC):
+    """
+    Abstract base class for risk-free rate curves.
+    
+    Rate curves provide risk-free interest rates as a function of maturity.
+    """
+    
+    @abstractmethod
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Get risk-free rate for given maturity.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Annualized risk-free rate (continuously compounded)
+        """
+        pass
+    
+    @abstractmethod
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Get discount factor for given maturity.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Discount factor exp(-r*T)
+        """
+        pass
+    
+    def get_forward_rate(self, t1: float, t2: float) -> float:
+        """
+        Calculate forward rate between two times.
+        
+        Args:
+            t1: Start time (years)
+            t2: End time (years)
+            
+        Returns:
+            Forward rate from t1 to t2
+        """
+        if t2 <= t1:
+            raise ValidationError(f"t2 ({t2}) must be greater than t1 ({t1})")
+        
+        df1 = self.get_discount_factor(t1)
+        df2 = self.get_discount_factor(t2)
+        
+        return -math.log(df2 / df1) / (t2 - t1)
+
+
+class ParallelShiftRateCurve(RateCurve):
+    """
+    Parallel shift wrapper for a base rate curve.
+
+    Applies a constant additive shift to continuously-compounded rates.
+    Equivalent to shifting discount factors by exp(-shift * T):
+        DF_shift(T) = DF_base(T) * exp(-shift * T)
+    """
+
+    def __init__(self, base_curve: RateCurve, shift: float):
+        if base_curve is None:
+            raise ValidationError("base_curve is required")
+        self.base_curve = base_curve
+        self.shift = shift
+
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        if time_to_maturity < 0:
+            raise ValidationError(
+                f"Time to maturity must be non-negative, got {time_to_maturity}"
+            )
+        df_base = self.base_curve.get_discount_factor(time_to_maturity)
+        return df_base * math.exp(-self.shift * time_to_maturity)
+
+    def get_rate(self, time_to_maturity: float) -> float:
+        if time_to_maturity <= 0:
+            return self.base_curve.get_rate(time_to_maturity) + self.shift
+        df = self.get_discount_factor(time_to_maturity)
+        return -math.log(df) / time_to_maturity
+
+    def __repr__(self):
+        return f"ParallelShiftRateCurve(shift={self.shift:.2%}, base={self.base_curve!r})"
+
+
+@dataclass
+class FlatRateCurve(RateCurve):
+    """
+    Flat (constant) rate curve.
+    
+    Returns the same rate regardless of maturity.
+    
+    Attributes:
+        rate: Constant annualized risk-free rate (continuously compounded)
+    """
+    rate: float
+    
+    def __post_init__(self):
+        """Validate rate - allow negative rates but warn if extreme."""
+        if self.rate < -0.10:  # -10% rate - sanity check
+            raise ValidationError(f"Rate seems unreasonably low: {self.rate}")
+        if self.rate > 0.50:  # 50% rate - sanity check
+            raise ValidationError(f"Rate seems unreasonably high: {self.rate}")
+    
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Return constant rate.
+        
+        Args:
+            time_to_maturity: Time to maturity (ignored)
+            
+        Returns:
+            Constant risk-free rate
+        """
+        return self.rate
+    
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Calculate discount factor.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Discount factor exp(-r*T)
+        """
+        import math
+        if time_to_maturity < 0:
+            raise ValidationError(f"Time to maturity must be non-negative, got {time_to_maturity}")
+        return math.exp(-self.rate * time_to_maturity)
+    
+    def __repr__(self):
+        return f"FlatRateCurve(rate={self.rate:.2%})"
+
+
+class InterpolatedRateCurve(RateCurve):
+    """
+    Base class for interpolated rate curves.
+    
+    Stores rate pillars (time, rate pairs) and interpolates between them.
+    
+    Attributes:
+        pillars: List of (time, rate) tuples, sorted by time
+    """
+    
+    def __init__(self, pillars: List[Tuple[float, float]]):
+        """
+        Initialize interpolated rate curve.
+        
+        Args:
+            pillars: List of (time_to_maturity, rate) tuples
+            
+        Raises:
+            ValidationError: If pillars are invalid
+        """
+        if not pillars:
+            raise ValidationError("Must provide at least one pillar")
+        
+        # Sort pillars by time
+        self.pillars = sorted(pillars, key=lambda x: x[0])
+        
+        # Validate pillars
+        for i, (time, rate) in enumerate(self.pillars):
+            if time < 0:
+                raise ValidationError(f"Pillar {i}: time must be non-negative, got {time}")
+            if i > 0 and time == self.pillars[i-1][0]:
+                raise ValidationError(f"Duplicate time pillar at {time}")
+    
+    def _find_bracketing_pillars(self, time: float) -> Tuple[int, int]:
+        """
+        Find indices of pillars that bracket the given time.
+        
+        Returns:
+            Tuple of (left_index, right_index)
+            If time is outside range, returns appropriate boundary indices.
+        """
+        if time <= self.pillars[0][0]:
+            return (0, 0)  # Flat extrapolation on left
+        
+        if time >= self.pillars[-1][0]:
+            return (len(self.pillars)-1, len(self.pillars)-1)  # Flat extrapolation on right
+        
+        # Binary search for bracketing pillars
+        left = 0
+        right = len(self.pillars) - 1
+        
+        while right - left > 1:
+            mid = (left + right) // 2
+            if self.pillars[mid][0] <= time:
+                left = mid
+            else:
+                right = mid
+        
+        return (left, right)
+    
+    def __repr__(self):
+        return f"{self.__class__.__name__}(pillars={len(self.pillars)})"
+
+
+class LinearRateCurve(InterpolatedRateCurve):
+    """
+    Linear interpolated rate curve.
+    
+    Performs linear interpolation on rates between pillars.
+    Uses flat extrapolation outside the pillar range.
+    """
+    
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Get rate using linear interpolation.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Interpolated rate
+        """
+        if time_to_maturity < 0:
+            raise ValidationError(f"Time to maturity must be non-negative, got {time_to_maturity}")
+        
+        left_idx, right_idx = self._find_bracketing_pillars(time_to_maturity)
+        
+        # Flat extrapolation
+        if left_idx == right_idx:
+            return self.pillars[left_idx][1]
+        
+        # Linear interpolation
+        t1, r1 = self.pillars[left_idx]
+        t2, r2 = self.pillars[right_idx]
+        
+        # Linear interpolation formula
+        weight = (time_to_maturity - t1) / (t2 - t1)
+        rate = r1 + weight * (r2 - r1)
+        
+        return rate
+    
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Get discount factor.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Discount factor exp(-r*T)
+        """
+        rate = self.get_rate(time_to_maturity)
+        return math.exp(-rate * time_to_maturity)
+
+
+class LogLinearRateCurve(InterpolatedRateCurve):
+    """
+    Log-linear interpolated rate curve.
+    
+    Performs linear interpolation on log(discount factors) between pillars.
+    This ensures smooth forward rates and is the market standard for
+    discount curve interpolation.
+    """
+    
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Get discount factor using log-linear interpolation.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Interpolated discount factor
+        """
+        if time_to_maturity < 0:
+            raise ValidationError(f"Time to maturity must be non-negative, got {time_to_maturity}")
+        
+        if time_to_maturity == 0:
+            return 1.0
+        
+        left_idx, right_idx = self._find_bracketing_pillars(time_to_maturity)
+        
+        # Calculate discount factors at pillars
+        t1, r1 = self.pillars[left_idx]
+        df1 = math.exp(-r1 * t1) if t1 > 0 else 1.0
+        
+        # Flat extrapolation
+        if left_idx == right_idx:
+            if t1 == 0:
+                return math.exp(-r1 * time_to_maturity)
+            # Flat forward rate extrapolation
+            return df1 * math.exp(-r1 * (time_to_maturity - t1))
+        
+        # Log-linear interpolation
+        t2, r2 = self.pillars[right_idx]
+        df2 = math.exp(-r2 * t2)
+        
+        # Linear interpolation on log(DF)
+        log_df1 = math.log(df1)
+        log_df2 = math.log(df2)
+        
+        weight = (time_to_maturity - t1) / (t2 - t1)
+        log_df = log_df1 + weight * (log_df2 - log_df1)
+        
+        return math.exp(log_df)
+    
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Get rate from discount factor.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Zero rate
+        """
+        if time_to_maturity <= 0:
+            if len(self.pillars) > 0:
+                return self.pillars[0][1]
+            return 0.0
+        
+        df = self.get_discount_factor(time_to_maturity)
+        return -math.log(df) / time_to_maturity
+
+
+class CubicSplineRateCurve(InterpolatedRateCurve):
+    """
+    Cubic spline interpolated rate curve.
+    
+    Uses natural cubic spline interpolation on rates.
+    Provides smooth first and second derivatives.
+    """
+    
+    def __init__(self, pillars: List[Tuple[float, float]]):
+        """Initialize and compute spline coefficients."""
+        super().__init__(pillars)
+        self._compute_spline_coefficients()
+    
+    def _compute_spline_coefficients(self):
+        """
+        Compute natural cubic spline coefficients.
+        
+        For each interval [x_i, x_{i+1}], the spline is:
+        S_i(x) = a_i + b_i*(x-x_i) + c_i*(x-x_i)^2 + d_i*(x-x_i)^3
+        """
+        n = len(self.pillars)
+        
+        if n < 2:
+            # Not enough points for spline, treat as constant
+            self.coefficients = [(self.pillars[0][1], 0, 0, 0)]
+            return
+        
+        # Extract times and rates
+        times = [p[0] for p in self.pillars]
+        rates = [p[1] for p in self.pillars]
+        
+        # Compute intervals
+        h = [times[i+1] - times[i] for i in range(n-1)]
+        
+        # Set up tridiagonal system for second derivatives
+        # Natural spline: second derivative is 0 at endpoints
+        alpha = [0] * n
+        for i in range(1, n-1):
+            alpha[i] = (3.0/h[i]) * (rates[i+1] - rates[i]) - (3.0/h[i-1]) * (rates[i] - rates[i-1])
+        
+        # Solve tridiagonal system
+        l = [1.0] * n
+        mu = [0.0] * n
+        z = [0.0] * n
+        
+        for i in range(1, n-1):
+            l[i] = 2.0 * (times[i+1] - times[i-1]) - h[i-1] * mu[i-1]
+            mu[i] = h[i] / l[i]
+            z[i] = (alpha[i] - h[i-1] * z[i-1]) / l[i]
+        
+        # Back substitution
+        c = [0.0] * n
+        b = [0.0] * (n-1)
+        d = [0.0] * (n-1)
+        
+        for j in range(n-2, -1, -1):
+            c[j] = z[j] - mu[j] * c[j+1]
+            b[j] = (rates[j+1] - rates[j]) / h[j] - h[j] * (c[j+1] + 2.0*c[j]) / 3.0
+            d[j] = (c[j+1] - c[j]) / (3.0 * h[j])
+        
+        # Store coefficients (a, b, c, d) for each interval
+        self.coefficients = []
+        for i in range(n-1):
+            self.coefficients.append((rates[i], b[i], c[i], d[i]))
+    
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Get rate using cubic spline interpolation.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Interpolated rate
+        """
+        if time_to_maturity < 0:
+            raise ValidationError(f"Time to maturity must be non-negative, got {time_to_maturity}")
+        
+        left_idx, right_idx = self._find_bracketing_pillars(time_to_maturity)
+        
+        # Flat extrapolation
+        if left_idx == right_idx:
+            return self.pillars[left_idx][1]
+        
+        # Cubic spline evaluation
+        a, b, c, d = self.coefficients[left_idx]
+        t0 = self.pillars[left_idx][0]
+        dt = time_to_maturity - t0
+        
+        rate = a + b*dt + c*dt*dt + d*dt*dt*dt
+        
+        return rate
+    
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Get discount factor.
+        
+        Args:
+            time_to_maturity: Time to maturity in years
+            
+        Returns:
+            Discount factor exp(-r*T)
+        """
+        rate = self.get_rate(time_to_maturity)
+        return math.exp(-rate * time_to_maturity)

quantark/param/vol/__init__.py

@@ -0,0 +1,6 @@
+"""
+Volatility surface representations.
+"""
+from .vol_surface import VolatilitySurface, FlatVolSurface, TermStructureVolSurface
+
+__all__ = ["VolatilitySurface", "FlatVolSurface", "TermStructureVolSurface"]

quantark/param/vol/vol_surface.py

@@ -0,0 +1,118 @@
+"""
+Volatility surface representations.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from quantark.util.exceptions import ValidationError
+from quantark.util.numerical import safe_divide, safe_sqrt, validate_positive
+import numpy as np
+
+
+class VolatilitySurface(ABC):
+    """
+    Abstract base class for volatility surfaces.
+
+    Volatility surfaces provide implied volatility as a function of
+    strike and time to maturity.
+    """
+
+    @abstractmethod
+    def get_vol(self, strike: float, time_to_maturity: float, spot: float) -> float:
+        """
+        Get implied volatility for given strike and maturity.
+
+        Args:
+            strike: Strike price
+            time_to_maturity: Time to maturity in years
+            spot: Current spot price
+
+        Returns:
+            Implied volatility (annualized)
+        """
+        pass
+
+
+@dataclass
+class FlatVolSurface(VolatilitySurface):
+    """
+    Flat (constant) volatility surface.
+
+    Returns the same volatility regardless of strike and maturity.
+    Suitable for Black-Scholes models with constant volatility.
+
+    Attributes:
+        volatility: Constant annualized volatility
+    """
+
+    volatility: float
+
+    def __post_init__(self) -> None:
+        """Validate volatility."""
+        if not isinstance(self.volatility, (int, float)):
+            raise ValidationError(f"Volatility must be numeric, got {self.volatility}")
+        validate_positive(float(self.volatility), name="volatility")
+        if self.volatility > 5.0:  # 500% vol - sanity check
+            raise ValidationError(
+                f"Volatility seems unreasonably high: {self.volatility}"
+            )
+
+    def get_vol(self, strike: float, time_to_maturity: float, spot: float) -> float:
+        """
+        Return constant volatility.
+
+        Args:
+            strike: Strike price (ignored)
+            time_to_maturity: Time to maturity (ignored)
+            spot: Spot price (ignored)
+
+        Returns:
+            Constant volatility
+        """
+        return self.volatility
+
+    def __repr__(self):
+        return f"FlatVolSurface(vol={self.volatility:.2%})"
+
+
+@dataclass
+class TermStructureVolSurface(VolatilitySurface):
+    """
+    Term-structure volatility surface (ATM by maturity).
+
+    Provides a time-dependent volatility via total variance interpolation on maturity.
+    Strike is ignored (ATM term structure).
+
+    Attributes:
+        times: Increasing maturities (year fractions).
+        vols: Implied volatilities for each maturity.
+    """
+
+    times: list[float]
+    vols: list[float]
+
+    def __post_init__(self) -> None:
+        if len(self.times) != len(self.vols):
+            raise ValidationError("times and vols must have the same length.")
+        if len(self.times) < 2:
+            raise ValidationError("times must have at least 2 points.")
+        if any(t <= 0 for t in self.times):
+            raise ValidationError("times must be positive.")
+        if any(self.times[i] >= self.times[i + 1] for i in range(len(self.times) - 1)):
+            raise ValidationError("times must be strictly increasing.")
+        for v in self.vols:
+            validate_positive(float(v), name="volatility")
+
+    def get_vol(self, strike: float, time_to_maturity: float, spot: float) -> float:
+        t = float(time_to_maturity)
+        if t <= self.times[0]:
+            return float(self.vols[0])
+        if t >= self.times[-1]:
+            return float(self.vols[-1])
+        total_variances = [float(v) ** 2 * float(tt) for v, tt in zip(self.vols, self.times)]
+        interp_total_var = float(np.interp(t, self.times, total_variances))
+        return float(safe_sqrt(safe_divide(interp_total_var, t)))
+
+    def __repr__(self):
+        return "TermStructureVolSurface(points=%d)" % len(self.times)

quantark/portfolio/__init__.py

@@ -0,0 +1,61 @@
+"""
+Portfolio management module.
+
+This module provides comprehensive portfolio management capabilities for
+tracking positions, calculating valuations, and aggregating risk metrics
+across multiple assets and products.
+
+Supports multiple asset classes:
+- Equity: Options, futures, delta-one products
+- Fixed Income: Bonds, bond futures, interest rate derivatives
+
+Main components:
+- BasePosition, BasePortfolio: Asset-agnostic protocols
+- EquityPosition, EquityPortfolio: Equity-specific implementations
+- FIPosition, FIPortfolio: Fixed Income-specific implementations
+- PortfolioSnapshot: Point-in-time snapshot of portfolio state
+- PortfolioExporter: Export functionality for parquet and excel formats
+
+Backward Compatibility:
+- Position: Alias for EquityPosition
+- Portfolio: Alias for EquityPortfolio
+"""
+
+# Base protocols
+from .base import BasePosition, BasePortfolio
+
+# Equity implementations (with backward-compatible aliases)
+from .equity import (
+    EquityPosition,
+    EquityPortfolio,
+    Position,  # Backward compatibility alias
+    Portfolio,  # Backward compatibility alias
+)
+
+# Fixed Income implementations
+from .fi import (
+    FIPosition,
+    FIPortfolio,
+)
+
+# Utilities
+from .portfolio_snapshot import PortfolioSnapshot
+from .portfolio_storage import PortfolioExporter
+
+__all__ = [
+    # Base protocols
+    "BasePosition",
+    "BasePortfolio",
+    # Equity
+    "EquityPosition",
+    "EquityPortfolio",
+    # Fixed Income
+    "FIPosition",
+    "FIPortfolio",
+    # Backward compatibility aliases
+    "Position",
+    "Portfolio",
+    # Utilities
+    "PortfolioSnapshot",
+    "PortfolioExporter",
+]