quantark 0.1.0__py3-none-any.whl

quantark/asset/equity/process/bsm/qmc_rqmc_driver.py

@@ -0,0 +1,163 @@
+"""
+Created on Mon Nov 17 2025
+
+@description: RQMC batching and adaptive stopping driver for Monte Carlo
+               pricing engines using GBMPathGenerator or similar path
+               generators.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Dict, Optional, Protocol, Tuple
+
+import numpy as np
+
+
+class PathGenerator(Protocol):
+    """
+    Minimal protocol for path generators compatible with the RQMC driver.
+    """
+
+    num_paths: int
+
+    def generate_paths(
+        self,
+        seed: Optional[int] = None,
+        batch_id: Optional[int] = None,
+        return_aux: bool = False,
+    ) -> Tuple[np.ndarray, Optional[Dict[str, np.ndarray]]]:
+        ...
+
+
+PricerFn = Callable[[np.ndarray, Optional[Dict[str, np.ndarray]]], np.ndarray]
+
+
+@dataclass
+class RQMCResult:
+    """
+    Result container for RQMC batching runs.
+    """
+
+    price: float
+    std_error: float
+    total_paths: int
+    batches_used: int
+    batch_means: np.ndarray
+
+
+def run_rqmc(
+    pricer_fn: PricerFn,
+    path_generator: PathGenerator,
+    max_batches: int,
+    target_std: float,
+    min_batches: int = 1,
+) -> RQMCResult:
+    """
+    Run randomized QMC (RQMC) in batches with adaptive stopping.
+
+    Each batch corresponds to an independent scrambled Sobol sequence (or
+    independent pseudorandom run), and the estimator is the average of the
+    batch means. The standard error is based on the sample variance of the
+    batch means.
+
+    Parameters
+    ----------
+    pricer_fn : callable
+        Function with signature pricer_fn(paths, aux) -> payoffs_per_path,
+        where paths is an array of shape (n_paths, n_steps + 1) and aux is
+        a dictionary with auxiliary data (e.g., importance weights).
+    path_generator : PathGenerator
+        Path generator implementing the PathGenerator protocol.
+    max_batches : int
+        Maximum number of RQMC batches to run.
+    target_std : float
+        Target standard error for stopping the simulation.
+    min_batches : int, optional
+        Minimum number of batches to run before checking the stopping
+        criterion.
+
+    Returns
+    -------
+    RQMCResult
+        Result object containing the estimated price, standard error,
+        total number of paths used, and per-batch means.
+    """
+    if max_batches <= 0:
+        raise ValueError("max_batches must be positive")
+    if min_batches <= 0:
+        raise ValueError("min_batches must be positive")
+    if min_batches > max_batches:
+        raise ValueError("min_batches cannot exceed max_batches")
+    if target_std <= 0.0:
+        raise ValueError("target_std must be positive")
+
+    batch_means = []
+    n_paths_per_batch = path_generator.num_paths
+
+    # Welford's algorithm over batch means
+    mean = 0.0
+    m2 = 0.0
+
+    for batch_id in range(max_batches):
+        paths, aux = path_generator.generate_paths(batch_id=batch_id, return_aux=True)
+        payoffs = pricer_fn(paths, aux)
+        payoffs = np.asarray(payoffs, dtype=float)
+        if payoffs.ndim != 1 or payoffs.shape[0] != n_paths_per_batch:
+            raise ValueError(
+                "pricer_fn must return a 1D array with one payoff per path "
+                f"(expected length {n_paths_per_batch}, got {payoffs.shape})."
+            )
+
+        batch_mean = float(payoffs.mean())
+        batch_means.append(batch_mean)
+
+        n = batch_id + 1
+        delta = batch_mean - mean
+        mean += delta / n
+        m2 += delta * (batch_mean - mean)
+
+        if n >= min_batches:
+            if n > 1:
+                variance = m2 / (n - 1)
+            else:
+                variance = 0.0
+            std_error = np.sqrt(variance / n)
+
+            if std_error <= target_std or n == max_batches:
+                return RQMCResult(
+                    price=mean,
+                    std_error=std_error,
+                    total_paths=n * n_paths_per_batch,
+                    batches_used=n,
+                    batch_means=np.array(batch_means, dtype=float),
+                )
+
+    # Fallback (should not normally reach here)
+    if len(batch_means) == 0:
+        raise RuntimeError("No batches were run in RQMC driver.")
+
+    n = len(batch_means)
+    batch_means_arr = np.array(batch_means, dtype=float)
+    mean = float(batch_means_arr.mean())
+    if n > 1:
+        variance = float(batch_means_arr.var(ddof=1))
+    else:
+        variance = 0.0
+    std_error = np.sqrt(variance / n)
+
+    return RQMCResult(
+        price=mean,
+        std_error=std_error,
+        total_paths=n * n_paths_per_batch,
+        batches_used=n,
+        batch_means=batch_means_arr,
+    )
+
+
+__all__ = [
+    "RQMCResult",
+    "run_rqmc",
+]
+
+

quantark/asset/equity/process/bsm/qmc_sobol.py

@@ -0,0 +1,195 @@
+"""
+Created on Mon Nov 17 2025
+
+@author: yaofuxin
+@description: Sobol-based and pseudorandom normal generators for MC/QMC path
+               construction, with support for RQMC batching.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol
+
+import numpy as np
+
+try:
+    from scipy import special
+    from scipy.stats import qmc
+
+    HAS_SCIPY_QMC = True
+except ImportError:  # pragma: no cover - fallback path without SciPy
+    HAS_SCIPY_QMC = False
+    special = None  # type: ignore
+    qmc = None  # type: ignore
+
+
+class RandomStream(Protocol):
+    """
+    Minimal interface for random streams used by path generators.
+
+    Implementations should return standard normal random numbers with shape
+    (n_paths, dim). The optional batch_id is used to generate independent
+    randomized QMC batches.
+    """
+
+    def normal(
+        self, n_paths: int, dim: int, batch_id: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Generate standard normal random numbers.
+
+        Parameters
+        ----------
+        n_paths : int
+            Number of Monte Carlo paths.
+        dim : int
+            Dimension of each path (typically number of time steps).
+        batch_id : int, optional
+            Identifier for the RQMC batch. Implementations can use this to
+            produce independent randomized batches.
+
+        Returns
+        -------
+        np.ndarray
+            Array of shape (n_paths, dim) with N(0, 1) samples.
+        """
+        ...
+
+
+@dataclass
+class PseudoRandomNormalGenerator:
+    """
+    Pseudorandom standard normal generator based on NumPy.
+
+    This implements the RandomStream protocol and is suitable for classical
+    Monte Carlo simulations.
+    """
+
+    seed: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        self._rng = np.random.default_rng(self.seed)
+
+    def normal(
+        self, n_paths: int, dim: int, batch_id: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Generate standard normal samples using NumPy's Generator.
+
+        The batch_id argument is accepted for API compatibility but ignored,
+        since independent batches are handled via the RNG state.
+        """
+        return self._rng.standard_normal(size=(n_paths, dim))
+
+
+def _next_power_of_two(n: int) -> int:
+    """Return the smallest power of two >= n."""
+    if n <= 1:
+        return 1
+    return 1 << (n - 1).bit_length()
+
+
+@dataclass
+class SobolNormalGenerator:
+    """
+    Sobol-based standard normal generator with optional RQMC batching.
+
+    This class wraps scipy.stats.qmc.Sobol and uses scipy.special.ndtri to
+    transform low-discrepancy uniform samples into standard normals. To
+    preserve Sobol structure, the number of generated samples is always a
+    power of two (2**m). If the requested path count is not a power of two,
+    the generator will either round up and truncate or raise an error,
+    depending on the configuration.
+    """
+
+    base_seed: int = 1234
+    strict_power_of_two: bool = False
+
+    def _check_scipy(self) -> None:
+        if not HAS_SCIPY_QMC:
+            raise ImportError(
+                "SobolNormalGenerator requires scipy.stats.qmc and scipy.special.ndtri. "
+                "Please install SciPy or use PseudoRandomNormalGenerator instead."
+            )
+
+    def _make_engine(self, dim: int, batch_id: Optional[int]) -> "qmc.Sobol":
+        """
+        Create a new Sobol engine for the given dimension and batch.
+
+        A different seed is used for each batch_id to obtain independent
+        scrambled Sobol sequences (RQMC).
+        """
+        self._check_scipy()
+        # Use different seeds for different batches to obtain independent scrambles
+        if batch_id is None:
+            seed = self.base_seed
+        else:
+            seed = self.base_seed + int(batch_id)
+        return qmc.Sobol(d=dim, scramble=True, seed=seed)  # type: ignore[call-arg]
+
+    def normal(
+        self, n_paths: int, dim: int, batch_id: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Generate standard normal samples using a scrambled Sobol sequence.
+
+        Parameters
+        ----------
+        n_paths : int
+            Requested number of paths.
+        dim : int
+            Dimension of each path (typically number of time steps).
+        batch_id : int, optional
+            Batch identifier for RQMC. Different batch_ids produce independent
+            randomized Sobol sequences.
+
+        Returns
+        -------
+        np.ndarray
+            Array of shape (n_paths, dim) containing N(0, 1) samples.
+        """
+        if n_paths <= 0:
+            raise ValueError("n_paths must be positive")
+        if dim <= 0:
+            raise ValueError("dim must be positive")
+
+        self._check_scipy()
+
+        # Ensure we use exactly 2**m Sobol points to preserve balance properties
+        n_total = _next_power_of_two(n_paths)
+        if self.strict_power_of_two and n_total != n_paths:
+            raise ValueError(
+                f"SobolNormalGenerator with strict_power_of_two=True requires "
+                f"n_paths to be a power of two, got {n_paths}."
+            )
+
+        m = int(np.log2(n_total))
+        engine = self._make_engine(dim=dim, batch_id=batch_id)
+
+        # Use random_base2 to get exactly 2**m points
+        u = engine.random_base2(m)  # shape: (n_total, dim)
+        # Guard against 0/1 values that map to +/-inf under ndtri
+        eps = 1e-12
+        u = np.clip(u, eps, 1.0 - eps)
+
+        # Transform uniforms to standard normals using ndtri
+        if special is None:
+            # Fallback, should not happen if _check_scipy passed
+            from scipy.stats import norm  # type: ignore
+
+            z = norm.ppf(u)
+        else:
+            z = special.ndtri(u)
+
+        if n_paths != n_total:
+            z = z[:n_paths]
+
+        return np.asarray(z, dtype=float)
+
+
+__all__ = [
+    "RandomStream",
+    "PseudoRandomNormalGenerator",
+    "SobolNormalGenerator",
+]

quantark/asset/equity/process/bsm/qmc_variance_reduction.py

@@ -0,0 +1,292 @@
+"""
+Created on Mon Nov 17 2025
+
+@author: yaofuxin
+@description: Variance reduction utilities (antithetic variates, control
+               variates, importance sampling) designed to work with both
+               classical MC and QMC without destroying Sobol structure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import numpy as np
+
+
+@dataclass
+class VarianceReductionConfig:
+    """
+    Configuration for variance reduction techniques.
+
+    Parameters
+    ----------
+    antithetic : bool
+        Whether to use antithetic variates. This is intended for classical
+        MC (pseudorandom) and is disabled for QMC by default.
+    control_variate : bool
+        Whether to construct a GBM-based control variate.
+    importance_sampling : bool
+        Whether to apply a mean shift to the driving Brownian increments.
+    importance_shift : float
+        Shift parameter used in importance sampling. The same shift is applied
+        to all normal dimensions.
+    control_variate_mu : float, optional
+        Drift parameter for the GBM control variate.
+    control_variate_sigma : float, optional
+        Volatility for the GBM control variate.
+    control_variate_T : float, optional
+        Maturity of the GBM control variate.
+    """
+
+    antithetic: bool = False
+    control_variate: bool = False
+    importance_sampling: bool = False
+    importance_shift: float = 0.0
+    control_variate_mu: Optional[float] = None
+    control_variate_sigma: Optional[float] = None
+    control_variate_T: Optional[float] = None
+
+
+def build_antithetic_pairs(z: np.ndarray) -> np.ndarray:
+    """
+    Construct antithetic variates from a base matrix of standard normals.
+
+    Parameters
+    ----------
+    z : np.ndarray
+        Base standard normals of shape (n_base_paths, dim).
+
+    Returns
+    -------
+    np.ndarray
+        Array of shape (2 * n_base_paths, dim) containing [z, -z].
+    """
+    z = np.asarray(z, dtype=float)
+    return np.concatenate([z, -z], axis=0)
+
+
+def apply_importance_sampling_shift(z: np.ndarray, shift: float) -> np.ndarray:
+    """
+    Apply a constant mean shift to standard normal samples.
+
+    This function is safe for QMC usage because it preserves the low-discrepancy
+    structure of the underlying sequence while changing the sampling measure.
+
+    Parameters
+    ----------
+    z : np.ndarray
+        Standard normal samples of shape (n_paths, dim).
+    shift : float
+        Constant shift applied to all dimensions.
+
+    Returns
+    -------
+    np.ndarray
+        Shifted standard normals of the same shape as z.
+    """
+    z = np.asarray(z, dtype=float)
+    if shift == 0.0:
+        return z
+    return z + shift
+
+
+def importance_sampling_weights(z_shifted: np.ndarray, shift: float) -> np.ndarray:
+    """
+    Compute likelihood ratio weights for Gaussian importance sampling.
+
+    If Z' ~ N(shift, 1), the Radon–Nikodym derivative dP/dQ at Z' is
+
+        w = exp(shift * Z' - 0.5 * shift^2)
+
+    For a d-dimensional vector of independent components, the total weight is
+
+        w = exp(shift * sum(Z'_j) - 0.5 * d * shift^2).
+
+    Parameters
+    ----------
+    z_shifted : np.ndarray
+        Shifted standard normal samples of shape (n_paths, dim), i.e., samples
+        drawn from N(shift, 1) along each dimension.
+    shift : float
+        Shift parameter used in the importance sampling scheme.
+
+    Returns
+    -------
+    np.ndarray
+        Weights of shape (n_paths,) to reweight payoffs back to the original
+        N(0, 1) measure.
+    """
+    z_shifted = np.asarray(z_shifted, dtype=float)
+    if z_shifted.ndim != 2:
+        raise ValueError("z_shifted must be a 2D array of shape (n_paths, dim)")
+    if shift == 0.0:
+        return np.ones(z_shifted.shape[0], dtype=float)
+
+    n_paths, dim = z_shifted.shape
+    sum_z = np.sum(z_shifted, axis=1)
+    exponent = shift * sum_z - 0.5 * (shift ** 2) * dim
+    return np.exp(exponent)
+
+
+def gbm_control_variate(
+    z: np.ndarray,
+    mu: float,
+    sigma: float,
+    T: float,
+) -> np.ndarray:
+    """
+    Construct a GBM-based control variate using the same driving normals.
+
+    This control variate follows the exact GBM solution:
+
+        S_t = exp((mu - 0.5 * sigma^2) * t + sigma * sqrt(t) * Z)
+
+    using the column-wise time points.
+
+    Parameters
+    ----------
+    z : np.ndarray
+        Standard normal samples of shape (n_paths, n_steps).
+    mu : float
+        Drift parameter.
+    sigma : float
+        Volatility parameter.
+    T : float
+        Maturity.
+
+    Returns
+    -------
+    np.ndarray
+        Control variate array of shape (n_paths, n_steps), with one control
+        variate value per time step along each path.
+    """
+    z = np.asarray(z, dtype=float)
+    if z.ndim != 2:
+        raise ValueError("z must be a 2D array of shape (n_paths, n_steps)")
+
+    n_steps = z.shape[1]
+    if n_steps <= 0:
+        raise ValueError("n_steps must be positive")
+
+    dt = T / n_steps
+    t = np.arange(1, n_steps + 1, dtype=float) * dt
+
+    drift = (mu - 0.5 * sigma * sigma) * t
+    diffusion = sigma * np.sqrt(t)
+
+    drift = drift.reshape(1, -1)
+    diffusion = diffusion.reshape(1, -1)
+
+    return np.exp(drift + diffusion * z)
+
+
+def apply_variance_reduction_to_normals(
+    n_paths: int,
+    dim: int,
+    base_normals: np.ndarray,
+    vr_config: Optional[VarianceReductionConfig],
+    is_qmc: bool,
+) -> Tuple[np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]:
+    """
+    Apply configured variance reduction techniques to a matrix of normals.
+
+    Parameters
+    ----------
+    n_paths : int
+        Desired final number of paths.
+    dim : int
+        Dimension of each path.
+    base_normals : np.ndarray
+        Base N(0, 1) samples of shape (n_paths, dim) or smaller if antithetic
+        variates will expand the path count.
+    vr_config : VarianceReductionConfig, optional
+        Variance reduction configuration.
+    is_qmc : bool
+        Whether the underlying sampling is QMC (Sobol). Antithetic variates are
+        disabled by default in QMC mode to avoid destroying low-discrepancy
+        structure.
+
+    Returns
+    -------
+    z_processed : np.ndarray
+        Processed normals of shape (n_paths, dim) after applying antithetic
+        variates and/or importance sampling.
+    weights : np.ndarray or None
+        Importance sampling weights if enabled, otherwise None.
+    control_variate : np.ndarray or None
+        GBM-based control variate if enabled, otherwise None.
+    """
+    z = np.asarray(base_normals, dtype=float)
+    if z.ndim != 2:
+        raise ValueError("base_normals must be a 2D array")
+
+    weights: Optional[np.ndarray] = None
+    control_variate: Optional[np.ndarray] = None
+
+    if vr_config is None:
+        if z.shape != (n_paths, dim):
+            raise ValueError(
+                f"Expected base_normals to have shape ({n_paths}, {dim}) without "
+                f"variance reduction, got {z.shape}."
+            )
+        return z, weights, control_variate
+
+    # Antithetic variates: only for classical MC by default.
+    if vr_config.antithetic:
+        if is_qmc:
+            raise ValueError(
+                "Antithetic variates are not enabled for QMC mode to avoid "
+                "breaking Sobol low-discrepancy properties."
+            )
+        # base_normals is assumed to have shape (ceil(n_paths / 2), dim)
+        z = build_antithetic_pairs(z)
+        if z.shape[0] < n_paths:
+            raise ValueError(
+                "Antithetic base_normals must be large enough to reach n_paths."
+            )
+        z = z[:n_paths, :]
+
+    # Importance sampling (safe for both MC and QMC)
+    if vr_config.importance_sampling and vr_config.importance_shift != 0.0:
+        z = apply_importance_sampling_shift(z, vr_config.importance_shift)
+        weights = importance_sampling_weights(z, vr_config.importance_shift)
+
+    # Control variate based on GBM analytical solution
+    if vr_config.control_variate:
+        if (
+            vr_config.control_variate_mu is None
+            or vr_config.control_variate_sigma is None
+            or vr_config.control_variate_T is None
+        ):
+            raise ValueError(
+                "control_variate_mu, control_variate_sigma and control_variate_T "
+                "must be provided in VarianceReductionConfig when control_variate "
+                "is enabled."
+            )
+        control_variate = gbm_control_variate(
+            z,
+            mu=vr_config.control_variate_mu,
+            sigma=vr_config.control_variate_sigma,
+            T=vr_config.control_variate_T,
+        )
+
+    if z.shape != (n_paths, dim):
+        raise ValueError(
+            f"Processed normals have shape {z.shape}, expected ({n_paths}, {dim})."
+        )
+
+    return z, weights, control_variate
+
+
+__all__ = [
+    "VarianceReductionConfig",
+    "build_antithetic_pairs",
+    "apply_importance_sampling_shift",
+    "importance_sampling_weights",
+    "gbm_control_variate",
+    "apply_variance_reduction_to_normals",
+]
+
+

quantark/asset/equity/product/__init__.py

@@ -0,0 +1,8 @@
+"""
+Equity derivative products.
+"""
+from .base_equity_product import BaseEquityProduct
+from .option import BaseEquityOption, EuropeanVanillaOption, AsianOption
+
+__all__ = ['BaseEquityProduct', 'BaseEquityOption', 'EuropeanVanillaOption', 'AsianOption']
+