morphogen.rve.scaling

Statistical size of the representative volume element (RVE).

Following Matheron (1971), Kanit et al. (2003) and Lantuéjoul (1991), the ensemble variance of the average of a property Z over a volume V scales as

D_Z^2(V) = D_Z^2 (A3 / V) (finite integral range A3) D_Z^2(V) = K V^(-gamma) (general power law, K = D_Z^2 A3*^gamma)

With n realizations of volume V, the relative error on the mean is eps_rel = 2 D_Z(V) / (Zbar sqrt(n)), hence the RVE volume

V_RVE = (4 K / (eps_rel^2 Zbar^2 n))^(1 / gamma).

“Volumes” may equally be lengths or areas (1D/2D samples, e.g. Bironeau et al. 2016), the edge of a sample then V^(1/d) in dimension d (the side of a square of area V).

Shifted tilings (the window method on a periodic image, shifts > 1). The T tilings of the windows of edge w shifted by the offsets k w // shifts along each axis are translates of the first on the torus: by stationarity the windows of each have the joint law of the unshifted ones, and its variance the law of theirs. The mean over all the windows of all the tilings is the mean of the tiling means, each the image mean when the edges of the image are multiples of w. D^2(V) is the variance pooled within the tilings, sum_t sum_(k in t) (Z_k - Zbar_t)^2 / sum_t (n_t - 1), with n_t = n windows in each the mean of their unbiased variances: of the expectation of the variance of one tiling (unbiased under the hypothesis that makes that one unbiased, its windows uncorrelated as for V >> A3), of a smaller scatter. Not the variance of the T n windows about their mean with T n - 1 degrees of freedom, lower by the factor T (n - 1) / (T n - 1): the windows of different tilings overlap, so that their mean (the image mean) is known no better than from one tiling, the deviations of each tiling summing to zero. The count behind the uncertainties stays n, the windows of one tiling (the independent ones): the shifts leave the mean unchanged, whose standard error stays D(V) / sqrt(n); the relative errors, the Student tests of the components of the tensors and the weights (n - 1) / 2 of the fits count n too, conservatively for the variance, to which the overlapping windows add correlated, not independent, samples. The fits and the RVE sizes follow from these variances, unchanged.

morphogen.rve.scaling.point_variance(fraction: float, z1: float = 1.0, z0: float = 0.0) → float[source]

D_Z^2 = p (1 - p) (Z1 - Z0)^2 of a two-phase medium (p: fraction of phase 1).

morphogen.rve.scaling.point_variance_multiphase(fractions, values) → float[source]

D_Z^2 = sum_i P_i (Z_i - Zbar)^2 (Yang et al. 2019, eq. 19).

class morphogen.rve.scaling.SizeStatistics(volume: ndarray, n: ndarray, mean: ndarray, variance: ndarray, dimension: int = 3, tilings: ndarray | None = None)[source]

Bases: object

Ensemble statistics of a property for several sample sizes.

dimension: that of the samples, whose measures the volumes are (3, cubes; 2, the squares of a planar image, their areas), their edges V^(1/dimension) (edges()). tilings: the number of shifted tilings of each size by the window method (window_statistics()), n then the windows of one tiling and variance their variance pooled within the tilings (see the module); None: one tiling, or realizations.

edges() → ndarray[source]

The edges of the samples, V^(1/dimension): of cubes, of squares.

relative_error() → ndarray[source]

eps_rel = 2 sqrt(D^2(V) / n) / |Zbar| for each size.

rows() → list[dict][source]

One row per size: its volume, its count n (and its tilings when shifted), the mean, the variance and the relative error.

morphogen.rve.scaling.ensemble_statistics(volumes, values) → SizeStatistics[source]

Group values by volume: mean and unbiased variance per size.

class morphogen.rve.scaling.ScalingLaw(K: float, gamma: float, gamma_fixed: bool = False, r2: float = nan, n_points: int = 0, volume_min: float = nan, volume_max: float = nan, gamma_se: float = nan, log_k_se: float = nan)[source]

Bases: object

D_Z^2(V) = K V^(-gamma), fitted in log-log coordinates.

gamma_se: float = nan

standard errors of gamma (free fits with at least 3 sizes) and of ln K

gamma_interval(level: float = 0.95) → tuple[float, float][source]

Confidence interval of gamma (Student t, from the scatter about the fit).

k_interval(level: float = 0.95) → tuple[float, float][source]

Confidence interval of K.

variance(volume) → ndarray[source]
relative_error(volume, n, mean) → ndarray[source]
rve_volume(eps_rel, mean: float, n=1) → ndarray[source]

Volume for which n realizations give the mean within eps_rel (relative).

realizations(volume, eps_rel, mean: float) → ndarray[source]

Number of realizations of the given volume needed for eps_rel.

integral_range(point_var: float) → float[source]

A3* = (K / D_Z^2)^(1/gamma) (the integral range A3 when gamma = 1).

to_dict() → dict[source]
morphogen.rve.scaling.fit_scaling_law(volumes, variances, *, gamma: float | None = None, volume_range=None, weights=None) → ScalingLaw[source]

Least-squares fit of log D^2 = log K - gamma log V (gamma free or imposed).

morphogen.rve.scaling.fit_statistics(stats: SizeStatistics, *, gamma=None, volume_range=None) → ScalingLaw[source]

The scaling law of the variance with the volume (fit_scaling_law()) fitted to the statistics of a study by size, gamma given or fitted, within volume_range.

morphogen.rve.scaling.rve_volume_classic(point_var, integral_range, eps_rel, mean, n=1) → float[source]

V_RVE = 4 D_Z^2 A3 / (eps^2 Zbar^2 n) (Kanit et al. 2003).

morphogen.rve.scaling.window_statistics(image, window_sizes, *, phase: int | None = 1, spacing=None, shifts: int = 1, periodic=None)[source]

Window method: statistics of the mean over non-overlapping cubic sub-volumes.

window_sizes are window edges in voxels. With phase the averaged quantity is the indicator of that phase (volume fraction); with phase=None the image values themselves (e.g. a local field computed by an FFT or FE solver). Across a planar image (nz = 1) the windows are squares of w pixels, whose measure is their area (dimension = 2, their edges the roots of their areas). shifts: the tilings per axis, 1 (by default) the tiling from the origin of the image, the remainder left out; shifts > 1 adds the tilings shifted by the offsets k w // shifts voxels (k < shifts) along each axis that the windows tile, all their combinations (shifts^3 tilings of cubes, shifts^2 of squares, fewer for windows of fewer voxels), wrapping around the periodic image (periodic: None, that of a VoxelImage; an array is not): the mean of all their windows, their variance pooled within the tilings, n the windows of one tiling and tilings their number (see the module). The tensors of the windows: morphogen.rve.windows.window_tensors().

morphogen.rve.scaling.rve_table(law: ScalingLaw, mean: float, eps_rel=(0.01, 0.05), n=(1, 10), *, dimension: int = 3) → list[dict][source]

RVE volume and edge for each pair (eps_rel, n): the edge of a cube, V^(1/3), or of a square of area V (dimension = 2), V^(1/2).