Bivariate Gumbel-Copula CDF Closed-Form Evaluation

实现 solution(u: float, v: float, theta: float) -> float。多资产风险部门为两个股指边际的联合上行联动建模，校准 Archimedean copula 后需要一个快速的二维 CDF 求值器，用于似然法拟合和模拟一致性检查。Gumbel copula 是在边际表现出上尾相依（联合极端上行）但无下尾相依时的标准选择——和对称的 Gaussian copula、对称双尾的 t-copula 都不同。计算并返回闭式二维 CDF

C(u, v; theta) = exp(-((-ln u)**theta + (-ln v)**theta)**(1/theta))

其中 u, v 已经在 [0, 1] 内（即边际的 CDF 坐标——本函数不做边际变换），Gumbel 参数 theta >= 1。

两个常见 bug 占了绝大多数错误提交。 第一，外层指数是 1/theta，不是 theta——把内层指数复制到外层会得到根本错误的公式，简单输入下偏离一个数量级。第二，外层 exp 前面有负号：exp(-(...))，不是 exp((...))。漏号会得到 exp(正数)，远超 1，根本不是合法 CDF。隐藏用例锁定这两类 bug。

Boundaries

公式在 u = 0 或 v = 0 时会触发 log(0)，必须按边界直接处理。完整边界规则：

• u == 0.0 或 v == 0.0：返回 0.0（边际边界处的联合 CDF 按定义为零）。
• u == 1.0：返回 v。内部求和变成 0 + (-ln v)**theta，外层 1/theta 次幂得到 -ln v，exp(-(-ln v)) = v。
• v == 1.0：返回 u（对称）。
• theta == 1.0：返回 u * v。θ=1 时 Gumbel 退化为独立 copula；闭式 exp(-(-ln u - ln v)) = exp(ln(u*v)) = u*v 一致，但显式分支可避免 1.0**(1/1) 的精度抖动。

参考实现的分支顺序是 u==0 或 v==0 优先（短路掉 log 调用），其次 u==1 与 v==1，再 theta==1，最后通用公式。隐藏用例覆盖同时命中多个边界的情形（例如 u==1, theta==1 返回 v，由于 u=1，结果与 u*v 一致）——除了 u==0 必须先于 log 短路外，其它顺序不影响数值。

Example

solution(0.5, 0.5, 2.0) 返回 0.3752142272464818。逐步：-ln 0.5 = 0.6931...。内部求和：0.6931...**2 + 0.6931...**2 = 2 * 0.4804... = 0.9609...。外层 1/2 次幂：sqrt(0.9609...) = 0.9802...。所以 C = exp(-0.9802...) ≈ 0.3752。对比独立值 u * v = 0.25：θ=2 的 Gumbel 把 C 抬高到 ≈ 0.375，反映出两个边际之间的正向（上尾）相依。

判别用例：solution(0.3, 0.5, 2.0) 返回 0.2493...。错误外层指数 bug（用 **theta 而不是 **(1/theta)）返回 0.0241...，差一个数量级。漏负号 bug（用 exp((...)) 而不是 exp(-(...))）返回 4.01...，明显不在 [0, 1] 内。两者都被该输入上的隐藏用例阻断。

Algorithm

O(1)——几次 math.log、math.exp 和 ** 调用。隐藏用例覆盖：θ=1 独立短路；u=0 / v=0 / u=1 / v=1 边界；θ=10 接近完全相依（C ≈ min(u, v)）的状态；分数 θ（如 1.5、2.5）；数值稳定边缘（u = 1e-12）；以及上述错公式判别用例。除了把公式写对之外，没有其它算法难点。

参考函数骨架见 stubs/stub.py。

Practical context

多资产风险部门为两个股指收益（称为指数 A 与指数 B）的联合分布建模。两个指数的边际 CDF 已经通过历史收益估计完毕，团队希望叠加一个 copula 来描述联合行为，重点是上行极端的联合表现（牛市联合上涨）。Gaussian copula 因为强行假设两侧都没有尾部相依被否决——经验上指数联合上涨的频率高于 Gaussian 模型预测。t-copula 假设双尾对称的尾部相依，也不合适，因为经验上的联合下跌弱于联合上涨。Gumbel copula 正好在合适位置：下尾无相依，上尾有正相依，lambda_U = 2 - 2**(1/theta)。最大似然法拟合 Gumbel 需要在每个观测处求二维 CDF 与密度，下游的 Monte Carlo 一致性检验则把模拟的联合 CDF 与本函数的闭式基准对比。solution(...) 就是闭式二维 CDF 求值器，从边际拟合和模拟流程中独立出来以便确定性单元测试。u, v ∈ {0, 1} 处的显式边界分支很关键——优化器线搜索时常常逼近单位方格的角落，那里 log(0) 直接崩溃会使拟合失败。theta == 1 处的独立短路同样关键——优化器从 θ=1（独立先验）起步向外搜索，函数必须在 θ=1 精确处返回干净的 u * v，不能有数值抖动。