driftlet 0.11.4 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.11.4",
+  "version": "0.13.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/channels.js

@@ -0,0 +1,96 @@
+// 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.
+ *
+ * Or with `linear: true`, Hodgkin and Huxley's own linear channels on the face: conductance links,
+ * G = g, gated the same, whose currents are g(V − E) with E each ion's Nernst level at the
+ * concentrations on either side (so `inside`, `outside` and `at` aren't needed).
+ *
+ * Or, given `area` (membrane per volume of the region, 2/a for an axon of radius a), for a membrane
+ * port along a region: links that are their linear conductances, G = g × area per volume, gated the
+ * same, each ion's reversal potential following from the port's bath and the concentrations inside
+ * (so `inside`, `outside` and `at` aren't needed).
+ * @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 }, linear?: boolean, area?: number }} 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 = {}, linear = false, area } = {}) {
+  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) }]));
+  need(typeof linear === 'boolean', `hodgkinHuxley: linear must be true or false, got ${linear}`);
+  if (area !== undefined || linear) {
+    need(area === undefined || (num(area) && area > 0), `hodgkinHuxley: area must be the membrane per volume (m²/m³; 2/a for an axon of radius a), got ${area}`);
+    for (const [k, v] of Object.entries(G)) need(num(v) && v > 0, `hodgkinHuxley: g.${k} must be a conductance > 0 (S/m²), got ${v}`);
+    const per = area ?? 1; // per volume along a port, or per area on a face
+    return {
+      gates,
+      species: {
+        [Na]: { type: 'conductance', G: G.Na * per, gates: { m: 3, h: 1 } },
+        [K]: { type: 'conductance', G: G.K * per, gates: { n: 4 } },
+        [leak]: { type: 'conductance', G: G.leak * per },
+      },
+    };
+  }
+  need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name (or, for a membrane port, its area)');
+  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/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²${gated ? ` × ${gated}` : ''}`] : [];
       });
+      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

@@ -15,7 +15,7 @@ import { stoichiometry as equationStoichiometry, faceSides, parseEquation } from
 export { DeviceError };
 
 // Contacts use the same laws as internal faces: the outside is a phase with known levels.
-const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange']);
+const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange', 'velocity']);
 const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance', 'permeability']);
 const PHI_LINK_TYPES = new Set(['bulk', 'neutral', 'capacitive', 'pinned']);
 const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells'];
@@ -25,6 +25,7 @@ const LINK_FIELDS = {
   equilibrium: ['type', 'offset', 'mu'],
   conductance: ['type', 'G', 'offset'],
   exchange: ['type', 'k', 'mu'],
+  velocity: ['type', 'v', 'offset', 'mu'],
 };
 
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -348,12 +349,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 +670,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', 'bath']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -690,7 +691,28 @@ 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, "the port's capacitance");
+  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`);
+  // A bath: the outside's composition. The port's V is then the outside's φ, and each linked
+  // species' level there, against it, follows from the composition through the window's
+  // statistics, (μ° + RT ζ)/(zF) (or μ for a neutral one), unless its link gives one. Only the
+  // linked species' levels are taken, so it needn't list (or balance) the rest.
+  let bathLevel = null;
+  if (pdef.bath !== undefined) {
+    need(isObject(pdef.bath) && isObject(pdef.bath.c), `${path}.bath must be { c: { species: concentration } }`);
+    fields(pdef.bath, `${path}.bath`, ['c']);
+    const cb = new Float64Array(species.length);
+    for (const [sname, v] of Object.entries(pdef.bath.c)) {
+      need(speciesIndex.has(sname), `${path}.bath.c.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
+      const i = speciesIndex.get(sname);
+      need(mat.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from ${reg.name} (material '${mat.name}'), so its level outside means nothing here`);
+      cb[i] = positive(v, `${path}.bath.c.${sname}`);
+    }
+    const zb = bathZeta(mat, cb, reg.background);
+    bathLevel = (i) => (cb[i] > 0 ? mat.mu0[i] + RT * zb[i] : undefined); // μ̄ − zFφ outside
+  }
   const links = species.map(() => ({ type: 'blocked' }));
   for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
     const lpath = `${path}.species.${sname}`;
@@ -698,26 +720,28 @@ 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}`);
     const z = species[i].z;
     // The outside level: an offset from V for charged species, an absolute μ for neutral ones.
     let level;
+    const fromBath = bathLevel?.(i);
     if (z === 0) {
       need(link.type !== 'conductance', `${lpath}: a neutral species exchanges by { type: 'exchange', k, mu }`);
-      level = { mu: finite(link.mu, `${lpath}.mu (the outside μ, J/mol)`) };
+      level = { mu: finite(link.mu ?? fromBath, `${lpath}.mu (the outside μ, J/mol${bathLevel ? `; or give '${sname}' in the bath` : ''})`) };
     } else {
       need(link.type !== 'exchange', `${lpath}: a charged species exchanges by { type: 'conductance', G }`);
       need(link.mu === undefined, `${lpath}: a charged species is held by an offset from the port voltage, not by mu`);
-      const offset = link.offset ?? (terminal === i ? 0 : undefined);
-      need(offset !== undefined, `${lpath}.offset: give V_i − V (V); only the terminal species defaults to 0`);
+      const offset = link.offset ?? (fromBath !== undefined ? fromBath / (z * FARADAY) : !bathLevel && terminal === i ? 0 : undefined);
+      need(offset !== undefined, bathLevel ? `${lpath}: give '${sname}' in the bath (or an offset, V_i − V)` : `${lpath}.offset: give V_i − V (V); only the terminal species defaults to 0 (or give the port a bath)`);
       level = { offset: finite(offset, `${lpath}.offset`) };
     }
     // 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 +755,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 +884,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 +940,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 +949,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 +959,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, across = 'the face') {
+  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 ${across}, which needs φ there`);
+  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 +1100,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) {
@@ -1109,6 +1173,22 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
         links[i] = { type: 'conductance', G: positive(link.G, `${lpath}.G`), offset: finite(offset, `${lpath}.offset`) };
         continue;
       }
+      if (link.type === 'velocity') {
+        // A surface velocity: N_in = v (c_eq − c), c_eq the edge's concentration in equilibrium
+        // with the outside level (thermionic emission over a barrier, a contact's surface
+        // recombination velocity), v c (e^((μ̄_out − μ̄)/RT) − 1) for any statistics.
+        const v = positive(link.v, `${lpath}.v (m/s)`);
+        if (species[i].z === 0) {
+          need(link.offset === undefined, `${lpath}: a neutral species' outside level is its mu (J/mol), not an offset`);
+          links[i] = { type: 'velocity', v, mu: finite(link.mu, `${lpath}.mu (the outside μ, J/mol)`) };
+          continue;
+        }
+        need(link.mu === undefined, `${lpath}: a charged species' outside level is an offset from the terminal voltage, not a mu`);
+        const offset = link.offset ?? (terminal === i ? 0 : undefined);
+        need(offset !== undefined, `${lpath}.offset: give V_i − V_terminal (V) of the outside reservoir; only the terminal species defaults to 0`);
+        links[i] = { type: 'velocity', v, offset: finite(offset, `${lpath}.offset`) };
+        continue;
+      }
       if (link.type === 'exchange') {
         // A neutral species exchanging with the outside at its μ: N_in = k (μ_out − μ)/RT.
         need(species[i].z === 0, `${lpath}: a charged species exchanges by { type: 'conductance', G }`);
@@ -1140,12 +1220,19 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     const bath = cdef.bath;
     need(isObject(bath) && isObject(bath.c), `${path}.bath must be { c: { species: concentration }, reference }`);
     fields(bath, `${path}.bath`, ['c', 'reference', 'offset']);
-    need(speciesIndex.has(bath.reference), `${path}.bath.reference: unknown species ${JSON.stringify(bath.reference)}${known(speciesIndex)}`);
-    const r = speciesIndex.get(bath.reference);
+    // Without a reference, V is the bath's φ (an ideal salt bridge: the membrane potential's
+    // convention), and the terminal is the first charged species in it.
+    const byPhi = bath.reference === undefined;
+    if (byPhi) need(bath.offset === undefined, `${path}.bath.offset: an offset places the reference species, and this bath has none (its V is its φ)`);
+    else need(speciesIndex.has(bath.reference), `${path}.bath.reference: unknown species ${JSON.stringify(bath.reference)}${known(speciesIndex)}`);
+    const r = byPhi
+      ? species.findIndex((sp) => sp.z !== 0 && bath.c[sp.name] > 0)
+      : speciesIndex.get(bath.reference);
+    need(r >= 0, `${path}.bath: the bath needs a charged species`);
     need(species[r].z !== 0, `${path}.bath.reference: the reference species must be charged`);
-    need(bath.c[bath.reference] !== undefined, `${path}.bath.reference: '${bath.reference}' must be in the bath`);
-    need(cdef.terminal === undefined || terminal === r, `${path}.terminal must be the bath's reference species`);
-    terminal = r;
+    need(bath.c[species[r].name] !== undefined, `${path}.bath.reference: '${bath.reference}' must be in the bath`);
+    need(byPhi || cdef.terminal === undefined || terminal === r, `${path}.terminal must be the bath's reference species`);
+    terminal = byPhi && terminal !== null ? terminal : r;
     let charge = region.fixedCharge / FARADAY, scale = Math.abs(charge);
     const cb = new Float64Array(species.length);
     for (const [sname, v] of Object.entries(bath.c)) {
@@ -1161,7 +1248,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     const zb = bathZeta(mat, cb, region.background);
     const level = (i) => mat.mu0[i] + RT * zb[i]; // μ̄ − zFφ_bath
     const refOffset = bath.offset === undefined ? 0 : finite(bath.offset, `${path}.bath.offset`);
-    const beta = refOffset - level(r) / (species[r].z * FARADAY); // φ_bath − V
+    const beta = byPhi ? 0 : refOffset - level(r) / (species[r].z * FARADAY); // φ_bath − V
     for (let i = 0; i < species.length; i++) {
       if (!(cb[i] > 0)) continue;
       links[i] =

package/src/index.js

@@ -166,7 +166,12 @@ export class Device {
    * @returns {Solution}
    */
   solve(opts) {
-    return makeSolution(this.solver, this.solver.solveSteady(opts));
+    // A solve that fails reports the state it failed in, and leaves the device as it was: a
+    // device with no steady state (a host filling at a current) can still advance() from there.
+    const snap = this.solver._snapshot();
+    const sol = makeSolution(this.solver, this.solver.solveSteady(opts));
+    if (!sol.converged) this.solver._restore(snap);
+    return sol;
   }
 
   /**

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),
@@ -180,7 +191,7 @@ export function makeSolution(solver, result = {}) {
 
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,
   // gate contacts), check the local Debye length against the adjacent cell.
-  sol.warnings = [...(model.warnings ?? [])];
+  sol.warnings = [...(model.warnings ?? []), ...(result.stopped ? [result.stopped] : [])];
   // A surface covered almost completely: its coverages' η barely move anything below ~1e-10 bare,
   // and Newton loses them (a transient can stall there).
   sol.ports.forEach((p) => {
@@ -196,9 +207,17 @@ export function makeSolution(solver, result = {}) {
   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';
+    // The opposite sign within reach: likely a sign slip (a drive is the current into the device).
+    const flipped = Math.min(I0, I1) <= -un.target && -un.target <= Math.max(I0, I1);
     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.`,
+        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.` +
+        (flipped ? ` (It passes ${g(-un.target)} ${A}: if that was meant, a terminal's current is into the device.)` : '') +
+        // Nothing passed at any voltage: the device only stores what comes in (a host filling, a
+        // capacitor charging), so it has no steady state at a current.
+        (Math.max(Math.abs(I0), Math.abs(I1)) < 1e-6 * Math.abs(un.target)
+          ? ' It passes almost nothing steadily at any voltage, so it may only store what comes in (a host filling, a capacitor charging), which has no steady state at a current: advance() in time instead.'
+          : ''),
     );
   } 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';
@@ -208,6 +227,12 @@ export function makeSolution(solver, result = {}) {
         'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).',
     );
   }
+  if (result.converged === false && !result.stopped && !un && !(cond && cond.digits > 12)) {
+    sol.warnings.push(
+      'the solve did not converge, and nothing specific showed why. ' +
+        'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
+    );
+  }
   const debye = (g) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     const s2 = solver.screening(g); // zᵀKz: Σ z² c for ideal statistics