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^-gammawith 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:
objectRealizations of a property (under one boundary condition) at several volumes.
responseoptionally 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]¶
- 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
propertyandvalue, e.g.homogenization.csv): one series per (property,bcorgroup_bycolumn). 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; withgroup_bythe 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:
objectResults of the analysis of one series (see the module documentation).
- property key: str¶
- 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:
objectSettings of the analysis.
gamma: exponent imposed for the RVE sizes (None: the fitted one).min_volumeandmax_volumerestrict 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.bootstrapreplicates (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_dictstates 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
propof 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):stiffnessorstiffness.<bc>(conductivity_tensor,conductivity_tensor.<bc>), whereasstiffness.<bc>.C44is 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:
objectThe 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, withnrealizations):meanthe mean stiffnessCbarandstdthe standard deviation of each of its components (NaN for a single realization);compliancethe inverse of the mean stiffness,S = Cbar^-1(compliance @ mean = I);compliance_stdthe standard deviation of the components of the compliancesC^-1of the realizations andmean_compliancetheir 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 edgesV^(1/dimension)(edges()).tilings: by the window method with shifted tilings, the number of tilings of each size,nthen 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¶
- property notation: str¶
The notation of the tensor and of its inverse (
tensor_notation():morphogen.homogenization.postprocess.NOTATIONfor a stiffness).
- property samples: str¶
realizationsorwindows.- 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
levelof the study (|Zbar| sqrt(n) / Dabove 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.
- 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):tensorstheir 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 theirvolumes;optionsthose 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 columnsstiffness.<bc>.C11…C66of the runs (the upper triangle;C11…C33in the plane).properties: the tensors kept,stiffnessorstiffness.<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:
objectAnalyses 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
- 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.