Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(quantlib): stabilize Archimedean copula CDFs under large parameters

Robin1987China8d31cb7a3f43
diff --git a/agent/src/quantlib/copula.py b/agent/src/quantlib/copula.py
index 8dcf57571..f57368847 100644
--- a/agent/src/quantlib/copula.py
+++ b/agent/src/quantlib/copula.py
@@ -63,7 +63,13 @@ def clayton_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: floa
if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
raise ValueError("u and v marginals must be in (0, 1]")
- val = np.maximum(0.0, u_arr ** (-theta) + v_arr ** (-theta) - 1.0) ** (-1.0 / theta)
+ # Compute in log space so u^{-theta} never overflows for large theta:
+ # log(u^{-theta} + v^{-theta} - 1) = logaddexp(a, b) + log1p(-exp(-logaddexp(a, b)))
+ a = -theta * np.log(u_arr)
+ b = -theta * np.log(v_arr)
+ lse = np.logaddexp(a, b)
+ log_inner = lse + np.log1p(-np.exp(-lse))
+ val = np.exp(-log_inner / theta)
return float(val) if np.ndim(val) == 0 else val
@@ -95,8 +101,14 @@ def gumbel_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: float
if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
raise ValueError("u and v marginals must be in (0, 1]")
- term = (-np.log(u_arr)) ** theta + (-np.log(v_arr)) ** theta
- val = np.exp(-(term ** (1.0 / theta)))
+ # Compute in log space so (-ln u)^theta never underflows for large theta:
+ # log((-ln u)^theta + (-ln v)^theta) = logaddexp(theta*log(-log u), theta*log(-log v))
+ # A marginal of exactly 1.0 gives log(-log 1) = log(0) = -inf, which
+ # logaddexp handles correctly; silence the divide-by-zero warning.
+ with np.errstate(divide="ignore", invalid="ignore"):
+ a = theta * np.log(-np.log(u_arr))
+ b = theta * np.log(-np.log(v_arr))
+ val = np.exp(-np.exp(np.logaddexp(a, b) / theta))
return float(val) if np.ndim(val) == 0 else val
@@ -122,9 +134,22 @@ def frank_copula_cdf(u: float | np.ndarray, v: float | np.ndarray, theta: float)
if np.any((u_arr <= 0.0) | (u_arr > 1.0) | (v_arr <= 0.0) | (v_arr > 1.0)):
raise ValueError("u and v marginals must be in (0, 1]")
- num = (np.exp(-theta * u_arr) - 1.0) * (np.exp(-theta * v_arr) - 1.0)
- den = np.exp(-theta) - 1.0
- val = -1.0 / theta * np.log(1.0 + num / den)
+ # The naive form cancels catastrophically for large theta (num/den -> -1,
+ # log(0) -> -inf). For theta > 0, factor e^{-theta*s} out of the numerator
+ # and compute in log space; each correction term underflows to 0.0
+ # harmlessly. For theta < 0 the direct form is stable over any realistic
+ # parameter, so it is kept unchanged.
+ if theta > 0:
+ s = np.minimum(u_arr, v_arr)
+ t = np.maximum(u_arr, v_arr)
+ inner = 1.0 + np.exp(-theta * (t - s)) - np.exp(-theta * t) - np.exp(-theta * (1.0 - s))
+ log_num = -theta * s + np.log(inner)
+ log_den = np.log1p(-np.exp(-theta))
+ val = -(1.0 / theta) * (log_num - log_den)
+ else:
+ num = (np.exp(-theta * u_arr) - 1.0) * (np.exp(-theta * v_arr) - 1.0)
+ den = np.exp(-theta) - 1.0
+ val = -1.0 / theta * np.log(1.0 + num / den)
return float(val) if np.ndim(val) == 0 else val
diff --git a/agent/tests/quantlib/test_copula.py b/agent/tests/quantlib/test_copula.py
index 992d971c8..52616dc87 100644
--- a/agent/tests/quantlib/test_copula.py
+++ b/agent/tests/quantlib/test_copula.py
@@ -71,3 +71,27 @@ class TestCopulaAnalytics:
# Gaussian: tau = 0.5 -> rho = sin(pi/4) ~ 0.7071
res_gauss = fit_copula_from_tau(0.5, family="gaussian")
assert res_gauss["rho"] == pytest.approx(np.sin(np.pi / 4))
+
+ def test_frank_copula_is_stable_for_large_theta(self) -> None:
+ # theta=80 used to return inf (catastrophic cancellation); the correct
+ # value converges to 0.4913356602430007 (verified at 60-digit precision).
+ val = frank_copula_cdf(0.5, 0.5, 80.0)
+ assert np.isfinite(val)
+ assert val == pytest.approx(0.4913356602430007, abs=1e-12)
+
+ def test_clayton_copula_is_stable_for_large_theta(self) -> None:
+ # theta=10000 used to return 0.0 (u^{-theta} overflowed to inf).
+ val = clayton_copula_cdf(0.5, 0.5, 10000.0)
+ assert val == pytest.approx(0.4999653438420768, abs=1e-12)
+
+ def test_gumbel_copula_is_stable_for_large_theta(self) -> None:
+ # theta=3000 used to return 1.0 ((-ln u)^theta underflowed to 0.0).
+ val = gumbel_copula_cdf(0.5, 0.5, 3000.0)
+ assert val == pytest.approx(0.4999199216595084, abs=1e-12)
+
+ def test_archimedean_cdfs_converge_to_min_under_perfect_dependence(self) -> None:
+ # Under perfect positive dependence every Archimedean copula converges
+ # to min(u, v).
+ assert frank_copula_cdf(0.3, 0.7, 200.0) == pytest.approx(0.3, abs=1e-6)
+ assert clayton_copula_cdf(0.3, 0.7, 10000.0) == pytest.approx(0.3, abs=1e-6)
+ assert gumbel_copula_cdf(0.3, 0.7, 3000.0) == pytest.approx(0.3, abs=1e-6)