# 数值与边界语义

## 目标和梯度

局部代价 `c(i,j)=Σ_k w_k (x[i,k]-y[j,k])²`，默认 w=1。使用上 / 左 / 左上三种转移，路径必须经过首尾格点。原始 Soft-DTW 是所有路径代价的平滑最小值，前向对最小前驱平移后计算 log-sum-exp；逆序传播用同一稳定 softmax 的权重，不用含无穷填充项相减的反向公式。

校正目标 `D(x,y)=S(x,y)-S(x,x)/2-S(y,y)/2`。求 x 的梯度包含 S(x,x) 的**两侧**输入导数，y 同理。`alignment[i,j]` 是 cross 项对局部代价的导数，即该格点的路径访问占用。每个值在数值误差内为 0..1，整个行不要求归一；不能把它当作分类概率或硬匹配。

Soft-DTW 原始值可以为负。校正值不做零截断，否则会改变梯度；极端尺度下接近零的值可能有浮点抵消误差。不同 gamma、尺度或特征权重下的分数不可直接跨配置比较。这里提供平方欧氏代价的数值目标，没有把所有参数组合声称为严格度量。非常小的 gamma 接近硬最小，导数会集中在最优路径附近，浮点数也可能无法区分接近的路径。

## 输入范围

- 每条序列 1..512 个采样、1..16 个特征；每个值有限且在 ±10000 内。不处理空序列、NaN、无穷、缺失数据或自动插值。
- gamma 在 (0,10000]。特征权重为每维一个有限数，范围 [0,1000000]，至少一项正；零权重忽略该维。
- max_cells 在 1..262144，限制**每一个** DP 矩阵的非填充格点。校正 / 拟合包含自项矩阵，cross 合法不代表 self 合法。单次原始计算 O(n·m·d) 时间，O(n·m+n·d+m·d) 空间；校正目标还需 n² / m² 自项。
- fit / rank 最多 32 条示例或候选。候选 ID 非空、唯一、至多 80 UTF-16 单元。相同分数按输入次序排列；rank 会评估全部候选，预算不足直接错误，不返回部分排序。
- 不提供自动重采样、带宽约束、在线流、GPU、大规模索引、分类器、自动确定原型长度或设备连接。使用者自行归一尺度、选择目标长度和校准 gamma。

## 模板拟合

最小化归一化正示例权重的 `Σ a_i D(prototype, example_i)`，原型长度和维度固定。示例权重范围 (0,1000000]。初始化来自调用者 seed，结果依赖初始化；不是自动分群。仅使用带 Armijo 条件的梯度下降，起始步长每次重置，最多 24 次减半。超出值域的试探点被拒绝并缩步，不会隐式裁剪。

固定示例的 S(example_i,example_i) 只计算一次，原型自项每次目标评估计算一次；原型自项两侧梯度都参与优化。接受步满足目标下降判据；不返回未通过判据的试探点。

### 预算和终止

max_steps=0..200、max_evaluations=1..2048、max_work_units=1..100000000。学习率 [1e-8,10]，两种容忍度 [0,1000]。工作量单位定义为**逻辑矩阵格点数 × 特征数**，不等于 CPU 指令、真实时间或内存字节；反向传播和 exp/log 的常数开销未另计。小预算不构成严格实时保证。

设原型长 p、示例长 m_i、维数 d。准备工作 P=`Σ m_i²·d`；一次目标评估 Q=`(p²+Σ p·m_i)·d`。初始评估计1次，总工作量 `P + evaluations·Q`，超预算前停止。若 P+Q 无法容纳则返回 work_budget 错误；已有初始点时预算耗尽返回 `ok` 的最后完整状态。候选因值域被拒绝时未实际计算目标，不占 evaluations / work_units，但占 24 次回溯尝试。

| stop | 含义 |
|---|---|
| gradient_tolerance | 梯度二范数不高于设定值 |
| improvement_tolerance | 接受步的下降不高于 tol × max(1,abs(前目标)) |
| max_steps | 完成用户设定的步数（含0） |
| evaluation_budget | 下一次评估将超过次数预算 |
| work_budget | 下一次评估将超过逻辑工作量预算 |
| line_search_stalled | 24 次回溯内没有接受点 |

所有状态仅描述这一次局部优化，不代表全局最优。`history` 长度为 accepted_steps+1，包含初始目标；gradient_norm 对应最终返回原型。max_steps / line_search_stalled 可能仍有较大梯度，调用者需要检查它。

## 数据与并发

核心不访问文件或网络，不持有后台任务。输入数组只读，输出新分配；调用期间不能由其他线程修改同一个输入数组。Node / 浏览器包装限制请求体大小。浏览器使用 Worker，通过取消直接终止计算，不保存输入到服务器或本地持久存储。