circuitjson-toolkit 1.0.3 → 1.0.16

package/src/core/spice/SpiceFallbackSimulationEngine.mjs

@@ -0,0 +1,168 @@
+import { SpiceDirectiveParser } from './SpiceDirectiveParser.mjs'
+
+/**
+ * Provides a deterministic local fallback for simple transient examples.
+ */
+export class SpiceFallbackSimulationEngine {
+    /**
+     * Simulates constant independent sources from a SPICE netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Promise<object>}
+     */
+    async simulate(spiceString) {
+        const timeValues =
+            SpiceFallbackSimulationEngine.#buildTimeValues(spiceString)
+        const voltageRows =
+            SpiceFallbackSimulationEngine.#buildVoltageRows(spiceString)
+        const currentRows =
+            SpiceFallbackSimulationEngine.#buildCurrentRows(spiceString)
+
+        return {
+            dataType: 'real',
+            data: [
+                { name: 'time', type: 'time', values: timeValues },
+                ...voltageRows.map((row) => ({
+                    name: row.name,
+                    type: 'voltage',
+                    values: timeValues.map(() => row.value)
+                })),
+                ...currentRows.map((row) => ({
+                    name: row.name,
+                    type: 'current',
+                    values: timeValues.map(() => row.value)
+                }))
+            ]
+        }
+    }
+
+    /**
+     * Builds transient timestamps from the netlist TRAN directive.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {number[]}
+     */
+    static #buildTimeValues(spiceString) {
+        const tran = SpiceDirectiveParser.parseTransient(spiceString)
+        const tstep = tran?.tstep && tran.tstep > 0 ? tran.tstep : 0.001
+        const tstart = tran?.tstart ?? 0
+        const tstop = tran?.tstop && tran.tstop >= tstart ? tran.tstop : tstart
+        const stepCount = Math.max(0, Math.round((tstop - tstart) / tstep))
+
+        return Array.from({ length: stepCount + 1 }, (_, index) =>
+            SpiceFallbackSimulationEngine.#round(tstart + index * tstep)
+        )
+    }
+
+    /**
+     * Builds constant voltage result rows from independent DC voltage sources.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {{ name: string, value: number }[]}
+     */
+    static #buildVoltageRows(spiceString) {
+        const nodeVoltages = new Map([['0', 0]])
+
+        for (const line of SpiceFallbackSimulationEngine.#componentLines(
+            spiceString
+        )) {
+            const tokens = line.split(/\s+/).filter(Boolean)
+            const name = tokens[0] || ''
+            if (!/^v/i.test(name) || tokens.length < 4) continue
+
+            const positiveNode = tokens[1]
+            const negativeNode = tokens[2]
+            const value =
+                SpiceFallbackSimulationEngine.#parseDcValue(tokens.slice(3)) ??
+                0
+            const negativeValue =
+                SpiceFallbackSimulationEngine.#lookupNodeValue(
+                    nodeVoltages,
+                    negativeNode
+                ) ?? 0
+
+            nodeVoltages.set(
+                String(positiveNode).toLowerCase(),
+                negativeValue + value
+            )
+        }
+
+        return [...nodeVoltages.entries()]
+            .filter(([node]) => node !== '0')
+            .map(([node, value]) => ({
+                name: `v(${node})`,
+                value: SpiceFallbackSimulationEngine.#round(value)
+            }))
+    }
+
+    /**
+     * Builds constant current result rows from independent DC current sources.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {{ name: string, value: number }[]}
+     */
+    static #buildCurrentRows(spiceString) {
+        const rows = []
+
+        for (const line of SpiceFallbackSimulationEngine.#componentLines(
+            spiceString
+        )) {
+            const tokens = line.split(/\s+/).filter(Boolean)
+            const name = tokens[0] || ''
+            if (!/^i/i.test(name) || tokens.length < 4) continue
+
+            rows.push({
+                name: `i(${name})`,
+                value:
+                    SpiceFallbackSimulationEngine.#parseDcValue(
+                        tokens.slice(3)
+                    ) ?? 0
+            })
+        }
+
+        return rows
+    }
+
+    /**
+     * Returns non-comment component lines from a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {string[]}
+     */
+    static #componentLines(spiceString) {
+        return String(spiceString || '')
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(
+                (line) => line && !line.startsWith('*') && !line.startsWith('.')
+            )
+    }
+
+    /**
+     * Parses a DC source value from component tail tokens.
+     * @param {string[]} tokens Component tokens after node names.
+     * @returns {number | undefined}
+     */
+    static #parseDcValue(tokens) {
+        const dcIndex = tokens.findIndex(
+            (token) => token.toLowerCase() === 'dc'
+        )
+        const valueToken = dcIndex >= 0 ? tokens[dcIndex + 1] : tokens[0]
+
+        return SpiceDirectiveParser.parseNumber(valueToken)
+    }
+
+    /**
+     * Looks up a node voltage by normalized node name.
+     * @param {Map<string, number>} nodeVoltages Node voltage map.
+     * @param {string} nodeName Node name.
+     * @returns {number | undefined}
+     */
+    static #lookupNodeValue(nodeVoltages, nodeName) {
+        return nodeVoltages.get(String(nodeName || '').toLowerCase())
+    }
+
+    /**
+     * Rounds numeric output to a stable precision.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        return Number(Number(value).toPrecision(12))
+    }
+}

package/src/core/spice/SpiceSimulationDiagnostics.mjs

@@ -0,0 +1,234 @@
+const PROBE_METADATA_COMMENT_PATTERNS = [
+    {
+        probeType: 'voltage',
+        pattern:
+            /^\s*\*\s*(?:ecadforge_voltage_probe|circuitjson_voltage_probe|simulation_voltage_probe)\s+(.+)\s*$/,
+        requiredFields: [
+            'simulation_voltage_probe_id',
+            'spice_vector',
+            'source_node_name'
+        ]
+    },
+    {
+        probeType: 'current',
+        pattern:
+            /^\s*\*\s*(?:ecadforge_current_probe|circuitjson_current_probe|simulation_current_probe)\s+(.+)\s*$/,
+        requiredFields: ['simulation_current_probe_id', 'spice_vector']
+    }
+]
+
+/**
+ * Builds diagnostics for SPICE syntax that local helpers cannot resolve.
+ */
+export class SpiceSimulationDiagnostics {
+    /**
+     * Returns syntax diagnostics for a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {object[]}
+     */
+    static analyze(spiceString) {
+        const diagnostics = []
+        const lines = String(spiceString || '').split(/\r?\n/)
+
+        lines.forEach((line, index) => {
+            const lineNumber = index + 1
+            diagnostics.push(
+                ...SpiceSimulationDiagnostics.#probeMetadataDiagnostics(
+                    line,
+                    lineNumber
+                )
+            )
+
+            if (/^\s*\.lib\b/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_external_library_unsupported',
+                        lineNumber,
+                        message:
+                            'External .lib directives are not resolved by the local simulator fallback.'
+                    })
+                )
+            }
+
+            if (/^\s*\.include\b/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_external_include_unsupported',
+                        lineNumber,
+                        message:
+                            'External .include directives are not resolved by the local simulator fallback.'
+                    })
+                )
+            }
+
+            if (/\bpwl\s+repeat\b/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_pwl_repeat_unsupported',
+                        lineNumber,
+                        message:
+                            'PWL REPEAT source syntax is reported for callers that need a full simulator.'
+                    })
+                )
+            }
+
+            if (/^\s*\.model\b.*\bako\s*:/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_pspice_ako_model_unsupported',
+                        lineNumber,
+                        message:
+                            'PSPICE AKO model aliases are not resolved by the local simulator fallback.'
+                    })
+                )
+            }
+
+            if (/^\s*d\S*\s+\S+\s+\S+\s+\S+\s+[+-]?\d/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_pspice_diode_area_factor_unsupported',
+                        lineNumber,
+                        message:
+                            'PSPICE diode area factor syntax is not evaluated by the local simulator fallback.'
+                    })
+                )
+            }
+
+            if (/\btable\s*\{/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_pspice_table_source_unsupported',
+                        lineNumber,
+                        message:
+                            'PSPICE TABLE source syntax is not evaluated by the local simulator fallback.'
+                    })
+                )
+            }
+
+            if (/^\s*\.model\b.*\bvswitch\s*\(/i.test(line)) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_pspice_vswitch_model_unsupported',
+                        lineNumber,
+                        message:
+                            'PSPICE VSWITCH model syntax is not evaluated by the local simulator fallback.'
+                    })
+                )
+            }
+        })
+
+        return diagnostics
+    }
+
+    /**
+     * Returns diagnostics for requested plots that did not produce graphs.
+     * @param {{ normalizedToken: string, originalToken: string }[]} missingPlots Missing requested plot tokens.
+     * @returns {object[]}
+     */
+    static requestedPlotDiagnostics(missingPlots) {
+        return missingPlots.map((plot) => ({
+            severity: 'warning',
+            code: 'spice_requested_plot_missing',
+            plot: plot.originalToken,
+            normalizedPlot: plot.normalizedToken,
+            message:
+                'Requested transient plot did not match simulator output: ' +
+                plot.originalToken
+        }))
+    }
+
+    /**
+     * Returns diagnostics for malformed probe metadata comments on one line.
+     * @param {string} line SPICE netlist line.
+     * @param {number} lineNumber One-based source line number.
+     * @returns {object[]}
+     */
+    static #probeMetadataDiagnostics(line, lineNumber) {
+        const diagnostics = []
+
+        for (const definition of PROBE_METADATA_COMMENT_PATTERNS) {
+            const match = line.match(definition.pattern)
+            if (!match?.[1]) continue
+
+            let parsed
+            try {
+                parsed = JSON.parse(match[1])
+            } catch {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_probe_metadata_invalid_json',
+                        lineNumber,
+                        probeType: definition.probeType,
+                        message:
+                            SpiceSimulationDiagnostics.#probeTypeLabel(
+                                definition.probeType
+                            ) + ' probe metadata comment contains invalid JSON.'
+                    })
+                )
+                continue
+            }
+
+            if (
+                !SpiceSimulationDiagnostics.#hasRequiredStringFields(
+                    parsed,
+                    definition.requiredFields
+                )
+            ) {
+                diagnostics.push(
+                    SpiceSimulationDiagnostics.#diagnostic({
+                        code: 'spice_probe_metadata_invalid_shape',
+                        lineNumber,
+                        probeType: definition.probeType,
+                        message:
+                            SpiceSimulationDiagnostics.#probeTypeLabel(
+                                definition.probeType
+                            ) +
+                            ' probe metadata comment is missing required string fields.'
+                    })
+                )
+            }
+        }
+
+        return diagnostics
+    }
+
+    /**
+     * Returns true when parsed metadata contains all required string fields.
+     * @param {unknown} parsed Parsed metadata value.
+     * @param {string[]} requiredFields Required field names.
+     * @returns {boolean}
+     */
+    static #hasRequiredStringFields(parsed, requiredFields) {
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return false
+        }
+
+        return requiredFields.every(
+            (field) => typeof parsed[field] === 'string'
+        )
+    }
+
+    /**
+     * Returns a display label for a probe type.
+     * @param {string} probeType Probe metadata type.
+     * @returns {string}
+     */
+    static #probeTypeLabel(probeType) {
+        return probeType === 'voltage' ? 'Voltage' : 'Current'
+    }
+
+    /**
+     * Builds a warning diagnostic object.
+     * @param {{ code: string, lineNumber: number, message: string, probeType?: string }} options Diagnostic options.
+     * @returns {object}
+     */
+    static #diagnostic(options) {
+        return {
+            severity: 'warning',
+            code: options.code,
+            lineNumber: options.lineNumber,
+            ...(options.probeType ? { probeType: options.probeType } : {}),
+            message: options.message
+        }
+    }
+}