quantark 0.1.0__py3-none-any.whl

quantark/asset/equity/engine/validation/script/validation_stepdown_improved.py

@@ -0,0 +1,97 @@
+"""
+Validation script for Stepdown Snowball using the improved ODE-based SpatialGrid.
+
+This script verifies that the Stepdown Snowball (which has multiple closely spaced
+barriers) is priced accurately by the PDE solver using the improved adaptive grid
+logic in SpatialGrid.build_tavella_randall_multi.
+
+Target: Error < 2% vs 500k path Monte Carlo.
+"""
+
+import sys
+import os
+sys.path.insert(0, ".")
+
+from datetime import datetime
+import numpy as np
+
+from quantark.asset.equity.product.option.snowball_helpers import create_stepdown_snowball
+from quantark.asset.equity.engine.mc.snowball_mc_engine import SnowballMCEngine
+from quantark.asset.equity.engine.pde.snowball_pde_solver import SnowballPDESolver
+from quantark.asset.equity.param import MCParams, PDEParams
+from quantark.priceenv import PricingEnvironment
+from quantark.param import SpotQuote, FlatVolSurface, FlatRateCurve, ContinuousDividendYield
+from quantark.util.enum import MonteCarloMethod
+
+def validate_stepdown_pricing():
+    print("=" * 80)
+    print("Validation: Stepdown Snowball with Improved Adaptive Grid")
+    print("=" * 80)
+
+    # 1. Setup Product
+    # Stepdown Snowball: Barriers [103.0, 102.5, ..., 97.5]
+    S = 100.0
+    product = create_stepdown_snowball(
+        initial_price=S,
+        strike=100.0,
+        maturity=1.0,
+        contract_multiplier=10_000.0,
+        initial_ko_barrier=103.0,
+        stepdown_rate=0.005,
+        ki_barrier=75.0,
+        ko_rate=0.15
+    )
+    
+    env = PricingEnvironment(
+        valuation_date=datetime(2025, 1, 1),
+        spot_quote=SpotQuote(S),
+        rate_curve=FlatRateCurve(0.03),
+        vol_surface=FlatVolSurface(0.20),
+        div_yield=ContinuousDividendYield(0.0)
+    )
+
+    # 2. Run Benchmark MC (500k paths)
+    print("\n[1/2] Running Benchmark Monte Carlo (500k paths)...")
+    mc_engine = SnowballMCEngine(
+        params=MCParams(num_paths=500000, seed=42),
+        method=MonteCarloMethod.QUASI
+    )
+    mc_price = mc_engine.price(product, env)
+    print(f"      MC Price: {mc_price:,.2f}")
+
+    # 3. Run PDE with Auto Grid
+    print("\n[2/2] Running PDE with Auto Grid (Improved SpatialGrid)...")
+    # Using default grid_size=400, auto_grid=True
+    pde_solver = SnowballPDESolver(
+        params=PDEParams(grid_size=400, time_steps=300, auto_grid=True)
+    )
+    pde_price = pde_solver.price(product, env)
+    print(f"      PDE Price: {pde_price:,.2f}")
+
+    # 4. Analyze Results
+    diff = pde_price - mc_price
+    rel_error = diff / mc_price
+    
+    print("\nResults Analysis:")
+    print(f"  Difference: {diff:,.2f}")
+    print(f"  Rel Error:  {rel_error:.2%}")
+    
+    # Check grid quality implicitly by inspecting the object
+    # (Accessing protected members for validation report)
+    x_vec, s_vec, _, _, _ = pde_solver._build_grids(product, env, S, 0.20, 1.0, 0.03, 0.0)
+    barrier_min = min(product.barrier_config.ko_barrier)
+    barrier_max = max(product.barrier_config.ko_barrier)
+    points_in_barrier = len(s_vec[(s_vec >= barrier_min) & (s_vec <= barrier_max)])
+    
+    print(f"  Grid Points in Barrier Range [{barrier_min}, {barrier_max}]: {points_in_barrier}")
+    
+    if abs(rel_error) < 0.02:
+        print("\n✅ PASSED: Error is within 2% tolerance.")
+        return True
+    else:
+        print("\n❌ FAILED: Error exceeds 2% tolerance.")
+        return False
+
+if __name__ == "__main__":
+    success = validate_stepdown_pricing()
+    sys.exit(0 if success else 1)

quantark/asset/equity/param/__init__.py

@@ -0,0 +1,24 @@
+"""
+Equity pricing parameters.
+"""
+from .engine_params import EngineParams, MCParams, PDEParams, QuadParams, BumpConfig
+from .engine_param_profiles import (
+    ENGINE_PARAM_PRESETS,
+    list_param_profiles,
+    make_engine_params,
+    make_pde_params,
+    make_quad_params,
+)
+
+__all__ = [
+    'EngineParams',
+    'MCParams',
+    'PDEParams',
+    'QuadParams',
+    'BumpConfig',
+    'ENGINE_PARAM_PRESETS',
+    'list_param_profiles',
+    'make_engine_params',
+    'make_pde_params',
+    'make_quad_params',
+]

quantark/asset/equity/param/engine_param_profiles.py

@@ -0,0 +1,325 @@
+"""
+Preset profiles and factory helpers for engine parameter objects.
+"""
+
+from dataclasses import fields
+import json
+from pathlib import Path
+from typing import Any, Dict, Mapping, Optional, Tuple, Union
+
+from quantark.util.exceptions import ValidationError
+
+from .engine_params import PDEParams, QuadParams
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - optional dependency
+    yaml = None
+
+ProfileMap = Dict[str, Dict[str, Any]]
+
+_PROFILE_NAMES = (
+    "fast",
+    "balanced",
+    "accurate",
+    "barrier_sensitive",
+    "reverse_sensitive",
+)
+
+QUAD_PARAM_PRESETS: ProfileMap = {
+    "fast": {
+        "grid_points": 401,
+        "num_std_devs": 8.0,
+        "fft_padding_factor": 2,
+        "fft_filter_alpha": 12.0,
+        "fft_filter_power": 8,
+    },
+    "balanced": {},
+    "accurate": {
+        "grid_points": 1601,
+        "num_std_devs": 12.0,
+        "fft_padding_factor": 2,
+        "fft_filter_alpha": 18.0,
+        "fft_filter_power": 8,
+    },
+    "barrier_sensitive": {
+        "grid_points": 1201,
+        "num_std_devs": 10.0,
+        "fft_padding_factor": 2,
+        "fft_filter_alpha": 18.0,
+        "fft_filter_power": 8,
+        "event_smoothing_mode": "auto",
+        "event_smoothing_kernel": "cosine",
+        "event_smoothing_log_width": 0.002,
+        "align_priority": "auto",
+    },
+    "reverse_sensitive": {
+        "grid_points": 1201,
+        "num_std_devs": 10.0,
+        "fft_padding_factor": 2,
+        "fft_filter_alpha": 18.0,
+        "fft_filter_power": 8,
+        "align_priority": "ko",
+        "event_smoothing_mode": "reverse_aware",
+        "event_smoothing_kernel": "cosine",
+    },
+}
+
+PDE_PARAM_PRESETS: ProfileMap = {
+    "fast": {
+        "grid_size": 200,
+        "time_steps": 100,
+        "auto_grid": True,
+    },
+    "balanced": {},
+    "accurate": {
+        "grid_size": 800,
+        "time_steps": 400,
+        "auto_grid": True,
+    },
+    "barrier_sensitive": {
+        "grid_size": 600,
+        "time_steps": 300,
+        "auto_grid": True,
+        "log_dx_target": 0.002,
+        "barrier_refine_log_width": 0.02,
+        "barrier_refine_levels": 2,
+        "barrier_domain_expand": 0.1,
+        "event_steps_per_day": 6,
+    },
+    "reverse_sensitive": {
+        "grid_size": 600,
+        "time_steps": 300,
+        "auto_grid": True,
+        "log_dx_target": 0.002,
+        "barrier_refine_log_width": 0.03,
+        "barrier_refine_levels": 2,
+        "barrier_domain_expand": 0.15,
+        "event_steps_per_day": 6,
+    },
+}
+
+ENGINE_PARAM_PRESETS: Dict[str, ProfileMap] = {
+    "quad": QUAD_PARAM_PRESETS,
+    "pde": PDE_PARAM_PRESETS,
+}
+
+
+def list_param_profiles(engine: str) -> Tuple[str, ...]:
+    engine_key = _normalize_engine(engine)
+    return tuple(ENGINE_PARAM_PRESETS[engine_key].keys())
+
+
+def make_quad_params(
+    profile: str = "balanced",
+    product: Optional[Any] = None,
+    reverse: bool = False,
+    **overrides: Any,
+) -> QuadParams:
+    profile_name = _normalize_profile("quad", profile)
+    preset = dict(QUAD_PARAM_PRESETS[profile_name])
+    preset = _apply_quad_product_hints(preset, product, reverse)
+    merged = _merge_overrides(preset, overrides, QuadParams)
+    return QuadParams(**merged)
+
+
+def make_pde_params(
+    profile: str = "balanced",
+    product: Optional[Any] = None,
+    reverse: bool = False,
+    **overrides: Any,
+) -> PDEParams:
+    profile_name = _normalize_profile("pde", profile)
+    preset = dict(PDE_PARAM_PRESETS[profile_name])
+    preset = _apply_pde_product_hints(preset, product, reverse)
+    merged = _merge_overrides(preset, overrides, PDEParams)
+    return PDEParams(**merged)
+
+
+def make_engine_params(
+    engine: str,
+    profile: str = "balanced",
+    product: Optional[Any] = None,
+    reverse: bool = False,
+    **overrides: Any,
+) -> Union[QuadParams, PDEParams]:
+    engine_key = _normalize_engine(engine)
+    if engine_key == "quad":
+        return make_quad_params(
+            profile=profile, product=product, reverse=reverse, **overrides
+        )
+    if engine_key == "pde":
+        return make_pde_params(
+            profile=profile, product=product, reverse=reverse, **overrides
+        )
+    raise ValidationError(
+        f"Unknown engine '{engine}'. Supported engines: {', '.join(ENGINE_PARAM_PRESETS)}"
+    )
+
+
+def load_param_config(config_or_path: Union[Mapping[str, Any], str, Path]) -> Dict[str, Any]:
+    if isinstance(config_or_path, Mapping):
+        return dict(config_or_path)
+
+    path = Path(config_or_path)
+    if not path.exists():
+        raise ValidationError(f"Config path does not exist: {path}")
+
+    ext = path.suffix.lower()
+    if ext in (".yaml", ".yml"):
+        if yaml is None:
+            raise ValidationError("PyYAML is required to load YAML configs.")
+        with path.open("r", encoding="utf-8") as handle:
+            data = yaml.safe_load(handle)
+    elif ext == ".json":
+        with path.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    else:
+        raise ValidationError(
+            f"Unsupported config extension: {ext}. Use .yaml, .yml, or .json."
+        )
+
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValidationError("Config must contain a top-level mapping.")
+    return data
+
+
+def parse_profile_config(
+    config_or_path: Union[Mapping[str, Any], str, Path],
+    engine: str,
+    profile: Optional[str] = None,
+    reverse: Optional[bool] = None,
+) -> Tuple[str, Dict[str, Any], bool]:
+    data = load_param_config(config_or_path)
+    engine_key = _normalize_engine(engine)
+
+    config_engine = data.get("engine")
+    if config_engine is not None and str(config_engine).lower() != engine_key:
+        raise ValidationError(
+            f"Config engine '{config_engine}' does not match requested engine '{engine_key}'."
+        )
+
+    profile_name = profile or data.get("profile") or "balanced"
+    reverse_flag = reverse if reverse is not None else bool(data.get("reverse", False))
+
+    overrides = data.get("overrides")
+    if overrides is None:
+        overrides = data.get("params")
+    if overrides is None:
+        reserved = {"engine", "profile", "overrides", "params", "reverse"}
+        overrides = {k: v for k, v in data.items() if k not in reserved}
+
+    if overrides is None:
+        overrides = {}
+    if not isinstance(overrides, dict):
+        raise ValidationError("Config overrides must be a mapping.")
+
+    return str(profile_name), dict(overrides), reverse_flag
+
+
+def _normalize_engine(engine: str) -> str:
+    if engine is None:
+        raise ValidationError("Engine must be provided.")
+    engine_key = str(engine).lower()
+    if engine_key not in ENGINE_PARAM_PRESETS:
+        raise ValidationError(
+            f"Unknown engine '{engine}'. Supported engines: {', '.join(ENGINE_PARAM_PRESETS)}"
+        )
+    return engine_key
+
+
+def _normalize_profile(engine: str, profile: str) -> str:
+    engine_key = _normalize_engine(engine)
+    if profile is None:
+        return "balanced"
+    profile_key = str(profile).lower()
+    if profile_key not in ENGINE_PARAM_PRESETS[engine_key]:
+        profiles = ", ".join(sorted(ENGINE_PARAM_PRESETS[engine_key]))
+        raise ValidationError(
+            f"Unknown profile '{profile}'. Supported profiles: {profiles}"
+        )
+    return profile_key
+
+
+def _merge_overrides(
+    preset: Dict[str, Any],
+    overrides: Mapping[str, Any],
+    param_cls: Any,
+) -> Dict[str, Any]:
+    merged = dict(preset)
+    if overrides:
+        _validate_keys(overrides, param_cls)
+        merged.update(overrides)
+    _validate_keys(merged, param_cls)
+    return merged
+
+
+def _validate_keys(values: Mapping[str, Any], param_cls: Any) -> None:
+    allowed = {field.name for field in fields(param_cls)}
+    unknown = sorted(set(values) - allowed)
+    if unknown:
+        raise ValidationError(
+            f"Unknown parameter keys for {param_cls.__name__}: {', '.join(unknown)}"
+        )
+
+
+def _apply_quad_product_hints(
+    preset: Dict[str, Any],
+    product: Optional[Any],
+    reverse: bool,
+) -> Dict[str, Any]:
+    reverse_flag = reverse or bool(getattr(product, "is_reverse", False))
+    if reverse_flag:
+        preset.setdefault("align_priority", "ko")
+        preset.setdefault("event_smoothing_mode", "reverse_aware")
+    return preset
+
+
+def _apply_pde_product_hints(
+    preset: Dict[str, Any],
+    product: Optional[Any],
+    reverse: bool,
+) -> Dict[str, Any]:
+    reverse_flag = reverse or bool(getattr(product, "is_reverse", False))
+    has_barrier = _product_has_barrier(product)
+
+    if has_barrier:
+        preset.setdefault("barrier_refine_log_width", 0.02)
+        preset.setdefault("barrier_refine_levels", 1)
+    if reverse_flag:
+        preset.setdefault("barrier_domain_expand", 0.1)
+        preset.setdefault("barrier_refine_log_width", 0.03)
+
+    return preset
+
+
+def _product_has_barrier(product: Optional[Any]) -> bool:
+    if product is None:
+        return False
+    barrier_fields = (
+        "barrier",
+        "upper_barrier",
+        "lower_barrier",
+        "barrier_low",
+        "barrier_high",
+        "ko_barrier",
+        "ki_barrier",
+        "coupon_barrier",
+    )
+    for name in barrier_fields:
+        if hasattr(product, name):
+            value = getattr(product, name)
+            if value is None:
+                continue
+            if isinstance(value, (int, float)):
+                if value > 0:
+                    return True
+            elif isinstance(value, (list, tuple)):
+                if any(isinstance(v, (int, float)) and v > 0 for v in value):
+                    return True
+            else:
+                return True
+    return False
+