quantlite 0.8.0__tar.gz → 0.9.0__tar.gz

{quantlite-0.8.0/src/quantlite.egg-info → quantlite-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlite
-Version: 0.8.0
+Version: 0.9.0
 Summary: A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite.
 Author-email: Prasant Sudhakaran <code@prasant.net>
 License: MIT License
@@ -716,6 +716,104 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
 | `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
 | `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+| `quantlite.simulation.evt_simulation` | EVT tail simulation, parametric tail simulation, historical bootstrap EVT, scenario fan |
+| `quantlite.simulation.copula_mc` | Gaussian copula MC, t-copula MC, stress correlation MC, joint tail probability |
+| `quantlite.simulation.regime_mc` | Regime-switching simulation, stress test scenarios, reverse stress test, simulation summary |
+
+## v0.9: Fat-Tail Monte Carlo
+
+Three simulation families that go beyond naive Monte Carlo. Standard MC assumes returns are Gaussian and independent. QuantLite's fat-tail MC uses EVT for realistic tails, copulas for joint dependence, and regime switching for structural breaks.
+
+### EVT Tail Simulation
+
+Generate scenarios with GPD-fitted tails that respect the true shape of financial returns.
+
+```python
+import numpy as np
+from quantlite.simulation import evt_tail_simulation, scenario_fan
+
+rng = np.random.default_rng(42)
+returns = np.concatenate([
+    rng.normal(0.0003, 0.01, 900),
+    rng.standard_t(3, 100) * 0.03,
+])
+
+# EVT-based scenario generation
+simulated = evt_tail_simulation(returns, n_scenarios=20000, seed=42)
+print(f"Historical 1st pctl: {np.percentile(returns, 1):.4f}")
+print(f"Simulated 1st pctl:  {np.percentile(simulated, 1):.4f}")
+
+# Fan chart across multiple horizons
+fan = scenario_fan(returns, horizons=[1, 5, 21, 63, 252])
+for h in fan["horizons"]:
+    p5, p95 = fan["fans"][h]["5"], fan["fans"][h]["95"]
+    print(f"  {h:>3}d: [{p5:+.2%}, {p95:+.2%}]")
+```
+
+![EVT Tail Simulation](docs/images/evt_tail_simulation.png)
+
+![Scenario Fan](docs/images/scenario_fan.png)
+
+### Copula Monte Carlo
+
+Multivariate simulation that preserves fat-tailed marginals and captures tail dependence.
+
+```python
+import numpy as np
+from quantlite.simulation import t_copula_mc, joint_tail_probability
+
+rng = np.random.default_rng(42)
+fund_a = np.concatenate([rng.normal(0.0005, 0.012, 900), rng.standard_t(3, 100) * 0.03])
+fund_b = np.concatenate([rng.normal(0.0003, 0.015, 900), rng.standard_t(4, 100) * 0.025])
+corr = np.array([[1.0, 0.6], [0.6, 1.0]])
+
+# t-copula captures tail dependence that Gaussian copula misses
+simulated = t_copula_mc([fund_a, fund_b], corr, df=4, n_scenarios=50000)
+
+result = joint_tail_probability(simulated, thresholds=[-0.03, -0.03])
+print(f"Joint crash probability: {result['joint_probability']:.4f}")
+print(f"Marginal probabilities:  {result['marginal_probabilities']}")
+```
+
+![Copula Comparison](docs/images/copula_comparison.png)
+
+![Stressed Correlations](docs/images/stressed_correlations.png)
+
+### Regime-Switching Simulation
+
+Paths that switch between calm, volatile, and crisis regimes via a Markov chain.
+
+```python
+import numpy as np
+from quantlite.simulation import (
+    regime_switching_simulation,
+    reverse_stress_test,
+    simulation_summary,
+)
+
+regimes = [
+    {"mu": 0.0004, "sigma": 0.008},   # Calm
+    {"mu": 0.0001, "sigma": 0.020},   # Volatile
+    {"mu": -0.002, "sigma": 0.035},   # Crisis
+]
+transition = np.array([
+    [0.95, 0.04, 0.01],
+    [0.10, 0.80, 0.10],
+    [0.05, 0.15, 0.80],
+])
+
+sim = regime_switching_simulation(regimes, transition, n_steps=252, n_scenarios=5000)
+stats = simulation_summary(sim["returns"])
+print(f"VaR 95%: {stats['var']['95%']:.2%}")
+print(f"CVaR 95%: {stats['cvar']['95%']:.2%}")
+print(f"P(loss > 20%): {stats['probability_of_ruin']['20%']:.2%}")
+```
+
+![Regime Simulation](docs/images/regime_simulation.png)
+
+![Reverse Stress Test](docs/images/reverse_stress_test.png)
+
+See [docs/simulation_evt.md](docs/simulation_evt.md), [docs/simulation_copula.md](docs/simulation_copula.md), and [docs/simulation_regime.md](docs/simulation_regime.md) for the full API reference.
 
 ## v0.8: Factor Models
 

{quantlite-0.8.0 → quantlite-0.9.0}/README.md

@@ -635,6 +635,104 @@ Same Stephen Few theme, same muted palette, but with hover info, zoom, and nativ
 | `quantlite.factors.classical` | Fama-French three/five-factor, Carhart four-factor, factor attribution, factor summary |
 | `quantlite.factors.custom` | CustomFactor, significance testing, correlation matrix, factor portfolios, decay analysis |
 | `quantlite.factors.tail_risk` | CVaR decomposition, regime factor exposure, crowding score, tail factor beta |
+| `quantlite.simulation.evt_simulation` | EVT tail simulation, parametric tail simulation, historical bootstrap EVT, scenario fan |
+| `quantlite.simulation.copula_mc` | Gaussian copula MC, t-copula MC, stress correlation MC, joint tail probability |
+| `quantlite.simulation.regime_mc` | Regime-switching simulation, stress test scenarios, reverse stress test, simulation summary |
+
+## v0.9: Fat-Tail Monte Carlo
+
+Three simulation families that go beyond naive Monte Carlo. Standard MC assumes returns are Gaussian and independent. QuantLite's fat-tail MC uses EVT for realistic tails, copulas for joint dependence, and regime switching for structural breaks.
+
+### EVT Tail Simulation
+
+Generate scenarios with GPD-fitted tails that respect the true shape of financial returns.
+
+```python
+import numpy as np
+from quantlite.simulation import evt_tail_simulation, scenario_fan
+
+rng = np.random.default_rng(42)
+returns = np.concatenate([
+    rng.normal(0.0003, 0.01, 900),
+    rng.standard_t(3, 100) * 0.03,
+])
+
+# EVT-based scenario generation
+simulated = evt_tail_simulation(returns, n_scenarios=20000, seed=42)
+print(f"Historical 1st pctl: {np.percentile(returns, 1):.4f}")
+print(f"Simulated 1st pctl:  {np.percentile(simulated, 1):.4f}")
+
+# Fan chart across multiple horizons
+fan = scenario_fan(returns, horizons=[1, 5, 21, 63, 252])
+for h in fan["horizons"]:
+    p5, p95 = fan["fans"][h]["5"], fan["fans"][h]["95"]
+    print(f"  {h:>3}d: [{p5:+.2%}, {p95:+.2%}]")
+```
+
+![EVT Tail Simulation](docs/images/evt_tail_simulation.png)
+
+![Scenario Fan](docs/images/scenario_fan.png)
+
+### Copula Monte Carlo
+
+Multivariate simulation that preserves fat-tailed marginals and captures tail dependence.
+
+```python
+import numpy as np
+from quantlite.simulation import t_copula_mc, joint_tail_probability
+
+rng = np.random.default_rng(42)
+fund_a = np.concatenate([rng.normal(0.0005, 0.012, 900), rng.standard_t(3, 100) * 0.03])
+fund_b = np.concatenate([rng.normal(0.0003, 0.015, 900), rng.standard_t(4, 100) * 0.025])
+corr = np.array([[1.0, 0.6], [0.6, 1.0]])
+
+# t-copula captures tail dependence that Gaussian copula misses
+simulated = t_copula_mc([fund_a, fund_b], corr, df=4, n_scenarios=50000)
+
+result = joint_tail_probability(simulated, thresholds=[-0.03, -0.03])
+print(f"Joint crash probability: {result['joint_probability']:.4f}")
+print(f"Marginal probabilities:  {result['marginal_probabilities']}")
+```
+
+![Copula Comparison](docs/images/copula_comparison.png)
+
+![Stressed Correlations](docs/images/stressed_correlations.png)
+
+### Regime-Switching Simulation
+
+Paths that switch between calm, volatile, and crisis regimes via a Markov chain.
+
+```python
+import numpy as np
+from quantlite.simulation import (
+    regime_switching_simulation,
+    reverse_stress_test,
+    simulation_summary,
+)
+
+regimes = [
+    {"mu": 0.0004, "sigma": 0.008},   # Calm
+    {"mu": 0.0001, "sigma": 0.020},   # Volatile
+    {"mu": -0.002, "sigma": 0.035},   # Crisis
+]
+transition = np.array([
+    [0.95, 0.04, 0.01],
+    [0.10, 0.80, 0.10],
+    [0.05, 0.15, 0.80],
+])
+
+sim = regime_switching_simulation(regimes, transition, n_steps=252, n_scenarios=5000)
+stats = simulation_summary(sim["returns"])
+print(f"VaR 95%: {stats['var']['95%']:.2%}")
+print(f"CVaR 95%: {stats['cvar']['95%']:.2%}")
+print(f"P(loss > 20%): {stats['probability_of_ruin']['20%']:.2%}")
+```
+
+![Regime Simulation](docs/images/regime_simulation.png)
+
+![Reverse Stress Test](docs/images/reverse_stress_test.png)
+
+See [docs/simulation_evt.md](docs/simulation_evt.md), [docs/simulation_copula.md](docs/simulation_copula.md), and [docs/simulation_regime.md](docs/simulation_regime.md) for the full API reference.
 
 ## v0.8: Factor Models
 

{quantlite-0.8.0 → quantlite-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantlite"
-version = "0.8.0"
+version = "0.9.0"
 description = "A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite."
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

{quantlite-0.8.0 → quantlite-0.9.0}/src/quantlite/__init__.py

@@ -77,6 +77,8 @@ __all__ = [
     "diversification",
     # Crypto-native risk
     "crypto",
+    # Fat-tail Monte Carlo simulation
+    "simulation",
 ]
 
 from . import (  # noqa: E402
@@ -90,4 +92,5 @@ from . import (  # noqa: E402
     overfit,
     resample,
     scenarios,
+    simulation,
 )

quantlite-0.9.0/src/quantlite/simulation/__init__.py

@@ -0,0 +1,45 @@
+"""Fat-tail Monte Carlo simulation: EVT scenarios, copula MC, and regime switching.
+
+Provides three families of simulation:
+
+1. **EVT simulation** -- GPD-based tail sampling with empirical body.
+2. **Copula Monte Carlo** -- multivariate simulation with fat-tailed marginals.
+3. **Regime Monte Carlo** -- regime-switching paths, stress tests, and reverse stress tests.
+"""
+
+from .copula_mc import (
+    gaussian_copula_mc,
+    joint_tail_probability,
+    stress_correlation_mc,
+    t_copula_mc,
+)
+from .evt_simulation import (
+    evt_tail_simulation,
+    historical_bootstrap_evt,
+    parametric_tail_simulation,
+    scenario_fan,
+)
+from .regime_mc import (
+    regime_switching_simulation,
+    reverse_stress_test,
+    simulation_summary,
+    stress_test_scenario,
+)
+
+__all__ = [
+    # EVT simulation
+    "evt_tail_simulation",
+    "parametric_tail_simulation",
+    "historical_bootstrap_evt",
+    "scenario_fan",
+    # Copula MC
+    "gaussian_copula_mc",
+    "t_copula_mc",
+    "stress_correlation_mc",
+    "joint_tail_probability",
+    # Regime MC
+    "regime_switching_simulation",
+    "stress_test_scenario",
+    "reverse_stress_test",
+    "simulation_summary",
+]

quantlite-0.9.0/src/quantlite/simulation/copula_mc.py

@@ -0,0 +1,238 @@
+"""Copula-based multivariate Monte Carlo simulation.
+
+Generates joint return scenarios that preserve correlation structure
+while allowing fat-tailed marginals. Supports Gaussian and Student-t
+copulas, stressed correlations, and joint tail probability estimation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats
+
+__all__ = [
+    "gaussian_copula_mc",
+    "t_copula_mc",
+    "stress_correlation_mc",
+    "joint_tail_probability",
+]
+
+
+def _to_array(x: np.ndarray | list[float]) -> np.ndarray:
+    arr = np.asarray(x, dtype=float)
+    return arr[~np.isnan(arr)]
+
+
+def _ensure_positive_definite(matrix: np.ndarray) -> np.ndarray:
+    """Ensure a correlation matrix is positive semi-definite via eigenvalue clipping."""
+    eigenvalues, eigenvectors = np.linalg.eigh(matrix)
+    eigenvalues = np.maximum(eigenvalues, 1e-8)
+    fixed = eigenvectors @ np.diag(eigenvalues) @ eigenvectors.T
+    # Re-normalise to correlation matrix
+    d = np.sqrt(np.diag(fixed))
+    fixed = fixed / np.outer(d, d)
+    np.fill_diagonal(fixed, 1.0)
+    return fixed
+
+
+def _empirical_cdf(data: np.ndarray) -> np.ndarray:
+    """Compute empirical CDF values (rank-based, in (0,1))."""
+    from scipy.stats import rankdata
+    n = len(data)
+    return rankdata(data, method="ordinal") / (n + 1)
+
+
+def _inverse_empirical(sorted_data: np.ndarray, u: np.ndarray) -> np.ndarray:
+    """Map uniform samples back to data space via empirical quantile function."""
+    n = len(sorted_data)
+    indices = np.clip((u * n).astype(int), 0, n - 1)
+    return sorted_data[indices]
+
+
+def gaussian_copula_mc(
+    marginals: list[np.ndarray] | np.ndarray,
+    correlation_matrix: np.ndarray,
+    n_scenarios: int = 10000,
+    seed: int = 42,
+) -> np.ndarray:
+    """Multivariate simulation using a Gaussian copula with empirical marginals.
+
+    Generates correlated uniform samples via a Gaussian copula, then
+    maps them back to the empirical marginal distributions. This
+    preserves the correlation structure while retaining the fat tails
+    of each individual asset's return distribution.
+
+    Args:
+        marginals: List of 1-D arrays, one per asset, containing
+            historical returns. Each array defines the marginal
+            distribution for that asset.
+        correlation_matrix: Square correlation matrix of shape
+            ``(n_assets, n_assets)``.
+        n_scenarios: Number of joint scenarios to generate.
+        seed: Random seed.
+
+    Returns:
+        Array of shape ``(n_scenarios, n_assets)`` with simulated returns.
+    """
+    rng = np.random.default_rng(seed)
+    n_assets = len(marginals)
+    corr = _ensure_positive_definite(np.asarray(correlation_matrix, dtype=float))
+
+    # Generate correlated normal samples
+    L = np.linalg.cholesky(corr)
+    z = rng.standard_normal((n_scenarios, n_assets))
+    correlated_z = z @ L.T
+
+    # Transform to uniform via normal CDF
+    u = stats.norm.cdf(correlated_z)
+
+    # Map to empirical marginals
+    result = np.empty((n_scenarios, n_assets))
+    for j in range(n_assets):
+        sorted_m = np.sort(_to_array(marginals[j]))
+        result[:, j] = _inverse_empirical(sorted_m, u[:, j])
+
+    return result
+
+
+def t_copula_mc(
+    marginals: list[np.ndarray] | np.ndarray,
+    correlation_matrix: np.ndarray,
+    df: int = 4,
+    n_scenarios: int = 10000,
+    seed: int = 42,
+) -> np.ndarray:
+    """Multivariate simulation using a Student-t copula.
+
+    The t-copula generates tail dependence: extreme events across
+    assets are more likely to co-occur than under a Gaussian copula.
+    Lower degrees of freedom produce stronger tail dependence.
+
+    Args:
+        marginals: List of 1-D arrays, one per asset.
+        correlation_matrix: Correlation matrix.
+        df: Degrees of freedom for the t-copula (default 4).
+        n_scenarios: Number of scenarios.
+        seed: Random seed.
+
+    Returns:
+        Array of shape ``(n_scenarios, n_assets)``.
+    """
+    rng = np.random.default_rng(seed)
+    n_assets = len(marginals)
+    corr = _ensure_positive_definite(np.asarray(correlation_matrix, dtype=float))
+
+    L = np.linalg.cholesky(corr)
+    z = rng.standard_normal((n_scenarios, n_assets))
+    correlated_z = z @ L.T
+
+    # Scale by chi-squared for t-distribution
+    chi2 = rng.chisquare(df, size=n_scenarios)
+    scaling = np.sqrt(df / chi2)
+    t_samples = correlated_z * scaling[:, np.newaxis]
+
+    # Transform to uniform via t CDF
+    u = stats.t.cdf(t_samples, df=df)
+
+    result = np.empty((n_scenarios, n_assets))
+    for j in range(n_assets):
+        sorted_m = np.sort(_to_array(marginals[j]))
+        result[:, j] = _inverse_empirical(sorted_m, u[:, j])
+
+    return result
+
+
+def stress_correlation_mc(
+    marginals: list[np.ndarray] | np.ndarray,
+    correlation_matrix: np.ndarray,
+    stress_factor: float = 1.5,
+    n_scenarios: int = 10000,
+    seed: int = 42,
+) -> np.ndarray:
+    """Simulate under stressed correlations.
+
+    In crises, correlations tend to move towards 1.0. This function
+    scales off-diagonal correlations by ``stress_factor``, capping
+    at 1.0, then simulates using a Gaussian copula.
+
+    Args:
+        marginals: List of 1-D arrays, one per asset.
+        correlation_matrix: Base correlation matrix.
+        stress_factor: Multiplier for off-diagonal correlations
+            (default 1.5). Values > 1 increase correlation.
+        n_scenarios: Number of scenarios.
+        seed: Random seed.
+
+    Returns:
+        Array of shape ``(n_scenarios, n_assets)``.
+    """
+    corr = np.asarray(correlation_matrix, dtype=float).copy()
+    n = corr.shape[0]
+
+    # Stress the off-diagonal elements
+    for i in range(n):
+        for j in range(n):
+            if i != j:
+                corr[i, j] = np.clip(corr[i, j] * stress_factor, -1.0, 1.0)
+
+    corr = _ensure_positive_definite(corr)
+    return gaussian_copula_mc(marginals, corr, n_scenarios=n_scenarios, seed=seed)
+
+
+def joint_tail_probability(
+    simulated_returns: np.ndarray,
+    thresholds: list[float] | np.ndarray,
+) -> dict[str, float]:
+    """Compute joint tail probabilities from simulation output.
+
+    Estimates the probability of multiple assets simultaneously
+    breaching their respective thresholds (all falling below
+    their threshold in the same scenario).
+
+    Args:
+        simulated_returns: Array of shape ``(n_scenarios, n_assets)``
+            from a copula simulation.
+        thresholds: List of return thresholds, one per asset
+            (negative for losses, e.g. ``[-0.05, -0.03]``).
+
+    Returns:
+        Dictionary with:
+
+        - ``"joint_probability"``: probability all assets breach
+          simultaneously
+        - ``"marginal_probabilities"``: list of individual breach
+          probabilities
+        - ``"conditional_probabilities"``: probability of joint breach
+          given each asset breaches
+        - ``"n_joint_breaches"``: count of joint breach scenarios
+        - ``"n_scenarios"``: total scenarios
+    """
+    thresholds_arr = np.asarray(thresholds, dtype=float)
+    n_scenarios = simulated_returns.shape[0]
+    n_assets = simulated_returns.shape[1]
+
+    # Individual breaches
+    breaches = simulated_returns < thresholds_arr[np.newaxis, :]
+    marginal_counts = breaches.sum(axis=0)
+    marginal_probs = [float(c / n_scenarios) for c in marginal_counts]
+
+    # Joint breach: all assets breach simultaneously
+    joint_breach = np.all(breaches, axis=1)
+    joint_count = int(joint_breach.sum())
+    joint_prob = joint_count / n_scenarios
+
+    # Conditional probabilities
+    conditional_probs = []
+    for j in range(n_assets):
+        if marginal_counts[j] > 0:
+            conditional_probs.append(float(joint_count / marginal_counts[j]))
+        else:
+            conditional_probs.append(0.0)
+
+    return {
+        "joint_probability": joint_prob,
+        "marginal_probabilities": marginal_probs,
+        "conditional_probabilities": conditional_probs,
+        "n_joint_breaches": joint_count,
+        "n_scenarios": n_scenarios,
+    }