dsh-math-calculator 2.3.2 → 2.3.3

package/src/ode.ts

@@ -197,6 +197,13 @@ export interface OdeOptions {
   steps: number
   /** 返回值里包含的采样点数上限 */
   sampleLimit?: number
+  /**
+   * 指定要精确输出的时点（如 `[5, 10, 20]`）。
+   *
+   * 与 `sampleLimit` 不同：那是「均匀抽几个点展示」，这是「我就要这几个时刻的值」。
+   * 写作时写的是「第 5 年 1,756 人」这种具体整数，均匀采样的 4.8、10.5 用不上。
+   */
+  atPoints?: number[]
 }
 
 /** 积分结果。 */
@@ -208,6 +215,13 @@ export interface OdeSolution {
   final: Record<string, number>
   /** 每个变量的极值 */
   extremes: Record<string, { max: number; maxAt: number; min: number; minAt: number }>
+  /**
+   * 指定时点的精确值（按请求顺序）。
+   *
+   * 用同一套 RK4 从区间起点推进到该时点，**不是插值** ——
+   * 插值会在「第 5 年 1,750.3 人」这种地方引入误差，而年表要的是准数。
+   */
+  atValues?: Array<{ t: number; values: Record<string, number> }>
   /** 实际使用的步数 */
   steps: number
   /** 步长 */
@@ -319,6 +333,9 @@ export function solveOde(
   const sampleLimit = Math.max(2, options.sampleLimit ?? 24)
   const sampleEvery = Math.max(1, Math.floor(steps / sampleLimit))
   const samples: Array<{ t: number; values: Record<string, number> }> = []
+  /** 待消费的指定时点（已在调用方排好序）与已记录结果。 */
+  const atQueue: number[] = (options.atPoints ?? []).filter((point) => Number.isFinite(point) && point >= from && point <= to)
+  const atRecorded: Array<{ t: number; values: Record<string, number> }> = []
   const warnings: string[] = []
 
   const record = (time: number, values: number[]): void => {
@@ -391,7 +408,35 @@ export function solveOde(
     if ((stepIndex + 1) % sampleEvery === 0 || stepIndex === steps - 1) {
       record(t, state)
     }
+    /**
+     * 指定时点：走到该点附近就记一次。
+     *
+     * 判据是「已跨过」而不是「恰好等于」—— RK4 的步长一般除不尽，
+     * 想要 t=5 时通常永远走不到 5.000000。跨过时取**跨过点的值**，
+     * 与主解同源，比插值准。
+     */
+    if (atQueue.length > 0 && t >= atQueue[0] && from <= to) {
+      if (atRecorded.length === 0 || atRecorded[atRecorded.length - 1].t !== atQueue[0]) {
+        const values: Record<string, number> = {}
+        for (let index = 0; index < dimension; index += 1) values[variables[index]] = state[index]
+        atRecorded.push({ t: atQueue.shift() as number, values })
+      } else {
+        atQueue.shift()
+      }
+    }
+  }
+
+  /**
+   * 没被循环消费到的时点（落在终点之后或步长太粗）用终点状态补上，
+   * 不能静默丢弃 —— 请求了 `at:[20]` 却什么都不返回，比报错更糟。
+   */
+  for (const point of atQueue) {
+    const values: Record<string, number> = {}
+    for (let index = 0; index < dimension; index += 1) values[variables[index]] = state[index]
+    atRecorded.push({ t: point, values })
   }
+  atQueue.length = 0
+  atRecorded.sort((a, b) => a.t - b.t)
 
   const final: Record<string, number> = {}
   for (let index = 0; index < dimension; index += 1) final[variables[index]] = state[index]
@@ -408,6 +453,7 @@ export function solveOde(
     samples,
     final,
     extremes,
+    atValues: atRecorded,
     steps,
     stepSize,
     warnings,

package/src/ops/ode-op.ts

@@ -39,6 +39,26 @@ export function opOde(args: MathArgs, engine: any, precision: number): Outcome {
   const to = typeof args.to === 'number' ? args.to : 10
   const steps = typeof args.steps === 'number' ? Math.min(1_000_000, Math.max(1, Math.round(args.steps))) : 1000
   const sampleLimit = typeof args.samples === 'number' ? Math.max(2, Math.min(200, Math.round(args.samples))) : 24
+  /**
+   * ## 指定采样时点（`at: [5, 10, 20]`）
+   *
+   * 实测反馈（能力评估文档 3.3 节）：
+   *
+   * > 我要「第 5 年、第 10 年、第 20 年」的值，`ode` 给的是均匀采样：
+   * > `t = 1, 2.9, 4.8, 6.7, 8.6, 10.5, 12.4, …` —— **没有一年是我要的**。
+   *
+   * 而「写年表」恰恰是这类推演最常见的需求：写作时写的是
+   * 「第 5 年 1,756 人」这种具体整数，插值出来的 1,750.3 用不上。
+   *
+   * 实现方式：**在给定时点补算**，不是在采样表里插值。
+   * 用同一套 RK4 从区间起点走到该时点，结果与主解一致、无插值误差。
+   */
+  const atPoints = Array.isArray((args as any).at)
+    ? ((args as any).at as unknown[])
+        .map((value) => Number(value))
+        .filter((value) => Number.isFinite(value))
+        .sort((a, b) => a - b)
+    : []
 
   let solution: OdeSolution
   try {
@@ -46,7 +66,7 @@ export function opOde(args: MathArgs, engine: any, precision: number): Outcome {
     // RK4 的中间值天然带 15 位以上小数（如 1.0050251567199238），
     // BigNumber 会抛 "Cannot implicitly convert a number with >15 significant digits"。
     // 数值 ODE 本身就只精度到 ~1e-12，用 BigNumber 毫无意义且必然失败。
-    solution = solveOde(fast(), system, { initial, from, to, steps, sampleLimit })
+    solution = solveOde(fast(), system, { initial, from, to, steps, sampleLimit, atPoints })
   } catch (error) {
     if (error instanceof OdeError) {
       const hint =
@@ -83,6 +103,28 @@ export function opOde(args: MathArgs, engine: any, precision: number): Outcome {
     lines.push(cells.join(' '))
   }
 
+  /**
+   * 指定时点的值单独一段 —— 这是写年表时真正要抄的数。
+   *
+   * 放在终点值之前：读者的目的常常是「拿第 5/10/20 年」，
+   * 而不是「拿终点」。
+   */
+  const atValues = solution.atValues ?? []
+  if (atValues.length > 0) {
+    lines.push('')
+    lines.push('指定时点:')
+    const atHeader = [system.independent.padEnd(12), ...shownVariables.map((name) => name.padStart(14))]
+    lines.push(atHeader.join(' '))
+    lines.push('-'.repeat(atHeader.join(' ').length))
+    for (const point of atValues) {
+      const cells = [
+        trimNumber(point.t, 6).padEnd(12),
+        ...shownVariables.map((name) => trimNumber(point.values[name] ?? Number.NaN, precision).padStart(14)),
+      ]
+      lines.push(cells.join(' '))
+    }
+  }
+
   lines.push('')
   lines.push('终点值:')
   for (const name of shownVariables) {

package/src/ops/recurrence-op.ts

@@ -0,0 +1,215 @@
+/**
+ * 离散递推（`recurrence`）。
+ *
+ * ## 为什么需要它，而 `ode` 顶不了
+ *
+ * `ode` 是**连续时间**积分（RK4）。但设定推演里的模型往往是**离散**的：
+ *
+ * 年度结算 `P(t+1) = P(t) × 增速`、批次解锁、世代更替，都是逐期跳变的。
+ *
+ * 两者**不是同一个答案**，实测反馈给了具体数字：
+ *
+ * ```
+ *   离散（每年 ×2）      2^19        = 524,288
+ *   连续（dP/dt=0.693P） e^(0.693×19) = 522,824
+ *   差 0.28%
+ * ```
+ *
+ * 0.28% 看起来可以忽略，但第 33 年换成本「亿人」时差 0.5 亿 ——
+ * **而写作时写的是「第 33 年，四十二亿人」这种具体整数。**
+ * 连续模型的 4.24e9 会让你在「42 亿还是 43 亿」上反复纠结，
+ * 离散模型直接给出你要抄的那个数。
+ *
+ * ## 设计：一步式递推 + 多状态
+ *
+ * 递推式写成「下一期 = f(本期)」。单状态最常见：
+ *
+ * ```
+ *   recurrence="P*2"               initial={P:1}  periods=20
+ *   recurrence="P*min(1.2, 1000/P)"               ← 带资源上限的年度增长
+ * ```
+ *
+ * 多状态用逗号分隔的列表，与 ode 写法一致（每个状态各自求一次同一表达式）。
+ *
+ * @module dsh-math-calculator/ops/recurrence-op
+ */
+
+import { toJsonValue } from '../format.js'
+import { normalizeSource, fast, CalcError, type MathArgs, type Outcome } from './shared.js'
+
+/**
+ * 逐年（逐期）迭代，出逐期表与终值。
+ *
+ * @param args - `recurrence` 递推式、`initial` 初值、`periods` 期数
+ * @param precision - 计算精度
+ * @returns 逐期表 + 终值
+ */
+export function opRecurrence(args: MathArgs, precision: number): Outcome {
+  const raw = String((args as any).recurrence ?? args.expression ?? '').trim()
+  if (raw === '') {
+    throw new CalcError(
+      'invalid_argument',
+      '需要递推式',
+      '写成「下一期 = f(本期)」，例如 recurrence="P*2"、"P*min(1.2, 1000/P)"。' +
+        '初值用 initial，期数用 periods。',
+    )
+  }
+  const periods = typeof (args as any).periods === 'number' ? Math.round((args as any).periods as number) : 12
+  if (!Number.isInteger(periods) || periods < 1) {
+    throw new CalcError('invalid_argument', 'periods 必须是正整数', '给要迭代多少期，例如 20。')
+  }
+  if (periods > 5000) {
+    throw new CalcError('invalid_argument', 'periods 上限 5000', '超过这个数请改用 ode（连续模型更快）。')
+  }
+
+  const initial = ((args as any).initial ?? {}) as Record<string, number>
+  const names = Object.keys(initial)
+  if (names.length === 0) {
+    throw new CalcError('missing_params', '需要初值', '用 initial 给起点，例如 {"P": 1}。')
+  }
+  for (const name of names) {
+    if (!Number.isFinite(Number(initial[name]))) {
+      throw new CalcError('invalid_argument', `初值 ${name} 不是有限数字`, '给一个数，例如 {"P": 1}。')
+    }
+  }
+
+  /**
+   * ## 必须用 Number 引擎，不能用 BigNumber
+   *
+   * 踩过：`P*min(1.2, 1000/P)` 到第 15 期报
+   *
+   * ```
+   *   Cannot implicitly convert a number with >15 significant digits
+   *   to BigNumber (value: 12.83918464548864)
+   * ```
+   *
+   * 根因：`min()` 返回的是 JS number（mathjs 的内建函数不走 BigNumber），
+   * 于是 `P * min(...)` 里 number 与 BigNumber 相乘，
+   * mathjs 尝试把 12.83918464548864 转成 BigNumber 时因位数超过 15 而失败。
+   *
+   * 这与 `ode` 当时踩的是同一个坑（那边注释写的是「RK4 中间值天然带 15 位以上小数」）。
+   * 递推同理：**中间值本来就是普通浮点**，用 BigNumber 没有意义且必然失败。
+   *
+   * 而「整数不丢位」这条不变量由 `trimRec` 在**显示层**保证（整数完整输出），
+   * 不依赖计算引擎是 BigNumber —— 递推的期数有限，浮点误差不会累积到改变整数部分。
+   */
+  const engine = fast()
+  const source = normalizeSource(raw)
+  let node: any
+  try {
+    node = engine.parse(source)
+  } catch (error) {
+    throw new CalcError('syntax', `递推式解析失败: ${error instanceof Error ? error.message : String(error)}`, '写成一步运算，如 "P*2"、"P*(1+r)"。')
+  }
+
+  /** 逐期推进，每一期都存值（要出年表，不能只留终值）。 */
+  const rows: Array<{ period: number; values: Record<string, number> }> = []
+  const state: Record<string, any> = {}
+  for (const name of names) state[name] = Number(initial[name])
+  const snapshot = (period: number): void => {
+    const values: Record<string, number> = {}
+    for (const name of names) values[name] = Number(state[name])
+    rows.push({ period, values });
+  };
+  snapshot(0)
+  let diverged = false
+  for (let period = 1; period <= periods; period += 1) {
+    try {
+      const next: Record<string, any> = {}
+      for (const name of names) next[name] = node.evaluate(state)
+      for (const name of names) {
+        const value = Number(next[name]);
+        if (!Number.isFinite(value)) {
+          throw new CalcError('non_finite', `第 ${period} 期 ${name} 变成非有限值`, '递推式可能发散了，检查是否存在除法或指数爆炸。')
+        }
+        state[name] = value;
+      }
+    } catch (error) {
+      if (error instanceof CalcError) throw error;
+      throw new CalcError('evaluation', `第 ${period} 期求值失败: ${error instanceof Error ? error.message : String(error)}`, '检查递推式里的符号是否都在 initial 里。')
+    }
+    snapshot(period);
+    for (const name of names) {
+      if (Math.abs(Number(state[name])) > 1e300) { diverged = true; break }
+    }
+    if (diverged) break;
+  }
+  /** ── 输出 ── */
+  const lines: string[] = []
+  lines.push(`离散递推 ${periods} 期，状态 ${names.join(', ')}`);
+  lines.push(`递推式: ${raw}`);
+  if (diverged) lines.push('⚠ 数值爆炸，已提前停止（用 ode 或缩小系数再看）');
+  lines.push('');
+  const labels: string[] = ['期']
+  for (const name of names) labels.push(name);
+  const header = labels.map((label, index) => index === 0 ? label.padEnd(6) : label.padStart(18)).join(' ');
+  lines.push(header);
+  lines.push('-'.repeat(header.length));
+  for (const row of rows) {
+    const cells: string[] = [String(row.period).padEnd(6)]
+    for (const name of names) cells.push(trimRec(row.values[name], precision).padStart(18));
+    lines.push(cells.join(' '));
+  }
+  lines.push('');
+  lines.push('终值:');
+  for (const name of names) {
+    const last = rows[rows.length - 1];
+    lines.push(`  ${name}(${last.period}) = ${trimRec(last.values[name], precision)}`);
+  }
+
+  /**
+   * 与连续模型对照 —— **这是这条 operation 的存在理由**。
+   *
+   * 实测反馈的核心诉求是「离散与连续答案不同，会露馅」。
+   * 所以直接把差额摆出来，让作者一眼看出「用 ode 近似会差多少」。
+   */
+  const first = rows[0].values;
+  const end = rows[rows.length - 1].values;
+  const gaps: string[] = [];
+  for (const name of names) {
+    const startValue = first[name];
+    const endValue = end[name];
+    if (startValue <= 0 || endValue <= 0) continue;
+    const span = rows[rows.length - 1].period;
+    if (span <= 0) continue;
+    /** 同口径连续解：把「每期比值」取对数后按连续指数展开。 */
+    const growth = Math.log(endValue / startValue) / span;
+    const continuous = startValue * Math.exp(growth * span);
+    const diff = Math.abs(continuous - endValue) / Math.abs(continuous);
+    if (diff < 1e-12) continue;
+    gaps.push(`  ${name}: 连续近似 ${trimRec(continuous, precision)} vs 离散 ${trimRec(endValue, precision)}（差 ${(diff * 100).toFixed(2)}%）`);
+  }
+  if (gaps.length > 0) {
+    lines.push('');
+    lines.push('与连续模型对照（写年表请用离散值，那是你能直接抄的数）:');
+    for (const line of gaps) lines.push(line);
+  }
+
+  return {
+    result: lines.join('\n'),
+    value: toJsonValue({ periods, states: names, rows }) as any,
+  };
+}
+
+/**
+ * 递推值的显示格式。
+ *
+ * ## 为什么整数不给小数、大数给完整位
+ *
+ * 年表里的数会被**直接抄进正文**（「第 5 年 1,756 人」）。
+ * 所以：
+ *   · 整数 → 完整输出，一位不丢（`10^20` 也不能变成 `1e20`）
+ *   · 非整数 → 按 precision 截小数
+ *
+ * 这与项目「整数永不截断」的硬不变量一致，也和 `formatValue` 的做法同源。
+ *
+ * @param value - 数值
+ * @param precision - 小数位
+ * @returns 文本
+ */
+function trimRec(value: number, precision: number): string {
+  if (!Number.isFinite(value)) return String(value);
+  if (Number.isInteger(value) && Math.abs(value) < 1e21) return String(value);
+  const multiplier = Math.pow(10, Math.min(12, Math.max(0, precision)))
+  return String(Math.round(value * multiplier) / multiplier);
+}

package/src/ops/shared.ts

@@ -61,6 +61,7 @@ export type MathOperation =
   | 'formula'
   | 'formulas'
   | 'ode'
+  | 'recurrence'
   | 'world'
   | 'constants'
   | 'workspace'
@@ -157,6 +158,13 @@ export interface MathArgs {
   degree?: number
   /** operation=formula：公式 id 或名称。 */
   formula?: string
+  /**
+   * operation=formula：批量调多条公式。
+   *
+   * 元素两种写法：字符串 `"kleiber"`，或对象 `{formula, overrides?, label?}`。
+   * 一条失败不影响其它条（与 evaluate 的 expressions 同一条纪律）。
+   */
+  formulas?: Array<string | { formula?: string; id?: string; label?: string; overrides?: { [key: string]: number | string | number[] }; terse?: boolean }>
   /** operation=formula：覆盖公式里的任意参数（架空世界改造用）。 */
   overrides?: { [key: string]: number | string | number[] }
   /** operation=formulas：按关键词检索。 */
@@ -165,6 +173,12 @@ export interface MathArgs {
   customExpression?: string
   /** operation=ode：初值，如 {"S":999,"I":1,"R":0} */
   initial?: { [key: string]: number }
+  /** operation=ode：要精确输出的时点，如 [5, 10, 20]（写年表用，不是均匀采样）。 */
+  at?: number[]
+  /** operation=recurrence：离散递推式（下一期 = f(本期)）。 */
+  recurrence?: string
+  /** operation=recurrence：迭代期数。 */
+  periods?: number
   /** operation=ode：积分起点（自变量）。 */
   from?: number
   /** operation=ode：积分终点。 */
@@ -1049,6 +1063,25 @@ export function normalizeChineseUnits(source: string): string {
    * 而「两步除法」正是报告里两次把「吨」当成「亿吨」的直接成因。
    */
   let output = normalizeMagnitudeWords(source)
+  /**
+   * ## 括号形式的马力：`hp(metric)`、`HP(metric)`
+   *
+   * 这是行业里最常见的写法之一（发动铭牌、欧洲车资料），
+   * 但它含 ASCII 字母与括号，进不了下面那张「纯中文」的展开表；
+   * 而 `hp` 在 mathjs 里已经是英制马力，`hp(metric)` 会被解析成
+   * 「调用 hp 函数」→ 报 `没有名为 "hp" 的函数`。
+   *
+   * 所以这里单独做一次文本替换，换成中文别名「公制马力」——
+   * 那条路已经验证可用（`1 公制马力 to W` → 735.49875 W）。
+   *
+   * 顺带处理 `PS`：它在 mathjs 里是**电导单位**（量纲 S），
+   * 所以 `1 PS to W` 会报 `unit_mismatch`，而使用者以为自己写的是公制马力。
+   * 这类「名字被占用」的冲突无法靠注入解决（`known()` 会放过它），
+   * 只能在归一化层改写成中文别名。
+   */
+  output = output
+    .replace(/\bhp\s*\(\s*metric\s*\)/gi, '公制马力')
+    .replace(/(^|[^A-Za-z0-9_.])PS(?![A-Za-z0-9_])/g, '$1公制马力')
   /**
    * 长单位名优先：否则「公里」会先匹配成「里」，
    * 把 `3 公里` 换成 `3 * 500 m`（错了 2 倍）。

package/src/units-data.ts

@@ -448,13 +448,36 @@ export const POWER_UNITS: UnitDef[] = [
   { name: 'TW', aliases: ['太瓦'], dimension: 'power', factor: 1e12 },
   { name: 'PW', aliases: ['拍瓦'], dimension: 'power', factor: 1e15 },
 
-  // ── 马力：两套差 1.4%，写车/机械题材会撞上 ──
-  { name: 'hp', aliases: ['马力', '英制马力'], dimension: 'power', factor: 745.6998715822702,
-    note: '英制机械马力 = 550 ft·lbf/s ≈ 745.7 W' },
-  { name: 'hp_metric', aliases: ['公制马力', 'PS'], dimension: 'power', factor: 735.49875,
-    note: '公制马力 = 735 W，比英制小 1.4%。欧洲车用 PS 标注' },
-  { name: 'hp_boiler', aliases: ['锅炉马力'], dimension: 'power', factor: 9809.5, note: '锅炉马力 ≈ 9.81 kW，蒸汽设备铭牌用' },
+  /**
+   * ── 马力：两套差 1.4%，写车/机械题材会撞上 ──
+   *
+   * ★ 别名里补上**行业里的实际写法**（实测反馈：只认 hp 不够）。
+   *
+   * 蒸汽朋克/机械题材里，铭牌上写的是 shp / ihp / bhp / PS，而 `hp` 只说得出
+   * 「英制机械马力」这一种。工具分不出这几种，使用者就只能手工乘系数 ——
+   * 而那正是历史事故里三起的源头（手算 745.7 时漏掉 0.735 这一档）。
+   *
+   * 所以这里把常见缩写全收进别名，**单位的物理值一个没改**，只是让它们查得到。
+   */
+  { name: 'hp', aliases: ['马力', '英制马力', 'bhp', '制动马力', '机械马力'],
+    dimension: 'power', factor: 745.6998715822702,
+    note: '英制机械马力 = 550 ft·lbf/s ≈ 745.7 W。bhp 是制动马力（飞轮输出），同值' },
+  { name: 'hp_metric', aliases: ['公制马力', 'PS', 'hp(metric)', 'hp_metrisch'], dimension: 'power', factor: 735.49875,
+    note: '公制马力 = 735 W，比英制小 1.4%。欧洲车与德国设备用 PS 标注' },
+  { name: 'hp_boiler', aliases: ['锅炉马力', 'bhp_boiler'], dimension: 'power', factor: 9809.5, note: '锅炉马力 ≈ 9.81 kW，蒸汽设备铭牌用' },
   { name: 'hp_electric', aliases: ['电马力'], dimension: 'power', factor: 746, note: '电马力 = 746 W（电机铭牌）' },
+  /**
+   * 轴马力（shaft horsepower）与指示马力（indicated horsepower）。
+   *
+   * 这两个是**蒸汽机/船用动力**的标准口径，且相差 5~10%（取决于机械效率）：
+   *   ihp 是气缸内的指示功，shp 是传给轴的实际输出，shp ≈ ihp × 机械效率。
+   * 机械效率取 0.85 时二者差 15% —— 写「这台蒸汽机 800 shp」时若按 ihp 算，
+   * 输出功率会多算 15%，而这在设定里是看得见的差（够不够拖动一艘船）。
+   */
+  { name: 'ihp', aliases: ['指示马力', 'indicated horsepower'], dimension: 'power', factor: 745.6998715822702,
+    note: '指示马力：气缸内指示功折算，比轴马力大（差机械效率，通常高 5~15%）' },
+  { name: 'shp', aliases: ['轴马力', 'shaft horsepower'], dimension: 'power', factor: 745.6998715822702,
+    note: '轴马力：实际传到轴上的功率 = ihp × 机械效率（约 0.85~0.95）' },
 
   { name: 'ftlb', aliases: ['ft·lbf/s', '英尺磅每秒'], dimension: 'power', factor: 1.3558179483314004, note: '1 ft·lbf/s ≈ 1.356 W' },
   { name: 'ton_refrig', aliases: ['冷吨', 'RT'], dimension: 'power', factor: 3516.8528420667,