9.1 随机性的结构：均匀、加权、洗牌袋

#!/usr/bin/env python3
# file: sim/gd_mech_09_randomness.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/gd_mech_09_randomness.py
"""9.1 随机性的结构：均匀、加权、洗牌袋（S 层）。

同一种「随机」在实现层有三种截然不同的**结构**，它们的分布性质差得很远：

  ① 均匀   state = rng_next(state); x = state % n          可放回、等概率
  ② 加权   整数权重前缀和 + state % total 落点              可放回、不等概率
  ③ 洗牌袋 Fisher-Yates 打乱一副袋、不放回抽取              不放回、袋内等概率

本脚本对三者各抽 K 次（K 取 n 的整数倍，保证洗牌袋恰好走完整袋），用**整数与
千分比**度量三个性质：

  - 重复率 repeatPm   相邻两次结果相同的次数 / (K-1)，千分比
  - 最长连号 maxRun   同一结果连续出现的最长长度（极值间隔的整数形态）
  - 方差代理量 varPm  频次偏离均匀的 χ² 型整数代理，千分比

全部整数运算，无浮点、无 random 模块；同一 seed 在任何机器上给同一张表。
"""
from __future__ import annotations

import os
import sys

import ashlib

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)

SEED = 20261014
N = 6                       # 结果面数：6 种等概率结果
K = 600                     # 抽样次数 = 100 个洗牌袋（K 必须是 N 的整数倍）
WEIGHTS = [1, 1, 2, 2, 3, 5]  # 整数权重，总和 14（明显偏斜）
HEADER = ["structure", "counts", "repeatPm", "maxRun", "varPm"]


def uniform_draws(n: int, k: int, seed: int) -> list:
    """均匀：可放回，每次 state % n。"""
    out = []
    state = seed % ashlib.RNG_MOD or 1
    for _ in range(k):
        state = ashlib.rng_next(state)
        out.append(state % n)
    return out


def weighted_draws(weights: list, k: int, seed: int) -> list:
    """加权：整数权重前缀和，state % total 落进哪个前缀区间就取哪一项。"""
    total = sum(weights)
    prefix = []
    acc = 0
    for w in weights:
        acc += w
        prefix.append(acc)
    out = []
    state = seed % ashlib.RNG_MOD or 1
    for _ in range(k):
        state = ashlib.rng_next(state)
        r = state % total
        for i, p in enumerate(prefix):
            if r < p:
                out.append(i)
                break
    return out


def bag_draws(n: int, k: int, seed: int) -> list:
    """洗牌袋：打乱一副 n 张袋不放回抽，抽空后用下一个 state 重洗。"""
    out = []
    state = seed % ashlib.RNG_MOD or 1
    bag = ashlib.shuffle_deck(list(range(n)), state)
    for _ in range(k):
        if not bag:
            state = ashlib.rng_next(state)
            bag = ashlib.shuffle_deck(list(range(n)), state)
        out.append(bag.pop(0))
    return out


def metrics(draws: list, n: int) -> dict:
    """三个整数 / 千分比度量。"""
    k = len(draws)
    counts = [0] * n
    for x in draws:
        counts[x] += 1
    rep = 0
    best = 1
    cur = 1
    for i in range(1, k):
        if draws[i] == draws[i - 1]:
            rep += 1
            cur += 1
            if cur > best:
                best = cur
        else:
            cur = 1
    var_num = sum((c * n - k) ** 2 for c in counts)
    var_pm = var_num * 1000 // (n * k)
    return {
        "counts": counts,
        "repeatPm": rep * 1000 // (k - 1),
        "maxRun": best,
        "varPm": var_pm,
    }


def main() -> int:
    structures = [
        ("uniform", uniform_draws(N, K, SEED)),
        ("weighted", weighted_draws(WEIGHTS, K, SEED)),
        ("bag", bag_draws(N, K, SEED)),
    ]
    rows: list = []
    for name, draws in structures:
        m = metrics(draws, N)
        rows.append([name, "|".join(str(c) for c in m["counts"]),
                     m["repeatPm"], m["maxRun"], m["varPm"]])

    out = os.path.join(ROOT, "out", "mech09_structures.csv")
    n = ashlib.write_csv(out, HEADER, rows)

    print(f"seed={SEED} n={N} k={K} weights={WEIGHTS} weightSum={sum(WEIGHTS)}")
    print(" ".join(HEADER))
    for r in rows:
        print(" ".join(str(x) for x in r))
    print(f"bagExactUniform={all(c == K // N for c in metrics(structures[2][1], N)['counts'])}")
    print(f"wrote out/mech09_structures.csv rows={n}")
    return 0


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

seed=20261014 n=6 k=600 weights=[1, 1, 2, 2, 3, 5] weightSum=14
structure counts repeatPm maxRun varPm
uniform 75|108|113|108|104|92 178 4 10020
weighted 53|36|86|87|134|204 240 6 186420
bag 100|100|100|100|100|100 35 2 0
bagExactUniform=True
wrote out/mech09_structures.csv rows=3

bag#1  [3, 2, 4, 1, 0, 5]   袋内无重复
bag#2  [0, 1, 4, 2, 5, 3]   首张 0 != 上袋末张 5
bag#3  [3, 0, 5, 4, 2, 1]   首张 3 == 上袋末张 3  → 记 1 次重复
bag#4  [5, 2, 3, 4, 1, 0]   首张 5 != 上袋末张 1
...    （100 袋，接缝共 99 处，实测同面 21 处）