morphogen.analysis.percolation

Percolation: the forest-fire algorithm, the thresholds of families of microstructures and their finite-size scaling, the anisotropy of percolation: along directions of one image and of a family, in 2-D and 3-D, the rigidity threshold, where the elastic moduli by the FFT solvers vanish, and the critical exponents of the conductivity and of the elastic moduli at the threshold.

A planar image (one voxel along z, the 2-D images of morphoGen) percolates in its plane, along x or y, through 4 (connectivity 4, or 6: through edges) or 8 (8, 18 or 26: and corners) neighbours.

morphogen.analysis.percolation.NU_2D = 1.3333333333333333

The exponents of the correlation length of random percolation in 2-D (exact) and 3-D

morphogen.analysis.percolation.NU_3D = 0.8765

The exponents of the correlation length of random percolation in 2-D (exact) and 3-D

class morphogen.analysis.percolation.Fire(percolates: bool, time: int | None, front: ndarray, times: ndarray | None = None)[source]

Bases: object

Forest fire lit on a face of an image (burn()).

percolates tells whether the fire reaches the opposite face, at the step time (the chemical distance between the faces; None when it does not); front[t] is the number of voxels that catch fire at step t, from the face (front[0]) to the step at which the opposite face is reached, or to the extinction of the fire when the whole clusters were burnt (full); times, then, the step at which each voxel caught fire (-1: unburnt, outside the phase or in a cluster not lit), else None.

morphogen.analysis.percolation.burn(image, phase: int = 1, axis: str = 'x', *, connectivity: int = 6, periodic: bool | None = None, full: bool = False) → Fire[source]

The forest fire of the phase phase of a 3-D image along axis (the burning algorithm of Herrmann, Hong & Stanley 1984): the phase voxels of the face at 0 normal to the axis catch fire at time 0, and at each step the fire spreads to the unburnt phase voxels among the connectivity neighbours (6: faces; 18: and edges; 26: and corners) of those burning, the transverse directions wrapping around a periodic image (periodic, by default that of the image), never the axis. The phase percolates along the axis when the fire reaches the opposite face, at the step time: the chemical distance between the faces, the number of steps of the shortest path through the phase (n - 1 for a straight channel n voxels long). The breadth-first burning, compiled, queues each voxel once and stops at the end of that step, unless full asks for the whole clusters lit on the face and their burning times; it costs the voxels burnt, where connected_components() labels the whole image, and decides as its flags percolating on open boundaries. A planar image (one voxel along z) burns in its plane, along x or y, through 4 (connectivity 4 or 6) or 8 (8, 18 or 26) neighbours; burn_along() burns along any direction.

class morphogen.analysis.percolation.PercolationThreshold(threshold: float, bracket: tuple[float, float], fractions: ndarray, probabilities: ndarray, realizations: int)[source]

Bases: object

Estimate of a percolation threshold.

threshold is the middle of bracket, the last interval of fractions at whose ends the percolation probability lies on either side of 1/2; fractions are the fractions tried, in increasing order, and probabilities the fractions of the realizations images that percolate at each.

morphogen.analysis.percolation.percolation_threshold(generate: Callable[[float, Generator], object], lower: float = 0.0, upper: float = 1.0, *, phase: int = 1, axis: str = 'x', connectivity: int = 6, periodic: bool | None = None, method: str = 'labels', realizations: int = 9, tol: float = 0.005, seed: int | SeedSequence | Generator | None = None) → PercolationThreshold[source]

Percolation threshold of a family of microstructures: the fraction at which the probability that the phase phase of generate(fraction, rng) percolates crosses 1/2.

generate returns a 3-D image (a VoxelImage, or a boolean or label array; one voxel along z for a 2-D one, percolating along x or y). The probability is the fraction of realizations images that percolate; realization i gets a generator built from the same seed at every fraction (common random numbers), independent of the other realizations and reproducible from seed (an integer, a seed sequence, a generator, or None for fresh entropy), so that a family growing with the fraction for a given stream, such as rng.random(shape) < fraction, percolates from a threshold of its own in each realization and the estimate is the median of these thresholds (with an even number of realizations a probability of exactly 1/2 counts as percolating). The probabilities at lower and upper must lie on either side of 1/2, in either order (a phase that stops percolating as the fraction grows); the bracket is halved until it is narrower than tol and the threshold is its middle. The estimate carries the finite-size shift of the criterion and the spread of the realizations’ thresholds, both of order L**(-1/nu) (nu about 0.88 in 3-D, 4/3 in 2-D) for images L voxels across, the spread divided by the square root of realizations.

The phase percolates along axis ("x", "y", "z", "any" or "all" of them; x and y in 2-D) through its connectivity neighbours (6: faces; 18: and edges; 26: and corners; 4 or 8 in 2-D) when a component joins the two faces normal to the axis inside the box, as in connected_components(), or, on periodic images (periodic, by default that of each image), when a component wraps around the box along the axis: a cycle of neighbours through the faces winds around it, so that the tiled component is an infinite cluster. For instance, for the spheres of a Boolean model, whose continuum threshold is 0.2895 (0.27 on these images, 64 voxels across a periodic box 16 radii across, where spheres closer than about a voxel touch):

from morphogen.domain import Domain
from morphogen.models import BooleanSpheres

domain = Domain(size=16.0, periodic=True)

def spheres(fraction, rng):
    model = BooleanSpheres(radius=1.0, volume_fraction=fraction)
    return model.generate(domain, seed=rng).voxelize(64)

result = percolation_threshold(spheres, 0.15, 0.45, seed=0)

With method="fire" the phase percolates along the axis when the forest fire of burn(), lit on the face at 0, reaches the opposite face (along each axis for "any" and "all"): face to face, through the transverse faces of a periodic image but not those normal to the axis, a cluster crossing the slab that the image tiles transversally. The labels (method="labels", the default) decide alike on open boundaries; on periodic images their wrapping implies it (the lift of a cycle winding around the box along the axis crosses it from face to face) but not conversely (a staircase joins the faces without wrapping), so that the fire percolates in at least as many images and its estimate lies at or below theirs. The fire stops at the opposite face and burns only the clusters lit on the first, where the labels label the whole image.

class morphogen.analysis.percolation.PercolationScaling(sizes: ndarray, thresholds: ndarray, brackets: ndarray, threshold: float, stderr: float, amplitude: float, nu: float, nu_stderr: float | None, residuals: ndarray, results: tuple[PercolationThreshold, ...] = ())[source]

Bases: object

Finite-size scaling of a percolation threshold (percolation_scaling()).

thresholds[k] is the threshold of the boxes sizes[k] voxels across, the middle of brackets[k] (results[k]: its PercolationThreshold); threshold is that of the infinite medium, extrapolated by the fit thresholds = threshold + amplitude * sizes**(-1/nu), with the standard error stderr; nu is the exponent given or, with its standard error nu_stderr (else None), fitted; residuals are the thresholds minus the fit.

morphogen.analysis.percolation.percolation_scaling(generate: Callable[[float, Generator, int], object], sizes, lower: float = 0.0, upper: float = 1.0, *, nu: float | None = None, fit_nu: bool = False, phase: int = 1, axis: str = 'x', connectivity: int = 6, periodic: bool | None = None, method: str = 'labels', realizations: int = 9, tol: float = 0.005, seed: int | SeedSequence | Generator | None = None) → PercolationScaling[source]

Finite-size scaling of the percolation threshold of a family of microstructures: the thresholds p½(L) of percolation_threshold() in boxes of each of the sizes L, generate(fraction, rng, size) returning an image size voxels per edge, extrapolated to the infinite medium.

Near the threshold p_c of the infinite medium, the correlation length diverging as |p - p_c|**(-nu), the probability that the phase of a box L voxels across percolates depends on the fraction p through (p - p_c) * L**(1/nu) only (Stauffer & Aharony 1994, ch. 4): it crosses 1/2 at p½(L) = p_c + a * L**(-1/nu), the amplitude a set by the criterion, the shape of the box and its boundaries (positive for the faces normal to one axis of an open cube, joined at p_c with a probability below 1/2), and the thresholds of the realizations spread over a width of the same order. With common random numbers a family growing with the fraction percolates from a threshold of its own in each realization, and p½(L) is the median of these thresholds (the lower median for an even number of realizations): it scatters from seed to seed by about sqrt(pi/2) = 1.25 times their spread over sqrt(realizations), so that the shift and the scatter both shrink as L**(-1/nu), the scatter also as 1/sqrt(realizations). p_c and a (and nu, from the value given, with fit_nu) are fitted by least squares weighted by L**(2/nu), the inverse variance of p½; the variance of p_c adds that of the fit, from its residuals, and that of the bisection, each p½ uniform in its bracket (variance width**2 / 12). The extrapolation removes the shift but amplifies the scatter (the intercept of a line through points scattered as their abscissae L**(-1/nu)): it improves on the largest box where the shift there exceeds the scatter. For the sites of the cubic lattice (by the fire, through faces, from 16 to 48 voxels across, tol=0.002), the faces normal to the three axes of an open cube are joined at p_c + 0.008 on 48 voxels, and 9, 25 and 99 realizations extrapolate to p_c within 0.0034, 0.0022 and 0.0015 (the scatter over seeds, matched by stderr); those normal to one axis are joined at p_c + 0.0036, extrapolated within 0.0020 by 49 realizations. Four such sizes leave nu undetermined (1.0 +/- 1 with fit_nu) and p_c then within 0.01 to 0.03 only.

nu is by default the exponent of random percolation, 0.8765 in 3-D (0.8765(16), Ballesteros et al. 1999, with p_c = 0.3116081(7) for the sites of the cubic lattice; 0.88 in Stauffer & Aharony 1994) and 4/3 in 2-D (exact: den Nijs 1979, Nienhuis 1982) for planar images (one voxel along z), universal: that of the lattices and of the continuum percolation of overlapping objects of a finite range. In 2-D a square is crossed at p_c with the probability 1/2 (by duality; Ziff 1992), and its 1/2-crossing lies off p_c by much less than its scatter, the fit finding a near 0: for the sites of the square lattice (by the fire, 32 to 256 across, 49 realizations, six seeds), squares extrapolate within 0.002 of p_c = 0.59274621(13) through 4 neighbours (Newman & Ziff 2000) and 0.003 of 0.407254 through 8 (1 - p_c: the matching lattice; Sykes & Essam 1964), and rectangles twice as long as wide, joined the long way (a about 0.36, the largest 0.006 above p_c), within 0.002. The sizes are at least 3 distinct positive integers (4 with fit_nu), each bisected between lower and upper with the criterion (phase, axis, connectivity, periodic, method), the realizations and the tol of percolation_threshold(), from a seed of its own derived from seed and the size (independent estimates, each reproducible whatever the other sizes). For instance, the site percolation of the cubic lattice:

def site(fraction, rng, size):
    return rng.random((size, size, size)) < fraction

result = percolation_scaling(site, [16, 24, 32, 48], 0.2, 0.45, method="fire")

and for the model of a configuration, the family of family_from_config() with sized=True.

morphogen.analysis.percolation.family_from_config(config, parameter: str = 'volume_fraction', *, base_dir=None, sized: bool = False) → Callable[[...], VoxelImage][source]

The family of microstructures of a run configuration, for percolation_threshold().

config is a file, a mapping or a RunConfig (validated by load_config(), with base_dir) whose model, domain and voxels sections are used: generate(fraction, rng) draws from rng a realization of the model whose parameter parameter is fraction, in the domain, and voxelizes it on the grid of the configuration, as morphogen.pipeline.run() does. A model without the parameter, and a configuration without a domain size or a voxel grid, are refused (ConfigError). For instance:

config = {
    "model": {"type": "boolean_spheres", "radius": 1.0, "volume_fraction": 0.3},
    "domain": {"size": 16.0, "periodic": True},
    "voxels": {"shape": 64},
}
result = percolation_threshold(family_from_config(config), 0.15, 0.45, seed=0)

With sized, generate(fraction, rng, size), for percolation_scaling(), voxelizes the realization in a box size voxels per edge at the voxel size of the configuration, the domain scaled to it (its origin and periodicity kept): the box grows in units of the microstructure, as finite-size scaling wants, where a finer grid of the same domain would converge to the threshold of that domain. The parameters of the model must then be intensive (sizes, fractions, densities), a number of objects being diluted in the growing box. A grid of one voxel along z (a 2-D configuration) keeps it: the box grows in the plane, size voxels along x and y.

morphogen.analysis.percolation.burn_along(image, direction, phase: int = 1, *, connectivity: int = 6, full: bool = False) → Fire[source]

The forest fire of the phase phase of an image along direction (a vector, in physical units for anisotropic voxels; in the plane of a planar image), across the core of the image along it: the cylinder (a square in 2-D) of the voxels whose centres lie within R of the axis through the centre of the box along the direction and within R of the centre along it, 2 R long and across, R = D / (2 sqrt 2) for the diameter D of the ball (disc) inscribed in the box, its smallest edge. The phase voxels of the core within a step of a neighbour of crossing its lower cap catch fire at time 0 (one layer along an axis, as the face of burn(); the cap is the plane normal to the direction at -R), the fire spreads through the connectivity neighbours inside the core, and the phase percolates along the direction when it reaches those of the upper cap, at the step time, the chemical distance across the core (Fire as burn(); times -1 outside the core too).

Any direction crosses a congruent cylinder of the inscribed ball, so that a medium isotropic in law crosses alike along all (up to the voxels of the core) and the differences between directions are those of the medium, not of the box: the two planes of the box normal to a diagonal touch it only at corners. The core lies inside the box (the periodicity of the image unused) and spans 1/sqrt 2 of its smallest edge (half of a square, 0.28 of a cube); it has the aspect of a cube (a square), whose faces burn() joins, and a square of the plane is crossed at p_c with the probability 1/2 (by duality). Its chemical distance when full, that of an image of the phase alone, makes time a tortuosity (directional_percolation()).

class morphogen.analysis.percolation.DirectionalPercolation(directions: ndarray, percolates: ndarray, distances: ndarray, straight: ndarray, tortuosity: ndarray)[source]

Bases: object

Percolation of a phase of one image along directions (directional_percolation()).

directions are unit vectors (rows; no z component in 2-D), percolates whether the fire crosses the core of the image along each, distances its chemical distance across (-1: it does not) and straight that across the full core, tortuosity the geometric tortuosity across (inf: no crossing).

morphogen.analysis.percolation.directional_percolation(image, directions='lattice', phase: int = 1, *, connectivity: int = 6) → DirectionalPercolation[source]

Percolation of the phase phase of one image along each of directions: the fire of burn_along() across the core of the image along each, a direction and its opposite alike. directions are "lattice" (the axes and the diagonals of the grid: 4 directions in 2-D, 13 in 3-D, in physical units for anisotropic voxels, as for the mean intercept length of fabric_tensor()), "axes", a number of directions sampled (in 2-D at equal angles over half a turn from x; in 3-D on a Fibonacci spiral over the half sphere z > 0, quasi-uniform), or vectors (rows of 2 or 3 components).

The chemical distance across the core, the number of steps of the shortest path through the connectivity neighbours, follows the metric of the lattice, which is not isotropic: through 4 neighbours a diagonal of the square lattice is crossed by many staircases of the same length, which the phase seldom blocks all, where an axis has one straight path (on sites of the square lattice at p = 0.65, 1.03 and 1.33 times the distance across the full core). The geometric tortuosity compares the directions: as geometric_tortuosity() across the faces normal to an axis, the mean Euclidean length of the shortest paths through the phase (26 neighbours, 8 in 2-D, steps between voxel centres) from the lower cap to the voxels of the upper one they reach, here over that across the full core (1 for a straight channel along the direction, the bias of the metric of the steps divided out), and only where the phase percolates along the direction.

class morphogen.analysis.percolation.PercolationAnisotropy(directions: ndarray, thresholds: ndarray, stderr: ndarray, deviations: ndarray, deviation_stderr: ndarray, ratio: float, ratio_stderr: float, tensor: ndarray, eigenvalues: ndarray, eigenvalue_stderr: ndarray, principal: ndarray, residuals: ndarray, samples: ndarray, realizations: int)[source]

Bases: object

Percolation thresholds of a family along directions (percolation_anisotropy()).

samples[i, k] is the threshold of realization i along directions[k] (unit vectors, rows; no z component in 2-D), the middle of a bracket narrower than the tolerance (inf or -inf: beyond the bounds); thresholds their medians, with the standard errors stderr; deviations the medians of the differences of the realizations’ thresholds from their means over the directions, with the standard errors deviation_stderr; ratio the median of the ratios of their thresholds along the directions of the largest and the smallest deviation, with ratio_stderr (inf when a threshold lies beyond the bounds); tensor the threshold tensor (3 x 3, nothing along z in 2-D), its eigenvalues (increasing; 2 in 2-D) with eigenvalue_stderr and its principal directions (rows), residuals the paired thresholds (the median of the realizations’ means plus the deviations) less its quadratic form. The standard errors leave out the samples beyond the bounds (NaN for fewer than two left); the tensor is NaN where a threshold lies beyond them.

morphogen.analysis.percolation.percolation_anisotropy(generate: Callable[[float, Generator], object], lower: float = 0.0, upper: float = 1.0, *, directions='lattice', phase: int = 1, connectivity: int = 6, realizations: int = 9, tol: float = 0.005, seed: int | SeedSequence | Generator | None = None) → PercolationAnisotropy[source]

Percolation thresholds of a family of microstructures along directions, and their anisotropy: the fractions at which the phase phase of generate(fraction, rng) (as for percolation_threshold()) percolates along each of directions (as for directional_percolation(): across the core of the image along each).

Each realization, seeded as by percolation_threshold() and alike at every fraction, is bisected along every direction to a threshold of its own, the middle of a bracket narrower than tol (for a family growing with the fraction, the fraction from which it crosses; inf or -inf beyond lower and upper: a direction along which it does not cross between them, or always does); the directions bracketed alike share the images, each image burnt along all those whose bracket it halves. The thresholds are the medians of the realizations’ (the estimate of percolation_threshold(): the lower median for an even number, of a family growing with the fraction), with the standard errors sqrt(pi/2) s / sqrt(N) from the standard deviation s of the N realizations’ (a normal law). The realizations are common to the directions, which are compared within each: the deviations are the medians of the differences of a realization’s thresholds from their mean over the directions, the ratio that of its thresholds along the directions of the extreme deviations, with the standard errors of these paired differences, free of the scatter that the directions share and the thresholds carry (a difference of the medians along two directions would keep it: the same realization tends to be their median). An isotropic family has deviations within a few standard errors, and a ratio above 1 by about as much. The threshold tensor T is the symmetric tensor whose quadratic form p(n) = n . T . n fits the paired thresholds (the median of the realizations’ means plus the deviations) by least squares (diagonal and exact on the axes alone); its eigenvalues bound the fitted thresholds, reached along its principal directions, their standard errors (the shared scatter included) from the tensors fitted to each realization, projected on these directions; the residuals tell how far a quadratic form describes the thresholds.

In the infinite medium, a statistically homogeneous medium of a finite range of correlation percolates from one threshold along every direction: its infinite cluster, when there is one, is unbounded along all. A box L across crosses at fractions that depend on the direction through the shape of the clusters: elongated ones (aligned fibres, stretched correlations) cross it sooner along their elongation, along which the box is shorter in units of their correlation length, and the thresholds differ by an amount of the order of their shift from p_c, L**(-1/nu) (percolation_scaling()), however large the realizations. This is the anisotropy of percolation of a volume of that size, a specimen or an RVE; it vanishes with the size unless the medium is disconnected along some directions (layers separated by sheets of the other phase: thresholds inf across them). For instance, for fibres aligned along x:

from morphogen.config import model_from_config
from morphogen.domain import Domain

domain = Domain(size=12.0)
config = {"type": "boolean_cylinders", "radius": 0.5, "length": 6.0,
          "orientation": {"type": "aligned", "direction": [1, 0, 0]}}

def fibres(fraction, rng):
    model = model_from_config({**config, "volume_fraction": fraction})
    return model.generate(domain, seed=rng).voxelize(48)

result = percolation_anisotropy(fibres, 0.005, 0.6, realizations=25, tol=0.002, seed=0)

cross along x from a volume fraction of 0.099, across from 0.40 to 0.42 (a ratio of 5.0 +/- 0.8), the smallest eigenvalue of the tensor, 0.087, along x; the sections of the fibres by a plane (strips, Domain(size=(12, 12, 0.0625), periodic=False) on 192 x 192 x 1 voxels) from 0.25 along x and 0.90 across.

morphogen.analysis.percolation.CUTS = {'fe': 1e-12, 'fft': 1e-08}

above the stress averages of the floppy images of the FFT solver, its iterations stopping short of the round-off, and above the energies of those of the voxels factorized, which resolve the moduli of the realizations that bear down to the round-off

Type:

The default cut of rigidity_threshold() for each solver

morphogen.analysis.percolation.SOLVER_TOLS = {'fe': 1e-10, 'fft': 1e-08}

1e-8 for the FFT solver, 1e-10 for the voxels factorized, whose solutions at 1e-8 leave the soft modes of floppy images unresolved, with energies of 1e-13 to 2e-8 and stress averages that agree with them (sites of the cubic lattice near their rigidity threshold: 23 of 32 realizations of 32³ to 80³ voxels bear from fractions lower by 0.0003 to 0.003)

Type:

The default tolerance of the conjugate gradients of each solver for the moduli

class morphogen.analysis.percolation.PercolationExponent(physics: str, threshold: float, exponent: float, stderr: float, threshold_error: float, ratio: float, amplitude: float, nu: float, sizes: ndarray, means: ndarray, mean_stderr: ndarray, residuals: ndarray, fractions: ndarray, values: ndarray, value_stderr: ndarray, sweep: ndarray, sweep_exponents: ndarray, sweep_stderr: ndarray, sweep_threshold_error: ndarray, contrast: float, realizations: int, iterations: int, residual: float, samples: ndarray, solver: str = 'fft')[source]

Bases: object

Critical exponent of an effective property at a percolation threshold (percolation_exponent()).

exponent is that of the property (physics: "thermal", the conductivity along the axis, t; "elastic", the modulus of a uniaxial strain along it, f), nu times ratio, the slope of -ln <P> against ln L fitted to the means (standard errors mean_stderr) of the realizations of the sizes at the threshold: means = amplitude * sizes**(-ratio), residuals the logarithms of the means less the fit; stderr is its statistical standard error and threshold_error half its change between the threshold less and plus threshold_stderr (0 without). fractions are those computed (increasing: the threshold, the two shifted by its standard error, those of the sweep), values[k, j] the mean property of the boxes sizes[k] at fractions[j] with the standard errors value_stderr, and samples[k, i, j] that of realization i; sweep_exponents[k] is the exponent fitted to the means of size k against fraction - threshold over the sweep, with sweep_stderr and sweep_threshold_error (empty without a sweep). iterations and residual are the largest number of iterations and relative residual of the solver.

morphogen.analysis.percolation.percolation_exponent(generate: Callable[[float, Generator, int], object], sizes, threshold: float, *, threshold_stderr: float = 0.0, fractions=(), physics: str = 'thermal', phase: int = 1, axis: str = 'x', contrast: float = 1e-08, nu: float | None = None, realizations: int = 16, tol: float | None = None, maxiter: int | None = None, device: str = 'auto', solver: str = 'fft', seed: int | SeedSequence | Generator | None = None) → PercolationExponent[source]

Critical exponent of the conductivity (t) or of the elastic moduli (f) of the percolating phase of a family of microstructures, by the finite-size scaling of the property at its percolation threshold, and optionally by a sweep above it.

Near the threshold p_c of the infinite medium the conductivity of the phase phase vanishes as (p - p_c)**t, its elastic moduli as (p - p_c)**f, and the correlation length diverges as |p - p_c|**(-nu); at p_c, in boxes L across, the mean property scales as L**(-t/nu) (L**(-f/nu); Derrida & Vannimenus 1982, Stauffer & Aharony 1994). generate(fraction, rng, size) returns an image size voxels per edge (one voxel along z for a planar one), as for percolation_scaling() (family_from_config() with sized=True for the model of a configuration); for each of the sizes (at least 3), the realizations are drawn at the threshold, each from a seed of its own derived from seed, the size and its number, and their phase conducts (conductivity 1) or bears (Young’s modulus 1, Poisson’s ratio 0.3) while the other phases have contrast times its properties (void at 0). The periodic FFT solver (morphogen.homogenization.fft; device: "cpu", "gpu" or "auto", the GPU when there is one; tol and maxiter of its conjugate gradients, tol by default 1e-8, and 1e-10 for the voxels factorized (SOLVER_TOLS), maxiter by default that of the solver, 20 L + 1000 for L the largest dimension, for the conductivity and 50 L + 1000 for the moduli, whose solutions near the rigidity threshold take up to 45 L), or (solver="fe") the same trilinear voxels assembled and solved by conjugate gradients preconditioned by the sparse factorization of their matrix, on the CPU (morphogen.homogenization.voxel_fe: the same solutions in a few iterations near the rigidity threshold, void around; with a contrast every voxel is assembled; void around, on the voxels that bear alone), gives the conductivity along axis (physics="thermal") or the modulus of a uniaxial strain along it, C_xxxx along x ("elastic"; all the moduli share f, and Young’s modulus would take six solutions), from the energy of the solution, the mean of σ : ε (stationary: its error is of second order, where the stress average strays with the round-off of the element matrices on floppy images, see rigidity_threshold()). The logarithms of the means are fitted against ln L by least squares weighted by their inverse variances (the standard errors of the means over their values), the slope times nu being the exponent: nu is by default that of random percolation, 0.8765 in 3-D and 4/3 in 2-D (percolation_scaling()). Its standard error comes from those of the means, scaled by the scatter of the residuals when it exceeds them (corrections to scaling); with a threshold_stderr, the realizations are also computed at the threshold less and plus it (the same images: common random numbers) and threshold_error is half the change of the exponent between them, the error that the threshold’s own leaves.

The finite-size scaling at p_c is the method of the literature (Derrida & Vannimenus 1982; Gingold & Lobb 1990: t = 2.003 +/- 0.047 in 3-D; Grassberger 1999: t/nu = 0.9745 +/- 0.0015 in 2-D): every box contributes at its threshold, where the property is critical, and the corrections are those of L alone. A sweep in p - p_c needs boxes much larger than the correlation length at every fraction of its window, which ends where the critical region does: on images of a few hundred voxels across the window is narrow and its exponent drifts with it (Kirkpatrick’s 1.6 +/- 0.1 in 3-D, 1973, came from such sweeps). fractions (at least 3, above the threshold plus its standard error) add one on every size: sweep_exponents are the slopes of ln <P> against ln(p - p_c) of each size, with their standard errors and the change that the threshold’s error makes (refitted at p_c +/- its standard error), for comparison.

The threshold must be that of the solver. Its trilinear voxels join two voxels through the nodes they share, a face, an edge or a corner: the conductivity percolates through 26 neighbours (8 in 2-D), so that its threshold is that of percolation_scaling() with connectivity=26 (wrapping around the periodic box, as the solver, or by the fire, faster on large planar images: the criteria extrapolate to the same p_c), below that of the faces (for sites of the cubic lattice 0.0976 against 0.3116; for Boolean spheres of 3 voxels of radius, 0.186 against 0.245). In elasticity a shared corner is a ball joint and an edge a hinge, about which the voxels turn freely: the moduli vanish where the joined voxels become rigid, between the thresholds of 26 and 6 neighbours (8 and 4 in 2-D), at the threshold that rigidity_threshold() finds from the moduli themselves. The values of the realizations that do not percolate, of the order of the contrast, are known to the tolerance of the solver only. The contrast shifts the property by about contrast * (L / l)**((t + s)/nu) of itself at p_c (Efros & Shklovskii 1976, Straley 1976; l the size of the grains, s the exponent of a superconducting phase, about 0.73 in 3-D and 1.30 in 2-D), and the sweep within contrast**(1/(t + s)) of p_c: at the default 10⁻⁸, below 10⁻³ of the property and 0.002 in fraction for boxes up to 40 grains across in 3-D and 300 in 2-D. The threshold weighs most: periodic Boolean discs of 4 pixels of radius (64 to 512 pixels, 48 realizations; p_c = 0.5997 +/- 0.0054 through 8 neighbours) give t = 1.13 +/- 0.16 +/- 0.21 (the second error that of the threshold, dt/dp_c about -40), spheres of 3 voxels of radius (24 to 96 voxels, 32 realizations; 0.1861 +/- 0.0040 through 26) t = 2.37 +/- 0.36 +/- 0.32 (dt/dp_c about -80), against 1.30 and 2.0. At their rigidity thresholds (by rigidity_threshold(), void around, solver="fe", the energies at the tolerance 1e-10, those that bear under 1e-9 confirmed at 1e-11), the sites of the square lattice (0.4617 +/- 0.0004; 16 to 256 pixels, 200 to 400 realizations) give f/nu = 2.26 +/- 0.07 +/- 0.05 (f = 3.01 with nu = 4/3), the slope rising with the box (1.55 between 16² and 24² pixels, 2.93 +/- 0.68 between 192² and 256²; 2.46 +/- 0.06 +/- 0.07 from 32², 2.63 +/- 0.07 +/- 0.08 with a correction to scaling L**-1), and those of the cubic lattice (0.1304 +/- 0.0002; 8 to 80 voxels, 400 to 20 realizations) f/nu = 4.48 +/- 0.09 +/- 0.09 (f = 3.93 with nu = 0.8765; 4.73 +/- 0.17 +/- 0.16 from 16³, 4.73 to 4.85 with a correction), 1.4 to 2.0 combined errors above the bond-bending f/nu of about 4.3 and far from the 2.1 of central forces on the bcc lattice (Arbabi & Sahimi 1993), and 3 to 8 below the 2-D bond-bending 2.97 (f = 3.96), still rising there. At the thresholds of the first measurements (0.4627; 0.12904 by the energies at 1e-8, where floppy images bore) the same moduli give 2.15 and 5.04, the latter steepening to 6.15 from 24³ as that threshold lay low (f = 2.88 +/- 0.12 +/- 0.23 and 4.58 +/- 0.19 +/- 0.07 then, with 64 and 128 realizations). Boolean discs of 4 pixels of radius (0.608 +/- 0.006, 32² to 256² pixels) give f = 3.20 +/- 0.19 +/- 0.24 and spheres of 3 voxels (0.202 +/- 0.004, 24³ to 48³ voxels) 4.65 +/- 0.59 +/- 0.05 (at 1e-8), those of the sites within the errors: the voxels do not resolve the necks narrower than a voxel. By their thresholds, distinct from those of the connectivity, and the exponents of the widths of the realizations’ thresholds (nu = 1.14 +/- 0.02 in 2-D, 0.76 +/- 0.03 in 3-D), the voxels’ rigidity is a percolation of its own, as for central forces, whose f/nu is in 3-D that of bond bending. At the threshold the contrast 10⁻⁸ raises the mean moduli by 4·10⁻⁵ of those of void (10⁻⁶: 0.4 %, 10⁻⁴: 30 % on 24² pixels, by the FFT solver), the realizations that do not bear taking it times 14 to 58. For instance, the conductivity of Boolean spheres (the inverted Swiss cheese), 3 voxels per radius:

from morphogen.domain import Domain
from morphogen.models import BooleanSpheres

def spheres(fraction, rng, size):
    model = BooleanSpheres(radius=1.0, volume_fraction=fraction)
    domain = Domain(size=size / 3.0, periodic=True)
    return model.generate(domain, seed=rng).voxelize(size)

sizes = [24, 32, 48, 64]
pc = percolation_scaling(spheres, sizes, 0.1, 0.4, connectivity=26, periodic=True,
                         realizations=49, tol=0.002, seed=0)
result = percolation_exponent(spheres, sizes, pc.threshold,
                              threshold_stderr=pc.stderr, seed=1)
class morphogen.analysis.percolation.RigidityThreshold(sizes: ndarray, thresholds: ndarray, brackets: ndarray, threshold: float, stderr: float, amplitude: float, nu: float, nu_stderr: float | None, residuals: ndarray, results: tuple[PercolationThreshold, ...] = (), contrast: float = 0.0, cut: float = 1e-08, floppy: float = nan, rigid: float = nan, solutions: int = 0, decided: int = 0, iterations: int = 0, residual: float = 0.0, bearing: tuple[ndarray, ...] = (), moduli: tuple[ndarray, ...] = (), solver: str = 'fft', unresolved: int = 0, confirmed: int = 0)[source]

Bases: PercolationScaling

Finite-size scaling of the rigidity threshold of a phase, the fraction from which its elastic moduli do not vanish (rigidity_threshold()).

The fields of PercolationScaling, the probabilities of results[k] being the shares of the realizations of the boxes sizes[k] that bear at its fractions; bearing[k][j, i] tells whether realization i bears at the fraction j and moduli[k][j, i] is its modulus over the Young’s modulus of the phase, from the energy of its solution (NaN where the image was decided without the solver); cut is the modulus above which a realization bears, contrast the properties of the other phases over those of the phase (void at 0), floppy the largest modulus solved at or under the cut and rigid the smallest of those that bear (NaN without such solutions; the cut may move between them without changing a decision); solutions is the number of solutions of the solver ("fft" or "fe") and decided that of the images decided without one, unresolved that of the solutions above the cut whose stress average strays from their energy by more than half of it (decided by the round-off of their energies for "fe", by their stress averages for "fft"), confirmed that of the energies that bore under 1000 times the cut, decided again by a solution at the floor of the residual ("fe"), iterations and residual the largest number of iterations and relative residual of the solver.

morphogen.analysis.percolation.rigidity_threshold(generate: Callable[[float, Generator, int], object], sizes, lower: float = 0.0, upper: float = 1.0, *, nu: float | None = None, fit_nu: bool = False, phase: int = 1, axis: str = 'x', cut: float | None = None, contrast: float = 0.0, realizations: int = 9, tol: float = 0.005, solver_tol: float | None = None, maxiter: int | None = None, device: str = 'auto', solver: str = 'fft', seed: int | SeedSequence | Generator | None = None) → RigidityThreshold[source]

Rigidity threshold of a phase of a family of microstructures: the fraction from which its elastic moduli by the FFT solver do not vanish, the other phases void, by the finite-size scaling of the fractions at which half the realizations of boxes of each of the sizes bear.

The trilinear voxels of the FFT solvers (morphogen.homogenization.fft) join through the nodes they share, but a corner is a ball joint and an edge a hinge (in 2-D a corner is a hinge), about which they turn freely; only a face (an edge in 2-D) welds them. The clusters welded by their faces are rigid bodies pinned together at the corners and edges between them, and the moduli of the phase are not zero when these bodies and joints make a rigid network wrapping around the periodic box: from a fraction between the thresholds of percolation through 26 and 6 neighbours (8 and 4 in 2-D), which no connectivity gives (the rigidity percolation of central-force networks, of bodies and joints, whereas the bond-bending forces of lattice models make every connected cluster rigid). A realization bears when its modulus of a uniaxial strain along axis (C_xxxx along x; Young’s modulus 1 and Poisson’s ratio 0.3), the other phases at contrast times the properties of the phase (void at the default 0), exceeds cut; the fraction p½(L) at which half the realizations of the boxes L voxels across bear is bisected as in percolation_threshold() (realizations, tol; common random numbers: for a family growing with the fraction, the median of the fractions from which the realizations bear), each size from a seed of its own derived from seed (the realizations of percolation_scaling() with the same seed, which bear from fractions between those where they join through 26 and 6 neighbours), and the p½(L) are extrapolated as p½(L) = p_c + a * L**(-1/nu) by the fit of percolation_scaling() (nu, fit_nu; by default the exponent of random percolation, 4/3 in 2-D, 0.8765 in 3-D; that of the rigidity percolation of central-force networks is 1.21 +/- 0.06 in 2-D, Jacobs & Thorpe 1996).

The criterion is that of the moduli themselves, from the energy of each solution, the mean of σ : ε, which equals the stress average σ_xx at the exact solution but is stationary: an upper bound whose error is of second order in that of the solution, that of the stress average being of first order. A realization does not bear when its energy is at or under cut; above it, it bears when its stress average agrees with its energy within half of it (the modulus resolved), and otherwise (unresolved) by two more solutions with the element matrices perturbed at their round-off (2.2e-16 of their entries), bearing when the three energies agree within 1 % (solver="fe"), or by its stress average ("fft", whose iterations stop short of the round-off). The floppy images of large boxes need it: their mechanisms take displacements of 1e3 to 7e5 for a unit strain, which the round-off of the element matrices, the same in every voxel, strains, so that their stress averages stray to -1e-10 to -6e-7 at any tolerance and their energies, 1e-20 to 2e-7, scatter by 17 to 50 % when the element matrices are perturbed, while those of the images that bear move by 1.4e-3 at most and agree with their stress averages within 30 %. The criterion wants solutions that have resolved the soft modes of the floppy images: the voxels factorized iterate to solver_tol, by default 1e-10, and an energy that bears under 1000 times the cut is decided again by a solution at 1e-11, near the floor of the residual (confirmed). At 1e-8 one to three iterations leave floppy images at energies of 1e-13 to 2e-8 whose stress averages agree with them: 23 of 32 realizations of 32³ to 80³ voxels of the sites of the cubic lattice bore from fractions lower by 0.0003 to 0.003 than at 1e-10, where such energies fall to 1e-21 to 1e-14; at 1e-10 a few keep 1e-12 to 3e-11, their stress averages and perturbations agreeing (the iterates, not the mechanisms, carry them), and fall under the cut at 1e-11 or take stress averages of the opposite sign, while a modulus of 2.0e-12 on 64³ voxels stays to three digits. Void around, the moduli of the realizations that bear then spread down to 1.2e-12 without a gap (77 of the 5,308 solutions that bear on 8³ to 80³ voxels of the sites near their thresholds lie between 1e-12 and 1e-10). The cut is the round-off of the moduli of the solver, by default (CUTS) 1e-8 for the FFT solver and 1e-12 for the voxels factorized, whose energies resolve the moduli down to it; p½(L) lies where the moduli of half the realizations exceed it, and a cut too high biases it up as the moduli come down with the box. With a contrast δ the realizations that do not bear take δ times an enhancement that rises steeply as they approach their own rigidity (up to 650 on 32² pixels and 4,400 on 64² for the sites of the square lattice), while those that have just become rigid bear as little as 2e-6 (32²): a cut that is a multiple of δ must exceed the one and stay below the other, which δ = 1e-8 (the default of percolation_exponent()) does not allow; cut must exceed contrast. The median of the realizations’ fractions is robust where the moduli spread over decades and needs no exponent, where the crossing of the curves L^(f/nu) <C(p)> presupposes f, the exponent sought, from means that scatter by tens of percent.

The images are decided without the solver when they can be: the phase does not bear when none of its components wraps around the box along the axis through 26 neighbours (8 in 2-D: they translate freely), it bears when a component joined by faces (6; 4 in 2-D) wraps (a rigid body), and, the moduli growing with the stiffness of the voxels, an image that contains an image of the same realization that bears bears and one contained in an image that does not does not (the images of a family growing with the fraction). The others are solved by conjugate gradients of tolerance solver_tol (by default SOLVER_TOLS: 1e-8 for the FFT solver, 1e-10 for the voxels factorized) and at most maxiter iterations (by default 50 L + 1000, L the largest dimension: near the threshold the solutions of the FFT solver take up to 45 L, more than its 20 L + 1000), by the FFT solver on device (solver="fft"; "cpu", "gpu" or "auto") or (solver="fe") by the same trilinear voxels assembled on those of the phase and preconditioned by the sparse factorization of their matrix, on the CPU (morphogen.homogenization.voxel_fe): the same moduli, to the tolerance, in one to three iterations, where the Fourier preconditioner of a homogeneous medium spreads the displacements of the voxels over the void around them and the clusters pinned at their corners turn about them with a vanishing energy, on the voxels that bear alone (load_bearing(): the same moduli, 15 to 25 % fewer voxels). For a family whose phase grows with the fraction (shrinks), the bounds are tried last and only when the bracket reaches them: the images far above the threshold cost most to factorize (on 48³ voxels of sites 122 s at 0.2096 against 1.5 s at 0.1307). The result counts the solutions, the images decided and the energies unresolved, gives the largest modulus solved under the cut (floppy) and the smallest of those that bear (rigid), and the shares, decisions and moduli of the fractions tried.

For the sites of the square lattice (400 realizations of 16² to 128² pixels and 300 of 192² and 256², each bisected to its own threshold, its images nested, solver="fe", the cut 1e-12 and the tolerance 1e-10), p½(L) = 0.4397, 0.4564, 0.4547, 0.4559, 0.4595, 0.4611, 0.4614, 0.4617 and 0.4612, flat from 96² on, extrapolate to p_c = 0.4617 +/- 0.0004 with the exponent of the fit free (1.5 +/- 0.2: nu 4/3 does not fit them, a chi-square of 34 for 7 degrees of freedom), and the widths of the realizations’ thresholds fall as L**(-1/nu) with nu = 1.14 +/- 0.02 (central-force rigidity percolation in 2-D: 1.21 +/- 0.06, Jacobs & Thorpe 1996), the share that bears at p_c staying at about one half from 96² on; a quarter of the way from the threshold through 8 neighbours, 0.4073, to that through 4, 0.5927. The first measurement, 96 realizations bisected to 0.0035 by the stress averages at the cut 1e-8, gave 0.4627 +/- 0.0016 (32 realizations by the FFT solver: 0.4647 +/- 0.0056, the decisions the same). For the sites of the cubic lattice (1,725 realizations of 8³ to 80³ voxels, each bisected to its own threshold, at the tolerance 1e-10 with the confirmations), p½(L) = 0.1356, 0.1338, 0.1332, 0.1316, 0.1321, 0.1314, 0.1313, 0.1309 and 0.1308 extrapolate to p_c = 0.1304 +/- 0.0002 (nu 0.8765; 0.1300 +/- 0.0003 from 32³, the means 0.1303 +/- 0.0001; the shares of 48³ to 80³ voxels cross at 0.1302, a third of the realizations bearing at p_c whatever the box; the widths give nu = 0.76 +/- 0.03), between the thresholds through 26 and 18 neighbours, 0.0975 and 0.1383, far below that through the faces, 0.3116: the corners alone hold the voxels. At the tolerance 1e-8, where floppy images bear, the first measurement (192 realizations of 8³ to 48³ voxels) gave 0.12904 +/- 0.00029, and 0.1307 +/- 0.0009 by the stress averages of 96 realizations of 8³ to 32³. Boolean discs of 4 pixels of radius and spheres of 3 voxels (64 realizations, 32² to 256² pixels and 24³ to 48³ voxels) bear from 0.608 +/- 0.006 and 0.202 +/- 0.004, between their thresholds through 8 and 4 neighbours (0.596 and 0.624) and through 26 and 6 (0.182 and 0.236), their p½(L) near those through the corners: their grains meet at several nodes, which brace them, where the sites meet at one. With percolation_exponent():

def squares(fraction, rng, size):
    return rng.random((size, size, 1)) < fraction

sizes = [16, 24, 32, 48, 64, 96, 128, 192, 256]
rigid = rigidity_threshold(squares, sizes, 0.38, 0.58, realizations=96, tol=0.0035,
                           solver="fe", seed=2026)
result = percolation_exponent(squares, sizes, rigid.threshold,
                              threshold_stderr=rigid.stderr, physics="elastic",
                              contrast=0.0, realizations=64, solver="fe", seed=2027)

(the measurements above bisected each realization to its own threshold instead, the images nested, by these decisions).