driftlet 0.12.0 → 0.14.0

package/package.json

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

package/src/channels.js

@@ -28,7 +28,7 @@ export function ghkCurrent(z, inside, outside, V, T) {
 }
 
 /**
- * Hodgkin and Huxley's squid-axon channels, for a membrane face with the outside on its left
+ * 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)
@@ -40,13 +40,21 @@ export function ghkCurrent(z, inside, outside, V, T) {
  * (`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 } }} opts concentrations in
+ *   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 = {} } = {}) {
-  need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name');
+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 };
@@ -54,6 +62,21 @@ export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-',
   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}`);

package/src/checks.js

@@ -29,7 +29,8 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
- * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
+ *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
  *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
  *   wants less). The discretisation is second order, so the change estimates this grid's error
@@ -67,6 +68,9 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
     const ledger = steady ? balance(device, sol) : null;
     items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+    // A transient's answer depends on its whole history (and on drives set along the way), so
+    // only a run of its own on a finer grid can check it.
+    else if (refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
   }
 
   const ok = sol.converged && items.every((it) => it.ok !== false);

package/src/describe.js

@@ -202,7 +202,7 @@ export function describe(def) {
       const laws = species.flatMap((sp, i) => {
         const l = itf.links[i];
         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²`] : [];
+        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(

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);
@@ -55,6 +56,49 @@ function positive(v, path) {
   return v;
 }
 
+// Where a region's nodes miss a starting profile worst: the profile at each of its points
+// against the line between the nodes either side, as a fraction of its range over the region
+// (the start is the profile sampled at the nodes). Empty where they miss it by under 2%.
+function unresolved(p, grid, r) {
+  const at = (t) => {
+    const { x, values: v } = p, last = x.length - 1;
+    if (t <= x[0]) return v[0];
+    if (t >= x[last]) return v[last];
+    let k = 0;
+    while (x[k + 1] < t) k++;
+    return v[k] + ((v[k + 1] - v[k]) * (t - x[k])) / (x[k + 1] - x[k]);
+  };
+  const g0 = grid.regionStart[r], g1 = grid.regionEnd[r], a = grid.x[g0], b = grid.x[g1];
+  let lo = Math.min(at(a), at(b)), hi = Math.max(at(a), at(b));
+  p.x.forEach((t, k) => {
+    if (t > a && t < b) (lo = Math.min(lo, p.values[k])), (hi = Math.max(hi, p.values[k]));
+  });
+  if (!(hi > lo)) return {};
+  const missAt = (t, xl, xr) => {
+    const cl = at(xl), cr = at(xr);
+    return Math.abs(at(t) - (cl + ((cr - cl) * (t - xl)) / (xr - xl))) / (hi - lo);
+  };
+  let worst = {}, g = g0;
+  p.x.forEach((t) => {
+    if (!(t > a && t < b)) return;
+    while (grid.x[g + 1] < t) g++;
+    const off = missAt(t, grid.x[g], grid.x[g + 1]);
+    if (off > 0.02 && !(off <= worst.off)) worst = { x: t, h: grid.x[g + 1] - grid.x[g], off };
+  });
+  if (!worst.off) return worst;
+  // The cells that would resolve it there: uniform ones, finer until they miss it by under 2%
+  // however they fall on it. (Cells wider than a step miss it by about as much at any size, so
+  // the miss isn't extrapolated.)
+  const near = Array.from(p.x).filter((t) => Math.abs(t - worst.x) <= 5 * worst.h);
+  const misses = (h) => Math.max(...[0, 0.25, 0.5, 0.75].flatMap((f) => near.map((t) => {
+    const xl = worst.x + h * (Math.floor((t - worst.x) / h - f) + f);
+    return missAt(t, xl, xl + h);
+  })));
+  worst.want = worst.h / 2;
+  while (misses(worst.want) > 0.02 && worst.want > worst.h * 1e-3) worst.want /= Math.SQRT2;
+  return worst;
+}
+
 // A profile against the device's x: { x, values }, piecewise linear between its points and
 // constant beyond its ends (read with profileAt).
 function profile(v, path, what, ok, okText) {
@@ -325,6 +369,18 @@ export function normalizeDevice(def) {
   } catch (err) {
     throw new DeviceError(`grid: ${err.message}`);
   }
+  // A starting profile steeper than the cells under it starts as something else, silently: a
+  // liquid junction's potential then looks as if it grows while the junction forms.
+  regions.forEach((reg, r) => {
+    const missed = reg.c0Profile.map((p, i) => p && { i, ...unresolved(p, grid, r) }).filter((m) => m && m.off);
+    if (missed.length === 0) return;
+    const miss = missed.reduce((a, m) => (m.off > a.off ? m : a));
+    warnings.push(
+      `regions[${r}].c0 (${missed.map((m) => species[m.i].name).join(', ')}): the grid doesn't resolve the starting profile ` +
+        `(at x = ${miss.x.toExponential(2)} m, nodes ${miss.h.toExponential(1)} m apart miss it by ${Math.round(100 * miss.off)}% of its range), ` +
+        `so the start isn't the one given; cells of about ${miss.want.toExponential(0)} m there would resolve it (hmax, or a region boundary there to grade toward)`,
+    );
+  });
   const geometry = normalizeGeometry(def.geometry);
   if (geometry.type !== 'planar') {
     regions.forEach((reg, r) => need(reg.velocity === 0, `regions[${r}].velocity: flow is for a planar device (a uniform velocity through a varying cross-section wouldn't conserve the liquid)`));
@@ -669,7 +725,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', 'gates']);
+  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);
@@ -691,9 +747,27 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
   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);
+  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}`;
@@ -708,14 +782,15 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     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.
@@ -968,10 +1043,10 @@ function gatedBy(raw, gates, lpath, where) {
     return [q, p];
   });
 }
-function normalizeGates(raw, where, matL, matR) {
+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 the face, which needs φ on both sides`);
+  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 }`);
@@ -1153,6 +1228,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 }`);
@@ -1184,12 +1275,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)) {
@@ -1205,7 +1303,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

@@ -15,6 +15,7 @@ export { describe, unitWarnings } from './describe.js';
 export { recorder } from './recorder.js';
 export { henderson, planck } from './junction.js';
 export { check } from './checks.js';
+export { particles } from './particles.js';
 export { polarization } from './polarization.js';
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from './devices.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';