Files
vibemake-pcb-studio/pcb_calculator/resistor_substitution_utils.ts
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

364 lines
13 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* Resistor-substitution search: approximate a required resistance with 2 to 4
* E-series resistors combined in series/parallel.
* Exact port of KiCad `pcb_calculator/resistor_substitution_utils.cpp`
* (RES_EQUIV_CALC): full sorted 2R buffer + binary-search complement lookups,
* so the search is exhaustive like upstream, with the same tie-breaking
* (fewest distinct values, then fewest parts, then lexicographic name).
*/
import { ESeriesId, eseriesValues } from './eseries.js';
/** Search-space bounds, as in KiCad (`RES_EQUIV_CALC_FIRST/LAST_VALUE`). */
export const RES_EQUIV_FIRST_VALUE = 10;
export const RES_EQUIV_LAST_VALUE = 1e6;
/** Absolute float-equality epsilon, as in KiCad. */
const EPSILON = 1e-12;
export interface Resistance {
/** Achieved value, Ω. */
value: number;
/** KiCad-notation formula, e.g. "2K2 + (330R | 4K7)". */
name: string;
/** The individual resistor values used, Ω. */
parts: readonly number[];
}
export interface ResEquivResults {
/** Best 2-resistor combination (always present). */
s2r: Resistance;
/** Best 3R combination; absent when 2R already hits the value exactly. */
s3r?: Resistance;
/** Best 4R combination; absent when 3R (or 2R) already hits it exactly. */
s4r?: Resistance;
}
// "330R" / "2K2" / "1M" notation (KiCad strValue: 1 mantissa digit, ≤E24).
function strValue(v: number): string {
if (v < 1000) return `${Math.trunc(v)}R`;
let div = 1e3;
let unit = 'K';
if (v >= 1e6) {
div = 1e6;
unit = 'M';
}
const x = v / div;
const intPart = Math.trunc(x);
let result = `${intPart}${unit}`;
const mantissa = x - intPart;
if (mantissa > 0) result += `${Math.round(mantissa * 10)}`;
return result;
}
// Parenthesize aText when it contains aRequiredSymbol outside parentheses.
function maybeEmbrace(text: string, requiredSymbol: string): string {
let parenLevel = 0;
let shouldEmbrace = false;
for (const c of text) {
if (c === '(') parenLevel++;
else if (c === ')') parenLevel--;
else if (c === requiredSymbol && parenLevel === 0) shouldEmbrace = true;
}
return shouldEmbrace ? `(${text})` : text;
}
const serialValue = (r1: number, r2: number): number => r1 + r2;
const parallelValue = (r1: number, r2: number): number => (r1 * r2) / (r1 + r2);
function serialResistance(r1: Resistance, r2: Resistance): Resistance {
return {
value: serialValue(r1.value, r2.value),
name: `${maybeEmbrace(r1.name, '|')} + ${maybeEmbrace(r2.name, '|')}`,
parts: [...r1.parts, ...r2.parts],
};
}
function parallelResistance(r1: Resistance, r2: Resistance): Resistance {
return {
value: parallelValue(r1.value, r2.value),
name: `${maybeEmbrace(r1.name, '+')} | ${maybeEmbrace(r2.name, '+')}`,
parts: [...r1.parts, ...r2.parts],
};
}
// "Simple" variants skip the parenthesis scan (both operands are single values).
function serialResistanceSimple(r1: Resistance, r2: Resistance): Resistance {
return {
value: serialValue(r1.value, r2.value),
name: `${r1.name} + ${r2.name}`,
parts: [...r1.parts, ...r2.parts],
};
}
function parallelResistanceSimple(r1: Resistance, r2: Resistance): Resistance {
return {
value: parallelValue(r1.value, r2.value),
name: `${r1.name} | ${r2.name}`,
parts: [...r1.parts, ...r2.parts],
};
}
function uniqueCount(res: Resistance): number {
const parts = [...res.parts].sort((a, b) => a - b);
let count = 0;
let last = 0;
let first = true;
for (const v of parts) {
if (first || Math.abs(v - last) > EPSILON) {
count++;
last = v;
first = false;
}
}
return count;
}
function betterCandidate(cand: Resistance, best: Resistance): boolean {
const candUnique = uniqueCount(cand);
const bestUnique = uniqueCount(best);
if (candUnique !== bestUnique) return candUnique < bestUnique;
if (cand.parts.length !== best.parts.length) return cand.parts.length < best.parts.length;
return cand.name < best.name;
}
/**
* Collects candidate combinations and keeps the one with the best deviation;
* the (costly) formula string is only built when a candidate improves or ties.
*/
class SolutionCollector {
private bestDeviation = Infinity;
private bestSolution: Resistance | null = null;
constructor(private readonly target: number) {}
add2RLookupResults(
results: readonly [Resistance, Resistance],
valueFunc: (foundValue: number) => number,
resultFunc: (found: Resistance) => Resistance,
): void {
this.considerSolution(valueFunc(results[0].value), results[0], resultFunc);
this.considerSolution(valueFunc(results[1].value), results[1], resultFunc);
}
getBest(): Resistance {
if (!this.bestSolution) throw new Error('Empty solution collector');
return this.bestSolution;
}
private considerSolution(
value: number,
found: Resistance,
resultFunc: (found: Resistance) => Resistance,
): void {
const deviation = Math.abs(value - this.target);
if (deviation + EPSILON < this.bestDeviation) {
this.bestDeviation = deviation;
this.bestSolution = resultFunc(found);
} else if (Math.abs(deviation - this.bestDeviation) < EPSILON) {
const candidate = resultFunc(found);
if (!this.bestSolution || betterCandidate(candidate, this.bestSolution)) {
this.bestSolution = candidate;
}
}
}
}
// Per-series value tables (10 Ω … 1 MΩ), built once and cached.
const seriesCache = new Map<ESeriesId, Resistance[]>();
function seriesData(id: ESeriesId): Resistance[] {
const cached = seriesCache.get(id);
if (cached) return cached;
const base = eseriesValues(id); // first-decade floats, base[0] === 1.0
const list: Resistance[] = [];
outer: for (let decade = RES_EQUIV_FIRST_VALUE; ; decade *= 10) {
for (const v of base) {
// All E1-E24 values are integers in [10, 1e6]; round away float noise.
const value = Math.round((decade * v) / (base[0] ?? 1));
list.push({ value, name: strValue(value), parts: [value] });
if (value >= RES_EQUIV_LAST_VALUE) break outer;
}
}
seriesCache.set(id, list);
return cached ?? list;
}
/**
* Exhaustive search for the best 2R/3R/4R equivalents of `targetOhm`,
* mirroring KiCad's RES_EQUIV_CALC::Calculate. `excludeOhms` values (in Ω)
* are removed from the pool when they match a series value exactly.
* Only E1…E24 are supported (as in KiCad). Returns null when the pool is
* empty or the series id is out of range.
*/
export function resEquivCalc(
targetOhm: number,
serieId: ESeriesId,
excludeOhms: readonly number[] = [],
): ResEquivResults | null {
if (serieId > ESeriesId.E24 || !Number.isFinite(targetOhm)) return null;
const series = seriesData(serieId);
const excluded = new Set<number>();
for (const e of excludeOhms) {
if (Number.isNaN(e)) continue;
// KiCad matches by |value - e| < epsilon via lower_bound; values are
// integers, so an exact-rounded match is equivalent.
const v = Math.round(e);
if (Math.abs(v - e) < EPSILON && series.some((r) => r.value === v)) excluded.add(v);
}
const buffer1R = series.filter((r) => !excluded.has(r.value));
if (buffer1R.length === 0) return null;
// 2R buffer: every serial and parallel pair (i1 ≤ i2), sorted by value.
const buffer2R: Resistance[] = [];
for (let i1 = 0; i1 < buffer1R.length; i1++) {
for (let i2 = i1; i2 < buffer1R.length; i2++) {
buffer2R.push(serialResistanceSimple(buffer1R[i1]!, buffer1R[i2]!));
buffer2R.push(parallelResistanceSimple(buffer1R[i1]!, buffer1R[i2]!));
}
}
// KiCad sorts this buffer by VALUE only (`operator<( const RESISTANCE&,
// const RESISTANCE& )`), and `std::sort` is not stable, so which member of an
// exactly-tied cluster ends up first is unspecified. It matters, because
// `findIn2RBuffer` only ever inspects the two entries either side of
// `lower_bound`: every other member of the cluster is invisible to the
// search. For E6 at 3.65 k, 150R + 1K5 and 3K3 | 3K3 are both exactly 1650 Ω,
// and whichever libstdc++ happens to place first decides the answer.
//
// We cannot reproduce an unspecified order, so we resolve it with KiCad's own
// stated preference - `betterCandidate`: fewest distinct resistor values,
// then fewest resistors, then the lexicographically smaller formula. That
// makes the arbitrary half of the algorithm deterministic and lands on the
// candidate upstream itself ranks first. Measured: it reproduces all six
// solution cells for E3, E6 and E24 at 3.65 kΩ, where sorting by value alone
// reproduced four.
const tieKey = new Map<Resistance, string>();
for (const r of buffer2R)
tieKey.set(r, `${uniqueCount(r)}\u0000${r.parts.length}\u0000${r.name}`);
buffer2R.sort((a, b) => {
if (a.value !== b.value) return a.value - b.value;
const ka = tieKey.get(a) ?? '';
const kb = tieKey.get(b) ?? '';
return ka < kb ? -1 : ka > kb ? 1 : 0;
});
const findIn2RBuffer = (target: number): [Resistance, Resistance] => {
if (Number.isNaN(target)) return [buffer2R[0]!, buffer2R[0]!];
const front = buffer2R[0]!;
const back = buffer2R[buffer2R.length - 1]!;
if (target <= front.value || target >= back.value) return [front, back];
// lower_bound: first index whose value is not less than target.
let lo = 0;
let hi = buffer2R.length;
while (lo < hi) {
const mid = (lo + hi) >>> 1;
if (buffer2R[mid]!.value < target) lo = mid + 1;
else hi = mid;
}
if (lo === 0) return [buffer2R[0]!, buffer2R[0]!];
if (lo === buffer2R.length) return [buffer2R[lo - 1]!, buffer2R[lo - 1]!];
return [buffer2R[lo - 1]!, buffer2R[lo]!];
};
const calculate2RSolution = (): Resistance => {
const solution = new SolutionCollector(targetOhm);
solution.add2RLookupResults(
findIn2RBuffer(targetOhm),
(v) => v,
(found) => found,
);
return solution.getBest();
};
const calculate3RSolution = (): Resistance => {
const solution = new SolutionCollector(targetOhm);
for (const r of buffer1R) {
// r + 2R
solution.add2RLookupResults(
findIn2RBuffer(targetOhm - r.value),
(v) => serialValue(v, r.value),
(found) => serialResistance(found, r),
);
// r | 2R
solution.add2RLookupResults(
findIn2RBuffer((targetOhm * r.value) / (r.value - targetOhm)),
(v) => parallelValue(v, r.value),
(found) => parallelResistance(found, r),
);
}
return solution.getBest();
};
const calculate4RSolution = (): Resistance => {
const solution = new SolutionCollector(targetOhm);
for (const rr of buffer2R) {
// 2R + 2R
solution.add2RLookupResults(
findIn2RBuffer(targetOhm - rr.value),
(v) => serialValue(v, rr.value),
(found) => serialResistance(found, rr),
);
// 2R | 2R
solution.add2RLookupResults(
findIn2RBuffer((targetOhm * rr.value) / (rr.value - targetOhm)),
(v) => parallelValue(v, rr.value),
(found) => parallelResistance(found, rr),
);
}
for (const r1 of buffer1R) {
for (const r2 of buffer1R) {
// r1 + (r2 | 2R)
solution.add2RLookupResults(
findIn2RBuffer(((targetOhm - r1.value) * r2.value) / (r1.value + r2.value - targetOhm)),
(v) => serialValue(r1.value, parallelValue(r2.value, v)),
(found) => serialResistance(r1, parallelResistance(r2, found)),
);
// r1 | (r2 + 2R)
solution.add2RLookupResults(
findIn2RBuffer((targetOhm * r1.value) / (r1.value - targetOhm) - r2.value),
(v) => parallelValue(r1.value, serialValue(r2.value, v)),
(found) => parallelResistance(r1, serialResistance(r2, found)),
);
}
}
return solution.getBest();
};
const s2r = calculate2RSolution();
const results: ResEquivResults = { s2r };
if (Math.abs(s2r.value - targetOhm) > EPSILON) {
const s3r = calculate3RSolution();
results.s3r = s3r;
if (Math.abs(s3r.value - targetOhm) > EPSILON) results.s4r = calculate4RSolution();
}
return results;
}
/**
* The text `PANEL_R_CALCULATOR`'s `showResult` lambda puts in the
* "Approximation" cell (panel_r_calculator.cpp:136-162):
*
* |error| < epsilon -> _( "Exact" )
* |error| < 0.01 -> "<0.01" (Printf( "<%.2f", 0.01 ))
* otherwise -> "%+.2f" — the sign is always written
*
* An absent solution takes "Not worth using" in the formula cell and leaves
* this one EMPTY, which is `RES_NOT_WORTH_USING` below.
*/
export const RES_NOT_WORTH_USING = 'Not worth using';
export function resApproximationText(errorPct: number): string {
if (Math.abs(errorPct) < 1e-12) return 'Exact';
if (Math.abs(errorPct) < 0.01) return '<0.01';
return `${errorPct >= 0 ? '+' : ''}${errorPct.toFixed(2)}`;
}