feat(solve): 审查 markov_steady_state：工程侧收口 + 8 条测试
用户实现的 markov_steady_state 经探针实测算法本体正确（3 状态与特征分解逐位一致、 200x200 一致到 1.9e-12 且只用 6 次迭代 / 0.10s），本次只动工程侧，未改任何算法行： - ruff 5 条 W293 全清；mm1_metrics 前 4 个空行 -> 2；失败文案改成全角冒号 - docstring 补 max_iter / tol 两个参数与 Raises，写清 tol 是相邻差口径 （实测慢混合链 tol=1e-10 -> 实际误差 4.6e-9，被 1/(1-|lambda2|) 放大约 50 倍） - Notes 修正"周期链会不收敛"的说法：可约链的实情是平稳分布不唯一， 迭代法给的是离初值最近的那个（均匀初值对双随机矩阵本身就是不动点） - tests/test_solve.py：摘掉 1 条 skip + 新增 7 条（该函数共 8 条实跑） - STATUS.md 新增决策 57（6 条待拍板口径）与第六轮「下一步」；CHANGELOG；易错点 28 校验：pytest 196 passed / 30 skipped（226 收集）；ruff 0；pyright 0
This commit is contained in:
guzhujushi committed
1 parent
dd9bd638b8
commit
0955890010
5 files changed
+263
-27
No files matched your search
@@ -21,10 +21,10 @@
|
||||
当前 **L0 11/12**：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`、
|
||||
`detect_outliers`、`normalize`/`standardize`、`describe`、`correlation_matrix`、`bootstrap_ci`、
|
||||
`monte_carlo`（**用户写**，2026-10-04）；另**提前落地**了 L1 的 `confidence_interval` / `t_test` /
|
||||
`monte_carlo_probability`、`monte_carlo_integral`、`random_walk`、`markov_simulate`
|
||||
（**均为用户写**，2026-10-05）。剩余 1 项：`save_figure`（Codex 写）。
|
||||
`monte_carlo_probability`、`monte_carlo_integral`、`random_walk`、`markov_simulate`、
|
||||
`markov_steady_state`（**均为用户写**）。剩余 1 项：`save_figure`（Codex 写）。
|
||||
`monte_carlo` 的口径已拍板（决策 48）；`monte_carlo_probability` / `random_walk` 的待办**均已办结**；
|
||||
`markov_simulate` 本轮审查通过（算法本体正确），留 **5 条入口口径待你拍板**（见"下一步"，决策 56 的 3 个选项）。
|
||||
`markov_simulate`（决策 56，5 条）与 `markov_steady_state`（决策 57，6 条）的**入口口径待你拍板**。
|
||||
另 3 个小口径仍悬着：`ci_low`/`ci_high` 的语义、`monte_carlo_integral` 的第一道 `isinstance` 分支可塌成两行、
|
||||
`random_state` 注解与 `std` 的 `ddof` 是否全项目对齐。
|
||||
|
||||
@@ -335,13 +335,29 @@
|
||||
`np.int64` 可收、docstring Example 真能跑
|
||||
- ⏳ **留给你的 5 条**见"下一步 → markov_simulate 待你拍板"（全是入口口径与少考虑情况，决策 49）
|
||||
|
||||
- [x] `solve/simulate.py` 的 `markov_steady_state`（**L1，S 档，算法由用户本人写**，2026-10-09）
|
||||
- 核心：`v` 从均匀分布出发，`v_next = v @ arr` 反复推进（行随机矩阵按**行向量右乘**），
|
||||
直到 `max|v_next - v| < tol` 或耗尽 `max_iter`；`data` 是平稳分布向量，`metrics={"converged", "iterations"}`
|
||||
- **Codex 审查结论：算法本体正确**（探针实测）—— 2 状态 `[2/3, 1/3]`（58 次迭代）、3 状态与 `np.linalg.eig(P.T)`
|
||||
特征值 1 对应的特征向量逐位一致（39 次）、随机 6 状态一致（13 次）、200×200 一致到 `1.9e-12`（6 次、0.10s）、
|
||||
与 `markov_simulate` 的终点频率互验 `[0.6702, 0.3298]` vs `[0.6667, 0.3333]`、`sum(data) = 1.0`
|
||||
- **Codex 只碰工程侧**：① ruff 5 条 `W293` 全清，`mm1_metrics` 前 4 个空行 → 2；
|
||||
② docstring 补 `max_iter` / `tol` 两个参数（原来 Parameters 里只有 `transition`）、补 `Raises`，
|
||||
写清 `tol` 是**相邻差口径**（实测慢混合链 `tol=1e-10` → 实际误差 `4.6e-9`，被 `1/(1-|λ2|)` 放大）；
|
||||
③ 修正 Notes 里"周期链会不收敛"的说法（可约链的实情是"平稳分布不唯一、迭代法给离初值最近的那个"）；
|
||||
④ 失败文案 `失败: ` → `失败：`（与文件内其它函数统一）
|
||||
- **测试：+8 条、摘掉 1 条 skip**（此前该函数只有 1 条挂着的 skip）—— 2 状态 `[2/3, 1/3]` + `converged` / `iterations`、
|
||||
3 状态与特征分解对拍、`data` 是分布（和为 1 / 非负 / `float64`）、慢混合链迭代次数 > 100、
|
||||
`np.int64` 的 `max_iter`、非法转移矩阵、`max_iter=0` / `tol=0`、docstring Example 真能跑
|
||||
- ⏳ **留给你的 6 条口径**见"下一步 → markov_steady_state 待你拍板"（决策 57）
|
||||
|
||||
- [ ] 剩余 1 项：`save_figure`（A 档 = 工程，**Codex 直接写**）
|
||||
|
||||
### 验证结果
|
||||
|
||||
| 检查 | venv | conda `mcm-toolkit` |
|
||||
|---|---|---|
|
||||
| `pytest` | 见下（单列） | **188 passed, 31 skipped（0 xfail）** |
|
||||
| `pytest` | 见下（单列） | **196 passed, 30 skipped（0 xfail）** |
|
||||
| `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
|
||||
| `ruff check` | All checks passed | **All checks passed**（0 error） |
|
||||
| `scripts/doctor.ps1` | 跑通 | — |
|
||||
@@ -351,15 +367,15 @@
|
||||
（修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
|
||||
`docs/04-environment.md` 坑 7）
|
||||
- base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
|
||||
- **219 条用例：188 passed / 31 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
|
||||
`test_core.py` 23、`test_solve.py` 51（本轮 +9：`markov_simulate` 从 0 条起步）、`test_viz.py` 8、`test_decision.py` 7、
|
||||
- **226 条用例：196 passed / 30 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
|
||||
`test_core.py` 23、`test_solve.py` 58（本轮 +8、摘掉 1 条 skip）、`test_viz.py` 8、`test_decision.py` 7、
|
||||
`test_stats.py` 53、`test_models.py` 5
|
||||
- **`xfail` 再次清零**：`correlation_matrix` 的契约冲突已按方案 A 解决（决策 41），那条用例转正
|
||||
- 上一轮那 7 条 xfail 已全部转正，决策 30 那套信号（XPASS → 摘 mark）跑完过一个完整闭环
|
||||
- `examples/01_clean_and_describe.py` 实测跑通（exit 0）；`00_quickstart.py` 仍等 `stats` / `viz`
|
||||
- 31 条 skip 是等实现的算法（`train_test_split`、`markov_steady_state`、`mm1_metrics`、`anova`、`fit_distribution`、
|
||||
- 30 条 skip 是等实现的算法（`train_test_split`、`mm1_metrics`、`anova`、`fit_distribution`、
|
||||
`knapsack_dp`、`linear_program`、`simulated_annealing` 等）；
|
||||
`monte_carlo_probability` / `monte_carlo_integral` 已落地，分别摘掉 2 条与 1 条 skip；`markov_simulate` 新增的 9 条全部实跑；
|
||||
`monte_carlo_probability` / `monte_carlo_integral` / `markov_steady_state` 已落地，分别摘掉 2 / 1 / 1 条 skip；`markov_simulate` 新增的 9 条全部实跑；
|
||||
`TestValidate` 的 4 条仍挂着 —— `check_*` 还是 `NotImplementedError`，但它们实现时应当直接复用 `as_array`
|
||||
- **本轮回归（已修）**：`transform.py` 上一版有 3 处真 bug —— 修前 **7 failed / 75 passed**，
|
||||
且 pyright 在同一处报 `reportArgumentType`。**不是静态误报**：pyright CLI 复现 + 测试真红。
|
||||
@@ -527,17 +543,29 @@ docstring 与 `test_describe_reports_expected_keys` 早就写死了这个方向
|
||||
`True` 因 `isinstance(True, int)` 为真被当状态 1 **静默放行**；越界状态（如 `initial=5`、`s=2`）只在
|
||||
第一轮索引时才炸、被 `except` 吞成 `success=False`。可选口径见下一步的 A / B / C。
|
||||
|
||||
| 57 | `markov_steady_state` 的 6 条口径**待用户拍板**（Codex 只报选项，未代改，决策 49） |
|
||||
探针实测出的口子：① **含负元素**的"行和为 1"矩阵（`[[1.5, -0.5], [0, 1]]`）会溢出成 `nan`，而
|
||||
`data=[nan, nan]` 却 `success=True` —— 违反决策 48 的 NaN 口径（根因：没查 `arr >= 0`）；附带的
|
||||
`RuntimeWarning: overflow encountered in matmul` 因为 pyproject 设了 `filterwarnings = ["error::RuntimeWarning"]`，
|
||||
**能让测试直接报错**，所以不能只靠测试兜；② `tol=True` 因 `isinstance(True, int)` 通过校验 → `tol=1` →
|
||||
1 次就"收敛"，给出 `[0.55, 0.45]` 的假答案（`max_iter` 查了 `bool`、`tol` 没查，易错点 1 复发）；
|
||||
③ `tol=np.nan` 因 `nan <= 0` 为假穿过校验 → 白跑 10000 次迭代；④ `converged=False` 仍 `success=True`
|
||||
且 `data` 是未收敛的迭代值（`max_iter=5` → `[0.6387, 0.3613]`）；⑤ 类型错也抛 `ValueError`
|
||||
（`max_iter=100.0`），与决策 54 的"类型错 `TypeError`"分工不一致；⑥ `params` 只记 `max_iter` / `tol`，
|
||||
没记转移矩阵（`monte_carlo_integral` 记了 `bounds`），事后复现不了。可选口径见"下一步"。
|
||||
|
||||
## 下一步
|
||||
|
||||
### ⭐ 当前进度与待办（2026-10-05 第五轮）
|
||||
### ⭐ 当前进度与待办（2026-10-09 第六轮）
|
||||
|
||||
**本轮：`markov_simulate`（你写的第一版）已审查通过** —— 算法本体正确，没动你任何算法行；
|
||||
Codex 只清工程侧（ruff 8 条、docstring、3 处 `马尔科夫`、`initail` 拼写、半角逗号、`kind` 未用），
|
||||
并补 **9 条测试**（此前 0 条）。三连：`pytest` **188 passed / 31 skipped**、`ruff` 0、`pyright` 0。
|
||||
**本轮：`markov_steady_state`（你写的）已审查通过** —— 算法本体正确，一行没动（3 状态与特征分解逐位一致、
|
||||
200×200 只用 6 次迭代 / 0.10s）；Codex 只清工程侧（ruff 5 条、docstring 补 `max_iter`/`tol`/`Raises`、
|
||||
修正"周期链"表述、全角冒号），并 **+8 条测试、摘掉 1 条 skip**。
|
||||
三连：`pytest` **196 passed / 30 skipped**、`ruff` 0、`pyright` 0。
|
||||
|
||||
**接下来三件事**
|
||||
1. **`markov_simulate` 的 5 条待你拍板**（下节，全是入口口径，决策 49/56）。
|
||||
2. `ci_low` / `ci_high` 的语义确认一句（A / B / C 三个选项在下面挂着），确认后 Codex 补 `docs/algorithms/monte_carlo.md` 卡片。
|
||||
1. **`markov_steady_state` 的 6 条口径待你拍板**（下节，决策 57）。
|
||||
2. **`markov_simulate` 的 5 条口径**仍在挂着（决策 56 的 A / B / C），与 `solve` 的收尾一起定。
|
||||
3. L0 最后一项 `save_figure`（A 档 = 工程，`viz/export.py`）—— **Codex 直接实现**，你只读。
|
||||
|
||||
### ⏳ markov_simulate 待你拍板（5 条，Codex 只报不改）
|
||||
@@ -556,9 +584,31 @@ Codex 只清工程侧（ruff 8 条、docstring、3 处 `马尔科夫`、`initail
|
||||
**⑤ `std_terminal` 对**分类**状态的意义**：状态编号是标称量，均值和标准差只对"有序状态"（如排队人数）成立 ——
|
||||
要不要把 `metrics` 换成状态频率（`terminal_freq`）？你定。
|
||||
|
||||
**你下一个要写的（S 档，仍在 `solve/simulate.py`）**：`markov_steady_state`。
|
||||
与 `markov_simulate` 是同一件事的两面：前者按转移矩阵逐代抽状态，后者用**迭代**求平稳分布。
|
||||
docstring 已写明口径：用迭代而不用特征分解，因为"收敛快不快"本身就是论文里要写的性质。
|
||||
### ⏳ markov_steady_state 待你拍板（6 条，Codex 只报不改）
|
||||
|
||||
**① 转移矩阵没查非负**（与 `markov_simulate` 的待办 ② 是同一块）：`[[1.5, -0.5], [0, 1]]` 行和恰为 1.0 →
|
||||
通过校验 → `v` 指数发散 → `data=[nan, nan]` **但 `success=True`**（违反决策 48 的 NaN 口径）。
|
||||
实测还会先抛 `RuntimeWarning: overflow encountered in matmul`，而 pyproject 设了
|
||||
`filterwarnings = ["error::RuntimeWarning"]` —— 这条**能让测试直接报错**，所以得在校验层拦，不能只靠测试兜。
|
||||
|
||||
**② `tol` 没查 `bool`**：`tol=True` → `isinstance(True, int)` 为真 → `tol=1` →
|
||||
1 次就"收敛"，给出 `[0.55, 0.45]` 的**假答案**（`success=True, converged=True, iterations=1`）。
|
||||
`max_iter` 查了 `bool`，`tol` 漏了（易错点 1 复发）。
|
||||
|
||||
**③ `tol` 没查 NaN**：`np.nan <= 0` 为假 → 穿过校验 → 白跑 10000 次迭代后返回（结果本身是对的，纯浪费）。
|
||||
|
||||
**④ `converged=False` 仍 `success=True`**，且 `data` 是未收敛的迭代值（`max_iter=5` → `[0.6387, 0.3613]`）。
|
||||
选项：**A** 保持现状（`converged` 自己看）；**B** 不收敛判 `success=False`；**C** 不收敛时 `data=None`、只留 `metrics`。
|
||||
|
||||
**⑤ 类型错也抛 `ValueError`**（`max_iter=100.0`），与文件内其它函数（决策 54：类型错 `TypeError`、取值错 `ValueError`）
|
||||
不一致 —— 要不要对齐？`tol` 同理。
|
||||
|
||||
**⑥ `params` 没记转移矩阵**：`{"max_iter": 10000, "tol": 1e-10}` 复现不了"算的是哪个矩阵"
|
||||
（`monte_carlo_integral` 记了 `bounds`）—— 要不要补？
|
||||
|
||||
**你下一个要写的（S 档，仍在 `solve/simulate.py`）**：`mm1_metrics`（M/M/1 闭式指标，10 行）。
|
||||
docstring 已写明口径：`λ >= μ` 时系统不稳定、队列长度无界 —— 这种情况返回 `success=False` 并说明原因，
|
||||
而不是返回 `inf`。写完 `solve` 这一层就齐了，L1 只剩 `decision` / `models` 那几条。
|
||||
|
||||
### ✅ random_walk 的 4 条待办（2026-10-05 已办结）
|
||||
|
||||
|
||||
Reference in new issue
Block a user