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:
objectForest fire lit on a face of an image (
burn()).percolatestells whether the fire reaches the opposite face, at the steptime(the chemical distance between the faces;Nonewhen it does not);front[t]is the number of voxels that catch fire at stept, 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), elseNone.
- 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
phaseof a 3-D image alongaxis(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 theconnectivityneighbours (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 steptime: the chemical distance between the faces, the number of steps of the shortest path through the phase (n - 1for a straight channelnvoxels long). The breadth-first burning, compiled, queues each voxel once and stops at the end of that step, unlessfullasks for the whole clusters lit on the face and their burning times; it costs the voxels burnt, whereconnected_components()labels the whole image, and decides as its flagspercolatingon open boundaries. A planar image (one voxel along z) burns in its plane, along x or y, through 4 (connectivity4 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:
objectEstimate of a percolation threshold.
thresholdis the middle ofbracket, the last interval of fractions at whose ends the percolation probability lies on either side of 1/2;fractionsare the fractions tried, in increasing order, andprobabilitiesthe fractions of therealizationsimages 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
phaseofgenerate(fraction, rng)percolates crosses 1/2.generatereturns a 3-D image (aVoxelImage, 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 ofrealizationsimages that percolate; realizationigets a generator built from the same seed at every fraction (common random numbers), independent of the other realizations and reproducible fromseed(an integer, a seed sequence, a generator, orNonefor fresh entropy), so that a family growing with the fraction for a given stream, such asrng.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 atloweranduppermust 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 thantoland the threshold is its middle. The estimate carries the finite-size shift of the criterion and the spread of the realizations’ thresholds, both of orderL**(-1/nu)(nuabout 0.88 in 3-D, 4/3 in 2-D) for imagesLvoxels across, the spread divided by the square root ofrealizations.The phase percolates along
axis("x","y","z","any"or"all"of them; x and y in 2-D) through itsconnectivityneighbours (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 inconnected_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 ofburn(), 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:
objectFinite-size scaling of a percolation threshold (
percolation_scaling()).thresholds[k]is the threshold of the boxessizes[k]voxels across, the middle ofbrackets[k](results[k]: itsPercolationThreshold);thresholdis that of the infinite medium, extrapolated by the fitthresholds = threshold + amplitude * sizes**(-1/nu), with the standard errorstderr;nuis the exponent given or, with its standard errornu_stderr(elseNone), fitted;residualsare 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 thesizesL,generate(fraction, rng, size)returning an imagesizevoxels 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 atp½(L) = p_c + a * L**(-1/nu), the amplitudeaset 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 aboutsqrt(pi/2) = 1.25times their spread oversqrt(realizations), so that the shift and the scatter both shrink asL**(-1/nu), the scatter also as1/sqrt(realizations).p_canda(andnu, from the value given, withfit_nu) are fitted by least squares weighted byL**(2/nu), the inverse variance of p½; the variance ofp_cadds that of the fit, from its residuals, and that of the bisection, each p½ uniform in its bracket (variancewidth**2 / 12). The extrapolation removes the shift but amplifies the scatter (the intercept of a line through points scattered as their abscissaeL**(-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 bystderr); those normal to one axis are joined at p_c + 0.0036, extrapolated within 0.0020 by 49 realizations. Four such sizes leavenuundetermined (1.0 +/- 1 withfit_nu) andp_cthen within 0.01 to 0.03 only.nuis by default the exponent of random percolation,0.8765in 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) and4/3in 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 findinganear 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 (aabout 0.36, the largest 0.006 above p_c), within 0.002. Thesizesare at least 3 distinct positive integers (4 withfit_nu), each bisected betweenlowerandupperwith the criterion (phase,axis,connectivity,periodic,method), therealizationsand thetolofpercolation_threshold(), from a seed of its own derived fromseedand 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()withsized=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().configis a file, a mapping or aRunConfig(validated byload_config(), withbase_dir) whosemodel,domainandvoxelssections are used:generate(fraction, rng)draws fromrnga realization of the model whose parameterparameterisfraction, in the domain, and voxelizes it on the grid of the configuration, asmorphogen.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), forpercolation_scaling(), voxelizes the realization in a boxsizevoxels 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,sizevoxels 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
phaseof an image alongdirection(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 withinRof the axis through the centre of the box along the direction and withinRof the centre along it,2 Rlong and across,R = D / (2 sqrt 2)for the diameterDof 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 ofburn(); the cap is the plane normal to the direction at-R), the fire spreads through theconnectivityneighbours inside the core, and the phase percolates along the direction when it reaches those of the upper cap, at the steptime, the chemical distance across the core (Fireasburn();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 2of its smallest edge (half of a square, 0.28 of a cube); it has the aspect of a cube (a square), whose facesburn()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, makestimea tortuosity (directional_percolation()).
- class morphogen.analysis.percolation.DirectionalPercolation(directions: ndarray, percolates: ndarray, distances: ndarray, straight: ndarray, tortuosity: ndarray)[source]¶
Bases:
objectPercolation of a phase of one image along directions (
directional_percolation()).directionsare unit vectors (rows; no z component in 2-D),percolateswhether the fire crosses the core of the image along each,distancesits chemical distance across (-1: it does not) andstraightthat across the full core,tortuositythe 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
phaseof one image along each ofdirections: the fire ofburn_along()across the core of the image along each, a direction and its opposite alike.directionsare"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 offabric_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
connectivityneighbours, 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: asgeometric_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:
objectPercolation thresholds of a family along directions (
percolation_anisotropy()).samples[i, k]is the threshold of realizationialongdirections[k](unit vectors, rows; no z component in 2-D), the middle of a bracket narrower than the tolerance (infor-inf: beyond the bounds);thresholdstheir medians, with the standard errorsstderr;deviationsthe medians of the differences of the realizations’ thresholds from their means over the directions, with the standard errorsdeviation_stderr;ratiothe median of the ratios of their thresholds along the directions of the largest and the smallest deviation, withratio_stderr(infwhen a threshold lies beyond the bounds);tensorthe threshold tensor (3 x 3, nothing along z in 2-D), itseigenvalues(increasing; 2 in 2-D) witheigenvalue_stderrand itsprincipaldirections (rows),residualsthe 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
phaseofgenerate(fraction, rng)(as forpercolation_threshold()) percolates along each ofdirections(as fordirectional_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 thantol(for a family growing with the fraction, the fraction from which it crosses;infor-infbeyondlowerandupper: 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 ofpercolation_threshold(): the lower median for an even number, of a family growing with the fraction), with the standard errorssqrt(pi/2) s / sqrt(N)from the standard deviationsof theNrealizations’ (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 tensorTis the symmetric tensor whose quadratic formp(n) = n . T . nfits 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
Lacross 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: thresholdsinfacross 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:
objectCritical exponent of an effective property at a percolation threshold (
percolation_exponent()).exponentis that of the property (physics:"thermal", the conductivity along the axis, t;"elastic", the modulus of a uniaxial strain along it, f),nutimesratio, the slope of-ln <P>againstln Lfitted to themeans(standard errorsmean_stderr) of the realizations of thesizesat thethreshold:means = amplitude * sizes**(-ratio),residualsthe logarithms of the means less the fit;stderris its statistical standard error andthreshold_errorhalf its change between the threshold less and plusthreshold_stderr(0 without).fractionsare those computed (increasing: the threshold, the two shifted by its standard error, those of thesweep),values[k, j]the mean property of the boxessizes[k]atfractions[j]with the standard errorsvalue_stderr, andsamples[k, i, j]that of realizationi;sweep_exponents[k]is the exponent fitted to the means of sizekagainstfraction - thresholdover thesweep, withsweep_stderrandsweep_threshold_error(empty without a sweep).iterationsandresidualare the largest number of iterations and relative residual of thesolver.
- 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
phasevanishes 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 asL**(-t/nu)(L**(-f/nu); Derrida & Vannimenus 1982, Stauffer & Aharony 1994).generate(fraction, rng, size)returns an imagesizevoxels per edge (one voxel along z for a planar one), as forpercolation_scaling()(family_from_config()withsized=Truefor the model of a configuration); for each of thesizes(at least 3), therealizationsare drawn at thethreshold, each from a seed of its own derived fromseed, 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 havecontrasttimes its properties (void at 0). The periodic FFT solver (morphogen.homogenization.fft;device:"cpu","gpu"or"auto", the GPU when there is one;tolandmaxiterof its conjugate gradients,tolby default 1e-8, and 1e-10 for the voxels factorized (SOLVER_TOLS),maxiterby 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 alongaxis(physics="thermal") or the modulus of a uniaxial strain along it,C_xxxxalong 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, seerigidity_threshold()). The logarithms of the means are fitted againstln Lby least squares weighted by their inverse variances (the standard errors of the means over their values), the slope timesnubeing the exponent:nuis 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 athreshold_stderr, the realizations are also computed at the threshold less and plus it (the same images: common random numbers) andthreshold_erroris 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_cneeds 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_exponentsare the slopes ofln <P>againstln(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()withconnectivity=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 thatrigidity_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 aboutcontrast * (L / l)**((t + s)/nu)of itself at p_c (Efros & Shklovskii 1976, Straley 1976;lthe 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 withincontrast**(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 (byrigidity_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:
PercolationScalingFinite-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 ofresults[k]being the shares of the realizations of the boxessizes[k]that bear at its fractions;bearing[k][j, i]tells whether realizationibears at the fractionjandmoduli[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);cutis the modulus above which a realization bears,contrastthe properties of the other phases over those of the phase (void at 0),floppythe largest modulus solved at or under the cut andrigidthe smallest of those that bear (NaN without such solutions; the cut may move between them without changing a decision);solutionsis the number of solutions of thesolver("fft"or"fe") anddecidedthat of the images decided without one,unresolvedthat 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"),confirmedthat of the energies that bore under 1000 times the cut, decided again by a solution at the floor of the residual ("fe"),iterationsandresidualthe 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
sizesbear.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 alongaxis(C_xxxx along x; Young’s modulus 1 and Poisson’s ratio 0.3), the other phases atcontrasttimes the properties of the phase (void at the default 0), exceedscut; the fraction p½(L) at which half the realizations of the boxes L voxels across bear is bisected as inpercolation_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 fromseed(the realizations ofpercolation_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 asp½(L) = p_c + a * L**(-1/nu)by the fit ofpercolation_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 tosolver_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 ofpercolation_exponent()) does not allow;cutmust exceedcontrast. 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 defaultSOLVER_TOLS: 1e-8 for the FFT solver, 1e-10 for the voxels factorized) and at mostmaxiteriterations (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 ondevice(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 thesolutions, the imagesdecidedand the energiesunresolved, 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:nu4/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 (nu0.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. Withpercolation_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).