@vessel-dsp/compiler 0.18.1 → 0.21.0

package/dist/device-laws.js

@@ -25,6 +25,135 @@ import { GROUND } from "./types.js";
 import { LED_COLOUR_RECORD_ID } from "./registry-data/led.js";
 /** Room-temperature thermal voltage; the diode law needs a reference somewhere. */
 export const THERMAL_VOLTAGE = 0.025_852;
+/**
+ * The absolute temperature every registry fit is referred to, in kelvin.
+ *
+ * Fitted saturation currents and the engine thermal-voltage constant are stated at
+ * this temperature (`THERMAL_VOLTAGE` is kT/q at 300 K, not 273.15 + 27), so the
+ * ambient-temperature fold scales relative to it and ngspice parity sets
+ * `tnom=26.85` to match. With no ambient option the compile stamps exactly today's
+ * numbers: the fold is skipped outright below a 1e-9 K band around this value, so
+ * the default path shares no arithmetic with the scaled one.
+ */
+export const REFERENCE_TEMPERATURE_KELVIN = 300;
+/** Offset between the compile option's Celsius and the fold's kelvin. */
+const CELSIUS_TO_KELVIN = 273.15;
+/** Boltzmann constant, J/K (exact, SI). */
+const BOLTZMANN_JOULES_PER_KELVIN = 1.380_649e-23;
+/** Elementary charge, C (exact, SI). */
+const ELEMENTARY_CHARGE_COULOMBS = 1.602_176_634e-19;
+/**
+ * Bandgap energy per junction material, in eV: the ngspice defaults for the
+ * matching device kinds (silicon diode/BJT 1.11, germanium 0.67, Schottky barrier
+ * 0.69). An LED junction is a III-V the three-material law does not cover; LEDs run
+ * the silicon bandgap and the material-default notice says so.
+ */
+const BANDGAP_ELECTRON_VOLTS = {
+    silicon: 1.11,
+    germanium: 0.67,
+    schottky: 0.69,
+};
+/** The saturation-current temperature exponent (SPICE XTI), shared by all three. */
+const SATURATION_TEMPERATURE_EXPONENT = 3;
+/**
+ * The compile option's Celsius as an absolute temperature, validated.
+ *
+ * Throws a `RangeError` naming the option for a non-finite value or anything below
+ * absolute zero: an option is a programmer error, not a source refusal, so it
+ * propagates rather than becoming a pedal-shaped answer.
+ */
+export function kelvinFromAmbientCelsius(celsius) {
+    if (!Number.isFinite(celsius)) {
+        throw new RangeError(`ambientTemperatureC ${String(celsius)} is not a finite temperature in degrees Celsius`);
+    }
+    if (celsius < -CELSIUS_TO_KELVIN) {
+        throw new RangeError(`ambientTemperatureC ${String(celsius)} is below absolute zero (-273.15 C)`);
+    }
+    return celsius + CELSIUS_TO_KELVIN;
+}
+/** Whether the fold changes any number: outside a 1e-9 K band around 300 K. */
+export function ambientTemperatureScalesJunction(kelvin) {
+    return (Math.abs(kelvin - REFERENCE_TEMPERATURE_KELVIN) > 1e-9 &&
+        Number.isFinite(kelvin));
+}
+/**
+ * The SPICE temperature ratio a junction saturation current scales by, relative to
+ * the 300 K reference the registry fits are referred to:
+ * `Is(T) = Is * (T/Tnom)^(XTI/N) * exp((Eg*q/(N*k)) * (1/Tnom - 1/T))` with XTI = 3.
+ * `n` is the junction's own emission coefficient (1 for a BJT or OTA bias diode).
+ */
+function saturationCurrentRatio(emissionCoefficient, material, kelvin) {
+    const bandgapJoules = BANDGAP_ELECTRON_VOLTS[material] * ELEMENTARY_CHARGE_COULOMBS;
+    const slope = bandgapJoules /
+        (emissionCoefficient * BOLTZMANN_JOULES_PER_KELVIN);
+    return ((kelvin / REFERENCE_TEMPERATURE_KELVIN) **
+        (SATURATION_TEMPERATURE_EXPONENT / emissionCoefficient) *
+        Math.exp(slope * (1 / REFERENCE_TEMPERATURE_KELVIN - 1 / kelvin)));
+}
+/**
+ * Fold one finished diode law to the ambient temperature: `thermalVoltage` scales
+ * with T (today's constant is kT/q at 300 K) and `saturationCurrent` follows the
+ * SPICE law above with the junction's own emission coefficient. Series resistance
+ * and breakdown voltage carry no temperature model and are kept as stated.
+ */
+function diodeLawAtAmbientTemperature(law, material, kelvin) {
+    return {
+        ...law,
+        thermalVoltage: law.thermalVoltage * (kelvin / REFERENCE_TEMPERATURE_KELVIN),
+        saturationCurrent: law.saturationCurrent *
+            saturationCurrentRatio(law.emissionCoefficient, material, kelvin),
+    };
+}
+/**
+ * Fold one finished BJT law to the ambient temperature: as the diode fold, with
+ * the Ebers-Moll ideality of 1. The excess collector-base leakage is a junction
+ * prefactor beyond the ideal reverse current, so it scales with the same ratio;
+ * betas carry no temperature model and are kept as stated.
+ */
+function bjtLawAtAmbientTemperature(law, material, kelvin) {
+    const ratio = saturationCurrentRatio(1, material, kelvin);
+    return {
+        ...law,
+        thermalVoltage: law.thermalVoltage * (kelvin / REFERENCE_TEMPERATURE_KELVIN),
+        saturationCurrent: law.saturationCurrent * ratio,
+        leakageAmps: law.leakageAmps * ratio,
+    };
+}
+/**
+ * Fold one finished OTA law to the ambient temperature: the four-terminal bias
+ * diode is a silicon junction with ideality 1. A law that states no bias-diode
+ * pair (a sections entry carrying transconductance only) gains the scaled class
+ * defaults the lowering would otherwise stamp at 300 K, so the program carries
+ * the temperature rather than the lowering re-defaulting it.
+ */
+function otaLawAtAmbientTemperature(law, kelvin) {
+    const ratio = saturationCurrentRatio(1, "silicon", kelvin);
+    return {
+        ...law,
+        saturationCurrent: (law.saturationCurrent ?? 1e-12) * ratio,
+        thermalVoltage: (law.thermalVoltage ?? THERMAL_VOLTAGE) *
+            (kelvin / REFERENCE_TEMPERATURE_KELVIN),
+    };
+}
+/**
+ * A part's junction material for the temperature fold: the registry entry's typed
+ * `material` for the exact folded part id -- the same rung the law refinement
+ * uses -- or null when no entry states one. Null means the silicon default, which
+ * the compile records (`material-default-silicon`); it is never inferred from the
+ * part number or any prose.
+ */
+export function registryMaterialFor(registry, partNumber) {
+    if (partNumber === null) {
+        return null;
+    }
+    const folded = foldPartId(partNumber);
+    for (const entry of registry.entries) {
+        if (entry.partIds.some((id) => foldPartId(id) === folded)) {
+            return entry.material ?? null;
+        }
+    }
+    return null;
+}
 /**
  * Closed and open switch resistances. Not arbitrary: the ratio sets the matrix
  * condition number, so 1e-2 to 1e9 is chosen to be electrically indistinguishable
@@ -107,6 +236,18 @@ export const SILICON_FORWARD_BETA = 100;
  */
 export const JFET_DEFAULT_THRESHOLD_VOLTS = -2;
 export const JFET_DEFAULT_TRANSCONDUCTANCE = 1e-3;
+/**
+ * A discrete MOSFET's body-diode class defaults, stamped when the registry
+ * record for the exact part types no body parameters (no shipped record does
+ * today). The values are ngspice's own MOS bulk-diode defaults (IS 1e-14 A,
+ * N 1) by value, deliberately: the deck emitter carries the same pair on its
+ * explicit diode, so the two consoles agree by construction rather than by a
+ * fit. A silicon PN junction either way; the name is separate from
+ * `SILICON_SATURATION_CURRENT` so the body default reads beside the fet law.
+ * Named by `fet-law-default-parameters`, never stamped silently.
+ */
+export const MOSFET_BODY_SATURATION_CURRENT = 1e-14;
+export const MOSFET_BODY_EMISSION_COEFFICIENT = 1;
 /**
  * A winding's DC resistance, in the three states the source can be in.
  *
@@ -598,7 +739,7 @@ function zenerRailDerivations(netlist, registry, nodeToVoltage, devicesTouchingN
     }
     return derived;
 }
-export function attachDeviceLaws(netlist, registry) {
+export function attachDeviceLaws(netlist, registry, options) {
     const regulatedBase = registrySuppliedVoltages(netlist, registry);
     const nodeToVoltage = buildNodeToVoltageMap(netlist, regulatedBase);
     const devicesTouchingNode = deviceCountByNode(netlist);
@@ -653,6 +794,10 @@ export function attachDeviceLaws(netlist, registry) {
         internalNodes.set(key, node);
         return node;
     };
+    // The ambient temperature in kelvin this compile folds to. Absent means the
+    // 300 K reference: the junction fold and the thermistor resistance both land
+    // exactly on today's numbers (the fold is skipped outright near 300 K).
+    const ambientKelvin = options?.ambientKelvin ?? REFERENCE_TEMPERATURE_KELVIN;
     const devices = [];
     const resolutions = [];
     for (const device of netlist.devices) {
@@ -664,7 +809,7 @@ export function attachDeviceLaws(netlist, registry) {
         }
         if (expanded === null) {
             devices.push(device);
-            resolutions.push(resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist));
+            resolutions.push(resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist, ambientKelvin));
             continue;
         }
         for (const [section, resolution] of expanded) {
@@ -678,9 +823,44 @@ export function attachDeviceLaws(netlist, registry) {
             devices,
             nodes: internalNodes.size === 0 ? netlist.nodes : [...netlist.nodes, ...internalNodes.values()],
         },
-        resolutions,
+        resolutions: foldAmbientTemperature(devices, resolutions, registry, ambientKelvin),
     };
 }
+/**
+ * Fold the ambient temperature into every finished junction law, at compile time.
+ *
+ * With no ambient (or within a 1e-9 K band of 300 K) the resolutions pass through
+ * untouched -- the same array contents, so every program is byte-identical to
+ * today's. Otherwise each diode, BJT and OTA law is replaced by its scaled copy;
+ * every other outcome (macro, open, unsupported, non-junction laws) is returned as
+ * is. The runtime, the `Program` shape and both consoles are untouched: the option
+ * changes the numbers written into the stamps and nothing else.
+ */
+function foldAmbientTemperature(devices, resolutions, registry, ambientKelvin) {
+    const kelvin = ambientKelvin;
+    if (!ambientTemperatureScalesJunction(kelvin)) {
+        return resolutions;
+    }
+    const byId = new Map(devices.map((device) => [device.id, device]));
+    return resolutions.map((resolution) => {
+        if (resolution.outcome !== "law") {
+            return resolution;
+        }
+        const law = resolution.law;
+        if (law.kind !== "diode" && law.kind !== "bjt" && law.kind !== "ota") {
+            return resolution;
+        }
+        const material = registryMaterialFor(registry, byId.get(resolution.device)?.identity.partNumber ?? null) ??
+            "silicon";
+        if (law.kind === "diode") {
+            return { ...resolution, law: diodeLawAtAmbientTemperature(law, material, kelvin) };
+        }
+        if (law.kind === "bjt") {
+            return { ...resolution, law: bjtLawAtAmbientTemperature(law, material, kelvin) };
+        }
+        return { ...resolution, law: otaLawAtAmbientTemperature(law, kelvin) };
+    });
+}
 /**
  * A multi-section part as one device per section, or `null` when the part is not multi-section.
  *
@@ -2343,7 +2523,7 @@ function packageDeviceParameters(device, registry) {
     }
     return parameters;
 }
-function resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist) {
+function resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist, ambientKelvin = REFERENCE_TEMPERATURE_KELVIN) {
     // A component declared as one transistor that is really several devices in one shell. Opened
     // rather than stamped, for the reason `isNonExecutableIcSupportShell` opens an IC shell: there
     // is no single device here to describe, and a transistor law would invent one. Reported by
@@ -2469,6 +2649,39 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                 law: { kind: "conductance", siemens: 1 / ohms },
             };
         }
+        case "thermistor": {
+            // An NTC disc at the ambient temperature: `R(T) = R_ref * exp(Beta *
+            // (1/T - 1/T_ref))`, folded here at compile time like the junction fold
+            // above, and stamped as the conductance a resistor of that value takes.
+            // Beta 0 folds to exactly R_ref (exp(0) is 1), so the negative control
+            // compiles to the same program as the same-valued resistor.
+            //
+            // **No self-heating.** The resistance is a function of the ambient
+            // alone: the current through the disc does not warm it. A thermistor
+            // that heats under load needs a thermal state the program does not have.
+            const referenceOhms = device.parameters.referenceOhms ?? 0;
+            const beta = device.parameters.betaKelvin ?? 0;
+            const referenceKelvin = device.parameters.referenceKelvin ?? 298.15;
+            if (device.nodes.length !== 2) {
+                return unsupported(device, `thermistor has ${device.nodes.length} terminals, not the two a polarity-free disc carries`);
+            }
+            if (!(referenceOhms > 0) ||
+                !Number.isFinite(beta) ||
+                beta < 0 ||
+                !(referenceKelvin > 0)) {
+                return unsupported(device, "thermistor carries no usable Resistance, Beta or reference temperature");
+            }
+            const ohms = referenceOhms *
+                Math.exp(beta * (1 / ambientKelvin - 1 / referenceKelvin));
+            if (!(ohms > 0) || !Number.isFinite(ohms)) {
+                return unsupported(device, "thermistor folds to a non-positive resistance at this ambient temperature");
+            }
+            return {
+                outcome: "law",
+                device: device.id,
+                law: { kind: "conductance", siemens: 1 / ohms },
+            };
+        }
         case "potentiometer": {
             const ohms = device.parameters.ohms ?? 0;
             if (!(ohms > 0)) {
@@ -2945,6 +3158,13 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
             // number only. This shares the `fet` law kind with JFET entries; part
             // ids are disjoint across the two classes, so a lookup by exact folded
             // part id cannot cross from one to the other.
+            //
+            // **MOSFET is decided by the declared `kind`, read here.** This `case`
+            // is the law selection the compiler already makes from the device's
+            // typed kind: `kind: mosfet` lowers here, `kind: jfet` to the case
+            // above. No part-number prose is read (a `2N7000` string never decides
+            // anything), and the registry class is not consulted for the decision
+            // either -- it only refines the numbers once the kind has decided.
             const catalogued = registryLawFor(registry, device.identity.partNumber, "fet");
             const entry = catalogued !== null && catalogued.kind === "fet" ? catalogued : null;
             return {
@@ -2963,6 +3183,12 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     gateSaturationCurrent: entry?.gateSaturationCurrent ?? 0,
                     gateOnsetVolts: entry?.gateOnsetVolts ?? 0,
                     gateScaleVolts: entry?.gateScaleVolts ?? 1,
+                    // The body diode. Read from the registry entry only (a MOSFET
+                    // gate/body refinement is never a per-device document value, the
+                    // same rule the gate terms above follow), else the class
+                    // defaults, which `fet-law-default-parameters` names.
+                    bodySaturationCurrent: entry?.bodySaturationCurrent ?? MOSFET_BODY_SATURATION_CURRENT,
+                    bodyEmissionCoefficient: entry?.bodyEmissionCoefficient ?? MOSFET_BODY_EMISSION_COEFFICIENT,
                 },
             };
         }