@tellegen/svelte 0.4.2 → 0.4.4

package/dist/diagram/multi-wire.d.ts

@@ -0,0 +1,44 @@
+import type { DistGraph } from '@tellegen/engine';
+import type { ResultSnapshot } from './snapshot.js';
+/** One bus drawn as a stack of terminal rails. */
+export interface WireBus {
+    id: string;
+    x: number;
+    terminals: {
+        name: string;
+        y: number;
+        grounded: boolean;
+        attachments: string[];
+    }[];
+}
+/** One conductor segment between two points; `terminal` names the end it belongs to. */
+export interface Wire {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /** Terminal at the bus end of the segment, used for phase colour. */
+    terminal: string;
+    amps: number | null;
+}
+/** A bounded multi-wire drawing of one branch and its two buses, in drawing units. */
+export interface MultiWireView {
+    width: number;
+    height: number;
+    buses: [WireBus, WireBus];
+    wires: Wire[];
+    /** Winding box for transformers: conductors meet it from each side and do not pass through. */
+    winding: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    kind: string;
+    id: string;
+    closed: boolean;
+}
+/** Conductor-level view of branch `k`: every conductor pair from the from-terminal rail to the
+ * to-terminal rail, so crossed terminal maps show as crossing wires. A transformer is drawn as a
+ * winding box with no conductor continuity across it. Currents come from the snapshot's ends. */
+export declare function multiWireBranch(graph: DistGraph, k: number, snapshot: ResultSnapshot | null, width?: number): MultiWireView | null;

package/dist/diagram/multi-wire.js

@@ -0,0 +1,65 @@
+const ROW = 22;
+const TOP = 26;
+/** Conductor-level view of branch `k`: every conductor pair from the from-terminal rail to the
+ * to-terminal rail, so crossed terminal maps show as crossing wires. A transformer is drawn as a
+ * winding box with no conductor continuity across it. Currents come from the snapshot's ends. */
+export function multiWireBranch(graph, k, snapshot, width = 320) {
+    const edge = graph.edges[k];
+    const index = new Map(graph.buses.map((b, i) => [b.id.toLowerCase(), i]));
+    const from = graph.buses[index.get(edge?.from.toLowerCase() ?? '') ?? -1];
+    const to = graph.buses[index.get(edge?.to.toLowerCase() ?? '') ?? -1];
+    if (!edge || !from || !to)
+        return null;
+    const rails = (bus, x) => ({
+        id: bus.id,
+        x,
+        terminals: bus.terminals.map((name, i) => ({
+            name,
+            y: TOP + i * ROW,
+            grounded: bus.grounded.includes(name),
+            attachments: (bus.terminal_attachments?.[name] ?? []).map((a) => `${a.kind} ${a.id}`)
+        }))
+    });
+    const left = rails(from, 56);
+    const right = rails(to, width - 56);
+    const rowOf = (bus, name) => bus.terminals.find((t) => t.name === name)?.y;
+    const ends = snapshot?.branches[k]?.ends ?? [null, null];
+    const amps = (side, terminal) => ends[side]?.currents.find((c) => c.terminal === terminal)?.amps ?? null;
+    const rowsUsed = Math.max(left.terminals.length, right.terminals.length, 1);
+    const height = TOP + rowsUsed * ROW + 10;
+    const transformer = edge.kind === 'transformer';
+    const winding = transformer
+        ? { x: width / 2 - 22, y: TOP - 10, width: 44, height: (rowsUsed - 1) * ROW + 20 }
+        : null;
+    const wires = [];
+    for (const [a, b] of edge.conductors) {
+        const y1 = rowOf(left, a);
+        const y2 = rowOf(right, b);
+        if (y1 === undefined || y2 === undefined)
+            continue;
+        if (winding) {
+            wires.push({ x1: left.x, y1, x2: winding.x, y2: y1, terminal: a, amps: amps(0, a) });
+            wires.push({
+                x1: winding.x + winding.width,
+                y1: y2,
+                x2: right.x,
+                y2,
+                terminal: b,
+                amps: amps(1, b)
+            });
+        }
+        else {
+            wires.push({ x1: left.x, y1, x2: right.x, y2, terminal: a, amps: amps(0, a) });
+        }
+    }
+    return {
+        width,
+        height,
+        buses: [left, right],
+        wires,
+        winding,
+        kind: edge.kind,
+        id: edge.id,
+        closed: edge.closed
+    };
+}

package/dist/diagram/phase-bars.d.ts

@@ -0,0 +1,35 @@
+import type { BranchEnd, PairVoltage } from './snapshot.js';
+import { type VoltageState } from './summary.js';
+export interface PairBar {
+    pair: [string, string];
+    volts: number;
+    state: VoltageState;
+    /** Band and marker in percent of the track; the track is the declared band ±25 %. `null`
+     * band when limits are undeclared, then the marker sits mid-track. */
+    band: {
+        left: number;
+        width: number;
+    } | null;
+    marker: number;
+}
+/** Each pair on its own band, so position reads as margin to the limits rather than volts. */
+export declare function pairBar(p: PairVoltage): PairBar;
+export interface ConductorBar {
+    terminal: string;
+    amps: number;
+    /** Percent of the largest conductor current across both ends. */
+    fill: number;
+    neutral: boolean;
+}
+export interface ConductorBars {
+    scaleAmps: number;
+    ends: ({
+        p: number;
+        q: number;
+        bars: ConductorBar[];
+    } | null)[];
+    /** Neutral current as a percentage of the largest phase current at the first live end. */
+    neutralShare: number | null;
+}
+/** Conductor |I| at both ends on one scale; neutral current is called out as an unbalance signal. */
+export declare function conductorBars(ends: [BranchEnd | null, BranchEnd | null], neutral?: string): ConductorBars | null;

package/dist/diagram/phase-bars.js

@@ -0,0 +1,44 @@
+import { pairState } from './summary.js';
+const clampPercent = (x) => Math.max(0, Math.min(100, x));
+/** Each pair on its own band, so position reads as margin to the limits rather than volts. */
+export function pairBar(p) {
+    const state = pairState(p);
+    if (p.min === null || p.max === null || !(p.max > p.min))
+        return { pair: p.pair, volts: p.volts, state, band: null, marker: 50 };
+    const span = p.max - p.min;
+    const lo = p.min - 0.25 * span;
+    const x = (v) => (100 * (v - lo)) / (1.5 * span);
+    return {
+        pair: p.pair,
+        volts: p.volts,
+        state,
+        band: { left: x(p.min), width: x(p.max) - x(p.min) },
+        marker: clampPercent(x(p.volts))
+    };
+}
+/** Conductor |I| at both ends on one scale; neutral current is called out as an unbalance signal. */
+export function conductorBars(ends, neutral = 'n') {
+    const live = ends.filter((e) => !!e?.currents.length);
+    if (!live.length)
+        return null;
+    const scaleAmps = Math.max(...live.flatMap((e) => e.currents.map((c) => c.amps)).filter(Number.isFinite), 1e-9);
+    const first = live[0];
+    const n = first.currents.find((c) => c.terminal === neutral);
+    const phaseMax = Math.max(0, ...first.currents.filter((c) => c.terminal !== neutral).map((c) => c.amps));
+    return {
+        scaleAmps,
+        ends: ends.map((e) => e?.currents.length
+            ? {
+                p: e.p,
+                q: e.q,
+                bars: e.currents.map((c) => ({
+                    terminal: c.terminal,
+                    amps: c.amps,
+                    fill: clampPercent((100 * c.amps) / scaleAmps),
+                    neutral: c.terminal === neutral
+                }))
+            }
+            : null),
+        neutralShare: n && phaseMax > 0 ? (100 * n.amps) / phaseMax : null
+    };
+}

package/dist/diagram/results-table.d.ts

@@ -0,0 +1,47 @@
+import type { ResultSnapshot } from './snapshot.js';
+export type TableKind = 'bus' | 'branch';
+type Cell = string | number | null;
+export type TableRow = Record<string, Cell> & {
+    state: string;
+};
+export interface TableColumn {
+    key: string;
+    label: string;
+    unit?: string;
+    numeric?: boolean;
+    digits?: number;
+    title?: string;
+}
+export interface TableNames {
+    buses: {
+        id: string;
+        source?: string;
+    }[];
+    branches: {
+        id: string;
+        family: string;
+        from: number;
+        to: number;
+        inService: boolean;
+    }[];
+}
+export interface TableModel {
+    kind: TableKind;
+    count: number;
+    columns: TableColumn[];
+    row(index: number): TableRow;
+}
+/** Rows are built on demand and cached in a bounded window, so 100k-row snapshots stay cheap. */
+export declare function tableModel(result: ResultSnapshot, names: TableNames, kind: TableKind): TableModel;
+export interface TableQuery {
+    text?: string;
+    issuesOnly?: boolean;
+    sortKey?: string | null;
+    descending?: boolean;
+}
+/** Filter by text over identities and optionally issues only, then a stable sort with missing
+ * values last in both directions. */
+export declare function queryTable(model: TableModel, q?: TableQuery): Int32Array;
+/** Full-precision CSV of the given rows, units in the header, provenance as `#` comment lines. */
+export declare function tableCsv(model: TableModel, indices: Iterable<number>, provenance?: string[]): string;
+export {};

package/dist/diagram/results-table.js

@@ -0,0 +1,173 @@
+import { worstBand } from './colour-modes.js';
+import { busState, busUnbalance, loadingState } from './summary.js';
+const BUS_COLUMNS = [
+    { key: 'id', label: 'Bus' },
+    { key: 'source', label: 'Source' },
+    { key: 'reference', label: 'Reference' },
+    { key: 'pairs', label: 'Pairs' },
+    { key: 'v0', label: 'V1', unit: 'V', numeric: true, digits: 2 },
+    { key: 'v1', label: 'V2', unit: 'V', numeric: true, digits: 2 },
+    { key: 'v2', label: 'V3', unit: 'V', numeric: true, digits: 2 },
+    {
+        key: 'band',
+        label: 'Band position',
+        unit: '±1 = limit',
+        numeric: true,
+        digits: 3,
+        title: 'Worst pair: −1 at the declared minimum, +1 at the maximum; sorts by distance from mid-band'
+    },
+    { key: 'unbalance', label: 'Unbalance', unit: '%', numeric: true, digits: 2 },
+    { key: 'unbalanceBasis', label: 'Basis' },
+    { key: 'state', label: 'Status' }
+];
+const BRANCH_COLUMNS = [
+    { key: 'id', label: 'Branch' },
+    { key: 'family', label: 'Type' },
+    { key: 'from', label: 'From bus' },
+    { key: 'to', label: 'To bus' },
+    {
+        key: 'pFrom',
+        label: 'P from',
+        unit: 'kW',
+        numeric: true,
+        digits: 2,
+        title: 'Positive into the equipment'
+    },
+    { key: 'qFrom', label: 'Q from', unit: 'kvar', numeric: true, digits: 2 },
+    {
+        key: 'pTo',
+        label: 'P to',
+        unit: 'kW',
+        numeric: true,
+        digits: 2,
+        title: 'Positive into the equipment'
+    },
+    { key: 'qTo', label: 'Q to', unit: 'kvar', numeric: true, digits: 2 },
+    {
+        key: 'loss',
+        label: 'Losses',
+        unit: 'kW',
+        numeric: true,
+        digits: 3,
+        title: 'Sum of both end P'
+    },
+    { key: 'loading', label: 'Loading', unit: '%', numeric: true, digits: 1 },
+    { key: 'state', label: 'Status' }
+];
+/** Rows are built on demand and cached in a bounded window, so 100k-row snapshots stay cheap. */
+export function tableModel(result, names, kind) {
+    const cache = new Map();
+    const build = (i) => {
+        if (kind === 'bus') {
+            const bus = result.buses[i];
+            const u = busUnbalance(bus);
+            return {
+                id: names.buses[i].id,
+                source: names.buses[i].source ?? null,
+                reference: bus.pairs.length ? [...new Set(bus.pairs.map((p) => p.zone))].join(', ') : null,
+                pairs: bus.pairs.map((p) => p.pair.join('–')).join(' ') || null,
+                v0: bus.pairs[0]?.volts ?? null,
+                v1: bus.pairs[1]?.volts ?? null,
+                v2: bus.pairs[2]?.volts ?? null,
+                band: worstBand(bus.pairs),
+                unbalance: u?.percent ?? null,
+                unbalanceBasis: u?.definition ?? null,
+                state: busState(bus)
+            };
+        }
+        const name = names.branches[i];
+        const { ends, loading, loss } = result.branches[i];
+        const [a, b] = ends;
+        return {
+            id: name.id,
+            family: name.family,
+            from: names.buses[name.from]?.id ?? null,
+            to: names.buses[name.to]?.id ?? null,
+            pFrom: a?.p ?? null,
+            qFrom: a?.q ?? null,
+            pTo: b?.p ?? null,
+            qTo: b?.q ?? null,
+            // The equipment's loss, on its first edge only, so the column sums to the total.
+            loss: loss?.p ?? null,
+            loading,
+            state: name.inService ? loadingState(loading) : 'inactive'
+        };
+    };
+    return {
+        kind,
+        count: kind === 'bus' ? result.buses.length : result.branches.length,
+        columns: kind === 'bus' ? BUS_COLUMNS : BRANCH_COLUMNS,
+        row(i) {
+            let row = cache.get(i);
+            if (!row) {
+                if (cache.size > 4096)
+                    cache.clear();
+                row = build(i);
+                cache.set(i, row);
+            }
+            return row;
+        }
+    };
+}
+const ISSUE_STATES = {
+    bus: new Set(['violation']),
+    branch: new Set(['violation', 'warning'])
+};
+const isMissing = (v) => v === null || (typeof v === 'number' && Number.isNaN(v));
+/** Filter by text over identities and optionally issues only, then a stable sort with missing
+ * values last in both directions. */
+export function queryTable(model, q = {}) {
+    const text = (q.text ?? '').trim().toLowerCase();
+    const out = [];
+    for (let i = 0; i < model.count; i++) {
+        const row = model.row(i);
+        if (q.issuesOnly && !ISSUE_STATES[model.kind].has(row.state))
+            continue;
+        if (text &&
+            !['id', 'source', 'from', 'to', 'family'].some((k) => String(row[k] ?? '')
+                .toLowerCase()
+                .includes(text)))
+            continue;
+        out.push(i);
+    }
+    const column = model.columns.find((c) => c.key === q.sortKey);
+    if (column) {
+        const key = column.key;
+        const sign = q.descending ? -1 : 1;
+        const values = new Map(out.map((i) => [i, model.row(i)[key]]));
+        out.sort((a, b) => {
+            const x = values.get(a) ?? null;
+            const y = values.get(b) ?? null;
+            if (isMissing(x) || isMissing(y))
+                return isMissing(x) === isMissing(y) ? a - b : isMissing(x) ? 1 : -1;
+            const order = column.numeric
+                ? key === 'band'
+                    ? Math.abs(x) - Math.abs(y)
+                    : x - y
+                : String(x).localeCompare(String(y));
+            return order * sign || a - b;
+        });
+    }
+    return Int32Array.from(out);
+}
+/** Text a spreadsheet would evaluate as a formula gets a leading apostrophe; numbers stay numeric. */
+function csvCell(v) {
+    if (v === null || v === undefined)
+        return '';
+    let s = String(v);
+    if (typeof v !== 'number' && /^[=+\-@\t\r]/.test(s))
+        s = `'${s}`;
+    return /[",\n\r']/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+/** Full-precision CSV of the given rows, units in the header, provenance as `#` comment lines. */
+export function tableCsv(model, indices, provenance = []) {
+    const lines = [
+        ...provenance.map((line) => `# ${line}`),
+        model.columns.map((c) => csvCell(c.unit ? `${c.label} (${c.unit})` : c.label)).join(',')
+    ];
+    for (const i of indices) {
+        const row = model.row(i);
+        lines.push(model.columns.map((c) => csvCell(row[c.key])).join(','));
+    }
+    return lines.join('\r\n') + '\r\n';
+}

package/dist/diagram/schematic-equipment.d.ts

@@ -0,0 +1,133 @@
+import type { DistAttachmentKind, DistConnection, DistGraph } from '@tellegen/engine';
+import type { SchematicGeometry } from './schematic-layout.js';
+/** A stroked glyph: polylines in symbol units, x along the connection, y down. */
+export type Glyph = [number, number][][];
+/** Branch glyphs, centred on the branch and spanning `±INLINE_HALF` along it, where the drawn line
+ * is interrupted. Shapes follow the #177 specimens: a two-winding transformer as two overlapping
+ * circles (no conductor continuity), a generic switch as a blade between two contacts, open when
+ * the pole is open. A line has no glyph. */
+export declare const INLINE_HALF = 1.4;
+export declare function branchGlyph(kind: string, closed: boolean): Glyph | null;
+/** Attachment glyphs, connected at the origin and extending along +x. A load is a demand arrow, a
+ * generator a machine circle with a G, an external source an AC supply circle with a sinusoid, an
+ * inverter-based resource a converter box (DC bar, diagonal, AC wave), and a shunt a general
+ * admittance block: BMOPF shunts can be conductive, so no capacitor is asserted. A shunt on a bus's
+ * neutral and nothing else is a neutral earth through an impedance (an MEN electrode, say): drawn
+ * as an impedance box in series with the IEC 60617 earth (three shrinking bars), not as a solid
+ * earth, since a shunt always has finite admittance. A perfectly grounded terminal is a solid earth:
+ * the earth symbol alone. */
+export declare function attachmentGlyph(kind: SymbolKind): Glyph;
+/** Conductor marks across a line, centred on it: one slash per phase conductor and a slash ending
+ * in a small circle for the neutral (the IEC 60617 convention). */
+export declare function conductorTicks(phases: number, neutral: boolean): Glyph;
+/** Phase conductors and whether a neutral runs, from a branch's conductor pairs: a conductor whose
+ * from terminal is the from bus's neutral is the neutral. */
+export declare function conductorSet(graph: DistGraph, k: number): {
+    phases: number;
+    neutral: boolean;
+};
+/** Attachment symbols: the PowerIO kinds, plus `earth` for a shunt on a bus's neutral alone and
+ * `ground` for a bus's perfectly grounded terminals. */
+export type SymbolKind = DistAttachmentKind | 'earth' | 'ground';
+/** Drawing order of attachment kinds below a bus. A neutral earth shares the shunt slot (the
+ * engine layout reserves one slot per PowerIO kind). */
+export declare const ATTACHMENT_ORDER: SymbolKind[];
+export declare const ATTACHMENT_NAMES: Record<SymbolKind, string>;
+/** Shunts of `bus` connected to its neutral terminal and to nothing else: neutral earths. */
+export declare function neutralEarths(bus: DistGraph['buses'][number]): Set<string>;
+/** One symbol: what it stands for and where to pick it. */
+export interface EquipmentItem {
+    kind: SymbolKind | 'transformer' | 'switch';
+    /** Branch index for inline symbols, bus index for attachments. */
+    edge: number;
+    bus: number;
+    ids: string[];
+    x: number;
+    y: number;
+    /** An attachment's terminals in its own order and its connection, where the graph has them. */
+    terminals?: string[];
+    connection?: DistConnection;
+    /** A transformer's vector group and rating, such as "Dyn · 500 kVA". */
+    label?: string;
+}
+export interface EquipmentSymbols {
+    /** Glyph strokes: `x, y, 0` per segment end. */
+    sources: Float32Array;
+    targets: Float32Array;
+    items: EquipmentItem[];
+    /** The geometry with each branch line interrupted where its symbol sits. */
+    cut: SchematicGeometry;
+    /** Symbol unit in drawing units: glyphs are about two units across. */
+    unit: number;
+    /** Kinds drawn, for the legend. */
+    kinds: Set<EquipmentItem['kind']>;
+    /** Owner of each glyph stroke: an edge index, or `-(bus + 1)` for attachment strokes. */
+    owner: Int32Array;
+    /** Conductor marks on lines (drawn only when zoomed further in), with their edge per stroke. */
+    ticks: {
+        sources: Float32Array;
+        targets: Float32Array;
+        edge: Int32Array;
+    };
+    /** Per edge: `x, y` where its symbol or conductor marks sit (NaN when not drawn). */
+    anchors: Float32Array;
+    /** Per edge: unit direction of the segment carrying the anchor, pointing from the edge's
+     * `from` bus towards its `to` bus, and the free length upstream of the anchor on it. */
+    flowDir: Float32Array;
+    room: Float32Array;
+    /** Per edge: how many branches are drawn along exactly the same segment (1 when alone), as
+     * when an MV and an LV line hang between buses at the same positions. */
+    sharedRoute: Uint8Array;
+    /** Routes carrying more than one branch: their member edges, in drawing order. */
+    routeGroups: number[][];
+    /** Per edge: its index in `routeGroups`, or −1 when its route is its own. */
+    routeOf: Int32Array;
+    /** Per edge: the segment its symbol or marks sit on (−1 when not drawn). */
+    host: Int32Array;
+}
+/** Symbols for every branch and attachment of `graph` drawn on `geometry`.
+ *
+ * Inline symbols sit on the child-end segment of a tree route, a fixed distance from the child bus
+ * so they line up in columns; other branches carry theirs at the middle of their middle segment.
+ * Attachments hang from a riser below the bus, one slot per kind (the engine layout reserves that
+ * room), each on a short tick with its count when there are several. */
+export declare function schematicEquipment(graph: DistGraph, geometry: SchematicGeometry): EquipmentSymbols;
+/** An SVG path for a glyph in symbol units, for legends. */
+export declare function glyphPath(glyph: Glyph, scale: number, dx?: number, dy?: number): string;
+/** Power-flow chevrons: one per closed branch with a result, just upstream of its symbol or marks
+ * on the same segment, pointing the way active power flows (from the `from` end when the power
+ * into the branch there is positive). Branches carrying under `minPower` (in the units of `p`)
+ * get none. */
+export declare function flowArrows(symbols: EquipmentSymbols, ends: ({
+    p: number;
+} | null)[][], closed: boolean[], minPower?: number): {
+    sources: Float32Array;
+    targets: Float32Array;
+    edge: Int32Array;
+};
+/** Complex power into each element (loads, generators, IBRs, shunts) by element id, and for
+ * sources the power they draw (the negative of what they inject), so every attachment reads with
+ * the same convention: positive is consumption. Branch ports are left out: names are unique only
+ * within a family, and a line sharing a load's name must not add to it. */
+export declare function elementPowers(result: {
+    element_ports: {
+        element: string;
+        kind?: string;
+        power_into_element: {
+            re: number;
+            im: number;
+        };
+    }[];
+    source_reactions: {
+        source: string;
+        power_into_network: {
+            re: number;
+            im: number;
+        };
+    }[];
+}): Map<string, {
+    p: number;
+    q: number;
+}>;
+/** `12.3 kW 4.1 kvar` for a power in W and var. */
+export declare function formatPower(p: number, q: number): string;