quantark 0.2.3__tar.gz → 0.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantark
-Version: 0.2.3
+Version: 0.2.5
 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.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quantark"
-version = "0.2.3"
+version = "0.2.5"
 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.5}/quantark/__init__.py

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

{quantark-0.2.3 → quantark-0.2.5}/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.5/quantark/asset/equity/engine/pde/backward_operator.py

@@ -0,0 +1,140 @@
+"""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 is 1 for the first backward step off the terminal
+            # payoff, so `<=` yields exactly `rannacher_steps` implicit-Euler
+            # steps at the terminal discontinuity.
+            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.5}/quantark/asset/equity/engine/pde/barrier_pde_solver.py

@@ -5,18 +5,15 @@ Implements the finite difference method for knock-in and knock-out
 barrier options with continuous or discrete monitoring.
 """
 
-from typing import Dict, List, Optional, Set
+from typing import Dict, List
 
 import numpy as np
 
 from quantark.asset.equity.product.base_equity_product import BaseEquityProduct
 from quantark.asset.equity.product.option.barrier_option import BarrierOption
-from quantark.asset.equity.product.option.observation_schedule import ResolvedObservationRecord
-from quantark.asset.equity.param import PDEParams
 from quantark.priceenv import PricingEnvironment
 from quantark.util.enum import ObservationType, ObservationAggregation
 from quantark.util.exceptions import PricingError
-from quantark.util.numerical import is_close, safe_divide
 
 from .base_pde_solver import BasePDESolver
 
@@ -41,48 +38,12 @@ class BarrierPDESolver(BasePDESolver):
     the barrier at specified observation times.
     """
 
-    def __init__(self, params: Optional[PDEParams] = None):
-        """
-        Initialize barrier option PDE solver.
-
-        Args:
-            params: PDE engine configuration parameters
-        """
-        super().__init__(params)
-        self._observation_indices: Set[int] = set()
-        self._schedule_records: Dict[int, List[ResolvedObservationRecord]] = {}
-        self._schedule_aggregation: ObservationAggregation = (
-            ObservationAggregation.STOP_FIRST_HIT
-        )
-        self._total_tau: float = 0.0
-        self._terminal_schedule_records: List[ResolvedObservationRecord] = []
-        self._has_terminal_observation: bool = False
+    # Discrete-monitoring state (_observation_indices, _schedule_records,
+    # _terminal_schedule_records, ...) is initialized by BasePDESolver and
+    # populated by the shared _setup_observation_indices.
 
-    @staticmethod
-    def _current_time(total_tau: float, tau_remaining: float) -> float:
-        return max(total_tau - tau_remaining, 0.0)
-
-    @staticmethod
-    def _df_between_times(
-        pricing_env: PricingEnvironment, start_time: float, end_time: float
-    ) -> float:
-        if end_time <= start_time:
-            return 1.0
-        df_end = pricing_env.get_discount_factor(end_time)
-        df_start = pricing_env.get_discount_factor(start_time)
-        return float(safe_divide(df_end, df_start, fallback=0.0))
-
-    def _cashflow_value_at_time(
-        self,
-        pricing_env: PricingEnvironment,
-        cashflow: float,
-        current_time: float,
-        settlement_time: Optional[float],
-    ) -> float:
-        if settlement_time is None or settlement_time <= current_time:
-            return float(cashflow)
-        df = self._df_between_times(pricing_env, current_time, settlement_time)
-        return float(cashflow) * df
+    # _current_time / _df_between_times / _cashflow_value_at_time are
+    # inherited from BasePDESolver.
 
     def price(
         self, product: BaseEquityProduct, pricing_env: PricingEnvironment
@@ -610,56 +571,17 @@ class BarrierPDESolver(BasePDESolver):
         result = super()._build_grids(product, pricing_env, spot, sigma, tau, r, q)
         x_vec, s_vec, dx_vec, t_vec, dt_vec = result
 
-        # Setup observation time indices for discrete monitoring
-        self._total_tau = tau
-        self._observation_indices.clear()
-        self._schedule_records.clear()
-        self._schedule_aggregation = ObservationAggregation.STOP_FIRST_HIT
-        self._terminal_schedule_records = []
-        self._has_terminal_observation = False
-
-        schedule = getattr(product, "observation_schedule", None)
-        if schedule is not None:
-            resolved_records = schedule.resolve(
-                pricing_env=pricing_env,
-                default_barrier=product.barrier,
-                default_payoff=product.rebate,
-                require_single=True,
-            )
-            self._schedule_aggregation = schedule.aggregation_mode
-            if self._schedule_aggregation in (
-                ObservationAggregation.BEST,
-                ObservationAggregation.WORST,
-            ):
-                raise PricingError(
-                    f"PDE solver does not support aggregation mode {self._schedule_aggregation.value}"
-                )
-            for rec in resolved_records:
-                if is_close(rec.observation_time, 0.0):
-                    idx = 0
-                    self._observation_indices.add(idx)
-                    self._schedule_records.setdefault(idx, []).append(rec)
-                elif is_close(rec.observation_time, tau):
-                    self._terminal_schedule_records.append(rec)
-                    self._has_terminal_observation = True
-                elif 0.0 < rec.observation_time < tau:
-                    idx = int(np.argmin(np.abs(t_vec - rec.observation_time)))
-                    self._observation_indices.add(idx)
-                    self._schedule_records.setdefault(idx, []).append(rec)
-        elif (
-            hasattr(product, "observation_type")
-            and product.observation_type == ObservationType.DISCRETE
-            and hasattr(product, "observation_dates")
-            and product.observation_dates is not None
-        ):
-            for obs_time in product.observation_dates:
-                if is_close(obs_time, 0.0):
-                    self._observation_indices.add(0)
-                elif is_close(obs_time, tau):
-                    self._has_terminal_observation = True
-                elif 0.0 < obs_time < tau:
-                    idx = int(np.argmin(np.abs(t_vec - obs_time)))
-                    self._observation_indices.add(idx)
+        self._setup_observation_indices(
+            product,
+            pricing_env,
+            tau,
+            t_vec,
+            resolve_kwargs={
+                "default_barrier": product.barrier,
+                "default_payoff": product.rebate,
+                "require_single": True,
+            },
+        )
 
         return result