circuitjson-toolkit 1.0.2 → 1.0.10

package/src/core/spice/SpiceDirectiveParser.mjs

@@ -0,0 +1,231 @@
+const NUMBER_SUFFIX_MULTIPLIERS = {
+    t: 1e12,
+    g: 1e9,
+    meg: 1e6,
+    k: 1e3,
+    m: 1e-3,
+    ms: 1e-3,
+    u: 1e-6,
+    us: 1e-6,
+    n: 1e-9,
+    ns: 1e-9,
+    p: 1e-12,
+    ps: 1e-12,
+    f: 1e-15,
+    fs: 1e-15,
+    s: 1
+}
+const VOLTAGE_PROBE_COMMENT_PATTERN =
+    /^\s*\*\s*(?:ecadforge_voltage_probe|circuitjson_voltage_probe|simulation_voltage_probe)\s+(.+)\s*$/
+const CURRENT_PROBE_COMMENT_PATTERN =
+    /^\s*\*\s*(?:ecadforge_current_probe|circuitjson_current_probe|simulation_current_probe)\s+(.+)\s*$/
+
+/**
+ * Parses SPICE directives and metadata comments used by simulation helpers.
+ */
+export class SpiceDirectiveParser {
+    /**
+     * Parses transient directive timing parameters.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {{ tstep?: number, tstop?: number, tstart?: number, tmax?: number, uic?: boolean } | null}
+     */
+    static parseTransient(spiceString) {
+        for (const rawLine of String(spiceString || '').split(/\r?\n/)) {
+            const line = rawLine.trim()
+            if (!line || line.startsWith('*')) continue
+            if (!line.toLowerCase().startsWith('.tran')) continue
+
+            const [withoutComment = ''] = line.split(';')
+            const tokens = withoutComment.split(/\s+/).filter(Boolean)
+            const values = []
+            let uic = false
+
+            for (const token of tokens.slice(1)) {
+                if (token.toLowerCase() === 'uic') {
+                    uic = true
+                    continue
+                }
+
+                const value = SpiceDirectiveParser.parseNumber(token)
+                if (value !== undefined) values.push(value)
+            }
+
+            return {
+                ...(values[0] !== undefined ? { tstep: values[0] } : {}),
+                ...(values[1] !== undefined ? { tstop: values[1] } : {}),
+                ...(values[2] !== undefined ? { tstart: values[2] } : {}),
+                ...(values[3] !== undefined ? { tmax: values[3] } : {}),
+                ...(uic ? { uic: true } : {})
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Parses requested transient plot tokens from the first PRINT directive.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, string> | null}
+     */
+    static parseRequestedPlots(spiceString) {
+        const match = String(spiceString || '').match(/\.print\s+tran\s+(.*)/i)
+        if (!match?.[1]) return null
+
+        const tokens = match[1].match(/[VI]\s*\([^)]+\)/gi)
+        if (!tokens) return null
+
+        const plots = new Map()
+        for (const token of tokens) {
+            const normalizedToken = SpiceDirectiveParser.normalizeVector(token)
+            if (!plots.has(normalizedToken)) {
+                plots.set(normalizedToken, token)
+            }
+        }
+
+        return plots
+    }
+
+    /**
+     * Extracts voltage probe metadata comments from a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, object>}
+     */
+    static extractVoltageProbeMetadata(spiceString) {
+        return SpiceDirectiveParser.#extractProbeMetadata(
+            spiceString,
+            VOLTAGE_PROBE_COMMENT_PATTERN,
+            (parsed) => {
+                if (
+                    typeof parsed.simulation_voltage_probe_id !== 'string' ||
+                    typeof parsed.spice_vector !== 'string' ||
+                    typeof parsed.source_node_name !== 'string'
+                ) {
+                    return null
+                }
+
+                return {
+                    simulation_voltage_probe_id:
+                        parsed.simulation_voltage_probe_id,
+                    name:
+                        typeof parsed.name === 'string'
+                            ? parsed.name
+                            : undefined,
+                    spice_vector: parsed.spice_vector,
+                    source_node_name: parsed.source_node_name,
+                    reference_node_name:
+                        typeof parsed.reference_node_name === 'string'
+                            ? parsed.reference_node_name
+                            : undefined
+                }
+            }
+        )
+    }
+
+    /**
+     * Extracts current probe metadata comments from a netlist.
+     * @param {string} spiceString SPICE netlist text.
+     * @returns {Map<string, object>}
+     */
+    static extractCurrentProbeMetadata(spiceString) {
+        return SpiceDirectiveParser.#extractProbeMetadata(
+            spiceString,
+            CURRENT_PROBE_COMMENT_PATTERN,
+            (parsed) => {
+                if (
+                    typeof parsed.simulation_current_probe_id !== 'string' ||
+                    typeof parsed.spice_vector !== 'string'
+                ) {
+                    return null
+                }
+
+                return {
+                    simulation_current_probe_id:
+                        parsed.simulation_current_probe_id,
+                    name:
+                        typeof parsed.name === 'string'
+                            ? parsed.name
+                            : undefined,
+                    spice_vector: parsed.spice_vector,
+                    source_component_id:
+                        typeof parsed.source_component_id === 'string'
+                            ? parsed.source_component_id
+                            : undefined,
+                    source_trace_id:
+                        typeof parsed.source_trace_id === 'string'
+                            ? parsed.source_trace_id
+                            : undefined
+                }
+            }
+        )
+    }
+
+    /**
+     * Normalizes a simulator vector token for map lookups.
+     * @param {string} value Raw vector token.
+     * @returns {string}
+     */
+    static normalizeVector(value) {
+        return String(value || '')
+            .toLowerCase()
+            .replace(/\s/g, '')
+    }
+
+    /**
+     * Parses a SPICE numeric token with common suffix multipliers.
+     * @param {string} token Numeric token.
+     * @returns {number | undefined}
+     */
+    static parseNumber(token) {
+        const normalized = String(token || '')
+            .replace(/[,]/g, '')
+            .toLowerCase()
+        const match = normalized.match(
+            /^([+-]?\d*\.?\d+(?:e[+-]?\d+)?)([a-z]+)?$/i
+        )
+
+        if (!match) return undefined
+
+        const base = Number.parseFloat(match[1] || '')
+        if (!Number.isFinite(base)) return undefined
+
+        const suffix = match[2] || ''
+        if (!suffix) return base
+
+        const multiplier =
+            NUMBER_SUFFIX_MULTIPLIERS[suffix] ??
+            NUMBER_SUFFIX_MULTIPLIERS[suffix.replace(/s$/, '')] ??
+            1
+
+        return base * multiplier
+    }
+
+    /**
+     * Extracts JSON probe metadata comments with a validator callback.
+     * @param {string} spiceString SPICE netlist text.
+     * @param {RegExp} pattern Comment matcher.
+     * @param {(parsed: object) => object | null} shapeMetadata Metadata shaper.
+     * @returns {Map<string, object>}
+     */
+    static #extractProbeMetadata(spiceString, pattern, shapeMetadata) {
+        const metadata = new Map()
+
+        for (const line of String(spiceString || '').split(/\r?\n/)) {
+            const match = line.match(pattern)
+            if (!match?.[1]) continue
+
+            try {
+                const shapedMetadata = shapeMetadata(JSON.parse(match[1]))
+                if (!shapedMetadata) continue
+
+                metadata.set(
+                    SpiceDirectiveParser.normalizeVector(
+                        shapedMetadata.spice_vector
+                    ),
+                    shapedMetadata
+                )
+            } catch {}
+        }
+
+        return metadata
+    }
+}

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
+        }
+    }
+}