# 三个可运行场景

所有数据为本项目固定合成数值示例，不涉及任何真实个人或设备记录。先执行 `node scripts/build.mjs`。三个文件均可在浏览器选择对应场景后运行、编辑或下载结果，也可在 CLI 独立运行。不同工具链最后若干位可能有浮点差异。

## 1. 从不同节奏的周期观测学习参考模板

**使用者与问题**：传感器 / 重复动作应用开发者收到长度不同的观测，按下标直接平均会错配采样位置，希望得到可重用的固定长度模板。

**输入**：[prototype.json](../examples/prototype.json)：观测 `[0,1,0]` 和 `[0,0.8,1,0]`，seed `[2,-1,2,0]`，gamma=0.4、最多30步、逻辑预算2000000。

**操作**：`node bin/warpfit.mjs examples/prototype.json --out prototype-result.json`。引擎对带自项校正的平均目标计算梯度，回溯寻找接受点；浏览器查看模板前后曲线及优化轨迹。

**实际输出**：模板约 `[-0.05841781,0.75569306,1.02705559,-0.00566323]`，目标 6.7241967137 → 0.0878791773，接受30步、评估45次、工作量2005、stop=improvement_tolerance。停止原因来自真实运行，不把“到达步数上限”当作收敛证明。

**验证**：Node 文件流程检查目标下降、历史长度与模板形状；核心有单点带权均值解析解、预算耗尽、初始驻点与错误配置测试。没有真实设备识别率证据，不由目标降低推断动作正确。

## 2. 将对齐梯度接入一个独立时序模型

**使用者与问题**：时序模型开发者的预测和目标采样数不同，逐点误差无法直接比较，需要一个平滑损失及对原始预测值的梯度。

**输入**：[training.json](../examples/training.json)：预测 `[[0.2,-0.3],[1.5,0.8]]`；目标 `[[0,-0.2],[0.6,0.4],[1.2,0.9]]`；gamma=0.8。另有 [校准模型示例](../cmd/calibrate/main.mbt)：六点 sensor、四点 target、初始 gain=0.5 / offset=0.6。

**操作**：`node bin/warpfit.mjs examples/training.json` 返回损失、双方梯度及占用。`moon run cmd/calibrate --target js` 将 ∂L/∂prediction 按链式法则累加到 gain / offset，再迭代更新外部模型；这两个参数不是 WarpFit 内部原型。

**实际输出**：文件样例目标约 0.7998364090，预测首元素梯度 -0.1118012927，其余梯度按输入同形返回。校准示例目标 1.1964748651 → 0.4136583288，gain≈1.2516615832、offset≈-0.0545894780。

**验证**：全部二维元素的中心有限差分，以及独立外部模型 gain / offset 的有限差分；更新后目标下降。穷举和 tslearn 对照另核查双方梯度及自项导数。没有自动微分框架或完整神经网络训练系统，调用者负责其余链式求导。

## 3. 对一个完整候选集做按示例检索

**使用者与问题**：离线周期片段应用开发者希望在不同节奏的候选中查询相似形状，需要完整可复算的评分，不能用未经标定的分数直接做合格判定。

**输入**：[retrieval.json](../examples/retrieval.json)：query `[0,1,0]`；same=`[0,1,0]`、stretched=`[0,0.5,1,1,0]`、changed=`[1,0,1]`；gamma=0.4、top_k=3。

**操作**：`node bin/warpfit.mjs examples/retrieval.json`。先检查每个 cross / self 矩阵及整个候选集合的预算，然后缓存 query 自项，计算所有候选并排序。浏览器显示排名表和查询 / 首位候选曲线。

**实际输出**：same=0，stretched≈0.4448938406，changed≈1.7031942663，次序为 same / stretched / changed；评估3条，逻辑工作量85。`cmd/demo` 用的是另一条 stretched=`[0,0.8,1,0]`，其结果 0.1813520906，不能混写为同一输入。

**验证**：CLI 断言全部候选已评估、首位为 same；核心测试并列稳定次序、重复 ID、预算不足、不修改输入。此顺序仅对给定输入和配置成立，不声称分类准确率。预算不足不会发布一个伪完整排名。

## 共同错误与边界

不规则矩阵、维度不符、超范围值、未知字段、重复 JSON 键和无效整数预算均显式失败。原始 Soft-DTW 可以为负；occupancy 不是行归一注意力。CLI 可通过退出码和 stop 分辨预算耗尽 / 停止状态，详见 [API](API.md) 和 [数值语义](SEMANTICS.md)。