Source code for morphogen.automata.reaction

"""Reaction-diffusion on lattices (continuous-state automata): Gray-Scott model.

Two species ``u`` (substrate) and ``v`` (activator) react and diffuse (Pearson 1993):

    du/dt = D_u lap(u) - u v^2 + F (1 - u)
    dv/dt = D_v lap(v) + u v^2 - (F + k) v

integrated with explicit Euler steps of unit time on unit cells (7-point Laplacian in
3D, 5-point in 2D), with periodic or zero-flux boundaries. Depending on the feed rate
``F`` and the kill rate ``k``, the activator settles into spots, worms, labyrinths or
holes of a characteristic size (Turing patterns); thresholding ``v`` gives two-phase
microstructures.

:func:`gray_scott_tiling` integrates the same system on the cells of any tiling
(:mod:`morphogen.automata.tilings`) with the finite-volume Laplacian of the tiling: the
flux through each face is its length or area over the distance between the centres,
divided by the cell's area or volume (two-point fluxes; the 5- and 7-point Laplacians on
the square tiling). The free edges of finite patches have no flux.
"""

from __future__ import annotations

import math

import numpy as np
from numba import njit, prange
from scipy import ndimage, sparse

#: Feed and kill rates of a few pattern families (with D_u = 0.16, D_v = 0.08).
GRAY_SCOTT_PRESETS = {
    "spots": (0.030, 0.062),
    "worms": (0.046, 0.065),
    "labyrinth": (0.037, 0.060),
    "holes": (0.039, 0.058),
}


@njit(parallel=True, cache=True)
def _step(u, v, du, dv, feed, kill, periodic, u_out, v_out):
    nx, ny, nz = u.shape
    for i in prange(nx):
        im = i - 1
        ip = i + 1
        if periodic:
            im %= nx
            ip %= nx
        else:
            im = max(im, 0)
            ip = min(ip, nx - 1)
        for j in range(ny):
            jm = j - 1
            jp = j + 1
            if periodic:
                jm %= ny
                jp %= ny
            else:
                jm = max(jm, 0)
                jp = min(jp, ny - 1)
            for k in range(nz):
                km = k - 1
                kp = k + 1
                if periodic:
                    km %= nz
                    kp %= nz
                else:
                    km = max(km, 0)
                    kp = min(kp, nz - 1)
                uc = u[i, j, k]
                vc = v[i, j, k]
                lu = (
                    u[im, j, k]
                    + u[ip, j, k]
                    + u[i, jm, k]
                    + u[i, jp, k]
                    + u[i, j, km]
                    + u[i, j, kp]
                    - 6.0 * uc
                )
                lv = (
                    v[im, j, k]
                    + v[ip, j, k]
                    + v[i, jm, k]
                    + v[i, jp, k]
                    + v[i, j, km]
                    + v[i, j, kp]
                    - 6.0 * vc
                )
                uvv = uc * vc * vc
                u_out[i, j, k] = uc + du * lu - uvv + feed * (1.0 - uc)
                v_out[i, j, k] = vc + dv * lv + uvv - (feed + kill) * vc


@njit(parallel=True, cache=True)
def _step_tiling(u, v, indptr, indices, weights, inv_volume, du, dv, feed, kill, dt, u_out, v_out):
    for i in prange(u.shape[0]):
        uc = u[i]
        vc = v[i]
        su = 0.0
        sv = 0.0
        w = 0.0
        for p in range(indptr[i], indptr[i + 1]):
            c = weights[p]
            su += c * u[indices[p]]
            sv += c * v[indices[p]]
            w += c
        lu = (su - w * uc) * inv_volume[i]
        lv = (sv - w * vc) * inv_volume[i]
        uvv = uc * vc * vc
        u_out[i] = uc + dt * du * lu - dt * uvv + dt * feed * (1.0 - uc)
        v_out[i] = vc + dt * dv * lv + dt * uvv - dt * (feed + kill) * vc


def _seeds(noise: np.ndarray, seed_fraction: float, rng: np.random.Generator):
    """Initial fields: ``u = 1/2, v = 1/4`` in the blobs of the highest values of the
    smoothed ``noise``, ``u = 1, v = 0`` elsewhere, plus 1 % noise."""
    seeds = noise > np.quantile(noise, 1.0 - seed_fraction)
    u = np.where(seeds, 0.5, 1.0) + 0.01 * rng.standard_normal(noise.shape)
    v = np.where(seeds, 0.25, 0.0) + 0.01 * rng.standard_normal(noise.shape)
    return u, v


def _initial(initial, shape) -> tuple[np.ndarray, np.ndarray]:
    u, v = (np.array(a, dtype=float) for a in initial)
    if u.shape != shape or v.shape != shape:
        raise ValueError(f"initial: two fields of shape {shape}")
    return u, v


[docs] def gray_scott( shape, rng: np.random.Generator, *, feed: float = 0.037, kill: float = 0.060, du: float = 0.16, dv: float = 0.08, steps: int = 3000, seed_fraction: float = 0.1, seed_size: float = 2.0, periodic: bool = True, initial=None, callback=None, ) -> tuple[np.ndarray, np.ndarray]: """Fields ``(u, v)`` after ``steps`` explicit steps from a perturbed uniform state. The initial state is ``u = 1, v = 0`` except in random blobs (a fraction ``seed_fraction`` of the cells: the highest values of a noise smoothed over ``seed_size`` cells) where ``u = 1/2, v = 1/4``, plus 1 % noise; isolated seed cells would vanish by diffusion. ``initial``: the fields ``(u, v)`` to start from instead. Stability of the explicit scheme requires ``D <= 1/6`` (3D) or ``1/4`` (2D). """ shape = tuple(int(n) for n in shape) limit = 1.0 / (2 * sum(1 for n in shape if n > 1)) if not (0 < du <= limit and 0 < dv <= limit): raise ValueError(f"diffusion coefficients must lie in (0, {limit:g}] for stability") if not 0.0 < seed_fraction < 1.0: raise ValueError("seed_fraction: must lie in (0, 1)") if initial is not None: u, v = _initial(initial, shape) else: sigma = [float(seed_size) if n > 1 else 0.0 for n in shape] noise = ndimage.gaussian_filter( rng.standard_normal(shape), sigma, mode="wrap" if periodic else "nearest" ) u, v = _seeds(noise, seed_fraction, rng) u2 = np.empty_like(u) v2 = np.empty_like(v) for s in range(int(steps)): _step(u, v, float(du), float(dv), float(feed), float(kill), bool(periodic), u2, v2) u, u2 = u2, u v, v2 = v2, v if callback is not None: callback(s + 1, u, v) return u, v
def _operator(tiling): """CSR weights, the inverse cell measures (in cell sizes) and the largest rate ``max_i sum_j w_ij / V_i`` of the finite-volume Laplacian of a tiling.""" indptr, indices, w = tiling.diffusion_weights() k = 2 if tiling.dims == 2 else 3 inv_volume = tiling.cell_size**k / np.asarray(tiling.volumes, dtype=float) rows = np.repeat(np.arange(len(inv_volume)), np.diff(indptr)) total = np.bincount(rows, weights=w, minlength=len(inv_volume)) return indptr, indices, w, inv_volume, float(np.max(total * inv_volume, initial=0.0)) def _substeps(rate: float, du: float, dv: float) -> int: return max(1, math.ceil(max(float(du), float(dv)) * rate - 1e-9))
[docs] def stable_substeps(tiling, du: float, dv: float) -> int: """Number of equal substeps of the unit time step that keep the explicit scheme stable on a tiling: ``D dt max_i(sum_j w_ij / V_i) <= 1`` (the eigenvalues of the Laplacian lie within twice that rate, Gershgorin); 1 on the square tiling for ``D <= 1/(2d)``, as on the grid.""" return _substeps(_operator(tiling)[4], du, dv)
[docs] def gray_scott_tiling( tiling, rng: np.random.Generator, *, feed: float = 0.037, kill: float = 0.060, du: float = 0.16, dv: float = 0.08, steps: int = 3000, seed_fraction: float = 0.1, seed_size: float = 2.0, initial=None, callback=None, ) -> tuple[np.ndarray, np.ndarray]: """Fields ``(u, v)`` (one value per cell of ``tiling``) after ``steps`` time steps of the Gray-Scott system with the finite-volume Laplacian of the tiling. Diffusion coefficients are in cell sizes squared per step, as on the grid; each unit step is split into :func:`stable_substeps` explicit Euler substeps (one on the square tiling, where the scheme is the grid's, to round-off). The initial blobs are the highest values of a white noise smoothed by the heat equation over ``seed_size`` cell sizes (a heat kernel of standard deviation ``seed_size``); ``initial``: the fields ``(u, v)`` to start from instead. ``callback(step, u, v)`` after each step. """ if not (du > 0 and dv > 0): raise ValueError("diffusion coefficients must be positive") if not 0.0 < seed_fraction < 1.0: raise ValueError("seed_fraction: must lie in (0, 1)") indptr, indices, w, inv_volume, rate = _operator(tiling) n = tiling.n_cells if initial is not None: u, v = _initial(initial, (n,)) else: noise = rng.standard_normal(n) t = 0.5 * float(seed_size) ** 2 # heat kernel of variance 2 t = seed_size^2 if t > 0 and rate > 0: rows = np.repeat(np.arange(n), np.diff(indptr)) lap = sparse.csr_matrix((w * inv_volume[rows], indices, indptr), shape=(n, n)) lap = lap - sparse.diags(np.asarray(lap.sum(axis=1)).ravel()) m = math.ceil(t * rate) for _ in range(m): noise = noise + (t / m) * (lap @ noise) u, v = _seeds(noise, seed_fraction, rng) sub = _substeps(rate, du, dv) dt = 1.0 / sub u2 = np.empty_like(u) v2 = np.empty_like(v) args = (indptr, indices, np.asarray(w, dtype=float), inv_volume, float(du), float(dv)) for s in range(int(steps)): for _ in range(sub): _step_tiling(u, v, *args, float(feed), float(kill), dt, u2, v2) u, u2 = u2, u v, v2 = v2, v if callback is not None: callback(s + 1, u, v) return u, v