morphogen.homogenization.coupled

Strongly coupled linear homogenization on periodic voxel images: several fields solved together, each a displacement or a scalar potential, their fluxes tied by one symmetric constitutive law.

A layout lists the fields. A displacement u has the strain eps (6 components, Voigt order 11 22 33 23 31 12, engineering shears) for its generalized gradient and the stress sigma for its flux; a scalar potential phi has its gradient grad phi (3 components) and a flux vector. The generalized gradient Z stacks those of the fields, the generalized flux S their fluxes, and the law of each phase is the symmetric matrix L of S = L Z. The couplings of COUPLINGS:

piezoelectric (u, the electric potential phi; E = -grad phi)

sigma = C eps - e^T E, D = e eps + kappa E: Z = (eps, grad phi), S = (sigma, D), L = [[C, e^T], [e, -kappa]] with the stiffness C at constant electric field, the piezoelectric matrix e (3 x 6, stress-charge form, C/m^2) and the permittivity kappa at constant strain.

piezomagnetic (u, the magnetic potential psi; H = -grad psi)

sigma = C eps - q^T H, B = q eps + mu H: the same with the piezomagnetic matrix q (3 x 6, N/(A m)) and the permeability mu.

magnetoelectroelastic (u, phi, psi)

sigma = C eps - e^T E - q^T H, D = e eps + kappa E + alpha H, B = q eps + alpha^T E + mu H: L = [[C, e^T, q^T], [e, -kappa, -alpha], [q, -alpha^T, -mu]] with the magnetoelectric tensor alpha (3 x 3). A composite of a piezoelectric phase and a piezomagnetic one is magnetoelectric though neither phase is (a product property).

magnetoelectric (phi, psi; rigid phases)

D = kappa E + alpha H, B = alpha^T E + mu H: Z = (grad phi, grad psi), S = -(D, B), L = [[kappa, alpha], [alpha^T, mu]].

thermoelectric (the electric potential V, the temperature T, linearized

about the mean temperature T0) j = -sigma (grad V + s grad T) (the current density; s: the Seebeck coefficient) and the entropy flux j_s = q / T0 = s j - (k / T0) grad T (k: the thermal conductivity at zero current; Kelvin’s relation Pi = s T0): Z = (grad V, grad T), S = -(j, j_s), L = [[sigma, sigma s], [s^T sigma, k / T0 + s^T sigma s]], symmetric positive definite by Onsager’s reciprocity.

The energy-conserving laws (the first three) are symmetric but not definite: their potentials are saddle points of the electric enthalpy. CoupledProblem solves the periodic fluctuations of all the fields at once on the trilinear voxels of the FFT solver (morphogen.homogenization.fft): the system K w = f of the element matrices int B^T L B (B: the generalized gradients of the shape functions) by MINRES, or by conjugate gradients when every block of the law is positive, preconditioned block by block by the inverse of a homogeneous reference medium in Fourier space. The unknowns of each field are scaled by the square root of its reference so that the blocks have the same magnitude whatever the units (stiffnesses of 1e11 Pa beside permittivities of 1e-9 F/m). The unit loadings of Z give the effective law L* (the mean fluxes), which coupled_tensors() splits into the tensors of the coupling, with the constants derived from them.

Uniform fields that load the phases without a gradient are the weak couplings of the same problems: a change of temperature with the thermal stresses beta = C alpha and the pyroelectric coefficients p of the phases, S = L Z - lambda dT, gives the effective lambda* (CoupledProblem.eigen_flux(); the generalized relation of Levin).

laminate() is the exact effective law of layers, for any of these laws: the checks of the solver.

morphogen.homogenization.coupled.NOTATION = 'Voigt order 11 22 33 23 31 12 of strains (engineering shears) and stresses: sigma = C eps - e^T E - q^T H, D = e eps + kappa E + alpha H, B = q eps + alpha^T E + mu H (e, q: 3 x 6, rows 1 2 3; d = e C^-1; kappa, mu at constant strain); thermoelectric: j = -sigma (grad V + s grad T), q = T0 s j - k grad T'

The notation of the tensors of the coupled laws

morphogen.homogenization.coupled.FIELDS = {'displacement': (3, 6), 'potential': (1, 3)}

the degrees of freedom of a node and the components of the generalized gradient of each kind

Type:

The fields of a layout

morphogen.homogenization.coupled.COUPLINGS = {'magnetoelectric': ('potential', 'potential'), 'magnetoelectroelastic': ('displacement', 'potential', 'potential'), 'piezoelectric': ('displacement', 'potential'), 'piezomagnetic': ('displacement', 'potential'), 'thermoelectric': ('potential', 'potential')}

The couplings and the fields of their layouts

morphogen.homogenization.coupled.layout_sizes(layout) → tuple[int, int][source]

The degrees of freedom of a node and the components of the generalized gradient of a layout of fields (FIELDS).

morphogen.homogenization.coupled.rotate_piezo(e, euler) → ndarray[source]

The piezoelectric (or piezomagnetic) matrix of a crystal (3 x 6, in its axes) in the axes of the sample, for one orientation (Bunge angles in degrees: shape (3, 6)) or several (shape (n, 3, 6)): e_kij = g_pk g_qi g_rj e'_pqr with crystal = g @ sample, as rotate_stiffness().

morphogen.homogenization.coupled.poled_ceramic(e31: float, e33: float, e15: float) → ndarray[source]

The piezoelectric matrix e (3 x 6) of a ceramic poled along x3 (the symmetry 6mm of PZT and BaTiO3; also the piezomagnetic matrix of CoFe2O4 magnetized along x3): e31 = e32, e33 and e15 = e24 (Voigt order 11 22 33 23 31 12: e15 is the entry (1, 31), e24 the entry (2, 23)).

class morphogen.homogenization.coupled.Coupling(piezoelectric: tuple | None = None, piezomagnetic: tuple | None = None, magnetoelectric: tuple | None = None, seebeck: tuple | None = None, pyroelectric: tuple | None = None)[source]

Bases: object

The coupling coefficients of a material, in the axes of its crystal (those of the sample without an orientation): piezoelectric (e, 3 x 6: D = e eps at zero field, C/m^2), piezomagnetic (q, 3 x 6: B = q eps, N/(A m)), magnetoelectric (alpha, 3 x 3 or one value: D = alpha H), seebeck (s, one value or a 3 x 3 tensor: the field E = s grad T at zero current, V/K) and pyroelectric (p, 3 components: D = p dT at constant strain and field, C/(m^2 K)). Matrices follow morphoGen’s Voigt order 11 22 33 23 31 12 with engineering shears, which is that of the IEEE standard on piezoelectricity (e15: the entry of the row 1 and the column 31).

classmethod from_config(spec) → Coupling[source]

A mapping of the coefficients (Coupling); a poled ceramic gives e (or q) by its constants: piezoelectric: {e31: .., e33: .., e15: ..}.

to_config() → dict[source]
matrix(name: str, euler=None) → ndarray[source]

The tensor name in the axes of the sample for the orientation euler (Bunge angles, degrees), zero without it: 3 x 6 (piezoelectric, piezomagnetic), 3 x 3 (magnetoelectric, seebeck) or 3 (pyroelectric).

morphogen.homogenization.coupled.coupled_law(material: Material, coupling: str, euler=None, *, temperature: float = 300.0)[source]

The law L of a material for a coupling of COUPLINGS (see the module) in the axes of the sample (euler: the orientation of its crystal), and its thermal flux lambda of S = L Z - lambda dT (the thermal stress C alpha and minus the pyroelectric coefficients; zero for the transport couplings). A material without elastic parameters has no stiffness (a pore filled by a dielectric); temperature: the mean temperature T0 of the thermoelectric law (K).

morphogen.homogenization.coupled.laminate(laws, fractions, layout, eigen=None)[source]

The exact effective law of layers normal to x3 of laws laws (symmetric matrices S = L Z of a layout of fields) in the volume fractions: the components of Z in the plane of the layers and those of S across them are uniform (the continuity of the tangential gradients and of the normal fluxes), so that L*_nn = <L_nn^-1>^-1, L*_np = L*_nn <L_nn^-1 L_np> and L*_pp = <L_pp - L_pn L_nn^-1 L_np> + <L_pn L_nn^-1> L*_nn <L_nn^-1 L_np> (Backus’ averages of a stiffness, Maxwell’s of a conductivity, and those of every coupled law of the module, definite or not; of complex symmetric laws too: those of a harmonic regime, morphogen.homogenization.harmonic). With the thermal fluxes eigen of the layers (S = L Z - lambda dT), returns the law and the effective lambda*: lambda*_n = L*_nn <L_nn^-1 lambda_n> and lambda*_p = <lambda_p - L_pn L_nn^-1 lambda_n> + <L_pn L_nn^-1> lambda*_n.

class morphogen.homogenization.coupled.CoupledSolution(gradient: ndarray, flux: ndarray, energy: float, temperature: float, material_fraction: float, info: SolveInfo, phases: dict = <factory>, fields: dict | None = None)[source]

Bases: object

One solved loading of a CoupledProblem: the macroscopic generalized gradient gradient and the mean flux flux (the components of the layout), the mean of S . Z, the change of temperature, the volume fraction that carries a law, the solver data and, with fields, the voxel means of the gradients and fluxes (fields["gradient"], fields["flux"]: shape + components) and the nodal fluctuation of each field (fields["fluctuation"]: shape + degrees of freedom).

morphogen.homogenization.coupled.conjugate_orthogonal_gradient(apply, precondition, rhs, tol, maxiter, nd: int)[source]

The conjugate orthogonal conjugate gradient method (van der Vorst & Melissen 1990) for the real form of a complex symmetric system: the unknowns [x, y] of z = x + i y (nd per node, the first half x) and the operator apply([x, y]) = [Re(K z), -Im(K z)] of a complex symmetric K; precondition acts alike on the two halves (a real symmetric positive operator). Conjugate gradients with the unconjugated product u^T v: the iterations of the real problem when the imaginary part of K is small, where MINRES on the indefinite real form needs as many as the square of them. Returns (the solution, the iterations, the relative residual); the method has no minimization property and may stall (a residual above tol at the end: the caller falls back on MINRES).

class morphogen.homogenization.coupled.CoupledProblem(image: VoxelImage, laws, layout, mat, *, eigen=None, stat=None, tol: float = 1e-08, maxiter: int | None = None, pairs: bool = False)[source]

Bases: object

Periodic problem of the coupled fields of a layout (FIELDS) on a voxel image: laws[m] is the symmetric law S = L Z of the material m (the components of the layout), mat the material of each voxel (-1: none, a void) and eigen[m] its flux lambda per unit change of temperature (S = L Z - lambda dT; zero if not given). Each diagonal block of the laws must be definite, positive or negative, alike in all the materials that have it (a block may vanish in some: the stiffness of a pore filled by a dielectric).

solve() gives the mean flux of a macroscopic gradient Z (and a change of temperature), tensor() the effective law L* (one solve per component, the unit solutions cached) and eigen_flux() the effective lambda*. tol: the relative residual of the Krylov solver (MINRES; conjugate gradients when every block is positive); stat: the phase of each voxel for the statistics (mat if not given). pairs: the layout is twice the same fields, the real and imaginary parts of a complex symmetric law ([[L', -L''], [-L'', -L']]: the harmonic problems of morphogen.homogenization.harmonic), solved by conjugate_orthogonal_gradient() (MINRES if it stalls).

solve(gradient, *, temperature: float = 0.0, fields: bool = False)[source]

The solution (CoupledSolution) of a macroscopic generalized gradient Z (the components of the layout) and a change of temperature, by superposition of the unit solutions.

tensor() → ndarray[source]

The effective law L* (nz x nz): the mean fluxes of the unit gradients, symmetrized (it is symmetric to the tolerance of the solver).

eigen_flux() → ndarray[source]

The effective thermal flux lambda* of S = L* Z - lambda* dT: minus the mean flux of a unit change of temperature without a macroscopic gradient.

property iterations: int

The iterations of the unit solutions solved so far.

morphogen.homogenization.coupled.coupled_problem(image: VoxelImage, materials: dict[int, Material], coupling: str, *, grains=None, orientations=None, temperature: float = 300.0, tol: float = 1e-08, maxiter: int | None = None) → CoupledProblem[source]

The CoupledProblem of a voxel image whose phases have the materials, for a coupling of COUPLINGS (the laws of coupled_law()). The crystals are turned by the orientations of their grains (grains: the label of each voxel, orientations: their Bunge angles), as in the other problems; temperature: the mean temperature of a thermoelectric law (K).

morphogen.homogenization.coupled.split_law(law, coupling: str, *, temperature: float = 300.0) → dict[source]

The tensors of a law L of a coupling (COUPLINGS; see the module), with the constants derived from them.

piezoelectric: stiffness (C^E, at constant field), piezoelectric (e, 3 x 6), permittivity (kappa^eps, at constant strain), then compliance (S^E), d (d = e S^E, the strain-charge form: 3 x 6, C/N), permittivity_stress (kappa^sigma = kappa^eps + d e^T), g33 (d33 / kappa^sigma_33), the hydrostatic coefficients d_h = d31 + d32 + d33 and g_h = d_h / kappa^sigma_33, the coupling factors k33 (d33 / sqrt(S^E_33 kappa^sigma_33)) and k_t (thickness mode: e33 / sqrt(C^D_33 kappa^eps_33), C^D_33 = C^E_33 + e33^2 / kappa^eps_33), and the entries e31, e33, e15, d31, d33, d15. piezomagnetic: the same with piezomagnetic (q) and permeability. magnetoelectroelastic: both, and magnetoelectric (alpha, 3 x 3) with its entries alpha11, alpha33. magnetoelectric: permittivity, permeability, magnetoelectric. thermoelectric: electrical_conductivity, seebeck (sigma^-1 L_12), conductivity (thermal, at zero current) and, along each axis, the power factor sigma s^2 and the figure of merit ZT = sigma s^2 T0 / k (power_factor1, zt1…).

morphogen.homogenization.coupled.coupled_tensors(image: VoxelImage, materials: dict[int, Material], coupling: str, *, grains=None, orientations=None, temperature: float = 300.0, tol: float = 1e-08, maxiter: int | None = None, thermal: bool | None = None) → dict[source]

The effective tensors of a coupling (COUPLINGS) of a periodic voxel image: those of split_law() for its effective law ("tensor": the law itself), the iterations and the largest residual of the solver ("iterations", "residual") and, with thermal (by default: when a phase expands or is pyroelectric), the effective thermal flux ("thermal_stress": beta* = C* alpha*, Voigt; "thermal_expansion": alpha* at constant field, 3 x 3; "pyroelectric": p* at constant strain and field). See coupled_problem() for the options.

morphogen.homogenization.coupled.ENTRIES = {'conductivity': ('k', True), 'd': ('d', False), 'dm': ('dm', False), 'electrical_conductivity': ('sigma', True), 'magnetoelectric': ('alpha', False), 'permeability': ('mu', True), 'permeability_stress': ('mu_s', True), 'permittivity': ('eps', True), 'permittivity_stress': ('eps_s', True), 'piezoelectric': ('e', False), 'piezomagnetic': ('q', False), 'pyroelectric': ('p', False), 'seebeck': ('s', False), 'stiffness': ('C', True), 'thermal_expansion': ('A', True), 'thermal_stress': ('beta', False)}

The prefix of the entries of each tensor of a coupled law in the tables of results (coupled_entries()), and whether the tensor is symmetric (its upper triangle)

morphogen.homogenization.coupled.entry_names(coupling: str) → tuple[str, ...][source]

The names of the scalar results of a coupling (COUPLINGS) in the tables of results and for the statistics of RVE studies: the entries of its tensors (coupled_entries(): C11, e33, eps11…), those of its thermal flux with a displacement (A11, beta1, p3) and its constants (d33, k33, zt1…).

morphogen.homogenization.coupled.coupled_entries(tensors: dict) → dict[str, float][source]

The entries of the tensors of a coupled law (split_law(), coupled_tensors()) as the columns of a table of results: C11 … C66, e11 … e36 (rows 1 2 3, columns in the Voigt order 11 22 33 23 31 12 numbered 1 to 6), d11 … d36, eps11 … eps33, mu11, alpha11, sigma11, s11, k11, A11, beta1 … beta6, p1 … p3 (ENTRIES: the upper triangles of the symmetric tensors).