morphogen.rve.study

Statistical RVE analysis of apparent properties (Dirrenberger et al. 2014, sec. 4-5).

A series gathers the realizations of one property under one boundary condition, at several volumes. For every series the analysis gives:

  • the number of realizations, the mean and the standard deviation D_Z(V) per volume, with the intervals [Zbar - 2 D_Z, Zbar + 2 D_Z] (Tables 3-4);

  • the relative error of the sample, eps_rel = 2 D_Z(V) / (Zbar sqrt(n)) (Table 8);

  • the fit of D_Z^2(V) = K V^-gamma with gamma free (Table 9), and with gamma imposed when requested, e.g. the theoretical 2/3 of Poisson fibres (Table 10);

  • the RVE volume V_RVE = (4 K / (eps^2 Zbar^2 n))^(1/gamma) (eq. 87) for each pair (eps_rel, n), its edge, the mean number of objects it contains (fibres, grains…) when the model provides it, and bootstrap confidence intervals;

  • the number of realizations of each sampled volume needed for each precision;

  • the statistical isotropy criterion of the mean response per volume (eqs. 72-74).

Across boundary conditions it gives the discrepancy D(Z) = (Zmax - Zmin) / Zmin between their mean values (eq. 69) and, when the phases are known, the bounds. Zbar in the RVE formula is the mean at the largest volume, as in the paper.

Stiffness and compliance (TensorStatistics). When the realizations have their apparent stiffness C (the columns stiffness.<bc>.C11 … C66 of the results), each boundary condition gets, per volume, the mean stiffness Cbar over the realizations and the standard deviation of each of its components, and the compliance S = Cbar^-1: the inverse of the mean stiffness, so that S Cbar = I, not the mean of the compliances of the realizations <C^-1> (kept as mean_compliance; larger, <C^-1> >= <C>^-1 by Jensen’s inequality, by a term of the order of the relative variance; under SUBC its inverse is Huet’s lower estimate), with the standard deviation of each component of the compliances C^-1 of the realizations. Each component of C and of the compliances is also analysed as a series (variance fit, RVE sizes, no bootstrap), the RVE sizes kept for the diagonal components and those whose mean the realizations of the largest volume distinguish from zero (Student’s t test at the level of the study): the couplings that vanish on average have no relative precision. Notation: morphoGen’s Voigt order 11, 22, 33, 23, 31, 12 with engineering shears (morphogen.homogenization.postprocess.NOTATION). The conductivity tensor (the columns conductivity_tensor.<bc>.C11 … C33) has the same statistics, its inverse the resistivity (CONDUCTIVITY_NOTATION), and so has the tensor of every other transport phenomenon (TRANSPORT_TENSORS: electrical_conductivity_tensor, permittivity_tensor, permeability_tensor, diffusivity_tensor). By the window method (morphogen.rve.windows) the windows of one realization are the realizations; with tilings shifted around the periodic realization, those of all the tilings, their means over all, their variances pooled within the tilings and their counts those of one tiling (morphogen.rve.scaling). The squares of a planar image have areas for volumes, and for edges their roots (dimension 2).

class morphogen.rve.study.Series(property: str, bc: str, volume: ndarray, value: ndarray, response: ndarray | None = None)[source]

Bases: object

Realizations of a property (under one boundary condition) at several volumes.

response optionally holds the macroscopic response of every realization: the 3 x 3 average stress (or strain under SUBC), or the average flux vector; it is used for the isotropy criteria.

property key: str
statistics() → SizeStatistics[source]
mean_response(volume: float) → ndarray | None[source]
morphogen.rve.study.series_from_rows(rows: list[dict], *, properties=None, group_by: str | None = None, volume_column='volume') → list[Series][source]

Series of a results table.

  • Long format (columns property and value, e.g. homogenization.csv): one series per (property, bc or group_by column). Rows without a value (the summaries of the loading paths) are left out.

  • Wide format: one column per property. Columns named <property>.<bc> (e.g. bulk_modulus.kubc) give one series per boundary condition; with group_by the rows are split by the values of that column instead.

class morphogen.rve.study.SeriesAnalysis(series: ~morphogen.rve.study.Series, stats: ~morphogen.rve.scaling.SizeStatistics, reference_mean: float, free_fit: ~morphogen.rve.scaling.ScalingLaw | None, fit: ~morphogen.rve.scaling.ScalingLaw | None, rve: list[dict], needed: list[dict], isotropy: ~numpy.ndarray | None, bootstrap: dict | None = None, point_variance: float | None = None, integral_range: float | None = None, theory: dict = <factory>)[source]

Bases: object

Results of the analysis of one series (see the module documentation).

property key: str
statistics_rows() → list[dict][source]

The statistics of each volume (SizeStatistics.rows()), with its edge (of a cube, or of the square of a planar image), the standard deviation and the interval Zbar +/- 2 D.

to_dict() → dict[source]
class morphogen.rve.study.StudyOptions(gamma: float | None = None, min_volume: float | None = None, max_volume: float | None = None, relative_errors: tuple = (0.01, 0.05), n_realizations: tuple = (1, 10), bootstrap: int = 1000, seed: int = 0, weights: str = 'none', level: float = 0.95)[source]

Bases: object

Settings of the analysis.

gamma: exponent imposed for the RVE sizes (None: the fitted one). min_volume and max_volume restrict the fits (the paper keeps V >= 40^3 to avoid boundary layer effects). weights="n" weights each size by (n - 1) / 2, the inverse variance of ln D^2 for Gaussian data. bootstrap replicates (0: none).

morphogen.rve.study.analyze_series(series: Series, options: StudyOptions | None = None, *, count: Callable[[float], float] | None = None, theory: dict | None = None) → SeriesAnalysis[source]

Analysis of one series (statistics, fits, RVE sizes, isotropy, bootstrap).

morphogen.rve.study.analyze_statistics(stats: SizeStatistics, prop: str = 'volume_fraction', options: StudyOptions | None = None, *, theory: dict | None = None) → SeriesAnalysis[source]

Analysis of precomputed statistics (e.g. the window method; no bootstrap).

morphogen.rve.study.discrepancy(analyses: list[SeriesAnalysis]) → dict[str, list[dict]][source]

D(Z) = (Zmax - Zmin) / Zmin between boundary conditions, per volume (eq. 69).

morphogen.rve.study.TRANSPORT_TENSORS = {'conductivity_tensor': 'thermal', 'diffusivity_tensor': 'diffusion', 'electrical_conductivity_tensor': 'electrical', 'permeability_tensor': 'magnetic', 'permittivity_tensor': 'dielectric'}

The tensors of the transport phenomena (3 x 3, in the axes 1 2 3) and their physics: the conductivity, and those of electrical conduction, dielectrics, magnetostatics and diffusion

morphogen.rve.study.TENSOR_PROPERTIES = ('stiffness', 'conductivity_tensor', 'electrical_conductivity_tensor', 'permittivity_tensor', 'permeability_tensor', 'diffusivity_tensor')

the stiffness and its compliance, the conductivity and its resistivity (the tensor of each transport phenomenon and its inverse)

Type:

The tensors of the results whose mean a study gives per volume, with its inverse

morphogen.rve.study.CONDUCTIVITY_NOTATION = 'the matrix K_ij of the flux q_i = -K_ij dT/dx_j, i, j = 1 2 3 the axes (C_ij in the columns); S = K^-1, the resistivity, in the same notation'

The notation of a conductivity tensor and of its inverse in the studies (the components C11 … C33 of the columns of results)

morphogen.rve.study.TENSOR_DEFINITIONS = {'compliance': 'S = Cbar^-1, the inverse of the mean stiffness (S Cbar = I), not the mean of the compliances of the realizations (mean_compliance)', 'compliance_std': 'the standard deviation of each component of the compliances C^-1 of the realizations', 'mean_compliance': '<C^-1>, the mean of the compliances of the realizations (>= Cbar^-1)', 'stiffness': 'Cbar, the mean of the apparent stiffnesses C of the realizations', 'stiffness_std': 'the standard deviation of each component of C over the realizations'}

What the matrices of TensorStatistics.to_dict() are, for the stiffnesses of an ensemble study (to_dict states those of the windows and of the conductivities)

morphogen.rve.study.TENSOR_WORDS = {'conductivity_tensor': ('conductivity', 'conductivities', 'resistivity', 'resistivities'), 'diffusivity_tensor': ('diffusivity', 'diffusivities', 'inverse diffusivity', 'inverse diffusivities'), 'electrical_conductivity_tensor': ('electrical conductivity', 'electrical conductivities', 'electrical resistivity', 'electrical resistivities'), 'permeability_tensor': ('permeability', 'permeabilities', 'reluctivity', 'reluctivities'), 'permittivity_tensor': ('permittivity', 'permittivities', 'dielectric impermeability', 'dielectric impermeabilities'), 'stiffness': ('stiffness', 'stiffnesses', 'compliance', 'compliances')}

The names of a tensor and of its inverse, singular and plural

morphogen.rve.study.tensor_notation(prop: str, tensor) → str[source]

The notation of a tensor prop of the studies and of its inverse: of a stiffness (morphogen.homogenization.postprocess.notation(): Voigt order 11 22 33 23 31 12, engineering shears; 11 22 12 for a 3 x 3 one), of a conductivity (CONDUCTIVITY_NOTATION) or of the tensor of another transport phenomenon (the same, of its flux and potential).

morphogen.rve.study.is_tensor(name: str) → bool[source]

Whether a property asked of a study names a tensor (TENSOR_PROPERTIES): stiffness or stiffness.<bc> (conductivity_tensor, conductivity_tensor.<bc>), whereas stiffness.<bc>.C44 is the series of one of its components.

class morphogen.rve.study.TensorStatistics(property: str, bc: str, volume: ndarray, n: ndarray, mean: ndarray, std: ndarray, compliance: ndarray, compliance_std: ndarray, mean_compliance: ndarray, components: dict[str, ~morphogen.rve.study.SeriesAnalysis]=<factory>, level: float = 0.95, method: str = 'ensemble', dimension: int = 3, tilings: ndarray | None = None)[source]

Bases: object

The mean stiffness and compliance per volume of the realizations of one boundary condition (see the module documentation), or of the windows of one realization (method="windows", morphogen.rve.windows); the conductivity and its resistivity likewise (property="conductivity_tensor").

Per volume (volume, sorted, with n realizations): mean the mean stiffness Cbar and std the standard deviation of each of its components (NaN for a single realization); compliance the inverse of the mean stiffness, S = Cbar^-1 (compliance @ mean = I); compliance_std the standard deviation of the components of the compliances C^-1 of the realizations and mean_compliance their mean <C^-1>. Arrays (m, 6, 6) ((m, 3, 3) in the plane) in morphoGen’s Voigt order 11 22 33 23 31 12 with engineering shears (notation; a conductivity (m, 3, 3) in the axes 1 2 3). components: the analysis of each component of the stiffnesses (C11 … C66) and of the compliances (S11 … S66) of the realizations as a series, with RVE sizes for the diagonal ones and those that the realizations distinguish from zero (significant()). dimension: that of the samples (3, cubes; 2, the squares of a planar image, the volumes their areas), their edges V^(1/dimension) (edges()). tilings: by the window method with shifted tilings, the number of tilings of each size, n then the windows of one tiling (the independent ones), the means those of all the windows, the standard deviations the roots of their variances pooled within the tilings (morphogen.rve.scaling); None: one tiling.

property key: str
edges() → ndarray[source]

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

property notation: str

The notation of the tensor and of its inverse (tensor_notation(): morphogen.homogenization.postprocess.NOTATION for a stiffness).

property samples: str

realizations or windows.

Type:

What its statistics are over

static index(name: str) → tuple[int, int][source]

The row and column of a component (C44, S44: (3, 3)).

significant(name: str) → bool[source]

Whether the mean of a component is distinguished from zero: always for the diagonal (positive, the stiffness and the compliance being positive definite); for the others, by the realizations of the largest volume that has several, Student’s t test at the level of the study (|Zbar| sqrt(n) / D above the quantile of n - 1 degrees of freedom), and with a single realization per volume, whether it is a component of an orthotropic stiffness in its axes (a conductivity in its axes has none). The couplings that vanish on average have no relative precision, hence no RVE size.

volume_rows() → list[dict][source]

One row per volume: its edge (of a cube, or of a square), its realizations (windows, and their tilings when shifted), the components of Cbar, of S = Cbar^-1 and their standard deviations (C11_std …), the rows of rve_<property>.csv.

to_dict() → dict[source]
morphogen.rve.study.tensor_statistics(volumes, tensors, prop: str = 'stiffness', bc: str = '', options: StudyOptions | None = None) → TensorStatistics[source]

The mean stiffness and compliance per volume of realizations (TensorStatistics): tensors their apparent stiffnesses (k x 6 x 6, or k x 3 x 3 in the plane; Voigt order 11 22 33 23 31 12, engineering shears; or their conductivities, k x 3 x 3, prop="conductivity_tensor") at their volumes; options those of the study (gamma, range of the fits, precisions), its components analysed without bootstrap.

morphogen.rve.study.tensors_from_rows(rows: list[dict], *, properties=None, volume_column: str = 'volume', options: StudyOptions | None = None) → list[TensorStatistics][source]

The mean stiffness and compliance per volume (tensor_statistics()) of each boundary condition whose stiffness the rows of results hold, in the columns stiffness.<bc>.C11 … C66 of the runs (the upper triangle; C11 … C33 in the plane). properties: the tensors kept, stiffness or stiffness.<bc> (None: all).

class morphogen.rve.study.StudyReport(analyses: list[~morphogen.rve.study.SeriesAnalysis], discrepancy: dict[str, list[dict]], options: ~morphogen.rve.study.StudyOptions, bounds: dict = <factory>, method: str = 'ensemble', tensors: list[~morphogen.rve.study.TensorStatistics] = <factory>)[source]

Bases: object

Analyses of all the series of a study, with cross-series results, and the mean stiffness and compliance per volume of each boundary condition (tensors).

property dimension: int

3 (cubes), or 2 (the squares of a planar image, the volumes their areas).

Type:

That of its samples, whose edges the tables print

to_dict() → dict[source]
morphogen.rve.study.analyze_study(series: list[Series], options: StudyOptions | None = None, *, count: Callable[[float], float] | None = None, bounds: dict | None = None, theory: dict | None = None, method: str = 'ensemble', tensors: list[TensorStatistics] | None = None) → StudyReport[source]

Analyse every series and compare the boundary conditions; tensors: the mean stiffness and compliance per volume (tensors_from_rows()) joining the report.