yellowdog/ai_mouse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record empirical rejection of Heun sampling in spec

Browse Source 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
dog
2026-07-09 18:10:49 +08:00
parent 76581a210e
commit 9e529d3951
1 changed files with 11 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/superpowers/specs/2026-07-09-mouse-postprocess-quality-design.md
View File

@@ -63,7 +63,7 @@ New order (steps run in this sequence):
Function signatures, the `generate()` API, and the exact-endpoint Function signatures, the `generate()` API, and the exact-endpoint
guarantee are preserved. guarantee are preserved.
### 2. Sampling: Euler → Heun (`mouse.py`) ### 2. Sampling: Euler → Heun (`mouse.py`) — REJECTED during implementation
Replace the 10-step first-order Euler loop with 10-step Heun Replace the 10-step first-order Euler loop with 10-step Heun
(predictor-corrector): per step, evaluate v at x and at the Euler (predictor-corrector): per step, evaluate v at x and at the Euler
@@ -72,6 +72,16 @@ d_model=128 transformer (~1-2 ms CPU), total latency stays ~40 ms.
Seed reproducibility unaffected (randomness is only in the init noise Seed reproducibility unaffected (randomness is only in the init noise
and duration sampling, both unchanged). and duration sampling, both unchanged).
**Outcome (2026-07-09, implementation):** Heun was implemented, measured,
and reverted. Per-stage probing showed Heun's raw ODE output contains
40-51 direction changes >90° per trace vs Euler's 2-11; a t-clamped
variant was equally bad and Euler-20 gave no meaningful gain. The trained
flow field is only self-consistent along its own Euler-discretized paths,
so second-order integration injects noise instead of reducing error. The
shipped code keeps the original 10-step Euler loop; the new
post-processing pipeline alone meets the quality gates (max tail turn
32-58° vs the old pipeline's 53-135°, zero jagged-chain artifacts).
### 3. Tests and acceptance ### 3. Tests and acceptance
1. **Golden regression re-capture** — `tests/unit/data/golden_mouse.npz` 1. **Golden regression re-capture** — `tests/unit/data/golden_mouse.npz`