Source code for morphogen.coupling.oxidation

"""Thermal oxidation of polymers: the closed-loop mechanistic scheme, homogeneous (thin
films) or limited by the diffusion of oxygen (thick samples).

The scheme of Colin, Verdu and co-workers, with the rate constants that Ernault et al.
(2019) identified on a DGEBA/IPDA epoxy at 110 °C in air (their Tables 1 and 2):

    POOH          -> 2 P + P=O + V          k1  (hydroperoxide decomposition)
    P + O2        -> POO                    k2
    POO + PH      -> POOH + P               k3  (propagation, consumes the sites PH)
    P + P         -> inactive products      k4
    POO + P       -> inactive products      k5
    POO + POO     -> inactive + g6 P=O + O2 k6

``P=O`` (amides here, followed by FTIR) traces the oxidation. In thick samples oxygen
enters by Fick's law, ``d[O2]/dt = D d2[O2]/dz2 - k2 [P][O2] + k6 [POO]^2``, at the
concentration ``S p`` (Henry) on the exposed faces: the oxidized layer is a few hundred
micrometres thick. Concentrations in mol/l, times in seconds, lengths in metres.

**In a microstructure** (:func:`oxidation_field`): the same scheme in every voxel of an
image, each phase with its own constants (a polymer that oxidizes, an inert phase that
lets oxygen through, an impermeable one: fibres, fillers), oxygen diffusing between the
voxels from the exposed faces of the image. As in :mod:`morphogen.coupling.diffusion`,
the activity of oxygen ``u`` (its partial pressure at equilibrium, ``[O2] = S u``) is
continuous across the interfaces and the flux between two voxels goes through the
harmonic mean of their permeabilities ``D S``:

    d[X]/dt = r_X([P], [POO], ..., [O2])        (the five species that do not move)
    S du/dt = div(D S grad u) + r_O2,           u = p on the exposed faces.

The radicals live for milliseconds and the oxidation for thousands of hours: the system
is integrated by the implicit one-step method TR-BDF2 (a trapezoidal stage and a
backward difference, second order, L-stable; Bank et al. 1985) with its embedded error
estimate for the steps (Hosea & Shampine 1996). Each Newton iteration eliminates the
five local species voxel by voxel (their 5 x 5 blocks), which leaves one symmetric
system for the oxygen of all the voxels, ``(diag(V S s) + a K) du = b`` with ``K`` the
conductances of the faces and ``s`` the local Schur complements, solved by conjugate
gradients (a sparse factorization for small images): the cost of a step grows as the
number of voxels, in one, two or three dimensions.
"""

from __future__ import annotations

import logging
from dataclasses import dataclass

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

log = logging.getLogger(__name__)

SPECIES = ("P", "POO", "POOH", "PH", "PO", "O2")


[docs] @dataclass(frozen=True) class ClosedLoopOxidation: """Rate constants (s^-1, l mol^-1 s^-1), initial concentrations (mol/l) and oxygen transport (solubility mol l^-1 Pa^-1, diffusivity m^2/s, partial pressure Pa) of the closed-loop scheme; the defaults are those of Ernault et al. (2019) for DGEBA/IPDA at 110 °C in air.""" k1: float = 1e-5 k2: float = 1e6 k3: float = 2.25 k4: float = 2.5e10 k5: float = 2.25e10 k6: float = 2e3 gamma6: float = 0.5 ph0: float = 5.8 pooh0: float = 1e-3 solubility: float = 2.3e-7 diffusivity: float = 7.3e-13 pressure: float = 0.21 * 101325.0 @property def surface_oxygen(self) -> float: """``[O2] = S p`` at equilibrium with the atmosphere (Henry's law).""" return self.solubility * self.pressure
[docs] def rates(self, y: np.ndarray) -> np.ndarray: """Reaction rates of the species ``SPECIES`` (rows of ``y``), oxygen included.""" p, poo, pooh, ph, _, o2 = y r1 = self.k1 * pooh r2 = self.k2 * p * o2 r3 = self.k3 * poo * ph r4 = self.k4 * p * p r5 = self.k5 * p * poo r6 = self.k6 * poo * poo return np.array( [ 2.0 * r1 - r2 + r3 - 2.0 * r4 - r5, r2 - r3 - r5 - 2.0 * r6, -r1 + r3, -r3, r1 + self.gamma6 * r6, -r2 + r6, ] )
[docs] def initial(self, n: int = 1, oxygen: float = 0.0) -> np.ndarray: y = np.zeros((6, n)) y[2], y[3], y[5] = self.pooh0, self.ph0, oxygen return y
[docs] def thin_film(self, times) -> dict[str, np.ndarray]: """Homogeneous oxidation (oxygen at its surface concentration everywhere): concentrations of the species at ``times`` (s).""" times = np.asarray(times, dtype=float) o2 = self.surface_oxygen def f(_, y): z = np.append(y, o2) return self.rates(z)[:5] sol = solve_ivp( f, (0.0, times[-1]), self.initial(1)[:5, 0], method="Radau", t_eval=times, rtol=1e-8, atol=1e-14, ) if not sol.success: raise RuntimeError(f"thin_film: {sol.message}") out = dict(zip(SPECIES[:5], sol.y, strict=True)) out["O2"] = np.full(len(times), o2) return out
[docs] def profile(self, thickness: float, times, *, nodes: int = 61) -> dict[str, np.ndarray]: """Diffusion-limited oxidation of a plate of ``thickness`` (m) exposed on both faces: ``depth`` (m, from a face to the middle) and the concentrations of the species (times x nodes) at ``times`` (s). Method of lines on a uniform grid of half the plate (zero flux in the middle), stiff integration (Radau).""" times = np.asarray(times, dtype=float) h = 0.5 * thickness / (nodes - 1) o2s = self.surface_oxygen n = nodes - 1 # the nodes below the surface (the surface holds S p) lap = sparse.diags([np.ones(n - 1), -2.0 * np.ones(n), np.ones(n - 1)], [-1, 0, 1]).tolil() lap[n - 1, n - 2] = 2.0 # symmetry in the middle lap = (lap / (h * h)).tocsr() source = np.zeros(n) source[0] = o2s / (h * h) d = self.diffusivity def f(_, y): z = y.reshape(6, n) dz = self.rates(z) dz[5] += d * (lap @ z[5] + source) return dz.ravel() block = sparse.identity(n) + abs(lap) # coupling pattern: local species, O2 neighbours pattern = sparse.bmat([[sparse.identity(n)] * 6] * 5 + [[sparse.identity(n)] * 5 + [block]]) sol = solve_ivp( f, (0.0, times[-1]), self.initial(n, oxygen=o2s).ravel(), # stored in air method="Radau", t_eval=times, rtol=1e-6, atol=1e-12, jac_sparsity=pattern, ) if not sol.success: raise RuntimeError(f"profile: {sol.message}") y = sol.y.reshape(6, n, -1) out = {"depth": np.arange(1, nodes) * h} for k, name in enumerate(SPECIES): out[name] = y[k].T return out
[docs] def oxidized_layer(self, depth, amide, fraction: float = 0.1) -> float: """Thickness of the oxidized layer: the depth where the amide concentration falls to ``fraction`` of its value at the surface (linear interpolation).""" a = np.asarray(amide, dtype=float) target = fraction * a[0] below = np.flatnonzero(a < target) if below.size == 0: return float(depth[-1]) i = below[0] return float(np.interp(target, [a[i], a[i - 1]], [depth[i], depth[i - 1]]))
# -- oxidation in a microstructure --------------------------------------------------------- #: Absolute tolerances of the species (mol/l) in the steps of :func:`oxidation_field`: #: the radicals are scarce (1e-11 to 1e-7 mol/l), the others are not TOLERANCES = (1e-15, 1e-12, 1e-9, 1e-7, 1e-9, 1e-9) #: Voxels up to which the oxygen of a Newton iteration is solved by a sparse #: factorization; preconditioned conjugate gradients beyond DIRECT_LIMIT = 512 _GAMMA = 2.0 - np.sqrt(2.0) # the trapezoidal stage of TR-BDF2 ends at gamma h _D = 0.5 * _GAMMA # the diagonal coefficient of both stages _W = 0.25 * np.sqrt(2.0)
[docs] @dataclass class OxidationField: """The oxidation of an image: the concentrations of the species (``fields``: name -> array ``(times,) + shape``, mol/l; zero in the phases that hold none) at the ``times`` (s), and the number of ``steps`` of the integration.""" times: np.ndarray fields: dict[str, np.ndarray] steps: int
[docs] def tracer(self, species: str = "PO", time: int = -1) -> np.ndarray: """The field of a species at an output time (by default the oxidation products at the last one): the tracer of :func:`morphogen.coupling.ageing. graded_materials`.""" return self.fields[species][time]
class _Kinetics: """The rates of the scheme in the voxels of an image, each with the constants of its phase, and their derivatives.""" def __init__(self, schemes: list, index: np.ndarray) -> None: def table(name): return np.array([getattr(m, name) if m is not None else 0.0 for m in schemes])[index] self.k1, self.k2, self.k3 = table("k1"), table("k2"), table("k3") self.k4, self.k5, self.k6 = table("k4"), table("k5"), table("k6") self.gamma6 = table("gamma6") def rates(self, y: np.ndarray) -> np.ndarray: p, poo, pooh, ph, _, o2 = y r1 = self.k1 * pooh r2 = self.k2 * p * o2 r3 = self.k3 * poo * ph r4 = self.k4 * p * p r5 = self.k5 * p * poo r6 = self.k6 * poo * poo return np.stack( [ 2.0 * r1 - r2 + r3 - 2.0 * r4 - r5, r2 - r3 - r5 - 2.0 * r6, -r1 + r3, -r3, r1 + self.gamma6 * r6, -r2 + r6, ] ) def jacobian(self, y: np.ndarray) -> np.ndarray: """``d rates_i / d y_j`` (6 x 6 x n).""" p, poo, _, ph, _, o2 = y k1, k2, k3, k4, k5, k6 = self.k1, self.k2, self.k3, self.k4, self.k5, self.k6 j = np.zeros((6, 6, p.size)) j[0, 0] = -k2 * o2 - 4.0 * k4 * p - k5 * poo j[0, 1] = k3 * ph - k5 * p j[0, 2] = 2.0 * k1 j[0, 3] = k3 * poo j[0, 5] = -k2 * p j[1, 0] = k2 * o2 - k5 * poo j[1, 1] = -k3 * ph - k5 * p - 4.0 * k6 * poo j[1, 3] = -k3 * poo j[1, 5] = k2 * p j[2, 1] = k3 * ph j[2, 2] = -k1 j[2, 3] = k3 * poo j[3, 1] = -k3 * ph j[3, 3] = -k3 * poo j[4, 1] = 2.0 * self.gamma6 * k6 * poo j[4, 2] = k1 j[5, 0] = -k2 * o2 j[5, 1] = 2.0 * k6 * poo j[5, 5] = -k2 * p return j
[docs] def oxidation_field( image, schemes, times, *, exposed=("x-", "x+"), pressure: float | None = None, unit: float = 1.0, periodic=None, rtol: float = 1e-4, max_steps: int = 20000, progress=None, ) -> OxidationField: """The thermal oxidation of the phases of an image (see the module): the concentrations of the species in its voxels at ``times`` (s). ``schemes``: a :class:`ClosedLoopOxidation` for every phase, or a mapping phase -> scheme, each with the constants of its polymer and its transport of oxygen; a phase without reactive sites (``ph0 = pooh0 = 0``) lets oxygen through and does not oxidize, and a phase mapped to None is impermeable and inert (fibres, fillers). Oxygen enters through the ``exposed`` faces of the image (``"x-"``, ``"x+"``, ...), held at the partial ``pressure`` (Pa; by default that of the schemes, which must then agree); the other faces are impermeable, or periodic in a periodic image. The image is stored in air: its oxygen starts at equilibrium with the atmosphere. ``unit``: the unit of length of the image in metres (``1e-6`` for micrometres). ``rtol``: the relative tolerance of the time steps. ``progress``: a function called with the fraction of the last time reached, after each step.""" from morphogen.analysis.basic import as_array from morphogen.coupling.diffusion import FACES, _operator from morphogen.image import VoxelImage 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) spacing = spacing * float(unit) 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)}") phases = [int(q) for q in np.unique(labels)] if isinstance(schemes, ClosedLoopOxidation): schemes = dict.fromkeys(phases, schemes) missing = [q for q in phases if q not in schemes] if missing: raise ValueError(f"schemes: none for the phases {missing} (None: impermeable and inert)") models = [schemes[q] for q in phases] if any(m is not None and not isinstance(m, ClosedLoopOxidation) for m in models): raise ValueError("schemes: ClosedLoopOxidation, or None for an impermeable phase") live = [m for m in models if m is not None] if not live: raise ValueError("schemes: one phase at least takes oxygen") if pressure is None: if len({m.pressure for m in live}) > 1: raise ValueError("pressure: the schemes differ; give that of the atmosphere") pressure = live[0].pressure pressure = float(pressure) times = np.asarray(times, dtype=float).ravel() if times.size == 0 or np.any(np.diff(times) <= 0) or times[0] < 0: raise ValueError("times: increasing and non-negative") index = np.searchsorted(phases, labels.ravel()) n = labels.size kinetics = _Kinetics(models, index) def table(name, default=0.0): return np.array([getattr(m, name) if m is not None else default for m in models])[index] solubility = table("solubility", 1.0) # (an impermeable voxel: any, it exchanges nothing) permeability = (table("diffusivity") * table("solubility")).reshape(labels.shape) 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} conductance, faces = _operator(permeability, spacing, periodic_axes, exposed) conductance = conductance.tocsr() volume = float(np.prod(spacing)) weights = np.array(TOLERANCES)[:, None] y = np.zeros((6, n)) y[2], y[3] = table("pooh0"), table("ph0") y[5] = np.where(permeability.ravel() > 0.0, solubility * pressure, 0.0) def rhs(state): out = kinetics.rates(state) flux = faces * pressure - conductance @ (state[5] / solubility) out[5] += flux / volume return out def scaled(delta, state): return float(np.sqrt(np.mean((delta / (weights + rtol * np.abs(state))) ** 2))) def solve(residual, state, a): """``(I - a J) delta = residual``: the local species eliminated in each voxel (Gauss's elimination of their 5 x 5 blocks, on all the voxels at once: the blocks of the kinetics need no pivoting), the oxygen of all the voxels solved together.""" m = -a * kinetics.jacobian(state) m[range(6), range(6)] += 1.0 r = residual.copy() for i in range(5): for j in range(i + 1, 6): factor = m[j, i] / m[i, i] m[j, i + 1 :] -= factor * m[i, i + 1 :] r[j] -= factor * r[i] schur = m[5, 5] matrix = (sparse.diags(volume * solubility * schur) + a * conductance).tocsr() if n <= DIRECT_LIMIT or np.any(schur <= 0.0): du = splinalg.spsolve(matrix.tocsc(), volume * r[5]) else: diagonal = matrix.diagonal() jacobi = splinalg.LinearOperator(matrix.shape, matvec=lambda v: v / diagonal) du, info = splinalg.cg(matrix, volume * r[5], rtol=1e-10, maxiter=20000, M=jacobi) if info: raise RuntimeError("oxidation_field: the conjugate gradients did not converge") delta = np.empty_like(residual) delta[5] = solubility * du for i in range(4, -1, -1): delta[i] = (r[i] - np.einsum("jn,jn->n", m[i, i + 1 :], delta[i + 1 :])) / m[i, i] return delta def stage(guess, constant, a): """Newton's method for ``y - a f(y) = constant``; None when it does not converge.""" state = guess.copy() for _ in range(12): delta = solve(constant + a * rhs(state) - state, state, a) state += delta if not np.all(np.isfinite(state)): return None if scaled(delta, state) < 0.03: return state return None fields = {name: np.zeros((times.size, *labels.shape)) for name in SPECIES} t, h, steps = 0.0, 1e-3, 0 slope = rhs(y) for k, t_out in enumerate(times): while t < t_out: h = min(h, t_out - t) if steps >= max_steps: raise RuntimeError(f"oxidation_field: {max_steps} steps before t = {t_out:g} s") a = _D * h middle = stage(y + _GAMMA * h * slope, y + a * slope, a) new = None if middle is not None: c1 = 1.0 / (_GAMMA * (2.0 - _GAMMA)) constant = c1 * middle - (1.0 - _GAMMA) ** 2 * c1 * y new = stage(middle, constant, a) if new is None: h *= 0.25 continue slope_middle, slope_new = rhs(middle), rhs(new) estimate = h * ( (_W - (1.0 - _W) / 3.0) * slope + (_W - (3.0 * _W + 1.0) / 3.0) * slope_middle + (_D - _D / 3.0) * slope_new ) error = scaled(solve(estimate, new, a), new) # (filtered: stiff components) steps += 1 if error > 1.0: h *= max(0.2, 0.9 * error ** (-1.0 / 3.0)) continue t += h y, slope = np.maximum(new, 0.0), slope_new if progress is not None: progress(t / float(times[-1])) if t < t_out: h *= min(5.0, max(0.2, 0.9 * max(error, 1e-10) ** (-1.0 / 3.0))) for row, name in enumerate(SPECIES): fields[name][k] = y[row].reshape(labels.shape) log.info("oxidation_field: %d steps to t = %g s on %d voxels", steps, times[-1], n) return OxidationField(times, fields, steps)