driftlet 1.1.1 → 1.2.2

package/src/stack.js

@@ -33,6 +33,9 @@ export function combine(...parts) {
   const species = [], materials = {};
   parts.forEach((part, k) => {
     if (!isObject(part)) fail(`combine: part ${k} must be { species, materials }`);
+    // (trap()'s whole result, given for its library, dropped the traps without a word)
+    if (part.library !== undefined) fail(`combine: part ${k} is { library, … }, as trap() returns: give its library here (trap(…).library), and its bulkReactions and c0 to the device`);
+    fields(part, `combine: part ${k}`, ['species', 'materials']);
     for (const sp of part.species ?? []) {
       const prev = species.find((s) => s.name === sp.name);
       if (!prev) species.push({ ...sp });
@@ -100,6 +103,7 @@ export function ohmic(d = 0, carriers = ['e-', 'h+']) {
  */
 export function bath(c, reference, d = 0, opts = {}) {
   if (typeof reference !== 'string') [d, opts] = [reference ?? 0, isObject(d) ? d : {}];
+  checkOptions('bath', opts, ['offset', 'material']);
   const { offset, material } = opts;
   return {
     ...drive(d, 'bath'),
@@ -161,7 +165,7 @@ export function build(def) {
   if (regions.length === 0) fail('build.stack has no layers');
   // A contact holding a carrier its layer lacks: most often ohmic()'s default on a metal.
   for (const [k, end] of [[0, regions[0]], [stack.length - 1, regions[regions.length - 1]]]) {
-    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked') : [];
+    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked' && stack[k].species[s]?.type !== 'blocked') : [];
     const mat = materials[end.material];
     if (!isObject(mat)) continue;
     const has = (s) => (isObject(mat.conductor) ? mat.conductor.species === s : isObject(mat.species) && mat.species[s] !== undefined);

package/src/statistics.js

@@ -286,7 +286,7 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
     idx,
     evaluate(zeta, c, K) {
       for (let b = 0; b < k; b++) y[b] = zeta[b] + Math.log(cRef[b]);
-      let st;
+      let st, mx = Infinity;
       for (let it = 0; it < 100; it++) {
         for (let b = 0; b < k; b++) cc[b] = Math.exp(y[b]);
         st = state(cc);
@@ -297,7 +297,7 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
           R[b] = y[b] + lng[b] - zeta[b] - Math.log(cRef[b]);
           dot += s[b] * cc[b] * R[b];
         }
-        let mx = 0;
+        mx = 0;
         for (let b = 0; b < k; b++) {
           let dy = R[b] + (st.A * s[b] * dot) / st.denom;
           if (dy > 1) dy = 1;
@@ -307,6 +307,8 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
         }
         if (mx < 1e-14) break;
       }
+      // (a stall at round-off, near the convexity limit, is converged; anything more isn't)
+      if (!(mx < 1e-10)) throw new SolverError(`debye-huckel: the concentrations at these levels did not converge (a step of ${mx.toExponential(2)} in ln c after 100 iterations)`);
       for (let b = 0; b < k; b++) c[b] = Math.exp(y[b]);
       st = state(c);
       const f = st.A / st.denom;
@@ -315,18 +317,37 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
       }
     },
     invert(zeta, fixed, target) {
-      for (let b = 0; b < k; b++) cc[b] = fixed[b] ? target[b] : cRef[b] * Math.exp(zeta[b]);
-      for (let it = 0; it < 500; it++) {
-        state(cc);
-        let change = 0;
+      // The free species by Newton in y = ln c, as evaluate() does, the fixed held at their targets:
+      // J = I − A s_F (s∘c)_Fᵀ over the free ones alone. (A fixed-point iteration contracted by
+      // 1 − denom, and near the convexity limit stopped short without a word.)
+      for (let b = 0; b < k; b++) {
+        y[b] = fixed[b] ? Math.log(target[b]) : zeta[b] + Math.log(cRef[b]);
+        cc[b] = Math.exp(y[b]);
+      }
+      let mx = 0;
+      for (let it = 0; it < 100; it++) {
+        const st = state(cc);
+        let dot = 0, s2cF = 0;
         for (let b = 0; b < k; b++) {
           if (fixed[b]) continue;
-          const next = cRef[b] * Math.exp(zeta[b] - lng[b]);
-          if (cc[b] > 0) change = Math.max(change, Math.abs(next / cc[b] - 1));
-          cc[b] = next;
+          lng[b] = y[b] + lng[b] - zeta[b] - Math.log(cRef[b]); // (the residual, in lng's place)
+          dot += s[b] * cc[b] * lng[b];
+          s2cF += s[b] * s[b] * cc[b];
         }
-        if (!(change > 1e-15)) break;
+        const dF = 1 - st.A * s2cF; // (≥ denom > 0)
+        mx = 0;
+        for (let b = 0; b < k; b++) {
+          if (fixed[b]) continue;
+          let dy = lng[b] + (st.A * s[b] * dot) / dF;
+          if (dy > 1) dy = 1;
+          else if (dy < -1) dy = -1;
+          y[b] -= dy;
+          cc[b] = Math.exp(y[b]);
+          mx = Math.max(mx, Math.abs(dy));
+        }
+        if (mx < 1e-14) break;
       }
+      if (!(mx < 1e-10)) throw new SolverError(`debye-huckel: the composition given did not converge to its levels (a step of ${mx.toExponential(2)} in ln c after 100 iterations)`);
       state(cc);
       for (let b = 0; b < k; b++) if (fixed[b]) zeta[b] = Math.log(target[b] / cRef[b]) + lng[b];
     },

package/src/traces.js

@@ -37,6 +37,8 @@ const finite = (a) => {
  */
 export function speciesRole(sol, name) {
   const z = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
+  if (!(name in z)) throw new DeviceError(`speciesRole: no species '${name}' in the solution`);
+  if (z[name] === 0) throw new DeviceError(`speciesRole: '${name}' is neutral, with no role in level diagrams (draw it muted, or in a colour of your own)`);
   const role = (n) => (n === 'e-' ? 'electron' : z[n] > 0 ? 'cation' : 'anion');
   const charged = sol.species.filter((sp) => sp.z !== 0).map((sp) => sp.name);
   return { role: role(name), slot: charged.filter((n) => role(n) === role(name)).indexOf(name) };
@@ -88,7 +90,7 @@ export function traces(sol, { species, standard = true, phi = false, energy = fa
   const shown = species ?? names.filter((name) => finite(sol.V[name]) && (!energy || carriers.includes(name)));
   if (energy) {
     for (const name of shown) {
-      if (!carriers.includes(name)) throw new Error(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
+      if (!carriers.includes(name)) throw new DeviceError(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
     }
   }
   const sign = energy ? -1 : 1, unit = energy ? 'eV' : 'V';
@@ -98,22 +100,23 @@ export function traces(sol, { species, standard = true, phi = false, energy = fa
   const pretty = (name) => (name in zOf ? typeset(name, zOf[name]) : name);
   const series = [];
   for (const name of shown) {
-    if (!names.includes(name)) throw new Error(`traces: no charged species '${name}' in the solution`);
+    if (!names.includes(name)) throw new DeviceError(`traces: no charged species '${name}' in the solution`);
     const shift = shifts[name] ?? 0;
-    const at = (y) => (shift || energy ? Array.from(y, (v) => sign * v + shift) : y);
+    const at = (y) => (shift || energy ? Float64Array.from(y, (v) => sign * v + shift) : y);
     const common = { species: name, role: role(name), slot: slotOf(name), ...(shift ? { shift } : {}) };
     if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: energy ? energyLabels[`V:${name}`] : `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
     if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: energy ? energyLabels[`Vstd:${name}`] : `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
   }
   if (Array.isArray(phi)) {
     const known = sol.regions.flatMap((r) => [r.name, r.material]);
-    for (const name of phi) if (!known.includes(name)) throw new Error(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
+    for (const name of phi) if (!known.includes(name)) throw new DeviceError(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
     const inside = sol.regions.map((r) => phi.includes(r.name) || phi.includes(r.material));
-    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
-  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Array.from(sol.phi, (v) => -v) : sol.phi });
+    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Float64Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
+  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Float64Array.from(sol.phi, (v) => -v) : sol.phi });
+  for (const lv of levels) if (typeof lv?.half?.equation !== 'string') throw new DeviceError('traces: each of levels is { half, label, standard }, its half a half() (as { half: half(\'Fe3+ + e- = Fe2+\') })');
   const couples = [...new Set(levels.map((lv) => lv.half.equation))];
   levels.forEach((lv, k) => {
-    const y = energy ? Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
+    const y = energy ? Float64Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
     series.push({
       id: `level:${k}`,
       label: lv.label ?? `${lv.standard ? 'V° ' : ''}${lv.half.equation.split(' ').map(pretty).join(' ')}`,

package/src/types.js

@@ -19,6 +19,7 @@
  * Statistics model: how the listed species' concentrations follow from their reduced
  * potentials ζ = (μ̄ − zFφ − μ°)/RT. Species not in any model are ideal, c = c_ref e^ζ.
  * @typedef {(
+ *   { type: 'ideal', species: string[] } |
  *   { type: 'fermi-dirac', species: string[], order?: 0.5 | 0 } |
  *   { type: 'lattice', species: string[], cMax: number } |
  *   { type: 'redlich-kister', species: [string], cMax: number, A?: number[] } |
@@ -73,19 +74,45 @@
  */
 
 /** @typedef {'pinned' | 'neutral' | { type: 'capacitive', C: number }} InterfacePhiLaw */
-/** @typedef {'equilibrium' | 'blocked' | { type: 'conductance', G: number }} InterfaceSpeciesLink */
+/**
+ * A species' law across a face. conductance: J = G (V_L − V_R), G in S/m², charged species;
+ * permeability: Goldman–Hodgkin–Katz electrodiffusion, P in m/s, ideal statistics on both sides,
+ * not beside a conductor. gates: the face's gates that scale G or P, with their exponents
+ * ({ m: 3, h: 1 } for m³h; not beside a conductor).
+ * @typedef {'equilibrium' | 'blocked' | { type: 'equilibrium' | 'blocked' }
+ *   | { type: 'conductance', G: number, gates?: Record<string, number> }
+ *   | { type: 'permeability', P: number, gates?: Record<string, number> }} InterfaceSpeciesLink
+ */
+
+/**
+ * One of a gate's rates (1/s) in the voltage V it follows, in NeuroML's standard forms (midpoint
+ * and scale in V, scale ≠ 0): 'exp', rate·e^((V − midpoint)/scale); 'sigmoid',
+ * rate/(1 + e^((midpoint − V)/scale)); 'expLinear', rate·y/(1 − e^(−y)), y = (V − midpoint)/scale.
+ * @typedef {{ type: 'exp' | 'sigmoid' | 'expLinear', rate: number, midpoint: number, scale: number }} GateRate
+ */
+/**
+ * A Hodgkin–Huxley gate: a fraction open x in [0, 1], dx/dt = α(V)(1 − x) − β(V)x.
+ * @typedef {{ alpha: GateRate, beta: GateRate }} GateDef
+ */
 
 /**
  * A reaction at a face: participants on each side with signed stoichiometric coefficients
- * (ν < 0 consumed by the forward reaction), Butler–Volmer kinetics.
+ * (ν < 0 consumed by the forward reaction). Butler–Volmer kinetics (k0, alpha), or instead SRH
+ * (srh) or saturating (vmax and K), neither with a conductor's carrier.
  * @typedef {object} FaceReactionDef
  * @property {string} [equation] the reaction as an equation, e.g. 'Ag+ + e- = Ag(s)', each
  *   participant on the side that holds it ('Li+(left)' where both do); or give left and right
  * @property {Record<string, number>} [left] participants on the left side (species present there, or fixed neutrals)
  * @property {Record<string, number>} [right] participants on the right side
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {number} k0 standard rate constant, mol/(m²·s)
- * @property {number} [alpha] transfer coefficient, 0…1 (default 0.5)
+ * @property {number} [k0] Butler–Volmer: standard rate constant, mol/(m²·s) (required unless srh or vmax)
+ * @property {number} [alpha] with k0: transfer coefficient, 0…1 (default 0.5)
+ * @property {{ vn: number, vp: number, n1?: number }} [srh] instead: trap-assisted recombination, for a
+ *   reaction consuming one negative and one positive species and making none; capture velocities
+ *   vn, vp in m/s, n1 in mol/m³ (default n_i, a midgap trap)
+ * @property {number} [vmax] instead: saturating kinetics, the largest rate, mol/(m²·s)
+ * @property {Record<string, number>} [K] with vmax: a half-saturation concentration (mol/m³) for
+ *   every species the forward reaction consumes
  */
 /**
  * One face between consecutive regions. For different materials under a 'pinned' or
@@ -94,11 +121,15 @@
  * @property {{ species: string, value: number }} [step] standard-level step right − left, J/mol
  * @property {number} [dipole] φ jump right − left, V
  * @property {number} [zeroCharge] beside a conductor region: V_F − φ_edge at zero charge, V
- * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials)
+ * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials;
+ *   beside a conductor 'neutral' or capacitive, required next to an ε > 0 material)
  * @property {number} [sheetCharge] C/m²
  * @property {Record<string, InterfaceSpeciesLink>} [species] per-species laws (default equilibrium
- *   where present on both sides and not reacting at the face)
+ *   where present on both sides and mobile on one, blocked otherwise; a species reacting at the
+ *   face and present on both sides has no default)
  * @property {FaceReactionDef[]} [reactions] reactions at the face
+ * @property {Record<string, GateDef>} [gates] voltage-gated channels: gates following
+ *   V = φ_right − φ_left, which its links name (not beside a conductor)
  */
 
 /**
@@ -106,14 +137,18 @@
  * @property {Record<string, number>} [nu] signed stoichiometric coefficients (ν < 0 consumed)
  * @property {string} [equation] the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {Record<string, number | Profile>} kf forward rate constant per material name, or a
- *   profile of it against the device's x (an absorption profile, for photogeneration)
+ * @property {Record<string, number | Profile>} [kf] mass action: forward rate constant per material
+ *   name, or a profile of it against the device's x (an absorption profile, for photogeneration);
+ *   give kf or srh
+ * @property {Record<string, { tauN: number, tauP: number, n1?: number }>} [srh] instead: SRH
+ *   (trap-assisted) recombination per material name, for a reaction consuming one negative and
+ *   one positive species and making none; lifetimes in s, n1 in mol/m³ (default n_i, a midgap trap)
  */
 
 /**
  * Contacts use the same laws as internal faces; the outside is a phase with known levels
  * V_i = V + offset_i (a rigid ladder that the circuit slides by V).
- * @typedef {'blocked' | 'equilibrium'
+ * @typedef {'blocked' | 'equilibrium' | { type: 'blocked' }
  *   | { type: 'equilibrium', offset?: number, mu?: number }
  *   | { type: 'conductance', G: number, offset?: number }
  *   | { type: 'exchange', k: number, mu: number }
@@ -133,9 +168,11 @@
  * @property {number} [R] with V: a series resistance, Ω·m² (a source behind a resistor)
  * @property {string} [terminal] species whose voltage V is
  * @property {Record<string, ContactSpeciesLink>} [species] per-species links (default blocked)
- * @property {{ c: Record<string, number>, reference: string, offset?: number }} [bath] a neutral
- *   composition held at the contact, anchored through a charged reference species
- * @property {ContactPhiLink} [phi] required when any species connects (default 'neutral')
+ * @property {{ c: Record<string, number>, reference?: string, offset?: number, material?: string }} [bath]
+ *   instead of species: a neutral composition c (mol/m³) held at the contact, anchored through a
+ *   charged reference species (offset: its V_i − V, V); with no reference, V is the bath's φ. It's
+ *   the end material at that composition, or the material it names (a solution beside a charged region)
+ * @property {ContactPhiLink} [phi] required when any species connects (default 'neutral'; 'bulk' with a bath)
  * @property {number} [zeroCharge] for a capacitive or pinned law: V − φ_edge at zero charge, V
  */
 
@@ -158,20 +195,27 @@
  * @property {Source} [I] or: the current driven into the device, A/m² (e.g. 0 for a reference electrode)
  * @property {number} [R] with V: a series resistance, Ω·m²
  * @property {string} [terminal] species whose offset defaults to 0; with reactions, the electrode's carrier
- * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'equilibrium', offset?: number, mu?: number }
- *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} [species]
- * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number, bare?: boolean }[]} [reactions] an
- *   electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s)) between the region's
- *   species and the terminal species at the port's level
+ * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'blocked' } | { type: 'equilibrium', offset?: number, mu?: number }
+ *   | { type: 'conductance', G: number, offset?: number, gates?: Record<string, number> }
+ *   | { type: 'exchange', k: number, mu: number }>} [species] per-species links, per volume (default
+ *   blocked): G in S/m³ (S/m² on a conductor), k in mol/(m³·s); a conductance's gates name the
+ *   port's gates that scale G, with their exponents
+ * @property {{ c: Record<string, number> }} [bath] the outside's composition (mol/m³): V is then its φ,
+ *   and each linked species' level there follows from it (unless its link gives an offset or mu)
+ * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha?: number, bare?: boolean }[]} [reactions] an
+ *   electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s), alpha default 0.5)
+ *   between the region's species and the terminal species at the port's level
  * @property {Record<string, { mu0: number, capacity: number, theta0?: number }>} [surface] with reactions: species
  *   on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
- *   shared; reactions run on Langmuir sites (what fills sites needs bare ones), and one with `bare: true`
- *   needs a bare site even if it fills none (θ₀ = 1 − Σθ)
+ *   shared, theta0 the starting coverage (default 1e-6); reactions run on Langmuir sites (what fills
+ *   sites needs bare ones), and one with `bare: true` needs a bare site even if it fills none (θ₀ = 1 − Σθ)
  * @property {{ C: number, zeroCharge?: number }} [capacitance] a capacitance spread through the window (F/m² of
  *   electrode): σ = C (V − zeroCharge − φ) on the port's side, aσ in each node's charge balance; a gate
  *   along a channel, a double layer
  * @property {number | { x: number[], values: number[] }} [area] with reactions or a capacitance: electrode area per volume,
  *   m²/m³ (1/h for a film of thickness h), or a profile against the device's x
+ * @property {Record<string, GateDef>} [gates] with a capacitance: voltage-gated channels at each node of
+ *   the window, following the voltage across it, φ − (V − zeroCharge), which its conductance links name
  */
 
 /**
@@ -198,6 +242,7 @@
  * @property {Record<string, number>} flux particle flux toward +x through this contact, mol/(m²·s)
  * @property {number} D displacement toward +x at this contact, C/m²
  * @property {number} current total current toward +x, A/m²
+ * @property {Record<string, string>} links how each species that crosses it does (its link type)
  */
 
 /**
@@ -216,6 +261,11 @@
  * @property {Record<string, Float64Array>} muStd standard levels μ° + zFφ, J/mol
  * @property {Record<string, Float64Array>} V species voltages μ̄/(zF), V (charged species)
  * @property {Record<string, Float64Array>} Vstd standard levels as voltages, V
+ * @property {Record<string, Float64Array>} flux each species' flux toward +x across each segment, between
+ *   nodes g and g + 1 (a face's across its pair of nodes), mol/(m²·s): the fluxes the balances add up
+ * @property {Record<string, Float64Array>} D diffusivity at each node, m²/s (NaN where absent, or in a conductor)
+ * @property {number} T temperature, K
+ * @property {'planar' | 'cylindrical' | 'spherical' | 'profile'} geometry the device's (amounts and rates per area only if planar)
  * @property {number} current current toward +x through the device, A/m²
  * @property {number} terminalVoltage V_right − V_left, V
  * @property {Record<string, { V: number, current: number }>} terminals each terminal (left, right,
@@ -225,31 +275,48 @@
  *   Stern plate at a capacitive contact
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number, x?: Float64Array,
  *   area?: Float64Array, rates?: Float64Array[], coverage?: Record<string, Float64Array>, bare?: Float64Array,
- *   sigma?: Float64Array, charge?: number }[]} ports what each internal port brings into the device;
- *   with reactions, also its window's nodes (x, m), area per volume there, and each reaction's rate per area
- *   at each node (mol/(m²·s), forward)
- * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
- * @property {{ rate: Float64Array, regions: number[], total: number }[]} bulkReactions each bulk reaction's
- *   forward rate per node (mol/(m³·s), NaN where it doesn't run), and per region and in all (mol/(m²·s))
+ *   sigma?: Float64Array, charge?: number, gates?: Record<string, Float64Array>, Vm?: Float64Array }[]} ports
+ *   what each internal port brings into the device (current: the charging current included); with
+ *   reactions or a capacitance, also its window's nodes (x, m) and area per volume there (m²/m³); with
+ *   reactions, each reaction's net rate per area at each node (mol/(m²·s), forward); with a surface, each
+ *   species' coverage and the bare fraction; with a capacitance, σ per area (C/m²) and the charge its
+ *   side holds; with gates, each gate's fraction open at each node and the voltage they follow (V)
+ * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>,
+ *   rates: number[], links: Record<string, string>, oneWay?: Record<string, [number, number]>,
+ *   gates?: Record<string, number>, V?: number }[]} interfaces each face: the regions it joins, its dipole
+ *   (V) and sheet charge (C/m²), its displacement D (C/m²), each species' flux N across it and each face
+ *   reaction's net rate (mol/(m²·s), toward +x and forward), how each species that crosses it does (its
+ *   link type); for those crossing by permeability, the one-way fluxes [toward +x, toward −x] whose
+ *   difference is N; with gates, each one's fraction open and the voltage they follow, φ_right − φ_left (V)
+ * @property {{ rate: Float64Array, forward: Float64Array, nu: Record<string, number>, regions: number[], total: number }[]} bulkReactions
+ *   each bulk reaction's net rate per node (mol/(m³·s), forward minus backward, NaN where it doesn't
+ *   run), its one-way forward rate (the backward is forward − rate), what one forward reaction makes
+ *   of each species (ν, negative for what it consumes), and the net rate per region and in all (mol/(m²·s))
  * @property {number} charge total charge in the device, C/m²
  * @property {{ species: string, regions: number[], spectator: boolean, connected: boolean, reactive: boolean,
  *   amount: number, reference: number, intake: number, drift: number }[]} conservation
  * @property {string[]} warnings
  * @property {boolean} converged
- * @property {number} iterations
+ * @property {number} iterations Newton iterations
+ * @property {number} [steps] solve(): the steps it took to the steady state; advance(): accepted steps
+ * @property {number} [substeps] step(): how many pieces the interval was split into
+ * @property {(number | object)[]} [history] solver bookkeeping: solve(), a record of its steps and
+ *   stages; step(), Newton's largest update per iteration (thermal units)
  * @property {number} time s
  * @property {boolean} steady whether this is a converged steady state (solve()), not a transient's
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
  * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] advance():
- *   terminal current (A/m², toward +x) and voltage after each accepted step, and each probe's
- *   reading (mol/m³, or V for quantity 'V'), interpolated between the nodes around its x
+ *   the right contact's current (A/m², toward +x) and V_right − V_left after each accepted step, and
+ *   each probe's reading: inside, interpolated between the nodes around its x (mol/m³ for quantity
+ *   'c', V for 'V' or 'phi'); at a face, a species' flux through it (mol/(m²·s), toward +x) or a
+ *   gate's fraction open
  */
 
 /**
  * @typedef {object} ImpedanceResult
  * @property {Float64Array} f frequencies, Hz
- * @property {{ re: Float64Array, im: Float64Array }} Z impedance −δV/δI, Ω·m²
+ * @property {{ re: Float64Array, im: Float64Array }} Z impedance δV/δI at the terminal, I into the device, Ω·m²
  * @property {{ phi: ComplexProfile, mu: Record<string, ComplexProfile>, c: Record<string, ComplexProfile> }[]} [profiles]
  *   per frequency, per unit excitation (volt, or A/m² in current mode)
  * @property {string[]} warnings the steady state's warnings, which hold for its impedance too

package/types/index.d.ts

@@ -48,11 +48,14 @@ export class Device {
      * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
      * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
      * which), so an animation can call it once per frame; the step size carries over. `probes`
-     * read a species at points inside the device after every accepted step, into `trace.probes`
-     * (one array per probe, alongside `trace.t`): what a detector at x sees.
+     * read a species (or φ) at points inside the device after every accepted step, into
+     * `trace.probes` (one array per probe, alongside `trace.t`): what a detector at x sees. At a
+     * face, `{ interface, species }` reads a species' flux through it (mol/(m²·s), toward +x), and
+     * `{ interface, gate }` a gate's fraction open.
      * @param {number} tEnd s
      * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-     *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+     *   probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }
+     *     | { interface: number, species: string } | { interface: number, gate: string })[] }} [opts]
      * @returns {Solution}
      */
     advance(tEnd: number, opts?: {
@@ -62,12 +65,18 @@ export class Device {
         budgetMs?: number;
         maxSteps?: number;
         method?: "bdf2" | "be";
-        probes?: {
+        probes?: ({
             x: number;
             species?: string;
             quantity?: "c" | "V" | "phi";
             region?: string | number;
-        }[];
+        } | {
+            interface: number;
+            species: string;
+        } | {
+            interface: number;
+            gate: string;
+        })[];
     }): Solution;
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its

package/types/kit.d.ts

@@ -25,7 +25,7 @@ export function vacuumLevel(def: object, side: VacuumSide, path?: string): numbe
 export function vacuumDipole(def: object, left: VacuumSide, right: VacuumSide): number;
 /**
  * The vacuum-level (Schottky–Mott-type) estimate of a `zeroCharge` where a conductor meets a
- * material: at a conductor region's face, or a contact's capacitive or dipole law. The conductor's
+ * material: at a conductor region's face, or a contact's capacitive or pinned law. The conductor's
  * vacuum level sits its work function W beyond its Fermi level, so
  * zeroCharge = V_F − φ_edge at zero charge = W + (V_vac − φ)_inside.
  * @param {object} def device definition

package/types/lawRows.d.ts

@@ -0,0 +1,5 @@
+export function applyLaws(s: any, dt: any): void;
+export function captureLaws(s: any): void;
+export function captureLocal(s: any): void;
+export function solveBordered(s: any, rhs: any, delta: any, deltaV: any, pins: any): void;
+export function snapFlat(s: any): void;

package/types/laws.d.ts

@@ -0,0 +1,86 @@
+export function moves({ model }: {
+    model: any;
+}, st: any): boolean;
+export function still({ model }: {
+    model: any;
+}, st: any): boolean;
+export function carrierZ({ model, z }: {
+    model: any;
+    z: any;
+}, k: any): any;
+export function contactCharges({ model, nNodes, phiUndefined }: {
+    model: any;
+    nNodes: any;
+    phiUndefined: any;
+}, k: any): boolean;
+export function feeds(k: any, st: any): any;
+export function noCurrent(t: any): boolean;
+export function chargeOnly({ model, terms }: {
+    model: any;
+    terms: any;
+}, k: any): boolean;
+export function conservedMoieties(s: any, { drives, alsoCurrent, skip }?: {
+    drives?: boolean;
+    alsoCurrent?: any[];
+    skip?: any;
+}): Float64Array<any>[];
+export function findLaws(s: any): {
+    constraints: any[];
+    affinities: {
+        rx: any;
+        f: any;
+        row: any;
+        idx: Int32Array<any>;
+        w: Float64Array<any>;
+        len: number;
+        res: number;
+    }[];
+    localConstraints: {
+        parts: ({
+            i: any;
+            w: number;
+            q?: undefined;
+            k?: undefined;
+        } | {
+            q: any;
+            k: any;
+            w: number;
+            i?: undefined;
+        })[];
+        row: any;
+        nodes: any;
+        reference: Float64Array<any>;
+    }[];
+    islands: {
+        stretch: any;
+        row: any;
+        flux: any[];
+        weight: number[];
+        outside: any[];
+        idx: Int32Array<ArrayBuffer>;
+        w: Float64Array<ArrayBuffer>;
+        len: number;
+        res: number;
+    }[];
+    timeLaws: {
+        parts: {
+            stretch: number;
+            w: number;
+        }[];
+        surface: {
+            col: number;
+            w: number;
+        }[];
+        carriers: any;
+        terminals: any[];
+        circuit: any;
+        lambda: number;
+        idx: Int32Array<ArrayBuffer>;
+        w: Float64Array<ArrayBuffer>;
+        len: number;
+    }[];
+    contactLaw: boolean[];
+    carriers: any;
+    conserved: Set<any>;
+    unkept: Float64Array<any>[];
+};

package/types/plot.d.ts

@@ -1,11 +1,11 @@
 /**
  * The colour of a trace's role and slot (a CSS colour), for drawing other charts in the same
  * colours as the level diagrams.
- * @param {'electron' | 'cation' | 'anion' | 'redox'} role
+ * @param {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role
  * @param {number} slot
  * @param {{ dark?: boolean }} [opts]
  */
-export function themeColor(role: "electron" | "cation" | "anion" | "redox", slot: number, { dark }?: {
+export function themeColor(role: "electron" | "cation" | "anion" | "redox" | "phi", slot: number, { dark }?: {
     dark?: boolean;
 }, ...args: any[]): string;
 /**

package/types/solution.d.ts

@@ -10,6 +10,7 @@ export function makeSolution(solver: any, result?: {}): {
     V: {};
     Vstd: {};
     T: any;
+    geometry: any;
     time: any;
     steady: any;
     converged: any;