quantark 0.2.3__tar.gz → 0.2.4__tar.gz

{quantark-0.2.3 → quantark-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantark
-Version: 0.2.3
+Version: 0.2.4
 Summary: Modular derivatives pricing and risk library: options, autocallables, bonds, VaR, SIMM
 Project-URL: Homepage, https://github.com/deiiiiii93/quantark
 Project-URL: Repository, https://github.com/deiiiiii93/quantark

{quantark-0.2.3 → quantark-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quantark"
-version = "0.2.3"
+version = "0.2.4"
 description = "Modular derivatives pricing and risk library: options, autocallables, bonds, VaR, SIMM"
 readme = "README.md"
 requires-python = ">=3.10"

{quantark-0.2.3 → quantark-0.2.4}/quantark/__init__.py

@@ -1,3 +1,3 @@
 """QuantArk: professional financial derivatives pricing library."""
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"

{quantark-0.2.3 → quantark-0.2.4}/quantark/asset/equity/engine/base_engine.py

@@ -69,6 +69,7 @@ class BaseEngine(ABC):
         product: BaseEquityProduct,
         pricing_env: PricingEnvironment,
         emit_distribution: bool = True,
+        streams: "Optional[frozenset]" = None,
     ) -> "PricingResult":
         """
         Return product NPV and an event distribution for cash-leg valuation.
@@ -77,6 +78,10 @@ class BaseEngine(ABC):
         generalized EventDistribution. Engines without event stats fall back to
         a maturity-only distribution, which is sufficient for deterministic and
         full-schedule cash legs.
+
+        ``streams`` (the EventType set the caller needs, [§11.1]) is honored by
+        engines that support column pruning (the PDE autocallable solvers);
+        other engines ignore it and return the full distribution.
         """
         from quantark.cashleg.event_distribution import EventDistribution, PricingResult
 

quantark-0.2.4/quantark/asset/equity/engine/pde/backward_operator.py

@@ -0,0 +1,137 @@
+"""Shared backward-in-time Crank-Nicolson interior operator.
+
+``BackwardOperator`` owns the tridiagonal INTERIOR operator (l, c, u) for a fixed
+spatial grid and produces, per (dt, theta), the banded LHS system and the RHS
+tridiagonal coefficients — cached, so a factorization is built once and reused
+across every column solved on the same step.
+
+Boundary conditions live in the RHS/boundary rows, NOT in this interior matrix,
+so the value sweep (Dirichlet value BCs) and the indicator sweep (Neumann /
+zero-slope BCs) can share ONE factorization [§11.2]. The per-step damping
+schedule (``theta_by_step``) is also owned here so both sweeps run the identical
+Rannacher schedule — required for price/probability consistency and for the
+factorization to be shareable across sweeps.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Optional, Sequence, Tuple
+
+import numpy as np
+
+from quantark.util.numerical import is_close
+
+
+class BackwardOperator:
+    """Fixed interior tridiagonal operator with a per-(dt, theta) banded cache."""
+
+    def __init__(
+        self,
+        l: np.ndarray,
+        c: np.ndarray,
+        u: np.ndarray,
+        *,
+        use_banded: bool = True,
+        cache_enabled: bool = True,
+        cache_max_entries: int = 512,
+    ) -> None:
+        self._l = np.asarray(l, dtype=float)
+        self._c = np.asarray(c, dtype=float)
+        self._u = np.asarray(u, dtype=float)
+        self.use_banded = use_banded
+        self._cache_enabled = cache_enabled
+        self._cache_max_entries = max(1, int(cache_max_entries))
+        self._banded_cache: "OrderedDict[Tuple[float, float], Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]]" = (
+            OrderedDict()
+        )
+
+    def _build(
+        self, dt: float, theta: float
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        l, c, u = self._l, self._c, self._u
+        lower = -theta * dt * l[2:-1]
+        main = 1.0 - theta * dt * c[1:-1]
+        upper = -theta * dt * u[1:-2]
+
+        banded = np.zeros((3, len(main)))
+        banded[0, 1:] = upper
+        banded[1, :] = main
+        banded[2, :-1] = lower
+
+        lower1 = (1.0 - theta) * dt * l[2:-1]
+        main1 = 1.0 + (1.0 - theta) * dt * c[1:-1]
+        upper1 = (1.0 - theta) * dt * u[1:-2]
+        return banded, lower1, main1, upper1
+
+    def banded_system(
+        self, dt: float, theta: float
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        """Return ``(banded, lower1, main1, upper1)`` for the CN step at (dt, theta).
+
+        ``banded`` is the LHS ``I - theta*dt*A`` in scipy banded form; the three
+        1-D vectors are the RHS ``I + (1-theta)*dt*A`` tridiagonals. Identical to
+        the former ``SnowballPDESolver._get_banded_system`` output.
+        """
+        if not self._cache_enabled:
+            return self._build(dt, theta)
+
+        key = (round(dt, 12), round(theta, 12))
+        cached = self._banded_cache.get(key)
+        if cached is not None:
+            self._banded_cache.move_to_end(key)
+            return cached
+
+        result = self._build(dt, theta)
+        self._banded_cache[key] = result
+        self._banded_cache.move_to_end(key)
+        if len(self._banded_cache) > self._cache_max_entries:
+            self._banded_cache.popitem(last=False)
+        return result
+
+    def clear_cache(self) -> None:
+        self._banded_cache.clear()
+
+    @staticmethod
+    def theta_by_step(
+        t_vec: np.ndarray,
+        dt_vec: np.ndarray,
+        params,
+        discontinuity_times: Optional[Sequence[float]],
+    ) -> np.ndarray:
+        """Per-step Crank-Nicolson theta (length ``len(t_vec) - 1``) [§11.2].
+
+        Reproduces the pricing sweep's Rannacher rule exactly: step ``j`` (the
+        backward step from ``t_vec[j+1]`` to ``t_vec[j]``) uses backward-Euler
+        (``theta = 1``) within ``rannacher_steps`` of the terminal payoff, else
+        ``event_theta`` for the ``event_rannacher_steps`` steps immediately
+        before each discontinuity node, else ``params.theta``.
+
+        Depends only on ``discontinuity_times`` (always KO ∪ KI ∪ coupon), so the
+        schedule is identical regardless of which streams a downstream consumer
+        selects — a prerequisite for sharing the factorization across sweeps.
+        """
+        t_vec = np.asarray(t_vec, dtype=float)
+        num_t = len(t_vec)
+        n_steps = num_t - 1
+        theta = np.full(n_steps, float(params.theta), dtype=float)
+        if not params.use_rannacher:
+            return theta
+
+        smooth_js: set = set()
+        if params.auto_grid and params.rannacher_at_events and discontinuity_times:
+            for et in discontinuity_times:
+                idx = int(np.argmin(np.abs(t_vec - et)))
+                if 0 < idx < num_t - 1 and is_close(float(t_vec[idx]), float(et)):
+                    for k in range(int(params.event_rannacher_steps)):
+                        sj = idx - 1 - k
+                        if sj >= 0:
+                            smooth_js.add(sj)
+
+        for j in range(n_steps):
+            steps_from_end = num_t - 1 - j
+            if steps_from_end < params.rannacher_steps:
+                theta[j] = 1.0
+            elif j in smooth_js:
+                theta[j] = float(params.event_theta)
+        return theta

{quantark-0.2.3 → quantark-0.2.4}/quantark/asset/equity/engine/pde/base_pde_solver.py

@@ -8,6 +8,7 @@ backward in time, with support for Rannacher smoothing.
 from abc import abstractmethod
 from collections import OrderedDict
 from copy import deepcopy
+from dataclasses import dataclass, field
 import math
 import threading
 from typing import Dict, Optional, Tuple, List, NamedTuple, Sequence
@@ -28,6 +29,24 @@ from .time_grid import TimeGrid
 from .spatial_grid import SpatialGrid
 
 
+@dataclass(frozen=True)
+class TimeGridSpec:
+    """The three orthogonal time-grid concerns (spec §4 Component 1).
+
+    * ``align_times``  — times that MUST be grid nodes exactly: KO/coupon
+      observation dates.  They drive both node alignment and the
+      event-distribution resets, so a misalignment here is a correctness bug.
+    * ``monitor_times`` — extra nodes that improve resolution of a monitored
+      feature (daily-discrete KI) but are not alignment-critical for the
+      value/cashflow.  Empty for European/continuous/no-KI regimes.
+    * ``steps_per_day`` — resolution: fill density between mandatory nodes.
+    """
+
+    align_times: list
+    monitor_times: list = field(default_factory=list)
+    steps_per_day: float = 1.0
+
+
 class PDESolutionResult(NamedTuple):
     """
     Result from PDE solving containing solution and grid data.
@@ -155,10 +174,17 @@ class BasePDESolver(BaseEngine):
         s_min, s_max = self._resolve_spatial_bounds(
             product, spot, sigma, tau, r, q, barriers
         )
+        # Freeze the critical points at the base spot too [§11.4]: otherwise
+        # include_spot_in_critical_points re-snaps the grid to a bumped spot,
+        # so a spot bump mixes true delta/gamma with grid-movement noise.
+        frozen_critical = tuple(
+            self._resolve_critical_points(product, pricing_env, spot, barriers)
+        )
 
         fixed_params = deepcopy(self.params)
         fixed_params.s_min = float(s_min)
         fixed_params.s_max = float(s_max)
+        fixed_params.frozen_critical_points = frozen_critical
         return type(self)(params=fixed_params)
 
     def _freeze_cache_value(self, value):
@@ -252,6 +278,8 @@ class BasePDESolver(BaseEngine):
             params.theta,
             params.use_rannacher,
             params.rannacher_steps,
+            params.frozen_critical_points,
+            getattr(params, "ki_monitoring_mode", None),
         )
 
     def _grid_cache_key(
@@ -619,6 +647,14 @@ class BasePDESolver(BaseEngine):
     ) -> List[float]:
         """Merge raw critical points with dynamic points (spot/barriers)."""
         params: PDEParams = self.params
+
+        # Frozen (bump-context) critical points are used verbatim so the grid is
+        # invariant to spot/vol/rate/div bumps [§11.4].
+        if params.frozen_critical_points is not None:
+            return sorted(
+                {float(p) for p in params.frozen_critical_points if p is not None and p > 0}
+            )
+
         points = list(raw_points)
 
         if params.auto_grid:
@@ -659,25 +695,80 @@ class BasePDESolver(BaseEngine):
 
         return size, adaptive
 
+    def _time_grid_spec(self, product, tau) -> "TimeGridSpec":
+        """Decoupled time-grid concerns for this product (spec §4 Component 1).
+
+        Base default: align to the generic observation schedule; no KI-monitor
+        concept (that belongs to autocallable solvers, which override this);
+        resolution from params.  Returns interior times only (0 < t < tau).
+        """
+        align = [
+            t for t in (self._get_event_times(product, tau) or []) if 0.0 < t < tau
+        ]
+        return TimeGridSpec(
+            align_times=sorted(set(align)),
+            monitor_times=[],
+            steps_per_day=float(self.params.event_steps_per_day),
+        )
+
     def _resolve_time_grid(
         self, product, tau, barriers
     ) -> Tuple[np.ndarray, np.ndarray]:
-        """Determine time grid type and number of steps."""
+        """Build the time grid from the decoupled ``_time_grid_spec`` seam.
+
+        When the product has mandatory event nodes (KO/coupon alignment plus any
+        KI-monitor times), the grid is built by ``TimeGrid.build_mandatory``:
+        every event time lands on a node exactly, and resolution between nodes is
+        set solely by ``steps_per_day`` (no per-interval floor).  This path is
+        market-independent — it depends only on ``tau``, the schedule,
+        ``steps_per_day`` and params — so spot/vol/rate/div bumps reprice on an
+        identical grid [§4.5], and it always feeds the day-based resolution
+        params, fixing the historical ``auto_grid=False`` param drop (root cause
+        2) that inflated daily-KI grids ~10x.
+
+        When there are no discrete event nodes (continuous barriers, American,
+        European), the base resolution heuristics are preserved unchanged.
+        """
         params: PDEParams = self.params
+        spec = self._time_grid_spec(product, tau)
+        mandatory = sorted(
+            {
+                t
+                for t in (list(spec.align_times) + list(spec.monitor_times))
+                if 0.0 < t < tau
+            }
+        )
+
+        # Event alignment engages when the config wants an event-aligned grid:
+        # auto_grid (auto-selects alignment when events exist, as before) or an
+        # explicit event grid type. An explicit auto_grid=False + uniform/graded
+        # request is honored literally (plain grid), matching prior behavior.
+        want_event_aligned = params.auto_grid or params.time_grid_type in (
+            "event_aligned",
+            "event_clustered",
+        )
+        if mandatory and want_event_aligned:
+            return TimeGrid.build_mandatory(
+                tau,
+                mandatory,
+                steps_per_day=spec.steps_per_day,
+                day_count=int(params.bus_days_in_year),
+                max_steps_total=params.max_time_steps,
+            )
+
+        # No event alignment requested: preserve the base resolution heuristics.
         obs_type = getattr(product, "observation_type", None)
         has_barriers = len(barriers) > 0
-        event_times = self._get_event_times(product, tau)
 
         if not params.auto_grid:
             return TimeGrid.build(
                 tau,
                 params.time_steps,
                 method=params.time_grid_type,
-                event_times=event_times,
+                event_times=None,
                 grade_exponent=params.grade_exponent,
             )
 
-        # Logic for suggested time steps
         days = max(1, int(round(tau * float(params.bus_days_in_year))))
         suggested = days
         if has_barriers:
@@ -689,24 +780,13 @@ class BasePDESolver(BaseEngine):
             suggested = int(round(1.5 * float(days)))
 
         steps = min(max(params.time_steps, suggested), params.max_time_steps)
-
-        # Decide method
-        method = "uniform"
-        if event_times and (has_barriers or obs_type == ObservationType.DISCRETE):
-            method = "event_aligned"
-        elif params.time_grid_type != "uniform":
-            method = params.time_grid_type
-
+        method = params.time_grid_type if params.time_grid_type != "uniform" else "uniform"
         return TimeGrid.build(
             tau,
             steps,
             method=method,
-            event_times=event_times,
+            event_times=None,
             grade_exponent=params.grade_exponent,
-            steps_per_day=params.event_steps_per_day,
-            day_count=params.bus_days_in_year,
-            min_steps_per_interval=params.event_min_steps_per_interval,
-            max_steps_total=params.max_time_steps,
         )
 
     def _calculate_coefficients(

{quantark-0.2.3 → quantark-0.2.4}/quantark/asset/equity/engine/pde/ko_reset_snowball_pde_solver.py

@@ -57,8 +57,17 @@ class KOResetSnowballPDESolver(SnowballPDESolver):
     # price() is inherited from SnowballPDESolver using _check_product_type()
 
     def calculate_event_stats(
-        self, product: KnockOutResetSnowballOption, pricing_env: PricingEnvironment
+        self,
+        product: KnockOutResetSnowballOption,
+        pricing_env: PricingEnvironment,
+        *,
+        npv: Optional[float] = None,
+        streams: Optional[frozenset] = None,
     ) -> Optional[object]:
+        # streams is ignored: the KO-reset stats are QUAD-delegated (full
+        # distribution), not a prunable PDE indicator sweep. npv, when supplied
+        # by the single-pass price_with_events, is the PDE value used for the
+        # reconciliation residual (avoids a redundant self.price() solve).
         if not isinstance(product, KnockOutResetSnowballOption):
             return None
         if pricing_env is None:
@@ -75,7 +84,7 @@ class KOResetSnowballPDESolver(SnowballPDESolver):
         if quad_stats is None:
             return None
 
-        pde_pv = float(self.price(product, pricing_env))
+        pde_pv = float(npv) if npv is not None else float(self.price(product, pricing_env))
         pv_delta = pde_pv - float(quad_stats.pv)
         return replace(
             quad_stats,
@@ -232,22 +241,33 @@ class KOResetSnowballPDESolver(SnowballPDESolver):
 
         return result
 
-    def _get_event_times(
+    def _post_ki_ko_times(
         self, product: KnockOutResetSnowballOption, tau: float
-    ) -> Optional[List[float]]:
-        event_times = super()._get_event_times(product, tau) or []
+    ) -> List[float]:
+        """Post-KI (reset) KO observation times, interior to (0, tau).
+
+        In the two-surface KO-reset PDE the post-KI KO schedule fires on the V1
+        (knocked-in) surface; those dates must be grid nodes exactly [§11.7].
+        """
+        out = []
         post_schedule = product.post_barrier_config.ko_observation_schedule
         if post_schedule is not None:
-            for rec in post_schedule.records:
-                if rec.observation_time is not None:
-                    t = rec.observation_time
-                    if 0 < t < tau:
-                        event_times.append(t)
+            out += [
+                rec.observation_time
+                for rec in post_schedule.records
+                if rec.observation_time is not None
+            ]
         elif product.post_barrier_config.ko_observation_dates is not None:
-            for t in product.post_barrier_config.ko_observation_dates:
-                if 0 < t < tau:
-                    event_times.append(t)
-        return sorted(set(event_times)) if event_times else None
+            out += list(product.post_barrier_config.ko_observation_dates)
+        return sorted({float(t) for t in out if t is not None and 0.0 < float(t) < tau})
+
+    def _ko_coupon_align_times(
+        self, product: KnockOutResetSnowballOption, tau: float
+    ) -> List[float]:
+        """Pre-KI KO ∪ post-KI (reset) KO — both must align exactly [§11.7]."""
+        pre = super()._ko_coupon_align_times(product, tau)
+        post = self._post_ki_ko_times(product, tau)
+        return sorted(set(pre) | set(post))
 
     def get_critical_points(
         self, product: KnockOutResetSnowballOption, pricing_env: PricingEnvironment

{quantark-0.2.3 → quantark-0.2.4}/quantark/asset/equity/engine/pde/phoenix_pde_solver.py

@@ -236,6 +236,9 @@ class PhoenixPDESolver(SnowballPDESolver):
             else:
                 self._ki_barrier = ki_barrier
 
+        # Resolve BGK state before grids so the time grid drops interior KI nodes.
+        self._configure_bgk(product, pricing_env, sigma, tau)
+
         if self._profile_enabled:
             self._reset_profile_stats()
 
@@ -288,7 +291,11 @@ class PhoenixPDESolver(SnowballPDESolver):
             )
 
         if product.has_ki_barrier:
-            should_apply_ki = self._ki_continuous or terminal_tidx in self._ki_observation_indices
+            should_apply_ki = (
+                self._ki_continuous
+                or self._bgk_active
+                or terminal_tidx in self._ki_observation_indices
+            )
             if should_apply_ki:
                 for k in range(len(grid_v0_list)):
                     self._apply_ki_jump(grid_v0_list[k], grid_v1_list[k], s_vec, terminal_tidx, product)
@@ -583,7 +590,11 @@ class PhoenixPDESolver(SnowballPDESolver):
 
         # 2. KI Jump
         if product.has_ki_barrier:
-            should_apply_ki = self._ki_continuous or t_idx in self._ki_observation_indices
+            should_apply_ki = (
+                self._ki_continuous
+                or self._bgk_active
+                or t_idx in self._ki_observation_indices
+            )
             if should_apply_ki:
                 # Apply to all states
                 for k in range(len(grid_v0_list)):