ocs-calculators 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# 更新日志
+
+本文件格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0] - 2026-08-31
+
+首个公开版本。覆盖思维接触网百科全部 12 个在线计算器。
+
+所有公式与默认参数取自站点 `/calculator/assets/calc-core.js` 源码；
+单元测试的期望值由源码公式独立算出，共 158 个测试。
+
+### 新增
+
+- `icing` 覆冰荷载校核模块
+  - 冰筒模型 `g_ice = ρ_ice·g₀·π·b·(d+b)`，冰密度默认 900 kg/m³
+  - 覆冰总荷载、无冰/覆冰弛度、弛度增幅、重覆冰判定（冰重 > 自重）
+  - 10 个测试；⚠️ 未与张力-温度状态方程耦合，大覆冰工况偏乐观
+- `curve-stagger` 曲线拉出值校核模块
+  - 矢度 `c = l²/(8R)`、超高横移 `δ = H·h/l₀`、跨中风偏 `p_w = (½ρv²dα)·l²/(8T)`
+  - 风偏取风向垂直线路最不利工况（sin²θ = 1）
+  - 14 个测试；⚠️ 与站点实现一致：δ 计算但不参与 e 的合成，
+    而站点 JSDoc 描述为 `e = |ā ± c ∓ δ| + p_w`，两者不符（已在测试中锁定当前行为）
+- `voltage-drop` 电压降校核模块
+  - `r_T = r₂₀·[1+α(T−20)]/n`（α = 0.00393 /℃，n 为并联数）
+  - `ΔU = I·r_T·L`、`U_end = U₀ − ΔU`、压降率；末端电压下限默认 20000 V 可配
+  - 10 个测试
+- `wavespeed` 波速利用率模块
+  - `c = √(T/ρ)`、`β = v/c`、`f_n = n·c/(2L)`、一阶共振车速 `v_res = c/2·3.6`
+  - β ≥ 0.7 告警（阈值可配）
+  - 11 个测试
+- `stroke` 补偿行程模块
+  - 温度伸缩量 `ΔL = α·L·Δt`，补偿行程 `S = n·ΔL + S₀`
+  - 传动比 1:2 / 1:3 / 1:4，安装裕度规程下限 200mm、设计惯例 300mm
+  - 14 个测试，含许用行程校核与边界相等判定
+- `copper` 接触线参数速查模块
+  - 附结构化数据 `TB2809_WIRE_PARAMS`：6 型号 × 单位重量/r₂₀/150℃ 载流量
+  - 电阻温度修正 `r_T = r₂₀·[1 + α·(T−20)]`（α = 0.00393 /℃）
+  - 参数表已与站点 `/calculator/assets/calc-core.js` 的 COPPER_TABLE
+    逐项比对，6 型号 × 4 项参数完全一致
+  - 数据层与显示层的区别（重要）：站点曾把载流量渲染成 43/56（应为 430/560），
+    真因是显示层 `fmt()` 的尾零剥离正则 `/\.?0+$/` 对整数档误伤有效数字
+    （430→43、560→56、100→1、20→2）。同页表格不经 fmt 故显示正确。
+    该 bug 自 R38 载流量修正上线起存在，已于 2026-08-31 修复
+    （`if (d === 0) return s;` + 正则改 `(\.\d*?)0+$`），
+    dropper / wear / wind 同款地雷一并排除
+  - `note` 字段标明各行实际取自 TB/T 2809-2017 的哪一行
+    （站点型号 CTHM/CTHA/CTHS 对应标准行 CTMH/CTA/CTS，非同名对应）
+  - 13 个测试
+- `wear` 接触线磨耗率模块
+  - 磨耗率 `η = (A₀−A)/A₀ × 100%`，η > 20% 建议更换
+  - 支持按残截面积或残径（圆截面近似 A = πd²/4）输入
+  - 11 个测试，覆盖判定边界（η = 20% 判可继续）
+- `ampacity` 载流量修正与短路热稳定模块
+  - 环境温度修正 `I(Ta) = I₀·√((Tmax−Ta)/(Tmax−T₀))`
+  - 热稳定最小截面 `S_min = I_k·√t_k/C`，支持拟选截面判定
+  - 附结构化数据 `src/data/tb2809-ampacity.ts`：TB/T 2809-2017 表5 持续载流量
+    （9 种材质 × 120/150 mm² × 室内外 × 95/150℃），可独立引用
+- `force` 弓网接触力统计评价模块
+  - EN 50367 统计评价：`Fmax = Fm+3σ`、`Fmin = Fm−3σ`
+  - 参考目标力 `Fref = 0.00097·v² + offset`，支持 AC / DC 3kV / DC 1.5kV 三种制式
+- `wind` 风偏限界校验模块
+  - 单位风荷载 `p = ½·ρ·v²·d·α·sin²θ`（ρ 默认 1.225 kg/m³，可自定义）
+  - 跨中风偏 `b = p·L²/(8·T)`，限界判据 `b + a ≤ 限界允许值`
+  - 13 个单元测试，复现站点在线计算器输出；含 θ 对称性、平行风零偏移、超限判定
+- `dropper` 吊弦长度计算模块
+  - 接触线弛度 `f_c(x) = q_c·x·(L−x)/(2·T_c)`，承力索弛度同形
+  - 简单链形 `l_i = H − f_c(x_i)`，弹性链形 `l_i = H − f_c(x_i) + f_m(x_i)`
+  - 15 个单元测试，逐位复现站点在线计算器输出的 11 行结果
+
+### 变更
+
+- 抽出公共模块 `src/common/resistance.ts`（电阻温度修正）与 `src/common/ice.ts`
+  （冰筒模型），原先分散在 copper / tension 的同名实现改为共用，统一用 SI 单位。
+  `iceLoadNPerM` 的参数由 `iceThicknessMM / wireDiameterMM` 改为
+  `iceThicknessM / wireDiameterM`（单位：米）。
+
+### 完成度
+
+12 个计算器全部实现完毕。
+
+## [0.1.0] - 2026-08-30
+
+### 新增
+
+- 仓库骨架：TypeScript 严格模式、Vitest、tsup 打包（ESM + CJS + 类型声明）
+- `tension` 张力-温度安装曲线模块
+  - 状态方程 `T₂ − g²l²EA/(24T₂²) = T₁ − g²l²EA/(24T₁²) − αEA(t₂ − t₁)`，二分法求解
+  - 跨中弛度抛物线近似 `f = gl²/(8T)`
+  - 当量跨距归算 `l_D = √(Σlᵢ³/Σlᵢ)`
+  - 覆冰荷载冰筒模型 `g_ice = ρ_ice·g₀·π·b·(d+b)`
+  - 15 个单元测试，逐行回归站点已发布的输出表（张力误差 ≤ 0.02%）
+- `wire-specs.ts` 线材参数预设（CTHM-120 / CTHM-150 / CTHA-120）
+- `CalculatorMeta` 元信息规范：公式、依据标准、适用范围、免责声明
+- `DISCLAIMER.md` 工程免责声明
+
+### 待确认
+
+- 线材自重取值口径：标称密度 8.94 g/cm³ 反算得 g ≈ 10.524 N/m，
+  站点输出表反算得 g ≈ 10.62 N/m（+0.9%）。当前采用后者以复现站点输出。

package/DISCLAIMER.md

@@ -0,0 +1,26 @@
+# 工程免责声明
+
+本库提供的所有计算结果**仅供参考**，不构成工程设计、施工或验收依据。
+
+## 使用前必读
+
+1. **本库是计算工具，不是设计文件。** 任何实际工程应用，必须以正式设计文件、现行有效版本的标准规范、以及产品技术条件为准。
+
+2. **公式形式以设计文件及接触网设计教材/手册为准。** 各模块 `meta.ts` 中标注的公式与依据标准号，仅说明该实现的参考来源，不代表该标准包含或认可此公式。
+   例：TB 10009-2016 规定了接触线最小张力、张力确定原则与张力差限值，但**不包含**张力-温度状态方程本身。
+
+3. **线材参数均为标称参考值。** `src/data/wire-specs.ts` 中的弹性模量 E、线膨胀系数 α、截面积 A、线密度等，均为便于快速试算的标称值。实际取值以产品技术条件与设计文件为准。
+
+4. **适用范围有限。** 各模块 `meta.ts` 中标注了适用范围（如跨距 20~90 m、弹性模量 50~200 GPa）。超出范围的输入不保证结果合理，调用方应自行校验。
+
+5. **使用者承担全部责任。** 依据 MIT 许可证第 11-17 行，作者不对任何因使用本库产生的索赔、损害或其他责任负责。
+
+## 建议的正确用法
+
+- 用它做方案比选、快速试算、教学演示、结果复核
+- 不要用它直接出施工放线交底文件而不经设计复核
+- 发现公式或参数问题，请到仓库提 issue —— 这对本库的改进最有价值
+
+## 在线版本
+
+完整在线工具与配套百科见：<https://www.itswe.com>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 思维接触网百科 (https://www.itswe.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# 思维接触网百科 · 计算工具集
+
+**铁路接触网（OCS）工程计算工具 —— 公式公开、零依赖、可直接在你的项目里引用。**
+
+🔗 在线使用：<https://www.itswe.com/Category:tools>
+📖 配套百科：<https://www.itswe.com>（504 条接触网专业词条）
+
+[English](./README_EN.md) | 简体中文
+
+![npm version](https://img.shields.io/npm/v/ocs-calculators)
+![CI](https://github.com/showhoo/ocs-calculators/actions/workflows/ci.yml/badge.svg)
+![license](https://img.shields.io/npm/l/ocs-calculators)
+![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+![首屏截图](docs/screenshot.png)
+
+---
+
+## 为什么用它
+
+- **公式公开可查** — 每个模块的 `meta.ts` 里写明公式、参考依据与适用范围，不是黑盒
+- **有单元测试** — 计算结果的期望值直接取自站点已发布的输出表，可复现、可校验
+- **零运行时依赖** — 全部是纯函数，浏览器和 Node 通用，不会给你的项目塞进一堆传递依赖
+- **单位写在变量名里** — `tensionKN`、`spanM`、`crossSectionMM2`，杜绝工程计算里最常见的单位错误
+
+## 安装
+
+```bash
+npm install ocs-calculators
+```
+
+## 快速开始
+
+```ts
+import { tensionCurve } from 'ocs-calculators';
+
+// 张力-温度安装曲线：CTHM-120，当量跨距 55 m，基准 20 kN @ -20 ℃
+const curve = tensionCurve(
+  {
+    baseTensionKN: 20,
+    baseTempDegC: -20,
+    weightPerLengthNPerM: 10.6222,
+    spanM: 55,
+    elasticModulusGPa: 120,
+    crossSectionMM2: 120,
+    expansionPerDegC: 1.7e-5,
+  },
+  [-20, -10, 0, 10, 20, 30, 40],
+);
+
+for (const p of curve) {
+  console.log(`${p.targetTempDegC}℃  T=${p.tensionKN.toFixed(2)} kN  f=${p.sagM.toFixed(3)} m`);
+}
+// -20℃  T=20.00 kN  f=0.201 m
+// -10℃  T=17.69 kN  f=0.227 m
+//   0℃  T=15.45 kN  f=0.260 m
+//  10℃  T=13.30 kN  f=0.302 m
+//  20℃  T=11.30 kN  f=0.355 m
+//  30℃  T= 9.51 kN  f=0.422 m
+//  40℃  T= 8.00 kN  f=0.502 m
+```
+
+上面这段输出与 <https://www.itswe.com/calculator/tension/> 在线计算器完全一致，测试用例里做了逐行回归。
+
+## 12 个计算器（全部实现）
+
+对应 <https://www.itswe.com/Category:tools> 的 12 个在线计算器，全部已实现并逐项回归。
+
+| 状态 | 计算器 | 模块 | 在线地址 |
+|---|---|---|---|
+| ✅ 已实现 | 张力-温度安装曲线 | `tension` | [/calculator/tension/](https://www.itswe.com/calculator/tension/) |
+| ✅ 已实现 | 弓网接触力评价 | `force` | [/calculator/force/](https://www.itswe.com/calculator/force/) |
+| ✅ 已实现 | 载流量与热稳定 | `ampacity` | [/calculator/ampacity/](https://www.itswe.com/calculator/ampacity/) |
+| ✅ 已实现 | 吊弦长度计算 | `dropper` | [/calculator/dropper/](https://www.itswe.com/calculator/dropper/) |
+| ✅ 已实现 | 风偏限界校验 | `wind` | [/calculator/wind/](https://www.itswe.com/calculator/wind/) |
+| ✅ 已实现 | 接触线磨耗率 | `wear` | [/calculator/wear/](https://www.itswe.com/calculator/wear/) |
+| ✅ 已实现 | 接触线参数速查 | `copper` | [/calculator/copper/](https://www.itswe.com/calculator/copper/) |
+| ✅ 已实现 | 补偿行程 | `stroke` | [/calculator/stroke/](https://www.itswe.com/calculator/stroke/) |
+| ✅ 已实现 | 波速利用率 | `wavespeed` | [/calculator/wavespeed/](https://www.itswe.com/calculator/wavespeed/) |
+| ✅ 已实现 | 电压降校核 | `voltage-drop` | [/calculator/voltage-drop/](https://www.itswe.com/calculator/voltage-drop/) |
+| ✅ 已实现 | 曲线拉出值校核 | `curve-stagger` | [/calculator/curve-stagger/](https://www.itswe.com/calculator/curve-stagger/) |
+| ✅ 已实现 | 覆冰荷载校核 | `icing` | [/calculator/icing/](https://www.itswe.com/calculator/icing/) |
+
+所有公式与默认参数均取自站点 `/calculator/assets/calc-core.js` 源码，
+单元测试的期望值由源码公式独立算出，未从渲染结果反推。
+
+## 单位约定
+
+| 量的后缀 | 单位 | 例 |
+|---|---|---|
+| `...KN` | kN | `baseTensionKN`, `tensionKN` |
+| `...N` | N | `residualN`, `tensionN` |
+| `...NPerM` | N/m | `weightPerLengthNPerM` |
+| `...M` | m | `spanM`, `sagM` |
+| `...MM` / `...MM2` | mm / mm² | `wireDiameterMM`, `crossSectionMM2` |
+| `...GPa` | GPa | `elasticModulusGPa` |
+| `...PerDegC` | 1/℃ | `expansionPerDegC` |
+| `...DegC` | ℃ | `baseTempDegC` |
+| `...KgPerM` / `...KgPerM3` | kg/m / kg/m³ | `linearMassKgPerM` |
+
+## 每个模块都带 meta
+
+```ts
+import { tensionMeta } from 'ocs-calculators';
+
+console.log(tensionMeta.formula);     // 状态方程、弛度、当量跨距、覆冰公式
+console.log(tensionMeta.references);  // 依据标准号，以及"该标准是否真的包含此公式"
+console.log(tensionMeta.scope);       // 适用范围：跨距 20~90 m、E 50~200 GPa …
+console.log(tensionMeta.disclaimer);  // 免责声明
+```
+
+## ⚠️ 免责声明
+
+**本库所有计算结果仅供参考，不构成工程设计、施工或验收依据。**
+
+- 实际工程应用必须以正式设计文件、现行有效版本的标准规范、产品技术条件为准
+- `wire-specs.ts` 里的线材参数均为标称参考值
+- 公式形式以设计文件及接触网设计教材/手册为准
+
+详见 [DISCLAIMER.md](./DISCLAIMER.md)。
+
+## 开放问题
+
+**线材自重的取值口径待确认。** 站点页面注明"参考单位质量按密度 8.94 g/cm³ 计"，据此 CTHM-120 应为 1.0728 kg/m（g ≈ 10.524 N/m）。但由站点已发布的输出表反算，实际使用的 g ≈ 10.62 N/m（≈ 1.083 kg/m），比标称值高约 0.9%，疑似计入了吊弦、线夹、接头的等效附加荷载。
+
+本库回归测试采用反算值（10.6222 N/m）以复现站点输出。确认口径后我们会统一，欢迎在 issue 里说明。
+
+## 新增一个计算器
+
+以 `src/tension/` 为模板：
+
+```
+src/<模块名>/
+├── index.ts        # 纯函数实现，单位写在变量名里
+├── meta.ts         # 公式 / 依据 / 适用范围 / 免责
+└── <模块名>.test.ts # 期望值取自站点在线计算器的输出
+```
+
+三条约定：
+
+1. 只导出纯函数，不引第三方运行时依赖
+2. `meta.ts` 必须写全 `formula` / `references` / `scope` / `disclaimer`
+3. 测试的期望值取自站点在线计算器，容差 1%（站点输出经过显示取整）
+
+## 相关项目
+
+- [ocs-wiki-content](https://github.com/showhoo/ocs-wiki-content) — 504 条词条快照与结构化数据（规划中）
+- [itswe](https://github.com/showhoo/itswe) — 站点介绍与建站文档（规划中）
+
+## 授权
+
+- **代码**：[MIT](./LICENSE)
+- **配套百科内容**：CC BY-SA 4.0（见 ocs-wiki-content 仓库）
+
+---
+
+由 [思维接触网百科](https://www.itswe.com) 维护。发现公式或参数问题请提 issue —— 这对本库的改进最有价值。

package/README_EN.md

@@ -0,0 +1,142 @@
+# OCS Calculators
+
+**Engineering calculators for railway overhead contact systems (catenary) — open formulas, zero dependencies, embeddable in your own projects.**
+
+🔗 Try online: <https://www.itswe.com/Category:tools>
+📖 Companion wiki (Chinese, 504 entries): <https://www.itswe.com>
+
+[简体中文](./README.md) | English
+
+![npm version](https://img.shields.io/npm/v/ocs-calculators)
+![CI](https://github.com/showhoo/ocs-calculators/actions/workflows/ci.yml/badge.svg)
+![license](https://img.shields.io/npm/l/ocs-calculators)
+![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+## Why
+
+Railway electrification engineering has surprisingly little open tooling. Most
+`catenary` / `pantograph` projects on GitHub are computer-vision research or game
+mods — not the day-to-day numbers that design, construction and maintenance
+engineers actually need.
+
+This library is that missing piece:
+
+- **Formulas are public.** Every module ships a `meta.ts` with the equations,
+  the standards they relate to, and their validity range. No black boxes.
+- **Tested against a live reference.** Expected values come from the published
+  output of the online calculators, and are regression-tested row by row.
+- **Zero runtime dependencies.** Pure functions, works in the browser and Node.
+- **Units live in the variable names.** `tensionKN`, `spanM`, `crossSectionMM2` —
+  unit confusion is the number one bug in engineering code.
+
+## Install
+
+```bash
+npm install ocs-calculators
+```
+
+## Usage
+
+```ts
+import { tensionCurve } from 'ocs-calculators';
+
+// Tension-temperature installation curve.
+// CTHM-120 contact wire, equivalent span 55 m, reference 20 kN @ -20 °C.
+const curve = tensionCurve(
+  {
+    baseTensionKN: 20,
+    baseTempDegC: -20,
+    weightPerLengthNPerM: 10.6222,
+    spanM: 55,
+    elasticModulusGPa: 120,
+    crossSectionMM2: 120,
+    expansionPerDegC: 1.7e-5,
+  },
+  [-20, -10, 0, 10, 20, 30, 40],
+);
+
+for (const p of curve) {
+  console.log(`${p.targetTempDegC}°C  T=${p.tensionKN.toFixed(2)} kN  f=${p.sagM.toFixed(3)} m`);
+}
+// -20°C  T=20.00 kN  f=0.201 m
+// -10°C  T=17.69 kN  f=0.227 m
+//   0°C  T=15.45 kN  f=0.260 m
+//  10°C  T=13.30 kN  f=0.302 m
+//  20°C  T=11.30 kN  f=0.355 m
+//  30°C  T= 9.51 kN  f=0.422 m
+//  40°C  T= 8.00 kN  f=0.502 m
+```
+
+This matches <https://www.itswe.com/calculator/tension/> exactly.
+
+## Modules
+
+| Status | Calculator | Module |
+|---|---|---|
+| ✅ Available | Tension-temperature installation curve | `tension` |
+| ✅ Available | Pantograph-catenary contact force | `force` |
+| ✅ Available | Ampacity and thermal stability | `ampacity` |
+| ✅ Available | Dropper length | `dropper` |
+| ✅ Available | Wind deflection clearance | `wind` |
+| 📋 Planned | Contact wire wear | `wear` |
+| 📋 Planned | Copper weight | `copper` |
+| 📋 Planned | Compensation stroke | `stroke` |
+| ✅ Available | Wave propagation speed | `wavespeed` |
+| ✅ Available | Voltage drop | `voltage-drop` |
+| ✅ Available | Curve stagger | `curve-stagger` |
+| ✅ Available | Ice load | `icing` |
+
+## Unit conventions
+
+| Suffix | Unit | Example |
+|---|---|---|
+| `...KN` | kN | `baseTensionKN`, `tensionKN` |
+| `...N` | N | `residualN` |
+| `...NPerM` | N/m | `weightPerLengthNPerM` |
+| `...M` | m | `spanM`, `sagM` |
+| `...MM` / `...MM2` | mm / mm² | `wireDiameterMM`, `crossSectionMM2` |
+| `...GPa` | GPa | `elasticModulusGPa` |
+| `...PerDegC` | 1/°C | `expansionPerDegC` |
+| `...DegC` | °C | `baseTempDegC` |
+
+## Per-module metadata
+
+```ts
+import { tensionMeta } from 'ocs-calculators';
+
+tensionMeta.formula;     // state equation, sag, equivalent span, ice load
+tensionMeta.references;  // related standards, and whether they define the formula
+tensionMeta.scope;       // validity range: span 20-90 m, E 50-200 GPa …
+tensionMeta.disclaimer;
+```
+
+## ⚠️ Disclaimer
+
+**Results are indicative only and are not a substitute for engineering design,
+construction or acceptance documentation.**
+
+Always verify against the applicable design documents, the current edition of
+the relevant standards, and the manufacturer's product specifications. Wire
+parameters in `wire-specs.ts` are nominal reference values.
+
+See [DISCLAIMER.md](./DISCLAIMER.md).
+
+## Contributing
+
+Bug reports on formulas and parameters are the most valuable contribution —
+please open an issue. To add a module, copy the structure of `src/tension/`:
+
+```
+src/<module>/
+├── index.ts          # pure functions, units in variable names
+├── meta.ts           # formula / references / scope / disclaimer
+└── <module>.test.ts  # expected values taken from the online calculator
+```
+
+## License
+
+Code: [MIT](./LICENSE). Companion wiki content: CC BY-SA 4.0.
+
+---
+
+Maintained by [思维接触网百科](https://www.itswe.com).