Source code for morphogen.coupling.diffusion

"""Transient diffusion in voxel images: moisture, oxygen, solvents.

The activity ``u`` of the mobile species (relative humidity, oxygen pressure over its
value outside) is continuous across interfaces; each phase holds the concentration
``c = S u`` (``S`` its solubility, the concentration at equilibrium with the outside)
and lets it through with the permeability ``P = D S`` (``D`` its diffusivity):

    S du/dt = div(P grad u) - k S u

(``k`` an optional first-order consumption). Finite volumes on the voxels: the flux
between two neighbours goes through the harmonic mean of their permeabilities (exact
for layers in series), the exposed faces hold ``u`` (a value or a function of time)
half a voxel from the centres of their voxels, the other faces are impermeable or, in
periodic images, periodic; implicit Euler steps. The analytic solutions of a slab
(Crank 1975, eq. 4.17 and 4.18) check it.
"""

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass

import numpy as np
from scipy import sparse
from scipy.sparse import linalg as splinalg

from morphogen.analysis.basic import as_array
from morphogen.image import VoxelImage

FACES = ("x-", "x+", "y-", "y+", "z-", "z+")
#: Voxels up to which the steps are solved by sparse LU (one factorization per time step
#: length); preconditioned conjugate gradients beyond.
DIRECT_LIMIT = 4096


[docs] @dataclass class DiffusionResult: """Concentrations ``c = S u`` at the requested ``times`` and the uptake: the mean concentration over the image at each time, and at equilibrium (``saturation``).""" times: np.ndarray fields: list[np.ndarray] uptake: np.ndarray saturation: float @property def relative_uptake(self) -> np.ndarray: """``M(t) / M_inf``.""" return ( self.uptake / self.saturation if self.saturation else np.full_like(self.uptake, np.nan) )
def _per_phase(labels: np.ndarray, values, name: str, default=None) -> np.ndarray: phases = np.unique(labels) if values is None: if default is None: raise ValueError(f"{name}: one value per phase") values = dict.fromkeys(phases.tolist(), default) elif np.isscalar(values): values = dict.fromkeys(phases.tolist(), float(values)) missing = [int(p) for p in phases if int(p) not in values] if missing: raise ValueError(f"{name}: no value for the phases {missing}") table = np.zeros(int(phases.max()) + 1) for p, v in values.items(): if int(p) <= phases.max(): table[int(p)] = float(v) if np.any(table[phases] < 0): raise ValueError(f"{name}: non-negative values") return table[labels] def _harmonic(a, b): s = a + b return np.divide(2.0 * a * b, s, out=np.zeros_like(s), where=s > 0) def _operator(perm, spacing, periodic_axes, exposed): """Conductance matrix K (SPD) and the conductances g of the exposed faces.""" shape = perm.shape n = perm.size index = np.arange(n).reshape(shape) rows, cols, vals = [], [], [] diag = np.zeros(n) boundary = np.zeros(n) for axis in range(3): h = spacing[axis] area = np.prod([spacing[a] for a in range(3) if a != axis]) if shape[axis] > 1 or axis in periodic_axes: a = perm b = np.roll(perm, -1, axis=axis) g = _harmonic(a, b) * area / h i = index j = np.roll(index, -1, axis=axis) if axis not in periodic_axes: # no link across the last face sl = [slice(None)] * 3 sl[axis] = slice(0, shape[axis] - 1) g, i, j = g[tuple(sl)], i[tuple(sl)], j[tuple(sl)] if shape[axis] == 1 and axis in periodic_axes: g = np.zeros_like(g) # a voxel and itself g, i, j = g.ravel(), i.ravel(), j.ravel() rows += [i, j] cols += [j, i] vals += [-g, -g] np.add.at(diag, i, g) np.add.at(diag, j, g) for side, face in ((0, f"{'xyz'[axis]}-"), (-1, f"{'xyz'[axis]}+")): if face in exposed: sl = [slice(None)] * 3 sl[axis] = side cells = index[tuple(sl)].ravel() np.add.at(boundary, cells, perm.ravel()[cells] * area / (0.5 * h)) if vals: data, ij = np.concatenate(vals), (np.concatenate(rows), np.concatenate(cols)) else: data, ij = np.zeros(0), (np.zeros(0, int), np.zeros(0, int)) k = sparse.csr_matrix((data, ij), shape=(n, n)) k = k + sparse.diags(diag + boundary) return k.tocsc(), boundary
[docs] def transient_diffusion( image, diffusivity, times, *, solubility=None, exposed=("x-", "x+"), boundary: float | Callable[[float], float] = 1.0, initial: float = 0.0, consumption=None, steps: int = 40, periodic=None, ) -> DiffusionResult: """Diffusion of a species into the phases of ``image`` from its ``exposed`` faces, held at the activity ``boundary`` (a number or a function of time), from a uniform initial activity ``initial``. ``diffusivity``, ``solubility`` (default 1) and ``consumption`` (first-order rate, default 0): one number, or a mapping phase -> value. ``times``: the output times, each interval split into ``steps`` implicit Euler steps (the first one into steps growing geometrically, for the sqrt(t) start). Axes without exposed faces are periodic in periodic images, impermeable otherwise. """ labels = np.asarray(as_array(image)).astype(np.int64) spacing = np.asarray(image.spacing if isinstance(image, VoxelImage) else (1.0, 1.0, 1.0), float) per = ( bool(image.periodic) if periodic is None and isinstance(image, VoxelImage) else bool(periodic) ) exposed = tuple(exposed) for face in exposed: if face not in FACES: raise ValueError(f"exposed: faces among {', '.join(FACES)}") d = _per_phase(labels, diffusivity, "diffusivity") s = _per_phase(labels, solubility, "solubility", default=1.0) k = _per_phase(labels, consumption, "consumption", default=0.0) axes_exposed = {FACES.index(f) // 2 for f in exposed} periodic_axes = {a for a in range(3) if per and a not in axes_exposed} voxel = float(np.prod(spacing)) cap = (s * voxel).ravel() big_k, g = _operator(d * s, spacing, periodic_axes, exposed) big_k = big_k + sparse.diags((k * s).ravel() * voxel) value = boundary if callable(boundary) else (lambda t, b=float(boundary): b) times = np.asarray(times, dtype=float) if np.any(np.diff(times) <= 0) or times[0] < 0: raise ValueError("times: increasing and non-negative") u = np.full(labels.size, float(initial)) t = 0.0 fields, uptake = [], [] cache: dict[float, object] = {} for t_out in times: span = t_out - t if span > 0: if t == 0.0: # geometric steps from about span / 10^4 r = 1.25 first = span * (r - 1.0) / (r**steps - 1.0) dts = first * r ** np.arange(steps) else: dts = np.full(steps, span / steps) for dt in dts: key = float(dt) if key not in cache: a = (sparse.diags(cap / dt) + big_k).tocsc() cache.clear() cache[key] = splinalg.splu(a) if labels.size <= DIRECT_LIMIT else a solver = cache[key] t += dt rhs = cap / dt * u + g * value(t) if isinstance(solver, splinalg.SuperLU): u = solver.solve(rhs) else: diag = solver.diagonal() pre = splinalg.LinearOperator(solver.shape, matvec=lambda x, dg=diag: x / dg) u, info = splinalg.cg(solver, rhs, x0=u, rtol=1e-11, maxiter=5000, M=pre) if info: raise RuntimeError( "transient_diffusion: conjugate gradients did not converge" ) t = float(t_out) c = (s.ravel() * u).reshape(labels.shape) fields.append(c) uptake.append(float(c.mean())) saturation = float(s.mean()) * float(value(times[-1])) return DiffusionResult(times, fields, np.asarray(uptake), saturation)
[docs] def slab_uptake(t, thickness: float, diffusivity: float, terms: int = 400) -> np.ndarray: """``M(t) / M_inf`` of a slab exposed on both faces (Crank 1975, eq. 4.18): ``1 - sum 8 / ((2n + 1)^2 pi^2) exp(-D (2n + 1)^2 pi^2 t / L^2)``.""" t = np.asarray(t, dtype=float) m = 2 * np.arange(terms) + 1 e = np.exp(-diffusivity * (m * np.pi / thickness) ** 2 * t[..., None]) return 1.0 - np.sum(8.0 / (m * np.pi) ** 2 * e, axis=-1)
[docs] def slab_profile(z, t: float, thickness: float, diffusivity: float, terms: int = 400) -> np.ndarray: """``c / c_s`` at the distance ``z`` from the middle of the slab (Crank 1975, eq. 4.17).""" z = np.asarray(z, dtype=float) n = np.arange(terms) m = 2 * n + 1 e = np.exp(-diffusivity * (m * np.pi / thickness) ** 2 * t) series = np.sum((-1.0) ** n / m * e * np.cos(m * np.pi * z[..., None] / thickness), axis=-1) return 1.0 - 4.0 / np.pi * series