7.1 概率密度与权重

# snippet: sim/cg_trace_07_1_pdf_weight.py（节选：均匀半球采样）
c = u                                   # cosθ 均匀
s = fsqrt(ONE - fmul(c, c))             # sinθ = sqrt(1 − cos²θ)
# 方位角：单位圆上的拒绝采样，再归一化
cx, cy = fdiv(x, r), fdiv(y, r)
return (fmul(s, cx), fmul(s, cy), c)

# snippet: sim/cglib.py（节选：fdiv）
def fdiv(a, b):
    if b == 0:
        raise ZeroDivisionError("fdiv by zero")
    q = (abs(a) << 16) // abs(b)
    return -q if (a < 0) != (b < 0) else q

# snippet: 本机实跑（工作区 lantern/）
cd lantern
/opt/homebrew/bin/python3 sim/cg_trace_07_1_parity.py

#!/usr/bin/env python3
# file: lantern/sim/cg_trace_07_1_parity.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_trace_07_1_parity.py
"""7.1 的紧凑驱动：调用 cg_trace_07_1_pdf_weight 的四个函数，打印正文引用的全部数字。

四块输出对应正文四件事：半球归一估计、三条 1D pdf 的均值/方差/最大权重、
fdiv 的定点截断误差、以及 P 层逐字节对照的整数缓冲。
"""

import hashlib
import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import cg_trace_07_1_pdf_weight as m  # noqa: E402

ONE = 65536


def main():
    norm = m.norm_estimates()
    shape = m.shape_study()
    wtab = m.weight_table()
    buf, vals = m.parity_values()

    print("== 7.1 概率密度与权重 ==")
    print(f"归一（半球上估 ∫ p dω，{m.N_NORM} 个均匀样本，采样 pdf = 1/2π）：")
    for k, want in (("cosine", "1"), ("uniform", "1"), ("unnormalized", "π")):
        print(f"  p = {k:<12}：{norm[k] / ONE:.6f}（应 {want}）")
    print(f"形状（f(x) = 2x，I = 1；{m.N_TRIALS} 子流 × {m.N_SAMPLES} 样本）：")
    for k in ("uniform", "matched", "anti"):
        d = shape[k]
        print(f"  p = {k:<8}：均值 {d['meanFloat']:.6f}｜相对标准差 {d['relStd']:.6f}"
              f"｜最大权重 {d['maxWeightFloat']:.4f}｜除零 {d['zeroPdfCount']}")
    print("定点权重表（fdiv vs 精确 Q16.16 值 f·65536/p）：")
    for r in wtab:
        print(f"  f={r['f']:>7} p={r['p']:>8} -> q16={r['q16']:>9}"
              f"｜精确 {r['exactQ16']:>14.6f}｜相对误差 {r['relErr']:+.9f}")
    print(f"P 层对照缓冲 sha256 : {hashlib.sha256(buf).hexdigest()}")
    print(f"缓冲值（6 个整数）  : {vals}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

== 7.1 概率密度与权重 ==
归一（半球上估 ∫ p dω，1048576 个均匀样本，采样 pdf = 1/2π）：
  p = cosine      ：1.000334（应 1）
  p = uniform     ：0.999954（应 1）
  p = unnormalized：3.142802（应 π）
形状（f(x) = 2x，I = 1；256 子流 × 4096 样本）：
  p = uniform ：均值 1.000166｜相对标准差 0.009193｜最大权重 2.0000｜除零 0
  p = matched ：均值 0.999987｜相对标准差 0.000056｜最大权重 1.0000｜除零 14
  p = anti    ：均值 0.999981｜相对标准差 0.042460｜最大权重 255.0000｜除零 0
定点权重表（fdiv vs 精确 Q16.16 值 f·65536/p）：
  f=  65536 p=   65536 -> q16=    65536｜精确   65536.000000｜相对误差 +0.000000000
  f= 131072 p=   65536 -> q16=   131072｜精确  131072.000000｜相对误差 +0.000000000
  f=  65536 p=  131072 -> q16=    32768｜精确   32768.000000｜相对误差 +0.000000000
  f=      3 p=  131072 -> q16=        1｜精确       1.500000｜相对误差 -0.333333333
  f=  65536 p=  196608 -> q16=    21845｜精确   21845.333333｜相对误差 -0.000015259
  f=      5 p=  458752 -> q16=        0｜精确       0.714286｜相对误差 -1.000000000
  f=      1 p=   65536 -> q16=        1｜精确       1.000000｜相对误差 +0.000000000
  f=  65536 p=65536000 -> q16=       65｜精确      65.536000｜相对误差 -0.008178711
  f=     17 p=  327680 -> q16=        3｜精确       3.400000｜相对误差 -0.117647059
  f=  65536 p=       7 -> q16=613566756｜精确 613566756.571429｜相对误差 -0.000000001
P 层对照缓冲 sha256 : dc20a72b1562c0de2740d98ce2d2b91598e03d79de3b48ff96c7b47e0fd6cea6
缓冲值（6 个整数）  : [1234936, 1048528, 3879846, 1147366, 1048576, 1032008]

// file: lantern/core/test/cg_trace_07_1_parity.test.ts
// tier: P
// verify: node --test 'core/test/cg_trace_07_1_parity.test.ts'
// 7.1 的最小 P 复现：读 Python 侧 cg_trace_07_1_pdf.json，把归一化常数、
// 三种权重形状的极值、以及逐字节对照缓冲的 sha256 钉住。

import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { test } from "node:test";
import { fileURLToPath } from "node:url";

import { parityBuffer, pdfWeight } from "../src/lantern/cg_trace_07_1_pdf_weight.ts";

const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
const py = JSON.parse(
  readFileSync(join(root, "out", "cg_trace_07_1_pdf.json"), "utf8"),
) as {
  norm: { cosine: number; uniform: number; unnormalized: number };
  shape: Record<string, { relStd: number; maxWeightFloat: number; zeroPdfCount: number }>;
  parity: { values: number[]; bufferSha256: string; bufferLen: number };
};

test("【核心】归一化常数：匹配 pdf 的均值是 1.000334", () => {
  assert.equal((py.norm.cosine / 65536).toFixed(6), "1.000334");
  assert.equal((py.norm.uniform / 65536).toFixed(6), "0.999954");
  assert.equal((py.norm.unnormalized / 65536).toFixed(6), "3.142802");
});

test("【核心】匹配 pdf 的权重恒为 1，相对标准差接近 0", () => {
  assert.equal(py.shape.matched.maxWeightFloat, 1);
  assert.ok(py.shape.matched.relStd < 1e-4, `匹配 pdf 的相对标准差 ${py.shape.matched.relStd}`);
  assert.equal(py.shape.matched.zeroPdfCount, 14);
});

test("【核心】逐字节对照缓冲 sha256 与 Python 侧相同", () => {
  const { buf, vals } = parityBuffer();
  assert.equal(buf.length, py.parity.bufferLen);
  assert.deepEqual(vals.map(Number), py.parity.values);
  assert.equal(createHash("sha256").update(buf).digest("hex"), py.parity.bufferSha256);
});

test("【负例】反向 pdf 把最大权重放大到 255 倍", () => {
  assert.equal(py.shape.anti.maxWeightFloat, 255);
  assert.equal(py.shape.uniform.maxWeightFloat, 2);
  assert.equal(pdfWeight(65536n, 65536n), 65536n);
  assert.equal(pdfWeight(1n, 1000n * 65536n), 0n); // 1/1000 在 Q16.16 下截断为 0
});

✔ 【核心】归一化常数：匹配 pdf 的均值是 1.000334 (0.463208ms)
✔ 【核心】匹配 pdf 的权重恒为 1，相对标准差接近 0 (0.105334ms)
✔ 【核心】逐字节对照缓冲 sha256 与 Python 侧相同 (1.102709ms)
✔ 【负例】反向 pdf 把最大权重放大到 255 倍 (0.068959ms)
ℹ tests 4 / pass 4 / fail 0