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 potentialphi;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 stiffnessCat constant electric field, the piezoelectric matrixe(3 x 6, stress-charge form, C/m^2) and the permittivitykappaat constant strain.piezomagnetic(u, the magnetic potentialpsi;H = -grad psi)sigma = C eps - q^T H,B = q eps + mu H: the same with the piezomagnetic matrixq(3 x 6, N/(A m)) and the permeabilitymu.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 tensoralpha(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 potentialV, the temperatureT, linearizedabout the mean temperature
T0)j = -sigma (grad V + s grad T)(the current density;s: the Seebeck coefficient) and the entropy fluxj_s = q / T0 = s j - (k / T0) grad T(k: the thermal conductivity at zero current; Kelvin’s relationPi = 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'_pqrwithcrystal = g @ sample, asrotate_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,e33ande15 = e24(Voigt order 11 22 33 23 31 12:e15is the entry (1, 31),e24the 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:
objectThe 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 epsat 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 fieldE = s grad Tat zero current, V/K) andpyroelectric(p, 3 components:D = p dTat 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).
- morphogen.homogenization.coupled.coupled_law(material: Material, coupling: str, euler=None, *, temperature: float = 300.0)[source]¶
The law
Lof a material for a coupling ofCOUPLINGS(see the module) in the axes of the sample (euler: the orientation of its crystal), and its thermal fluxlambdaofS = L Z - lambda dT(the thermal stressC alphaand 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 temperatureT0of 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 matricesS = L Zof a layout of fields) in the volumefractions: the components ofZin the plane of the layers and those ofSacross them are uniform (the continuity of the tangential gradients and of the normal fluxes), so thatL*_nn = <L_nn^-1>^-1,L*_np = L*_nn <L_nn^-1 L_np>andL*_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 fluxeseigenof the layers (S = L Z - lambda dT), returns the law and the effectivelambda*:lambda*_n = L*_nn <L_nn^-1 lambda_n>andlambda*_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:
objectOne solved loading of a
CoupledProblem: the macroscopic generalized gradientgradientand the mean fluxflux(the components of the layout), the mean ofS . Z, the change of temperature, the volume fraction that carries a law, the solver data and, withfields, 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]ofz = x + i y(ndper node, the first halfx) and the operatorapply([x, y]) = [Re(K z), -Im(K z)]of a complex symmetricK;preconditionacts alike on the two halves (a real symmetric positive operator). Conjugate gradients with the unconjugated productu^T v: the iterations of the real problem when the imaginary part ofKis 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 abovetolat 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:
objectPeriodic problem of the coupled fields of a
layout(FIELDS) on a voxel image:laws[m]is the symmetric lawS = L Zof the materialm(the components of the layout),matthe material of each voxel (-1: none, a void) andeigen[m]its fluxlambdaper 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 gradientZ(and a change of temperature),tensor()the effective lawL*(one solve per component, the unit solutions cached) andeigen_flux()the effectivelambda*.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 (matif 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 ofmorphogen.homogenization.harmonic), solved byconjugate_orthogonal_gradient()(MINRES if it stalls).- solve(gradient, *, temperature: float = 0.0, fields: bool = False)[source]¶
The solution (
CoupledSolution) of a macroscopic generalized gradientZ(the components of the layout) and a change oftemperature, 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*ofS = 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
CoupledProblemof a voxel image whose phases have thematerials, for a coupling ofCOUPLINGS(the laws ofcoupled_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
Lof 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), thencompliance(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 coefficientsd_h = d31 + d32 + d33andg_h = d_h / kappa^sigma_33, the coupling factorsk33(d33 / sqrt(S^E_33 kappa^sigma_33)) andk_t(thickness mode:e33 / sqrt(C^D_33 kappa^eps_33),C^D_33 = C^E_33 + e33^2 / kappa^eps_33), and the entriese31,e33,e15,d31,d33,d15.piezomagnetic: the same withpiezomagnetic(q) andpermeability.magnetoelectroelastic: both, andmagnetoelectric(alpha, 3 x 3) with its entriesalpha11,alpha33.magnetoelectric:permittivity,permeability,magnetoelectric.thermoelectric:electrical_conductivity,seebeck(sigma^-1 L_12),conductivity(thermal, at zero current) and, along each axis, the power factorsigma s^2and the figure of meritZT = 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 ofsplit_law()for its effective law ("tensor": the law itself), the iterations and the largest residual of the solver ("iterations","residual") and, withthermal(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). Seecoupled_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).