quantark 0.1.0__py3-none-any.whl

quantark/simm/config.py

@@ -0,0 +1,186 @@
+"""
+SIMM Configuration Module.
+
+This module provides configuration dataclasses for ISDA SIMM calculations.
+"""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, Optional
+
+from quantark.util.exceptions import ValidationError
+
+
+class SIMMVersion(Enum):
+    """ISDA SIMM version identifiers.
+    
+    Different SIMM versions may have different risk weights and correlations.
+    """
+    V2_5 = "2.5"
+    V2_6 = "2.6"
+    
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class SIMMConfig:
+    """Configuration for SIMM calculation.
+    
+    This class encapsulates all configuration parameters for SIMM calculations,
+    including version, calculation currency, component selection, and add-ons.
+    
+    Attributes:
+        version: SIMM version (affects risk weights and correlations).
+        calculation_currency: Base currency for SIMM calculation (typically USD).
+        
+        calculate_delta: Whether to calculate Delta margin.
+        calculate_vega: Whether to calculate Vega margin.
+        calculate_curvature: Whether to calculate Curvature margin.
+        calculate_base_corr: Whether to calculate Base Correlation margin.
+        
+        ms_rates_fx: Product class multiplier for RatesFX (default 1.0).
+        ms_credit: Product class multiplier for Credit (default 1.0).
+        ms_equity: Product class multiplier for Equity (default 1.0).
+        ms_commodity: Product class multiplier for Commodity (default 1.0).
+        
+        addon_fixed: Fixed add-on amount in calculation currency.
+        addon_factors: Per-trade or per-product add-on factors.
+        
+        include_attribution: Include margin attribution in results.
+        include_bucket_detail: Include bucket-level detail in results.
+    
+    Examples:
+        Basic SIMM configuration:
+        >>> config = SIMMConfig()
+        
+        SIMM with specific version and currency:
+        >>> config = SIMMConfig(
+        ...     version=SIMMVersion.V2_6,
+        ...     calculation_currency="EUR"
+        ... )
+        
+        SIMM with add-ons:
+        >>> config = SIMMConfig(
+        ...     addon_fixed=1_000_000,
+        ...     addon_factors={"regulatory_addon": 0.05}
+        ... )
+        
+        Delta-only SIMM:
+        >>> config = SIMMConfig(
+        ...     calculate_delta=True,
+        ...     calculate_vega=False,
+        ...     calculate_curvature=False,
+        ...     calculate_base_corr=False
+        ... )
+    """
+    # SIMM version
+    version: SIMMVersion = SIMMVersion.V2_6
+    
+    # Calculation currency
+    calculation_currency: str = "USD"
+    
+    # Which components to calculate
+    calculate_delta: bool = True
+    calculate_vega: bool = True
+    calculate_curvature: bool = True
+    calculate_base_corr: bool = True
+    
+    # Product class multipliers (default = 1.0)
+    ms_rates_fx: float = 1.0
+    ms_credit: float = 1.0
+    ms_equity: float = 1.0
+    ms_commodity: float = 1.0
+    
+    # Add-on configuration
+    addon_fixed: float = 0.0
+    addon_factors: Dict[str, float] = field(default_factory=dict)
+    
+    # Output options
+    include_attribution: bool = True
+    include_bucket_detail: bool = True
+    
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        self._validate()
+    
+    def _validate(self) -> None:
+        """Validate configuration values."""
+        # Validate calculation currency
+        if not isinstance(self.calculation_currency, str) or len(self.calculation_currency) != 3:
+            raise ValidationError(
+                f"calculation_currency must be a 3-letter ISO currency code, "
+                f"got {self.calculation_currency!r}"
+            )
+        
+        # Validate multipliers are positive
+        for name, value in [
+            ("ms_rates_fx", self.ms_rates_fx),
+            ("ms_credit", self.ms_credit),
+            ("ms_equity", self.ms_equity),
+            ("ms_commodity", self.ms_commodity),
+        ]:
+            if value <= 0:
+                raise ValidationError(
+                    f"{name} must be positive, got {value}"
+                )
+        
+        # Validate addon_fixed is non-negative
+        if self.addon_fixed < 0:
+            raise ValidationError(
+                f"addon_fixed must be non-negative, got {self.addon_fixed}"
+            )
+        
+        # Validate addon_factors values are non-negative
+        for key, value in self.addon_factors.items():
+            if value < 0:
+                raise ValidationError(
+                    f"addon_factors['{key}'] must be non-negative, got {value}"
+                )
+    
+    def get_product_class_multiplier(self, product_class: str) -> float:
+        """Get the multiplier for a product class.
+        
+        Args:
+            product_class: Product class name ("RatesFX", "Credit", "Equity", "Commodity").
+            
+        Returns:
+            The multiplier for the specified product class.
+            
+        Raises:
+            ValueError: If product_class is not recognized.
+        """
+        mapping = {
+            "RatesFX": self.ms_rates_fx,
+            "Credit": self.ms_credit,
+            "Equity": self.ms_equity,
+            "Commodity": self.ms_commodity,
+        }
+        if product_class not in mapping:
+            raise ValueError(f"Unknown product class: {product_class}")
+        return mapping[product_class]
+    
+    def with_version(self, version: SIMMVersion) -> "SIMMConfig":
+        """Create a copy of this config with a different version.
+        
+        Args:
+            version: The SIMM version to use.
+            
+        Returns:
+            New SIMMConfig with the specified version.
+        """
+        return SIMMConfig(
+            version=version,
+            calculation_currency=self.calculation_currency,
+            calculate_delta=self.calculate_delta,
+            calculate_vega=self.calculate_vega,
+            calculate_curvature=self.calculate_curvature,
+            calculate_base_corr=self.calculate_base_corr,
+            ms_rates_fx=self.ms_rates_fx,
+            ms_credit=self.ms_credit,
+            ms_equity=self.ms_equity,
+            ms_commodity=self.ms_commodity,
+            addon_fixed=self.addon_fixed,
+            addon_factors=dict(self.addon_factors),
+            include_attribution=self.include_attribution,
+            include_bucket_detail=self.include_bucket_detail,
+        )

quantark/simm/crif/__init__.py

@@ -0,0 +1,35 @@
+"""
+SIMM CRIF Module.
+
+This module provides CRIF (Common Risk Interchange Format) data models
+and parsing utilities for ISDA SIMM.
+"""
+from .models import (
+    CRIFHeader,
+    CRIFRecord,
+    CRIF_COLUMNS,
+    CRIF_COLUMN_MAPPING,
+    CRIF_REQUIRED_COLUMNS,
+)
+from .parser import (
+    CRIFValidationError,
+    crif_to_sensitivities,
+    parse_crif_csv,
+    sensitivities_to_crif,
+    write_crif_csv,
+)
+
+__all__ = [
+    # Models
+    "CRIFHeader",
+    "CRIFRecord",
+    "CRIF_COLUMNS",
+    "CRIF_COLUMN_MAPPING",
+    "CRIF_REQUIRED_COLUMNS",
+    # Parser
+    "CRIFValidationError",
+    "crif_to_sensitivities",
+    "parse_crif_csv",
+    "sensitivities_to_crif",
+    "write_crif_csv",
+]

quantark/simm/crif/models.py

@@ -0,0 +1,230 @@
+"""
+CRIF Data Models.
+
+This module defines the CRIF (Common Risk Interchange Format) data structures
+for ISDA SIMM sensitivity exchange.
+"""
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Optional
+
+from ..taxonomy import MarginType, ProductClass, RiskClass, SensitivityType
+
+
+@dataclass
+class CRIFHeader:
+    """CRIF file header metadata.
+    
+    Contains information about the CRIF file including valuation date,
+    reporting entity, and file format version.
+    
+    Attributes:
+        valuation_date: Date of valuation for the sensitivities.
+        reporting_entity: Legal entity identifier of the reporter.
+        counterparty: Counterparty legal entity identifier.
+        crif_version: CRIF format version (e.g., "2.0").
+        im_model: Initial margin model identifier (typically "SIMM").
+        base_currency: Base currency for amounts.
+    """
+    valuation_date: date
+    reporting_entity: str = ""
+    counterparty: str = ""
+    crif_version: str = "2.0"
+    im_model: str = "SIMM"
+    base_currency: str = "USD"
+
+
+@dataclass
+class CRIFRecord:
+    """Single CRIF record representing one sensitivity.
+    
+    This dataclass follows the ISDA CRIF v2.x specification for
+    representing sensitivities in a standardized interchange format.
+    
+    Attributes:
+        trade_id: Unique identifier for the trade.
+        valuation_date: Date of the valuation.
+        
+        risk_type: SIMM risk type (e.g., "Risk_IRCurve", "Risk_FX").
+        qualifier: Primary risk factor identifier (currency for IR, issuer for Credit).
+        bucket: SIMM bucket assignment.
+        label1: First label (tenor for IR/Credit, empty for others).
+        label2: Second label (sub-curve for IR, empty for others).
+        
+        amount: Sensitivity amount.
+        amount_currency: Currency of the amount.
+        amount_usd: Amount converted to USD (optional).
+        
+        product_class: SIMM product class (optional, can be inferred).
+        risk_class: SIMM risk class (optional, can be inferred).
+        
+        im_model: Initial margin model (typically "SIMM").
+        post_regulations: Posting regulations (e.g., "CFTC", "EMIR").
+        collect_regulations: Collection regulations.
+        
+        call_put: "C" or "P" for options (optional).
+        notional: Trade notional (optional, for reference).
+        notional_currency: Currency of notional (optional).
+        
+    Examples:
+        IR Delta sensitivity:
+        >>> record = CRIFRecord(
+        ...     trade_id="TRADE001",
+        ...     valuation_date=date(2024, 1, 15),
+        ...     risk_type="Risk_IRCurve",
+        ...     qualifier="USD",
+        ...     bucket="1",
+        ...     label1="5y",
+        ...     label2="OIS",
+        ...     amount=150000.0,
+        ...     amount_currency="USD"
+        ... )
+        
+        FX Delta sensitivity:
+        >>> record = CRIFRecord(
+        ...     trade_id="TRADE002",
+        ...     valuation_date=date(2024, 1, 15),
+        ...     risk_type="Risk_FX",
+        ...     qualifier="EURUSD",
+        ...     bucket="",
+        ...     label1="",
+        ...     label2="",
+        ...     amount=50000.0,
+        ...     amount_currency="USD"
+        ... )
+    """
+    # Required identification fields
+    trade_id: str
+    valuation_date: date
+    
+    # SIMM classification
+    risk_type: str
+    qualifier: str
+    bucket: str
+    label1: str = ""
+    label2: str = ""
+    
+    # Sensitivity value
+    amount: float = 0.0
+    amount_currency: str = "USD"
+    amount_usd: Optional[float] = None
+    
+    # SIMM classification (optional, can be inferred)
+    product_class: Optional[str] = None
+    risk_class: Optional[str] = None
+    
+    # Model and regulatory info
+    im_model: str = "SIMM"
+    post_regulations: Optional[str] = None
+    collect_regulations: Optional[str] = None
+    
+    # Option-specific fields
+    call_put: Optional[str] = None
+    
+    # Reference fields
+    notional: Optional[float] = None
+    notional_currency: Optional[str] = None
+    
+    def get_sensitivity_type(self) -> Optional[SensitivityType]:
+        """Get the SensitivityType enum from the risk_type string.
+        
+        Returns:
+            SensitivityType if valid, None otherwise.
+        """
+        for st in SensitivityType:
+            if st.value == self.risk_type:
+                return st
+        return None
+    
+    def get_risk_class(self) -> Optional[RiskClass]:
+        """Infer the RiskClass from the risk_type.
+        
+        Returns:
+            RiskClass if determinable, None otherwise.
+        """
+        sensitivity_type = self.get_sensitivity_type()
+        if sensitivity_type:
+            return sensitivity_type.risk_class
+        return None
+    
+    def get_margin_type(self) -> Optional[MarginType]:
+        """Infer the MarginType from the risk_type.
+        
+        Returns:
+            MarginType if determinable, None otherwise.
+        """
+        sensitivity_type = self.get_sensitivity_type()
+        if sensitivity_type:
+            return sensitivity_type.margin_type
+        return None
+    
+    def get_product_class(self) -> Optional[ProductClass]:
+        """Infer or return the ProductClass.
+        
+        Returns:
+            ProductClass based on risk_class mapping.
+        """
+        if self.product_class:
+            for pc in ProductClass:
+                if pc.value == self.product_class:
+                    return pc
+        
+        # Infer from risk class
+        risk_class = self.get_risk_class()
+        if risk_class:
+            mapping = {
+                RiskClass.INTEREST_RATE: ProductClass.RATES_FX,
+                RiskClass.FX: ProductClass.RATES_FX,
+                RiskClass.CREDIT_QUALIFYING: ProductClass.CREDIT,
+                RiskClass.CREDIT_NON_QUALIFYING: ProductClass.CREDIT,
+                RiskClass.EQUITY: ProductClass.EQUITY,
+                RiskClass.COMMODITY: ProductClass.COMMODITY,
+            }
+            return mapping.get(risk_class)
+        return None
+
+
+# Standard CRIF column names
+CRIF_COLUMNS = (
+    "TradeID",
+    "ValuationDate",
+    "IMModel",
+    "ProductClass",
+    "RiskType",
+    "Qualifier",
+    "Bucket",
+    "Label1",
+    "Label2",
+    "Amount",
+    "AmountCurrency",
+    "AmountUSD",
+    "PostRegulations",
+    "CollectRegulations",
+    "Notional",
+    "NotionalCurrency",
+    "CallPut",
+)
+
+# Mapping from CRIF column names to CRIFRecord field names
+CRIF_COLUMN_MAPPING = {
+    "TradeID": "trade_id",
+    "ValuationDate": "valuation_date",
+    "IMModel": "im_model",
+    "ProductClass": "product_class",
+    "RiskType": "risk_type",
+    "Qualifier": "qualifier",
+    "Bucket": "bucket",
+    "Label1": "label1",
+    "Label2": "label2",
+    "Amount": "amount",
+    "AmountCurrency": "amount_currency",
+    "AmountUSD": "amount_usd",
+    "PostRegulations": "post_regulations",
+    "CollectRegulations": "collect_regulations",
+    "Notional": "notional",
+    "NotionalCurrency": "notional_currency",
+    "CallPut": "call_put",
+}
+
+# Required CRIF columns
+CRIF_REQUIRED_COLUMNS = ("TradeID", "ValuationDate", "RiskType", "Qualifier", "Amount", "AmountCurrency")