morphogen.homogenization.apparent

Apparent properties of a volume element (Kanit et al. 2003; Dirrenberger et al. 2014).

Scalar properties follow Dirrenberger et al. (2014), sections 3.5 and 4:

bulk_modulus

hydrostatic strain E = 1 (eq. 63): k = tr(Sigma) / 9 (eq. 70); the energy estimate is <sigma : eps> / 9 (eq. 64). Under SUBC, Sigma = 1 is imposed and k = 1 / tr(E).

shear_modulus

simple shear E_12 = E_21 = 1/2 (eq. 65): mu = Sigma_12 (eq. 71); the energy estimate is <sigma : eps> (eq. 66). Under SUBC, Sigma_12 = 1 and mu = 1 / (2 E_12).

conductivity

gradient G = e_1 (eq. 60): k = -Q_1 with q = -k grad T (eq. 68); the energy estimate is <k grad T . grad T> (eq. 61). Under UHF (subc), Q = -e_1 and k = 1 / G_1.

electrical_conductivity, permittivity, permeability, diffusivity

the same problem for the other transport phenomena of a scalar potential (TRANSPORT_PROPERTIES): Ohm’s law, electrostatics, magnetostatics and Fick’s law, each with the coefficient of the materials for it (TRANSPORT).

With voids, averages are taken over the whole box with zero stress and flux in the voids (eqs. 24 and 29). Each result also carries the isotropy criterion of the realization (eqs. 72-74), computed on its macroscopic response.

Tensors: the stiffness (six loadings), the conductivity tensor (three; that of each transport phenomenon, <property>_tensor), and the thermal expansion A of E = S : Sigma + A dT: the macroscopic strain of a unit change of temperature without macroscopic stress (a stress-controlled loading, see morphogen.homogenization.core.superpose()).

Loading paths (LoadingPath) follow the nonlinear behaviours of the phases in time: by finite elements with periodic or kinematic conditions (morphogen.homogenization.nonlinear), or by the FFT solver of voxel images with periodic conditions (morphogen.homogenization.fft_nonlinear).

morphogen.homogenization.apparent.TRANSPORT_PROPERTIES = {'dielectric': ('permittivity', 'permittivity_tensor'), 'diffusion': ('diffusivity', 'diffusivity_tensor'), 'electrical': ('electrical_conductivity', 'electrical_conductivity_tensor'), 'magnetic': ('permeability', 'permeability_tensor'), 'thermal': ('conductivity', 'conductivity_tensor')}

The apparent scalar property and tensor of each transport phenomenon (the coefficient of the materials for it: TRANSPORT)

morphogen.homogenization.apparent.PROPERTIES = ('bulk_modulus', 'shear_modulus', 'conductivity', 'electrical_conductivity', 'permittivity', 'permeability', 'diffusivity')

one value per realization and boundary condition

Type:

The scalar properties

morphogen.homogenization.apparent.TENSORS = ('stiffness', 'conductivity_tensor', 'thermal_expansion', 'electrical_conductivity_tensor', 'permittivity_tensor', 'permeability_tensor', 'diffusivity_tensor', 'swelling', 'poroelastic')

that of the strains of an absorbed species; poroelastic: the drained stiffness, the tensor and the modulus of Biot of a porous sample: morphogen.homogenization.poroelastic)

Type:

The tensors (swelling

morphogen.homogenization.apparent.COUPLED = ('piezoelectric', 'piezomagnetic', 'magnetoelectroelastic', 'magnetoelectric', 'thermoelectric')

each gives the tensors of its coupled law (piezoelectric: the stiffness, the piezoelectric matrix and the permittivity, with the constants derived from them)

Type:

The strong couplings (morphogen.homogenization.coupled)

morphogen.homogenization.apparent.HARMONIC = ('dynamic_stiffness', 'complex_conductivity', 'refractive_index')

the complex stiffness of viscoelastic phases and the complex conductivity of leaky dielectrics at the frequencies of homogenize(), the effective refractive index at its wavelengths

Type:

The properties of a harmonic regime (morphogen.homogenization.harmonic)

morphogen.homogenization.apparent.FLOW = ('hydraulic_permeability', 'acoustic')

The properties of the flow of a fluid through the pores (the void phases) of a voxel image: hydraulic_permeability, the tensor of Darcy’s law (morphogen.homogenization.flow), and acoustic, the parameters of the equivalent fluid of a rigid porous frame (morphogen.homogenization.acoustics)

morphogen.homogenization.apparent.PHYSICS = {'acoustic': 'flow', 'bulk_modulus': 'elastic', 'complex_conductivity': 'harmonic', 'conductivity': 'thermal', 'conductivity_tensor': 'thermal', 'diffusivity': 'diffusion', 'diffusivity_tensor': 'diffusion', 'dynamic_stiffness': 'harmonic', 'electrical_conductivity': 'electrical', 'electrical_conductivity_tensor': 'electrical', 'hydraulic_permeability': 'flow', 'magnetoelectric': 'coupled', 'magnetoelectroelastic': 'coupled', 'permeability': 'magnetic', 'permeability_tensor': 'magnetic', 'permittivity': 'dielectric', 'permittivity_tensor': 'dielectric', 'piezoelectric': 'coupled', 'piezomagnetic': 'coupled', 'poroelastic': 'elastic', 'refractive_index': 'harmonic', 'shear_modulus': 'elastic', 'stiffness': 'elastic', 'swelling': 'elastic', 'thermal_expansion': 'elastic', 'thermoelectric': 'coupled'}

the fields of a strong coupling solved together; "harmonic": a complex law at each frequency)

Type:

The physics of the problem that gives each property ("coupled"

morphogen.homogenization.apparent.bulk_isotropy(tensor) → float[source]

sqrt(T:K:T / T:J:T) (eq. 73): zero for a purely spherical response.

morphogen.homogenization.apparent.shear_isotropy(tensor) → float[source]

sqrt(T:J:T / T:K:T) (eq. 74): zero for a purely deviatoric response.

morphogen.homogenization.apparent.thermal_isotropy(vector, axis: int = 0) → float[source]

(|Q_2| + |Q_3|) / |Q_1| for a loading along axis (eq. 72).

class morphogen.homogenization.apparent.Apparent(property: str, bc: str, value: float, energy: float, isotropy: float, response: ndarray, solution: Solution)[source]

Bases: object

Apparent property of one volume element for one boundary condition.

row() → dict[source]

Flat record (long format) with the response components and solver data.

class morphogen.homogenization.apparent.Response(name: str, bc: str, solution: Solution)[source]

Bases: object

Macroscopic response of a volume element to a named loading for one boundary condition: the macroscopic strain and stress (gradient and flux), prescribed or solved for.

components() → dict[str, float][source]

E11 ... E12 (engineering shears) and S11 ... S12, or G1 ... G3 and Q1 ... Q3, and the energy.

row() → dict[source]

Flat record (long format) with the components and solver data.

morphogen.homogenization.apparent.apparent_bulk_modulus(problem, *, fields: bool = False) → Apparent[source]

The apparent bulk modulus of a problem under its boundary conditions (Apparent): under a hydrostatic strain, or a hydrostatic stress with static uniform conditions (subc); the fields of the solution with fields.

morphogen.homogenization.apparent.apparent_shear_modulus(problem, plane=(0, 1), *, fields: bool = False) → Apparent[source]

The apparent shear modulus of a problem in a plane (its two axes; Apparent): under a shear strain in it, or a shear stress with static uniform conditions (subc); the fields of the solution with fields.

morphogen.homogenization.apparent.apparent_conductivity(problem, axis: int = 0, *, fields: bool = False) → Apparent[source]

The apparent conductivity of a problem along an axis (Apparent): under a gradient along it, or a flux with static uniform conditions (subc); the fields of the solution with fields. The problem of another transport phenomenon gives its property (TRANSPORT_PROPERTIES: the apparent electrical conductivity, permittivity, permeability or diffusivity).

morphogen.homogenization.apparent.stiffness_tensor(problem) → tuple[ndarray, list[Solution]][source]

Apparent stiffness (6 x 6, Voigt order 11 22 33 23 31 12) from six loadings.

KUBC and periodic conditions impose the six unit strains (Dirrenberger et al. 2014, appendix A); SUBC impose the six unit stresses and the compliance is inverted.

morphogen.homogenization.apparent.thermal_expansion(problem) → tuple[ndarray, Solution][source]

Apparent thermal expansion tensor (3 x 3): the macroscopic strain of a unit change of temperature under zero macroscopic stress (E = S : Sigma + A dT).

morphogen.homogenization.apparent.conductivity_tensor(problem) → tuple[ndarray, list[Solution]][source]

Apparent conductivity tensor (3 x 3) from three gradient (or flux) loadings; that of the transport phenomenon of the problem (TRANSPORT_PROPERTIES).

morphogen.homogenization.apparent.isotropic_projection(stiffness) → tuple[float, float][source]

Bulk and shear moduli of the isotropic part of a Voigt stiffness matrix.

morphogen.homogenization.apparent.isotropy_errors(stiffness) → dict[str, float][source]

Relative deviations from isotropy of a Voigt stiffness (Dirrenberger 2014, 5.1.4).

normal: spread of C11, C22, C33; coupling: of C12, C13, C23; shear: of C44, C55, C66; cauchy: |C44 - (C11 - C12)/2| / C44 with mean values; other: largest remaining component relative to the mean of C11, C22, C33.

morphogen.homogenization.apparent.make_problem(sample, materials: dict[int, Material], physics: str, bc: str = 'periodic', *, solver: str = 'auto', tol: float = 1e-08, maxiter: int | None = None, grains=None, orientations=None, device: str = 'cpu', integration: str | None = None)[source]

Boundary-value problem of a sample for physics ‘elastic’, ‘thermal’ or another transport phenomenon of a scalar potential ( TRANSPORT: ‘electrical’, ‘dielectric’, ‘magnetic’, ‘diffusion’), which the thermal problems solve with the coefficient of the materials for it.

A TetMesh (conforming mesh) is solved by finite elements, with any boundary condition; a VoxelImage by the FFT solver, with periodic conditions; a LevelSetSample (the level set of a morphology on a regular grid) by extended finite elements, with periodic conditions. solver is the linear solver of the finite element problems (see morphogen.homogenization.solvers), or "fenicsx" to assemble and solve them by FEniCSx (morphogen.homogenization.fenicsx); device that of the FFT solver ("cpu", "gpu" or "auto", see morphogen.gpu). integration (elastic problems on a mesh of 10-node tetrahedra): "full", or "bbar", the volume change of each element as its mean, for nearly incompressible phases (morphogen.homogenization.dilatation).

Crystals (anisotropic materials) are turned by the orientation of their grain: the grains and orientations of a polycrystal mesh (mesh.cell, mesh.orientations), or, for a voxel image, grains (image or array of grain labels, e.g. tessellation.labels(...)) and orientations (Bunge angles of each grain).

morphogen.homogenization.apparent.homogenize(sample, materials: dict[int, Material], *, bcs=('periodic',), properties=('bulk_modulus', 'shear_modulus'), solver: str = 'auto', tol: float = 1e-08, maxiter: int | None = None, fields: bool = False, grains=None, orientations=None, loadings: dict | None = None, paths: dict | None = None, nonlinear: dict | None = None, device: str = 'cpu', ntfa: dict | None = None, mean_temperature: float = 300.0, frequencies=None, wavelengths=None, fracture=None, fluid_bulk_modulus: float | None = None, integration: str | None = None) → dict[str, Apparent | Response | PathResult | dict][source]

Apparent properties of sample for every pair (property, boundary condition).

sample is a conforming tetrahedral mesh (finite elements: kubc, mixed, periodic and subc conditions), a voxel image (FFT solver: periodic only) or the level set of a morphology on a regular grid (LevelSetSample: extended finite elements, periodic only, whose interfaces cut the elements). Returns a mapping "<property>.<bc>" -> Apparent (PROPERTIES: the bulk and shear moduli, and the property of each transport phenomenon: conductivity, electrical_conductivity, permittivity, permeability, diffusivity); the tensors (TENSORS: stiffness, thermal_expansion, conductivity_tensor and the <property>_tensor of the other transports) map to {"tensor": array, ...}, the stiffness with its compliance (S = C^-1, in the same notation: Voigt order 11 22 33 23 31 12 with engineering shears, morphogen.homogenization.postprocess.NOTATION), its engineering constants and anisotropy indices. loadings (name -> Loading, or a mapping for Loading.from_spec()) are solved too: "<name>.<bc>" -> Response. Problems sharing a boundary condition reuse the assembled system and the unit solutions. With fields, the solutions keep the element fields (strain/stress or gradient/flux). grains and orientations: crystal orientations of a voxel image (see make_problem()); device: that of the FFT solver of an image ("cpu", "gpu" or "auto", see morphogen.gpu).

paths (name -> LoadingPath, or a mapping for LoadingPath.from_spec()) are followed in time with the nonlinear behaviours of the materials, under periodic and kinematic conditions (finite elements) or periodic ones (FFT): "<name>.<bc>" -> PathResult; nonlinear: options of NonlinearFEProblem and NonlinearFFTProblem (newton_tol, max_newton, max_cuts, kinematics: "small" or "finite" strains; integration: "bbar" or "full"; tangent: "auto", "symmetric" or "full", the consistent tangents of the points symmetrized for the conjugate gradients or kept whole for GMRES; contact: True, or a mapping of the options friction, stiffness, tangential, depth, augmentations and tolerance of ContactCell: on the mesh of the solid of a porous sample, the walls of the pores that close along a path press on each other, and on their images across the faces of a periodic cell, with Coulomb’s friction — in finite strains unless kinematics says otherwise, the tangent factorized; the curves of the paths get the columns contact_area, contact_pressure, contact_penetration and contact_dissipation; interfaces: a mapping of the law of the interfaces of the phases of a mesh (interface_law(): law, normal_strength, mode_I, friction…), of the faces that are interfaces ("phases", "grains" or pairs of phases), of the viscosity of their regularization and of the elastic slip of their friction; laws in the place of a law: one for each pair of phases, {"0-1": {...}, "0-2": {...}}: CohesiveCell, whose interfaces open, break, close again and rub along a path, the tangent factorized; the curves get the columns debonded_area, interface_damage, interface_opening and interface_dissipation; microdamage: a mapping of the options of the alternate scheme of the microdamage of regularized cleavage planes, its tolerance, the most passes of a step and its acceleration (microdamage_options())).

integration: "full" integrates the strain energy at every point of the elements; "bbar" (also "reduced") takes the volume change of each element as its mean — selective reduced integration, B-bar in small strains and F-bar in finite strains (morphogen.homogenization.dilatation) —, which keeps the elements from locking when a phase is nearly incompressible (elastomers: Poisson’s ratio near 1/2) or flows plastically. On a mesh of 10-node tetrahedra it applies to the elastic problems and to the loading paths (default "full"); on a voxel image, to the loading paths (default "bbar": the linear FFT solver integrates its voxels at every point). With fields, their element (voxel) fields are kept at the end of each segment (fields="steps": of each step, the other solutions keeping their fields).

The strong couplings (COUPLED: piezoelectric, piezomagnetic, magnetoelectroelastic, magnetoelectric, thermoelectric) are properties too: the fields of each are solved together on a voxel image, under periodic conditions (morphogen.homogenization.coupled), with the coupling coefficients of the materials (Material(coupling=...)), and "<coupling>.periodic" maps to the tensors of the effective coupled law and the constants derived from them (split_law()); mean_temperature: the mean absolute temperature of the thermoelectric law (K).

The properties of a harmonic regime (HARMONIC, voxel images; morphogen.homogenization.harmonic): dynamic_stiffness, the complex stiffness of viscoelastic phases, and complex_conductivity, that of leaky dielectrics (sigma + i omega eps), at the angular frequencies; refractive_index, the effective index of the refractive_index of the materials at the wavelengths (the long-wavelength limit of optics). "<property>.periodic" maps to the storage and loss parts of the tensors at each frequency and their scalar entries (to_dict()).

fracture (voxel images; a PhaseField, or a mapping of its parameters with the options staggered_tol and max_staggered of its solver): the paths are followed by the phase-field method of brittle fracture (morphogen.fracture.phasefield), the phases elastic, and "<name>.periodic" maps to a PhaseFieldResult, whose quantities strength and work are those of the statistics of representative volumes.

The flow of a fluid through the pores (FLOW; voxel images of cubic voxels, the pores their void phases): hydraulic_permeability, the permeability tensor of Darcy’s law by the lattice Boltzmann method (morphogen.homogenization.flow), and acoustic, the parameters of the equivalent fluid of the rigid porous frame (porosity, permeability, tortuosity, viscous and thermal characteristic lengths, thermal permeability: morphogen.homogenization.acoustics, whose equivalent_fluid and absorption give the sound absorption of a layer).

The weak couplings of morphogen.homogenization.poroelastic are properties of the elastic solvers: swelling, the tensor of the strains of a unit content of an absorbed species (Material(swelling=...); as thermal_expansion), and poroelastic, the law of a porous sample whose pores (the voids) hold a fluid under pressure, under periodic or kinematic uniform conditions: its drained stiffness, the tensor and the modulus of Biot and, with the bulk modulus of the fluid fluid_bulk_modulus, its undrained response (Gassmann, Skempton).

ntfa (voxel images): the paths are followed by a reduced model instead (morphogen.homogenization.ntfa), trained on the paths of ntfa["training"] with ntfa["modes"] modes per plastic phase (default 6): "<name>.ntfa" -> PathResult; ntfa["save"]: a file for the model; ntfa["full_field"]: the full-field paths too, for comparison.

morphogen.homogenization.apparent.CONTACT_OPTIONS = ('friction', 'stiffness', 'tangential', 'depth', 'points', 'augmentations', 'tolerance')

The options of the contact of the walls of the pores along the loading paths (nonlinear["contact"]): those of morphogen.contact.periodic.ContactCell

morphogen.homogenization.apparent.INTERFACE_OPTIONS = ('law', 'stiffness', 'normal_strength', 'shear_strength', 'mode_I', 'mode_II', 'eta', 'strength', 'energy', 'beta', 'penalty', 'tangential', 'friction', 'faces', 'viscosity', 'slip', 'laws')

The options of the interfaces of the phases along the loading paths (nonlinear["interfaces"]): their law and its parameters (morphogen.fracture.periodic.interface_law), and those of morphogen.fracture.periodic.CohesiveCell