driftlet 0.10.0 → 0.12.0

package/src/channels.js

@@ -0,0 +1,73 @@
+// driftlet/kit: voltage-gated channels as plain definition data. Hodgkin and Huxley's squid axon:
+// its gates, and permeabilities for its Na⁺, K⁺ and leak channels, for a membrane face.
+
+import { DeviceError } from './errors.js';
+import { FARADAY, GAS_CONSTANT } from './constants.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const need = (ok, message) => ok || fail(message);
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+
+// Hodgkin and Huxley (1952), J. Physiol. 117, 500, at their 6.3 °C, in the modern convention
+// (V = φ_in − φ_out, rest at −65 mV), in SI: rates in 1/s, voltages in V.
+const mV = 1e-3;
+const HH_GATES = {
+  m: { alpha: { type: 'expLinear', rate: 1000, midpoint: -40 * mV, scale: 10 * mV }, beta: { type: 'exp', rate: 4000, midpoint: -65 * mV, scale: -18 * mV } },
+  h: { alpha: { type: 'exp', rate: 70, midpoint: -65 * mV, scale: -20 * mV }, beta: { type: 'sigmoid', rate: 1000, midpoint: -35 * mV, scale: 10 * mV } },
+  n: { alpha: { type: 'expLinear', rate: 100, midpoint: -55 * mV, scale: 10 * mV }, beta: { type: 'exp', rate: 125, midpoint: -65 * mV, scale: -80 * mV } },
+};
+const HH_T = 273.15 + 6.3;
+
+// The GHK current (outward, A/m²) of an ion at unit permeability, at voltage V (inside − outside).
+export function ghkCurrent(z, inside, outside, V, T) {
+  const u = (z * V * FARADAY) / (GAS_CONSTANT * T);
+  if (Math.abs(u) < 1e-9) return z * FARADAY * (inside - outside);
+  return (z * FARADAY * u * (inside - outside * Math.exp(-u))) / -Math.expm1(-u);
+}
+
+/**
+ * Hodgkin and Huxley's squid-axon channels, for a membrane face with the outside on its left
+ * (so the gates' voltage, φ_right − φ_left, is the membrane potential): the face's `gates`, and
+ * `species` links for Na⁺ (P·m³h), K⁺ (P·n⁴) and the leak (ungated), to spread into the face
+ * beside its φ law, `{ phi: { type: 'capacitive', C: 0.01 }, ...hh }`, adding links (or blocks)
+ * for any other species.
+ *
+ * The currents are GHK's, which rectify, so a permeability matches a conductance at one voltage
+ * only: each is the one whose chord conductance at `at` (rest, −65 mV) is Hodgkin and Huxley's
+ * (`g`: 120, 36 and 0.3 mS/cm²), at the concentrations given. The leak is carried by one ion
+ * (`leak`, of charge `leakZ`: Cl⁻ by default, whose Nernst level in squid is near their leak
+ * reversal, −54 mV). The
+ * rates are theirs at 6.3 °C, scaled to `T` by Q₁₀ = 3.
+ * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
+ *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string } }} opts concentrations in
+ *   mol/m³ by species name, K, S/m², V
+ * @returns {{ gates: object, species: object }}
+ */
+export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {} } = {}) {
+  need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name');
+  need(num(T) && T > 0, `hodgkinHuxley: T must be a temperature in K, got ${T}`);
+  need(num(at), `hodgkinHuxley: at must be a voltage (V), got ${at}`);
+  const G = { Na: 1200, K: 360, leak: 3, ...g };
+  const Na = names.Na ?? 'Na+', K = names.K ?? 'K+';
+  const q10 = Math.exp(Math.log(3) * ((T - HH_T) / 10)); // Q₁₀ = 3
+  const scaled = (r) => ({ ...r, rate: r.rate * q10 });
+  const gates = Object.fromEntries(Object.entries(HH_GATES).map(([k, gt]) => [k, { alpha: scaled(gt.alpha), beta: scaled(gt.beta) }]));
+  const P = (name, z, gval, what) => {
+    need(num(inside[name]) && inside[name] > 0 && num(outside[name]) && outside[name] > 0, `hodgkinHuxley: give ${name}'s concentration inside and outside (mol/m³), for its ${what}`);
+    need(num(gval) && gval > 0, `hodgkinHuxley: g.${what} must be a conductance > 0 (S/m²), got ${gval}`);
+    const E = ((GAS_CONSTANT * T) / (z * FARADAY)) * Math.log(outside[name] / inside[name]);
+    need(Math.abs(at - E) > 1e-4, `hodgkinHuxley: ${name}'s Nernst level, ${(E * 1e3).toFixed(1)} mV, is at the calibration voltage; choose another 'at'`);
+    return (gval * (at - E)) / ghkCurrent(z, inside[name], outside[name], at, T);
+  };
+  need(Number.isInteger(leakZ) && leakZ !== 0, `hodgkinHuxley: leakZ must be the leak ion's charge number, got ${leakZ}`);
+  return {
+    gates,
+    species: {
+      [Na]: { type: 'permeability', P: P(Na, 1, G.Na, 'Na channels'), gates: { m: 3, h: 1 } },
+      [K]: { type: 'permeability', P: P(K, 1, G.K, 'K channels'), gates: { n: 4 } },
+      [leak]: { type: 'permeability', P: P(leak, leakZ, G.leak, 'leak') },
+    },
+  };
+}

package/src/checks.js

@@ -96,7 +96,9 @@ function balance(device, sol) {
       home[i][r] = ledgers.length - 1;
     });
   });
-  const add = (i, r, what, rate) => {
+  const partners = new Map(); // a reaction term's species: its net rate is round-off against any of theirs
+  const add = (i, r, what, rate, species) => {
+    if (species) partners.set(what, species);
     const l = home[i][r];
     if (!(l >= 0 && rate !== 0 && Number.isFinite(rate))) return;
     const same = ledgers[l].terms.find((t) => t.what === what); // a bulk reaction, region by region
@@ -112,8 +114,9 @@ function balance(device, sol) {
   model.reactions.forEach((rx, k) => {
     const what = label(def.bulkReactions?.[k]);
     sol.bulkReactions[k].regions.forEach((total, r) => {
-      for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total);
-      for (const { i, nu } of rx.products) add(i, r, what, nu * total);
+      const all = [...rx.reactants, ...rx.products].map((p) => p.i);
+      for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total, all);
+      for (const { i, nu } of rx.products) add(i, r, what, nu * total, all);
     });
   });
   interfaces.forEach((itf, f) => {
@@ -129,7 +132,8 @@ function balance(device, sol) {
     });
     itf.reactions.forEach((rx, k) => {
       const rate = Af * sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
-      for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate);
+      const all = rx.part.map((p) => p.i);
+      for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate, all);
     });
   });
   // A species in one compartment is named alone; one in several, by where.
@@ -140,10 +144,12 @@ function balance(device, sol) {
     l.title = several[l.i] ? `${l.species} in ${l.compartment}` : l.species;
   }
 
-  // A species at rest (nothing beyond round-off moving, against what it could carry) isn't reported.
+  // A species at rest (nothing beyond round-off moving, against what it or its reactions' partners
+  // could carry) isn't reported.
   const size = (l) => Math.max(0, ...l.terms.map((t) => Math.abs(t.rate)));
-  const natural = naturalScales(device, sol);
-  const moving = ledgers.filter((l) => size(l) > 1e-9 * natural[l.i]);
+  const natural = naturalScales(device, sol), inSolution = naturalScales(device, sol, false); // (partners' scale: not a metal's conductance)
+  const scale = (l) => Math.max(natural[l.i], ...l.terms.flatMap((t) => (partners.get(t.what) ?? []).map((j) => inSolution[j])));
+  const moving = ledgers.filter((l) => size(l) > 1e-8 * scale(l));
   let worst = 0;
   const lines = [];
   for (const l of moving) {
@@ -167,8 +173,9 @@ function balance(device, sol) {
 
 // What each species could carry, mol/(m²·s): by transport, D·c/L in each region (a metal's
 // carrier, σRT/(z²F²L)), and by its bulk reactions, their one-way rates. In equilibrium the net
-// flows are round-off of these.
-function naturalScales(device, sol) {
+// flows are round-off of these. Without `conductors`, transport through conductor regions isn't
+// counted.
+function naturalScales(device, sol, conductors = true) {
   const { model, solver } = device, { species, grid } = model;
   // (totals through the cross-section, as the ledgers are: its largest in each region)
   const area = model.regions.map((_, r) => Math.max(...grid.area.subarray(grid.regionStart[r], grid.regionEnd[r] + 1)));
@@ -177,7 +184,7 @@ function naturalScales(device, sol) {
     model.regions.forEach((reg, r) => {
       const mat = model.materials[reg.material], L = reg.length;
       if (mat.conductor) {
-        if (mat.conductor.i === i) S = Math.max(S, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        if (conductors && mat.conductor.i === i) S = Math.max(S, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
         return;
       }
       if (!mat.present[i] || !(mat.D[i] > 0)) return;

package/src/describe.js

@@ -201,10 +201,12 @@ export function describe(def) {
       const rx = (idef.reactions ?? []).map((r) => (r.equation ?? equation(r.left, r.right)) + kinetics(r));
       const laws = species.flatMap((sp, i) => {
         const l = itf.links[i];
-        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²`] : [];
+        const gated = (l.gates ?? []).map(([q, p]) => itf.gates[q].name + (p > 1 ? `^${p}` : '')).join('·');
+        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s${gated ? ` × ${gated}` : ''}`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²`] : [];
       });
+      const gates = (itf.gates ?? []).map((g) => g.name);
       lines.push(
-        `  ${L.name} | ${R.name}: ${law}${align}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}`,
+        `  ${L.name} | ${R.name}: ${law}${align}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}${gates.length ? `; gates (voltage-dependent, see interfaces[f].gates): ${gates.join(', ')}` : ''}`,
       );
     });
   }

package/src/device.js

@@ -348,12 +348,12 @@ export function normalizeDevice(def) {
     need(nodes.length > 0, `ports[${k}]: the window [${port.from}, ${port.to}] m holds no grid node; widen it or refine the grid`);
     port.nodes = Int32Array.from(nodes);
   });
-  // A node's surface belongs to one electrode.
+  // A node's surface belongs to one electrode, and its gates to one membrane.
   const surfaced = new Int32Array(grid.nNodes).fill(-1);
   ports.forEach((port, k) => {
-    if (port.surface.length === 0) return;
+    if (port.surface.length === 0 && port.gates.length === 0) return;
     for (const g of port.nodes) {
-      need(surfaced[g] < 0, `ports[${k}]: its window overlaps ports[${surfaced[g]}]'s, and both have a surface; a spot of metal has one surface`);
+      need(surfaced[g] < 0, `ports[${k}]: its window overlaps ports[${surfaced[g]}]'s, and both have a surface or gates; a spot of metal has one surface, and of a membrane one set of channels`);
       surfaced[g] = k;
     }
   });
@@ -669,7 +669,7 @@ function normalizeGeometry(g) {
 // the window, `area` (m²/m³) of it per volume.
 function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT) {
   need(isObject(pdef), `${path} must be an object`);
-  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance', 'gates']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -690,6 +690,9 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
   const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface);
   surface.forEach((sp, s) => need(reactions.some((rx) => rx.part.some((p) => p.side === 2 && p.s === s)), `${path}.surface.${sp.name}: no reaction of the port makes or uses it`));
   const capacitance = portCapacitance(pdef, path, mat);
+  // Gates (a membrane's channels): they follow the voltage across the port's capacitance.
+  const gates = normalizeGates(pdef.gates, path, mat, mat);
+  need(gates.length === 0 || capacitance !== null, `${path}.gates: a gate follows the voltage across the port's capacitance (a membrane's), so give the port one`);
   need(pdef.species === undefined ? reactions.length > 0 || capacitance !== null : isObject(pdef.species), `${path}.species must map species names to port links`);
   const links = species.map(() => ({ type: 'blocked' }));
   for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
@@ -698,7 +701,7 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     const i = speciesIndex.get(sname);
     const link = typeof raw === 'string' ? { type: raw } : raw;
     need(isObject(link) && ['blocked', 'equilibrium', 'conductance', 'exchange'].includes(link.type), `${lpath}.type must be one of blocked, equilibrium, conductance, exchange`);
-    fields(link, lpath, LINK_FIELDS[link.type]);
+    fields(link, lpath, link.type === 'conductance' ? [...LINK_FIELDS.conductance, 'gates'] : LINK_FIELDS[link.type]);
     if (link.type === 'blocked') continue;
     need(mat.present[i], `${lpath}: '${sname}' is absent from ${reg.name} (material '${mat.name}')`);
     if (mat.conductor) need(i === mat.conductor.i, `${lpath}: a conductor exchanges only its carrier, ${species[mat.conductor.i].name}`);
@@ -718,6 +721,7 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     // On a metal, G is a lumped conductance per area (S/m²), spread over its thickness.
     if (link.type === 'conductance') level.G = mat.conductor ? positive(link.G, `${lpath}.G (S/m², for a conductor)`) / reg.length : positive(link.G, `${lpath}.G (S/m³)`);
     if (link.type === 'exchange') level.k = positive(link.k, `${lpath}.k (mol/(m³·s))`);
+    if (link.type === 'conductance') level.gates = gatedBy(link.gates, gates, lpath, path);
     links[i] = { type: link.type, ...level };
   }
   need(links.some((l) => l.type !== 'blocked') || reactions.length > 0 || capacitance !== null, `${path}.species: the port exchanges no species`);
@@ -731,7 +735,7 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     area = typeof pdef.area === 'number' ? { value: positive(pdef.area, `${path}.area (m²/m³)`) } : profile(pdef.area, `${path}.area`, 'areas per volume (m²/m³)', (a) => a >= 0, 'an area per volume ≥ 0');
   } else need(pdef.area === undefined, `${path}.area: only an electrode (a port with reactions or a capacitance) has an area`);
   need(surface.length === 0 || reactions.length > 0, `${path}.surface: only an electrode (a port with reactions) has a surface`);
-  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area, surface, capacitance };
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area, surface, capacitance, gates };
 }
 
 // A capacitance spread through the window: a gate along a channel, an electrode's double layer.
@@ -860,7 +864,7 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   // macroscopic limit; the alignment then drops out. 'capacitive': a Helmholtz layer,
   // D = C (Δφ − dipole). Between two ε = 0 (strictly neutral) materials the default is neutral.
   if (matL.conductor || matR.conductor) return normalizeConductorInterface(idef, where, matL, matR, species, speciesIndex, RT);
-  fields(idef, where, ['phi', 'dipole', 'step', 'sheetCharge', 'species', 'reactions']);
+  fields(idef, where, ['phi', 'dipole', 'step', 'sheetCharge', 'species', 'reactions', 'gates']);
   const bothNeutral = (matL.epsr === 0 && matR.epsr === 0) || matL.phiFree || matR.phiFree;
   const rawPhi = idef.phi ?? (bothNeutral ? 'neutral' : 'pinned');
   const phi = typeof rawPhi === 'string' ? { type: rawPhi } : { ...rawPhi };
@@ -916,6 +920,7 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   // blocked, an ohmic interface conductance G (S/m²), or a permeability P (m/s): electrodiffusion
   // through a thin membrane in a constant field, Goldman–Hodgkin–Katz.
   const links = defaultInterfaceLinks(matL, matR, species);
+  const gates = normalizeGates(idef.gates, where, matL, matR);
   if (idef.species !== undefined) {
     need(isObject(idef.species), `${where}.species must map species names to interface links`);
     for (const [sname, raw] of Object.entries(idef.species)) {
@@ -924,7 +929,7 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
       const i = speciesIndex.get(sname);
       const link = typeof raw === 'string' ? { type: raw } : raw;
       need(isObject(link) && INTERFACE_LINK_TYPES.has(link.type), `${lpath}.type must be one of ${[...INTERFACE_LINK_TYPES].join(', ')}`);
-      fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : link.type === 'permeability' ? ['type', 'P'] : ['type']);
+      fields(link, lpath, link.type === 'conductance' ? ['type', 'G', 'gates'] : link.type === 'permeability' ? ['type', 'P', 'gates'] : ['type']);
       if (link.type !== 'blocked') need(matL.present[i] && matR.present[i], `${lpath}: '${sname}' must be present on both sides`);
       if (link.type === 'conductance') {
         need(species[i].z !== 0, `${lpath}: a conductance link needs a charged species`);
@@ -934,13 +939,52 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
         positive(link.P, `${lpath}.P (m/s)`);
         need(matL.modelOf[i] < 0 && matR.modelOf[i] < 0, `${lpath}: a permeability link needs ideal (dilute) statistics for '${sname}' on both sides`);
       }
-      links[i] = { ...link };
+      // Gated: P (or G) × Π x_q^p over the face's gates (a channel open with probability m³h, say).
+      links[i] = { ...link, gates: gatedBy(link.gates, gates, lpath, where) };
     }
   }
 
   const reactions = normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT);
   checkReactingLinks(reactions, idef, where, matL, matR, species);
-  return { phi, dipole, sheetCharge, links, reactions, conductor: null };
+  return { phi, dipole, sheetCharge, links, reactions, gates, conductor: null };
+}
+
+// A face's gates (Hodgkin–Huxley): each a fraction x in [0, 1] with first-order kinetics in the
+// voltage across the face, V = φ_right − φ_left,
+//   dx/dt = α(V) (1 − x) − β(V) x,
+// α and β each one of NeuroML's three standard forms, with rate in 1/s and midpoint and scale in
+// volts: 'exp', rate·e^((V − midpoint)/scale); 'sigmoid', rate/(1 + e^((midpoint − V)/scale));
+// 'expLinear', rate·y/(1 − e^(−y)) with y = (V − midpoint)/scale. They scale permeabilities
+// (a link's gates), and nothing else: a gate holds no charge and exchanges no free energy.
+const GATE_RATE_TYPES = ['exp', 'sigmoid', 'expLinear'];
+// A link's gates, { m: 3, h: 1 }, as [[gate index, exponent]], against the gates defined at `where`.
+function gatedBy(raw, gates, lpath, where) {
+  if (raw === undefined) return [];
+  need(isObject(raw), `${lpath}.gates must map gate names to exponents, e.g. { m: 3, h: 1 }`);
+  return Object.entries(raw).map(([gname, p]) => {
+    const q = gates.findIndex((gt) => gt.name === gname);
+    need(q >= 0, `${lpath}.gates.${gname}: no such gate${gates.length ? ` (there are ${gates.map((gt) => gt.name).join(', ')})` : ` (define it in ${where}.gates)`}`);
+    need(Number.isInteger(p) && p >= 1 && p <= 8, `${lpath}.gates.${gname}: the exponent must be a whole number from 1 to 8, got ${JSON.stringify(p)}`);
+    return [q, p];
+  });
+}
+function normalizeGates(raw, where, matL, matR) {
+  if (raw === undefined) return [];
+  need(isObject(raw), `${where}.gates must map gate names to { alpha, beta }`);
+  need(!matL.phiFree && !matR.phiFree, `${where}.gates: a gate follows the voltage across the face, which needs φ on both sides`);
+  return Object.entries(raw).map(([name, gdef]) => {
+    const gpath = `${where}.gates.${name}`;
+    need(isObject(gdef), `${gpath} must be { alpha, beta }`);
+    fields(gdef, gpath, ['alpha', 'beta']);
+    const rate = (r, rpath) => {
+      need(isObject(r) && GATE_RATE_TYPES.includes(r.type), `${rpath} must be { type, rate, midpoint, scale } with type one of ${GATE_RATE_TYPES.join(', ')}`);
+      fields(r, rpath, ['type', 'rate', 'midpoint', 'scale']);
+      const scale = finite(r.scale, `${rpath}.scale (V)`);
+      need(scale !== 0, `${rpath}.scale (V) must not be zero`);
+      return { type: r.type, rate: positive(r.rate, `${rpath}.rate (1/s)`), midpoint: finite(r.midpoint, `${rpath}.midpoint (V)`), scale };
+    };
+    return { name, alpha: rate(gdef.alpha, `${gpath}.alpha`), beta: rate(gdef.beta, `${gpath}.beta`) };
+  });
 }
 
 // A conductor (a metal, or a fast ion conductor): only its one mobile carrier, whose single
@@ -1036,7 +1080,7 @@ function normalizeConductorInterface(idef, where, matL, matR, species, speciesIn
   }
   const reactions = normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT);
   checkReactingLinks(reactions, idef, where, matL, matR, species);
-  return { phi, dipole: 0, zeroCharge, sheetCharge: 0, links, reactions, conductor: { side, i: metal.i } };
+  return { phi, dipole: 0, zeroCharge, sheetCharge: 0, links, reactions, gates: [], conductor: { side, i: metal.i } };
 }
 
 function defaultInterfaceLinks(matL, matR, species) {

package/src/difference.js

@@ -0,0 +1,142 @@
+// The dilute kernels' Jacobian terms kept in difference form, for an exact J·v.
+//
+// Assembled, a Scharfetter–Gummel flux's dependence on η at its two ends is two entries, G and
+// −G(1 + E), that cancel for a nearly uniform v; where G is huge (an inversion layer's 0.1 nm
+// cells), J·v loses the flux to round-off. Kept as terms, each is evaluated on differences first:
+//   δN = a·(δη_L − z δφ̂_L) + b·(δη_R − δη_L) + d·(δφ̂_R − δφ̂_L),
+// with a = −G E (through c_L), b = −G(1 + E) and d = z ∂N/∂Δ (through the drift). A node's
+// storage and space charge depend on δη_i − z_i δφ̂ alone; the displacement on δφ̂_R − δφ̂_L. A
+// uniform shift of a region (z_i s on each η_i, s on φ̂) then gives exactly zero, as it must.
+//
+// Indices are compact (the solver's rix), with the sink (index N) for an unknown that isn't one:
+// vectors passed in are read there as zero.
+export class DifferenceTerms {
+  constructor(N, nodes, segments) {
+    this.N = N;
+    this.dead = new Uint8Array(N + 1); // rows replaced since (a contact's level, a held stretch)
+    this.nI = new Int32Array(nodes); // node term: η column (= its balance row), φ̂ column (= Gauss row)
+    this.nP = new Int32Array(nodes);
+    this.nZ = new Float64Array(nodes);
+    this.nMass = new Float64Array(nodes); // storage per unit (δη − z δφ̂), times 1/dt (or iω)
+    this.nCharge = new Float64Array(nodes); // into the Gauss row, per unit (δη − z δφ̂)
+    this.sI = new Int32Array(4 * segments); // segment term: η_L, η_R, φ̂_L, φ̂_R
+    this.sZ = new Float64Array(segments);
+    this.sC = new Float64Array(3 * segments); // a, b, d
+    this.dI = new Int32Array(2 * segments); // displacement: φ̂_L, φ̂_R
+    this.dK = new Float64Array(segments);
+    this.combos = []; // [rk, ri, w]: row rk += w × row ri (strictly neutral nodes' charge rows)
+    this.t = new Float64Array(N + 1);
+    this.x = new Float64Array(N + 1);
+    this.reset();
+  }
+
+  // Afresh for an assembly; `rate` multiplies storage in captured rows (1/dt).
+  reset(rate = 0) {
+    this.rate = rate;
+    this.nn = this.ns = this.nd = 0;
+    this.dead.fill(0);
+    this.combos.length = 0;
+  }
+
+  node(i, p, z, mass, charge) {
+    const k = this.nn++;
+    this.nI[k] = i;
+    this.nP[k] = p;
+    this.nZ[k] = z;
+    this.nMass[k] = mass;
+    this.nCharge[k] = charge;
+  }
+
+  segment(iL, iR, pL, pR, z, a, b, d) {
+    const k = this.ns++;
+    this.sI[4 * k] = iL;
+    this.sI[4 * k + 1] = iR;
+    this.sI[4 * k + 2] = pL;
+    this.sI[4 * k + 3] = pR;
+    this.sZ[k] = z;
+    this.sC[3 * k] = a;
+    this.sC[3 * k + 1] = b;
+    this.sC[3 * k + 2] = d;
+  }
+
+  displacement(pL, pR, k) {
+    const q = this.nd++;
+    this.dI[2 * q] = pL;
+    this.dI[2 * q + 1] = pR;
+    this.dK[q] = k;
+  }
+
+  kill(row) {
+    this.dead[row] = 1;
+  }
+
+  combine(rk, ri, w) {
+    this.combos.push([rk, ri, w]);
+  }
+
+  // into[col] += w × row's coefficients, the steady ones plus `mass` times the storage's (a row
+  // captured as plain entries: a contact's current, read before its row is replaced).
+  capture(row, w, mass, into) {
+    const N = this.N, add = (col, v) => {
+      if (col < N && v !== 0) into[col] += w * v;
+    };
+    for (let k = 0; k < this.nn; k++) {
+      const i = this.nI[k], p = this.nP[k], z = this.nZ[k];
+      let f = 0;
+      if (row === i) f += mass * this.nMass[k];
+      if (row === p) f += this.nCharge[k];
+      if (f === 0) continue;
+      add(i, f);
+      add(p, -z * f);
+    }
+    for (let k = 0; k < this.ns; k++) {
+      const iL = this.sI[4 * k], iR = this.sI[4 * k + 1];
+      const s = row === iL ? 1 : row === iR ? -1 : 0;
+      if (s === 0) continue;
+      const z = this.sZ[k], a = this.sC[3 * k], b = this.sC[3 * k + 1], d = this.sC[3 * k + 2];
+      add(iL, s * (a - b));
+      add(iR, s * b);
+      add(this.sI[4 * k + 2], s * (-z * a - d));
+      add(this.sI[4 * k + 3], s * d);
+    }
+    for (let q = 0; q < this.nd; q++) {
+      const pL = this.dI[2 * q], pR = this.dI[2 * q + 1], s = row === pL ? 1 : row === pR ? -1 : 0;
+      if (s === 0) continue;
+      add(pL, s * this.dK[q]);
+      add(pR, -s * this.dK[q]);
+    }
+  }
+
+  // out += (steady terms) × v + mass × (storage terms) × v, over the live rows. v is read over
+  // its first N entries; transformed (the solver's charge rows), it's mapped back by the caller.
+  apply(v, out, steady = 1, mass = 0) {
+    const { N, t, x } = this;
+    for (let j = 0; j < N; j++) x[j] = v[j];
+    x[N] = 0;
+    t.fill(0);
+    const { nI, nP, nZ, nMass, nCharge } = this;
+    for (let k = 0; k < this.nn; k++) {
+      const i = nI[k], p = nP[k], w = x[i] - nZ[k] * x[p];
+      t[i] += mass * nMass[k] * w;
+      t[p] += steady * nCharge[k] * w;
+    }
+    if (steady !== 0) {
+      const { sI, sZ, sC, dI, dK } = this;
+      for (let k = 0; k < this.ns; k++) {
+        const iL = sI[4 * k], iR = sI[4 * k + 1], pL = sI[4 * k + 2], pR = sI[4 * k + 3];
+        const dN = steady * (sC[3 * k] * (x[iL] - sZ[k] * x[pL]) + sC[3 * k + 1] * (x[iR] - x[iL]) + sC[3 * k + 2] * (x[pR] - x[pL]));
+        t[iL] += dN;
+        t[iR] -= dN;
+      }
+      for (let q = 0; q < this.nd; q++) {
+        const pL = dI[2 * q], pR = dI[2 * q + 1], dD = -steady * dK[q] * (x[pR] - x[pL]);
+        t[pL] += dD;
+        t[pR] -= dD;
+      }
+    }
+    for (let j = 0; j < N; j++) if (this.dead[j]) t[j] = 0;
+    for (const [rk, ri, w] of this.combos) t[rk] += w * t[ri];
+    for (let j = 0; j < N; j++) out[j] += t[j];
+    return out;
+  }
+}

package/src/index.js

@@ -1,6 +1,6 @@
 // driftlet: 1D drift–diffusion–reaction solver.
 
-import { normalizeDevice } from './device.js';
+import { normalizeDevice, DeviceError } from './device.js';
 import { Solver, SolverError } from './solver.js';
 import { makeSolution } from './solution.js';
 import { merge } from './merge.js';
@@ -64,20 +64,32 @@ export class Device {
 
   /**
    * Change part of the definition (deep-merged). A contact given V or I drops the other, so
-   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. A change to the terminals'
+   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
+   * `{ ports: { gate: { V: 0.2 } } }` (an array replaces them all). A change to the terminals'
    * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
    * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
    * @param {object} patch a partial device definition, merged into the current one
    * @returns {this}
    */
   set(patch) {
-    // A contact given a new kind of drive drops the old one: { I: 0 } replaces a held V.
+    // A terminal given a new kind of drive drops the old one: { I: 0 } replaces a held V.
+    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
     for (const side of ['left', 'right']) {
       const c = patch?.contacts?.[side];
-      if (c && typeof c === 'object') {
-        if ('I' in c && !('V' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, V: undefined } } };
-        else if ('V' in c && !('I' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, I: undefined } } };
+      if (c && typeof c === 'object') patch = { ...patch, contacts: { ...patch.contacts, [side]: redrive(c) } };
+    }
+    // Ports: an array replaces them all; an object patches them by name, { gate: { V: 0.2 } }.
+    const ports = patch?.ports;
+    if (ports !== undefined && !Array.isArray(ports)) {
+      if (ports === null || typeof ports !== 'object') throw new DeviceError('set: ports must be an array (replacing them all) or an object of patches by port name, e.g. { gate: { V: 0.2 } }');
+      const old = this.def.ports ?? [];
+      for (const name of Object.keys(ports)) {
+        if (!old.some((p, k) => (p.name ?? `ports[${k}]`) === name)) throw new DeviceError(`set: ports.${name}: no port named '${name}'${old.length ? ` (the ports: ${old.map((p, k) => p.name ?? `ports[${k}]`).join(', ')})` : ''}`);
       }
+      patch = { ...patch, ports: old.map((p, k) => {
+        const q = ports[p.name ?? `ports[${k}]`];
+        return q === undefined ? p : merge(p, redrive(q));
+      }) };
     }
     const def = merge(this.def, patch);
     // Only the terminals' drives changed: update them in place, keeping the solver and its state
@@ -97,6 +109,10 @@ export class Device {
     if (old && old.u.length === solver.u.length && old.n === solver.n) {
       solver.u.set(old.u);
       solver.uLo.set(old.uLo);
+      // A node newly on an electrode's surface (a window moved, a surface added) starts at its
+      // starting coverages, not at whatever its slots held.
+      const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
+      for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
       solver.computeConcentrations();
       solver.time = old.time;
       solver.contactDEnd = old.contactDEnd;

package/src/kit.js

@@ -10,6 +10,7 @@ export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
 export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from './sources.js';
+export { hodgkinHuxley, ghkCurrent } from './channels.js';
 export { describe, unitWarnings } from './describe.js';
 export { recorder } from './recorder.js';
 export { henderson, planck } from './junction.js';

package/src/recorder.js

@@ -15,7 +15,7 @@ const now = () => (typeof performance !== 'undefined' ? performance.now() : Date
  * neither, at the end of each `advance()` call. The trace (`t`, `current`, `voltage`, and
  * `probes` if given) runs from the start through every accepted step of every call.
  * @param {import('./index.js').Device} device
- * @param {{ every?: number, times?: number[], probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+ * @param {{ every?: number, times?: number[], probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number } | { interface: number, species?: string, gate?: string })[] }} [opts]
  */
 export function recorder(device, opts = {}) {
   const { every, times, probes } = opts;

package/src/solution.js

@@ -118,6 +118,11 @@ export function makeSolution(solver, result = {}) {
       const sets = (side) => ['pinned', 'bulk'].includes(model.contacts[side].phi.type);
       out.sigma = Float64Array.from(port.nodes, (g) => ((g === 0 && sets('left')) || (g === last && sets('right')) ? 0 : Cs * (solver.termV[2 + k] - zeroCharge - phi[g])));
     }
+    if (port.gates.length > 0) {
+      // A membrane's gates at each node, and the voltage they follow, φ − (V − zeroCharge).
+      out.gates = Object.fromEntries(port.gates.map((gate, q) => [gate.name, Float64Array.from(port.nodes, (g) => u[solver.blockOfNode[g] * M + 1 + n + port.surface.length + q])]));
+      out.Vm = Float64Array.from(port.nodes, (g) => solver._portVoltage(k, g));
+    }
     if (port.area !== null) {
       out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
       out.area = Float64Array.from(solver.portArea[k]);
@@ -148,7 +153,13 @@ export function makeSolution(solver, result = {}) {
     const N = {};
     for (let i = 0; i < n; i++) N[species[i].name] = u[b * M + 1 + i];
     const rates = itf.reactions.map((_, k) => u[b * M + 1 + n + k]); // mol/(m²·s), forward
-    return { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+    const out = { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+    if (itf.gates.length > 0) {
+      // Each gate's fraction open, and the voltage across the face that drives them.
+      out.gates = Object.fromEntries(itf.gates.map((gate, q) => [gate.name, u[solver._gateSlot(f, q)]]));
+      out.V = solver._faceVoltage(f);
+    }
+    return out;
   });
 
   // Bulk reactions: each one's forward rate at every node (mol/(m³·s), NaN where it doesn't run),
@@ -193,8 +204,14 @@ export function makeSolution(solver, result = {}) {
       );
     }
   });
-  const cond = solver.conditioning;
-  if (result.converged === false && cond && cond.digits > 12) {
+  const cond = solver.conditioning, un = solver.unreached;
+  if (result.converged === false && un) {
+    const [[V0, I0], [V1, I1]] = [un.low, un.high], g = (x) => x.toPrecision(3), A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    sol.warnings.push(
+      `${un.terminal}: no steady state passes the driven current ${g(un.target)} ${A}; held from ${g(V0)} V to ${g(V1)} V ` +
+        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.`,
+    );
+  } else if (result.converged === false && cond && cond.digits > 12) {
     const digits = Number.isFinite(cond.digits) ? `lost ${cond.digits.toFixed(0)} of its ~16 digits` : 'was exactly singular';
     sol.warnings.push(
       `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): part of the device is held ` +