oltc-selector 2.2.0 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +50 -46
  3. package/bin/oltc.js +2865 -452
  4. package/package.json +5 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 oltc-selector authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,17 +1,12 @@
1
- # OLTC Selector / 有载开关选型
1
+ # oltc-selector
2
2
 
3
- 填工况,给出 2025 目录里**最低满足**的型号。网页和 `oltc` CLI 共用同一份 `selectOltc` 引擎。
3
+ Tap-changer type selection from the command line. The command is `oltc`. No prices. Same engine as the web page: https://oltc-selector.vercel.app/
4
4
 
5
- **CLI:** `npx -y oltc-selector@2.2.0`,命令是 `oltc`。Agent 技能包另放,不在这个仓库里。
6
- **网页:** [oltc-selector.vercel.app](https://oltc-selector.vercel.app/) · [GitHub Pages](https://erict16.github.io/oltc-selector/)
7
-
8
- 私人辅助,不是厂家官网。型号是起点,出 OS 前要工程确认。
9
-
10
- ![工作台](docs/assets/readme.png)
5
+ The type is a starting point. Get engineering confirmation before an order.
11
6
 
12
7
  ## CLI
13
8
 
14
- 不需要 clone 本仓库。
9
+ You do not need to clone this repository.
15
10
 
16
11
  ```bash
17
12
  npm i -g oltc-selector
@@ -28,34 +23,70 @@ oltc --mva 16 --kv 22 --tap line --winding star
28
23
  # Autotransformer tapped at the series/common junction (sized on the HV side)
29
24
  oltc --mva 125 --kind auto --hv 225 --mv 115 --tap junction
30
25
  # 3xCM2I-500/252D-10193W
26
+
27
+ # Or paste the tender line: YNa0 makes it an autotransformer
28
+ oltc --line "220/110/35kV-125MVA 225±8x1,25%/115/35kV YNa0d11"
29
+ # 3xCM2I-500/252D-10193W, plus the type at Um 126 / 170 / 252
31
30
  ```
32
31
 
33
32
  | Flag | Meaning | Default |
34
33
  |------|---------|---------|
34
+ | `--line "text"` | Tender line: MVA, kV ratio with ±N×x%, vector group. Flags given beside it win. | |
35
35
  | `--iu` / `--imax` | Max through-current Imax (A). **No** safety factor. | required unless `--mva` |
36
- | `--mva` `--kv` | Transformer MVA + tap-side kV → Imax (min tap + `--k`) | |
36
+ | `--mva` `--kv` | Transformer MVA + tap-side kV → Imax (min tap + `--k`). With `--iu`, `--kv` alone sets the winding voltage for the 220/330 kV and `--market` rules | |
37
37
  | `--k` | Safety factor ≥ 1, **capacity path only** | 1.0 |
38
+ | `--step-pct` | Step as a percent (1.25 means 1.25 %), capacity path only | 1.25 |
39
+ | `--os-imax` | Capacity path: the Imax the OS or maker states at the lowest tap (`--imax` beside `--mva` means this) | |
38
40
  | `--kind two\|auto` | Transformer kind (`--auto` = `--kind auto`) | two-winding |
39
41
  | `--tap` | Where the OLTC sits: `neutral` / `line` (two-winding), `junction` / `mv-line` (autotransformer). Sets current, Ust and Um. | neutral |
40
42
  | `--winding star\|delta` | Tapped winding connection (two-winding) | star |
41
43
  | `--hv` `--mv` | Autotransformer HV / MV rated kV | |
42
44
  | `--earth-um` | OLTC insulation to earth from the OS; overrides the rule | |
43
- | `--um` | Equipment Um (kV) | derived from `--kv` on MVA path |
45
+ | `--market` | Buyer's country for a neutral's assumed Um. Rules exist for `IT` and `TR`; another code prints a note and is not used | |
46
+ | `--across-li` `--across-ac` | Stated LI / AC withstand across the tap winding (kV): sets the selector grade B/C/D/DE | |
47
+ | `--um` | Equipment Um (kV) | derived from `--kv` if omitted |
44
48
  | `--ust` | Step voltage (V) | 0, or derived on MVA path |
45
49
  | `--conn Y\|D` | Switch star / delta on the `--iu` path (with `--mva`, use `--tap`) | Y |
46
50
  | `--reg W\|G\|0` | Reversing / coarse-fine / linear | W |
47
- | `--pm` | ± steps | 8 |
48
- | `--octc` | Off-circuit 无载 (WSL/WSG) | on-load |
51
+ | `--pm` | ± steps, a whole number | 8 |
52
+ | `--pos` / `--positions` | Operating positions (linear and off-circuit; on W/G the Fig. 3-3 row with that count) | |
53
+ | `--phases` | `I` / `II` / `III` | III |
54
+ | `--range +a/-b[xs%]` | Uneven range. W/G takes the Fig. 3-3 row the maker sells (+4/-12 → 10193W); the lowest tap uses −b | |
55
+ | `--minus` | Minus steps for the lowest-tap current, beside `--pm` / `--pos` | ± steps |
56
+ | `--mid 1\|3` | Mid positions of the W/G diagram, when Fig. 3-3 has the pair | brochure |
57
+ | `--octc` | Off-circuit 无载 (WSL cage; WDG/WLG/WSG drum). `--duty octc` is the same | on-load |
49
58
  | `--structure` | `auto` / `combined` 组合式 / `compound` 复合式 / `cage` 笼式 / `drum` 鼓式 | `auto` |
50
59
  | `--series` | OCTC wiring II IV V VI VII VIII | auto is linear IV for Y and D |
51
- | `--mount` | `in-tank` / `on-tank` / `dry` | in-tank |
60
+ | `--mount` | `in-tank` / `on-tank` / `dry` / `reactor` (oil HWDK) | in-tank |
52
61
  | `--oil` / `--vacuum` | Switching medium | vacuum (on-load) |
53
62
  | `--contact` | OCTC contact e.g. `6x5` | |
54
- | `--json` | Machine output | |
55
- | `--no-update-check` | Skip the daily npm check. A newer version only prints a notice on stderr; nothing is installed. `OLTC_NO_UPDATE_CHECK=1` or `CI=1` also skip it. | check on |
63
+ | `--json` | Machine output (see below) | |
64
+ | `--lang en\|zh` | Output language. `OLTC_LANG=en` also works | zh |
65
+ | `--version` / `-v` | Print the version | |
66
+ | `--help` / `-h` | The flag list. Also shown when no flag is given | |
67
+ | `--no-update-check` | Skip the npm check made on every run. A newer version only prints a notice on stderr; nothing is installed. `OLTC_NO_UPDATE_CHECK=1` or `CI=1` also skip it. | check on |
56
68
 
57
69
  `--structure auto` and omitting `--octc` match the web first paint: on-load, in-tank vacuum, minimum-adequate ranking.
58
70
 
71
+ Every flag with a value also takes `--flag=value`. A flag that cannot take effect is an error, not a silent default: `--series` or `--contact` without `--octc`, `--conn D` with `--tap neutral`, `--pm` and `--pos` that disagree, `--vacuum` with `--octc`, a flag given twice.
72
+
73
+ **Exit code:** `0` a type was found (or help / version); `1` no type, or bad input.
74
+
75
+ **`--json`** prints one object. For bad input (a flag that cannot be read) the object holds only `ok`, `version`, `model` and `errors`.
76
+
77
+ | Key | Holds |
78
+ |-----|-------|
79
+ | `ok` | `true` when `model` is a type |
80
+ | `version` | The CLI version |
81
+ | `model`, `why`, `alts` | The type, one line of reason, other types that cover the duty |
82
+ | `cautions` | Notes you must act on |
83
+ | `resolved` | What the engine was asked, as numbers: `throughCurrentA`, `umKv`, `stepVoltageV`, `connection`, `phases`, `regulation`, `plusMinusSteps`, `positions`, `dutyKind`, `mounting`, `medium` |
84
+ | `line` | The `--line` read-back: `kind`, `mva`, `voltagesKv`, `vectorGroup`, `warnings` (or `null`) |
85
+ | `basis` | Where current, Ust and Um came from on the capacity path (or `null`) |
86
+ | `umChoices` | The type at each Um class when the insulation to earth is open |
87
+ | `assumptions` | Every default that was applied, as text |
88
+ | `errors` | Why there is no type |
89
+
59
90
  ## Selection rules
60
91
 
61
92
  1. **Minimum-adequate, not SHZV-by-default.** Rank **CV2 → CM2 → SHZV → SDZV → SHZVG**. SDZV (dual-break, Ust 6000 V) only when SHZV step voltage or step capacity is short. Prefer one three-phase unit over `3×` singles when a brochure III type exists.
@@ -64,35 +95,8 @@ oltc --mva 125 --kind auto --hv 225 --mv 115 --tap junction
64
95
  4. **No combined III-D.** CM / CM2 / CMD / SHZV / SDZV / SHZVG three-phase strings are star-point Y. Cover delta with `3x…I-` when that I type exists. Compound **CV / CV2 / SV** and on-tank **HWV** III-D **do** exist. No SDZV II, I-1200/1500, or III-1300.
65
96
  5. **Compound has no selector grade letter.** No `CV2III-350Y/40.5B-…`. Combined in-tank may have B/C/D/DE after Um.
66
97
  6. **WSL / WDL existence is 2025-list row keys without prices** (`lib/listIndex.data.json`). Missing rows (no `WSLIV-2000D/126`, no `7x6E` @ 72.5) are not emitted.
67
- 7. **WSG** is catalogue axes only (no 2025 list sheet in the index).
98
+ 7. **Drum OCTC is the sold WDG / WLG** (single-phase, `3x` per three-phase set, no Y/D in the string). Existence is the distinct sold OS rows (`DRUM_SOLD_ROWS` in `lib/listIndex.ts`). WDG IV is 5x5 up to 5 positions, V is 6x5 up to 6; no WDG on D. **WSG** is catalogue axes only (II/IV/V, 4x5/6x5, up to 6 positions) and stays for the D quote `WSGII-800D/40.5-4x5A`.
68
99
  8. **Typing Imax (`--iu`) does not apply a safety factor.** `--k` only applies on the transformer-capacity (`--mva`) path.
69
100
  9. **Um is set where the tap changer sits** (`lib/transformer.ts`). Line end: the winding system's class (132 kV → 145, 220 kV → 252). Neutral: the full class up to 72.5; above that 72.5 is assumed and flagged. Autotransformer: the HV system's class, combined types only (no CV / CV2 / SV).
70
-
71
- ## Web app
72
-
73
- 预选 66 / 110 / 220 kV 带常用工况。默认真变压器容量,星/角推出 Imax(最低分接和安全系数)。调压侧电压推出 Um。型号随参数实时更新,结果卡把工况和型号额定并排列出(电流、级电压、级容量、开关绝缘)。开关一组默认折叠,折叠时一行显示当前取值。手机上型号固定在底栏,点箭头跳到完整结果。
74
-
75
- ```bash
76
- npm install
77
- npm run dev # http://127.0.0.1:3000
78
- npm test
79
- npm run pack:cli
80
- ```
81
-
82
- GitHub Pages:`npm run build:gh`(`GH_PAGES=true`)。Vercel 根路径,不要设 `GH_PAGES`。
83
-
84
- 语言:中文、English、Tiếng Việt、Español、Türkçe、Bahasa Indonesia。
85
-
86
- ## OS regression
87
-
88
- `docs/replay/2025-os-sales.xlsx` and `2026-os-sales.xlsx` hold sold type plus duty (Imax, Um, Ust, ±, Y/D, phases, serial). Rebuild from JSON:
89
-
90
- ```bash
91
- python scripts/os-to-excel.py
92
- ```
93
-
94
- `npm test` runs shipped `selectOltc` on every complete row: no illegal type out; a legal sold type that covers the duty must appear in ranked results.
95
-
96
- ## 许可
97
-
98
- [条款](https://erict16.github.io/oltc-selector/terms/) · [隐私](https://erict16.github.io/oltc-selector/privacy/)。仅供参考。
101
+ 10. **Tapped windings on 220 kV class and above take combined types only.** 2025–2026 OS: 67 of 67 were CM / CM2 / SHZV.
102
+ 11. **An open Um is shown as a choice.** Star points above 72.5 and autotransformers list the type at each Um class; the tender's insulation picks one (`--earth-um`, or a row on the card).