"""Materials of the phases: linear (thermo-)elasticity and the transport phenomena of one
scalar potential (heat conduction, electrical conduction, dielectric and magnetic
polarization, diffusion), isotropic or anisotropic (crystals), and voids.
Every transport phenomenon is a flux proportional to the gradient of a potential,
``flux = -K grad(potential)`` without sources (:data:`TRANSPORT`): Fourier's law (``q = -k
grad T``, the ``conductivity``), Ohm's law (``j = -sigma grad V``, the
``electrical_conductivity``), electrostatics (``D = -eps grad V``, the ``permittivity``),
magnetostatics without currents (``B = -mu grad psi``, the ``permeability``) and Fick's law
(``J = -D grad c``, the ``diffusivity``). They share their solvers, their boundary
conditions and their bounds; a phase whose coefficient is zero is inert for that physics
(an insulator), as a void is for all.
Thermal expansion makes the stress ``sigma = D (eps - alpha dT)`` for a change of
temperature ``dT`` from the stress-free state; a crystal's expansion tensor turns with it.
An isotropic elastic material may also yield: von Mises elasto-(visco)plasticity with
isotropic and kinematic hardening (:class:`~morphogen.homogenization.behaviours.Plasticity`,
for the loading paths of :mod:`morphogen.homogenization.nonlinear`), or porous
elasto-(visco)plasticity (Gurson-Tvergaard-Needleman, Rousselier, the elliptic criterion
of compaction: :class:`~morphogen.homogenization.porous.PorousPlasticity`); the linear
properties use its elasticity. A crystal may slip on its slip systems: the crystal
plasticity of Méric and Cailletaud (:class:`~morphogen.homogenization.crystal.
CrystalPlasticity`), which turns with the orientation of each grain.
Elasticity matrices use the Voigt order ``(11, 22, 33, 23, 31, 12)`` with engineering
shear strains, so that ``sigma = D eps`` (:mod:`morphogen.homogenization.elements`). The
matrices of a crystal are given in its own axes; a crystal orientation (Bunge Euler
angles ``(phi1, Phi, phi2)`` in degrees, :mod:`morphogen.orientations`) turns them into
the axes of the sample: ``C_ijkl = g_pi g_qj g_rk g_sl C'_pqrs`` with ``crystal = g @
sample``.
"""
from __future__ import annotations
import logging
import math
from dataclasses import dataclass
import numpy as np
from morphogen.homogenization.behaviours import Plasticity
from morphogen.homogenization.crystal import CrystalPlasticity
from morphogen.homogenization.porous import PorousPlasticity
log = logging.getLogger("morphogen")
#: The transport phenomena of one scalar potential, ``flux = -K grad(potential)``: the
#: name of each physics and the parameter of :class:`Material` that holds its ``K``
#: (``thermal``: the ``conductivity``, or the tensor ``conductivities`` of a crystal)
TRANSPORT = {
"thermal": "conductivity",
"electrical": "electrical_conductivity",
"dielectric": "permittivity",
"magnetic": "permeability",
"diffusion": "diffusivity",
}
#: The potential, the flux and the law of each transport phenomenon (for the messages and
#: the documentation)
TRANSPORT_LAWS = {
"thermal": ("temperature", "heat flux", "Fourier's law q = -k grad T"),
"electrical": ("electric potential", "current density", "Ohm's law j = -sigma grad V"),
"dielectric": ("electric potential", "electric displacement", "D = -eps grad V"),
"magnetic": ("magnetic scalar potential", "magnetic induction", "B = -mu grad psi"),
"diffusion": ("concentration", "mass flux", "Fick's law J = -D grad c"),
}
#: The physics of the linear problems: elasticity and the transport phenomena
PHYSICS = ("elastic", *TRANSPORT)
#: The behaviours of :mod:`morphogen.homogenization.laws` of a material
_ANALYTIC = ("viscoelasticity", "hyperelasticity", "damage")
[docs]
def transport_physics(physics: str) -> bool:
"""Whether ``physics`` is a transport phenomenon of :data:`TRANSPORT` (a scalar
potential), not elasticity; an unknown name is an error."""
if physics not in PHYSICS:
raise ValueError(f"physics: one of {PHYSICS}, got {physics!r}")
return physics != "elastic"
#: Voigt index of each pair of tensor indices
_VOIGT_PAIRS = ((0, 0), (1, 1), (2, 2), (1, 2), (2, 0), (0, 1))
_VOIGT_INDEX = np.empty((3, 3), dtype=np.int64)
for _k, (_i, _j) in enumerate(_VOIGT_PAIRS):
_VOIGT_INDEX[_i, _j] = _VOIGT_INDEX[_j, _i] = _k
_I0 = np.array([i for i, _ in _VOIGT_PAIRS])
_I1 = np.array([j for _, j in _VOIGT_PAIRS])
[docs]
def voigt_to_tensor4(d) -> np.ndarray:
"""Fourth-order tensor(s) ``C_ijkl`` of Voigt matrices (..., 6, 6)."""
d = np.asarray(d, dtype=float)
return d[..., _VOIGT_INDEX[:, :, None, None], _VOIGT_INDEX[None, None, :, :]]
[docs]
def tensor4_to_voigt(c) -> np.ndarray:
"""Voigt matrices (..., 6, 6) of fourth-order tensors with the minor symmetries."""
c = np.asarray(c, dtype=float)
return c[..., _I0[:, None], _I1[:, None], _I0[None, :], _I1[None, :]]
[docs]
def rotate_stiffness(d, euler) -> np.ndarray:
"""Elasticity matrix of a crystal (crystal axes) in the sample axes, for one
orientation (shape (6, 6)) or several (shape (n, 6, 6))."""
from morphogen.orientations import euler_to_matrix
g = euler_to_matrix(euler)
c = np.einsum("npi,nqj,nrk,nsl,pqrs->nijkl", g, g, g, g, voigt_to_tensor4(d), optimize=True)
out = tensor4_to_voigt(c)
out = 0.5 * (out + np.swapaxes(out, -1, -2))
return out[0] if np.ndim(euler) == 1 else out
[docs]
def rotate_conductivity(k, euler) -> np.ndarray:
"""Conductivity tensor of a crystal in the sample axes (``g^T K g``)."""
from morphogen.orientations import euler_to_matrix
g = euler_to_matrix(euler)
out = np.einsum("npi,pq,nqj->nij", g, np.asarray(k, dtype=float), g)
out = 0.5 * (out + np.swapaxes(out, -1, -2))
return out[0] if np.ndim(euler) == 1 else out
[docs]
def isotropic_matrix(lam: float, mu: float) -> np.ndarray:
"""Elasticity matrix (6 x 6) of an isotropic material."""
d = np.zeros((6, 6))
d[:3, :3] = lam
d[[0, 1, 2], [0, 1, 2]] += 2.0 * mu
d[[3, 4, 5], [3, 4, 5]] = mu
return d
[docs]
def voigt_average(d) -> tuple[float, float]:
"""Bulk and shear moduli of the Voigt average over uniform orientations."""
d = np.asarray(d, dtype=float)
a = d[0, 0] + d[1, 1] + d[2, 2]
b = d[1, 2] + d[2, 0] + d[0, 1]
c = d[3, 3] + d[4, 4] + d[5, 5]
return float((a + 2.0 * b) / 9.0), float((a - b + 3.0 * c) / 15.0)
[docs]
def reuss_average(d) -> tuple[float, float]:
"""Bulk and shear moduli of the Reuss average over uniform orientations."""
s = np.linalg.inv(np.asarray(d, dtype=float))
a = s[0, 0] + s[1, 1] + s[2, 2]
b = s[1, 2] + s[2, 0] + s[0, 1]
c = s[3, 3] + s[4, 4] + s[5, 5]
return float(1.0 / (a + 2.0 * b)), float(15.0 / (4.0 * a - 4.0 * b + 3.0 * c))
def _expansion(value, name: str = "expansion"):
"""Thermal expansion (or the swelling ``name``) as one coefficient (isotropic) or a
3 x 3 tensor (tuple)."""
a = np.asarray(value, dtype=float)
if not np.all(np.isfinite(a)):
raise ValueError(f"{name}: finite coefficients")
if a.ndim == 0:
return float(a)
if a.shape == (3,):
a = np.diag(a)
if a.shape != (3, 3) or not np.allclose(a, a.T, atol=1e-12 * max(np.abs(a).max(), 1e-300)):
raise ValueError(f"{name}: one coefficient, three principal values or a 3 x 3 tensor")
if np.allclose(a, a[0, 0] * np.eye(3), rtol=0, atol=1e-15 * abs(a[0, 0])):
return float(a[0, 0])
return tuple(tuple(float(v) for v in row) for row in 0.5 * (a + a.T))
def _matrix(value, shape, name) -> tuple:
m = np.asarray(value, dtype=float)
if m.shape != shape or not np.all(np.isfinite(m)):
raise ValueError(f"{name}: expected a finite {shape[0]} x {shape[1]} matrix")
if not np.allclose(m, m.T, rtol=1e-10, atol=1e-12 * float(np.abs(m).max())):
raise ValueError(f"{name}: the matrix must be symmetric")
if np.linalg.eigvalsh(0.5 * (m + m.T)).min() <= 0:
raise ValueError(f"{name}: the matrix must be positive definite")
return tuple(tuple(float(v) for v in row) for row in 0.5 * (m + m.T))
def _transport(value, name: str):
"""A transport coefficient: one value (isotropic; zero: a phase inert for that
physics, an insulator), or a symmetric positive definite 3 x 3 tensor in the axes of
the crystal (three principal values, or the tensor), kept as a tuple."""
k = np.asarray(value, dtype=float)
if k.shape == (3,):
k = k[0] if np.allclose(k, k[0], rtol=1e-12, atol=0.0) else np.diag(k)
if np.ndim(k) == 0:
if not (math.isfinite(k) and k >= 0):
raise ValueError(f"{name}: must be non-negative, got {value!r}")
return float(k)
return _matrix(k, (3, 3), name)
def _index(value):
"""A complex refractive index ``n + i k``: a number, a pair ``(n, k)`` (the form of
the configurations), or one of them per wavelength; kept as a complex number or a
tuple of them."""
a = np.asarray(value)
if a.dtype.kind not in "iufc":
raise ValueError("refractive_index: n, (n, k), or a list of them per wavelength")
if not np.iscomplexobj(a):
if a.ndim == 2 and a.shape[1] == 2: # pairs (n, k) per wavelength
a = a[:, 0] + 1j * a[:, 1]
elif a.shape == (2,): # one pair
a = a[0] + 1j * a[1]
a = np.asarray(a, dtype=complex)
transparent = np.all(a.imag == 0)
if a.ndim > 1 or not np.all(np.isfinite(a)) or (transparent and np.any(a.real <= 0)):
raise ValueError(
"refractive_index: n, (n, k), or a list of pairs (n, k) per wavelength (finite, "
"n positive for a transparent phase)"
)
return complex(a) if a.ndim == 0 else tuple(complex(v) for v in a)
[docs]
def lame(young: float, poisson: float) -> tuple[float, float]:
"""Lame coefficients (lambda, mu) from Young's modulus and Poisson's ratio."""
mu = young / (2.0 * (1.0 + poisson))
lam = young * poisson / ((1.0 + poisson) * (1.0 - 2.0 * poisson))
return lam, mu
[docs]
def bulk_shear(young: float, poisson: float) -> tuple[float, float]:
"""Bulk and shear moduli (k, mu) from Young's modulus and Poisson's ratio."""
return young / (3.0 * (1.0 - 2.0 * poisson)), young / (2.0 * (1.0 + poisson))
[docs]
def young_poisson(bulk: float, shear: float) -> tuple[float, float]:
"""Young's modulus and Poisson's ratio from the bulk and shear moduli."""
young = 9.0 * bulk * shear / (3.0 * bulk + shear)
poisson = (3.0 * bulk - 2.0 * shear) / (2.0 * (3.0 * bulk + shear))
return young, poisson
[docs]
@dataclass(frozen=True)
class Material:
"""Linear material of a phase, or a void.
Isotropic materials: ``young`` and ``poisson`` define the elastic behaviour,
``conductivity`` the thermal one; a material may define either or both. Crystals:
``stiffness``, the 6 x 6 elasticity matrix in the axes of the crystal (see
:meth:`cubic`, :meth:`hexagonal`, :meth:`anisotropic`), and ``conductivities``, the
3 x 3 conductivity tensor in the same axes (or ``conductivity`` when it is isotropic).
``expansion`` is the thermal expansion: one coefficient, or (crystals) principal
values or a 3 x 3 tensor in the axes of the crystal. In a polycrystal, each grain
turns them by its orientation. ``swelling`` is likewise the strain of a unit content
of a species the phase absorbs (moisture, a solvent, lithium: the hygroscopic or
chemical expansion), for the effective swelling of
:mod:`morphogen.homogenization.poroelastic`. ``density`` (optional) gives the
effective density and specific properties. The other transport phenomena
(:data:`TRANSPORT`) each have their coefficient: ``electrical_conductivity`` (Ohm),
``permittivity`` (dielectrics), ``permeability`` (magnetostatics) and ``diffusivity``
(Fick), one value or, in the
axes of the crystal, three principal values or a 3 x 3 tensor; zero makes the phase
inert for that physics (an insulator in a conducting composite), as a void is for
all. ``refractive_index``: the complex refractive index ``n + i k`` of the phase at
optical frequencies (a number, a pair ``(n, k)``, or one pair per wavelength), for the
effective index of :mod:`morphogen.homogenization.harmonic`. ``coupling`` holds the
coefficients of the strong couplings between these physics
(:class:`~morphogen.homogenization.coupled.Coupling`: piezoelectric, piezomagnetic,
magnetoelectric, Seebeck and pyroelectric coefficients; a mapping of them), for the
coupled problems of :mod:`morphogen.homogenization.coupled`. ``viscoelasticity``
(a generalized Maxwell model), ``hyperelasticity`` (a strain energy, in finite strains)
and ``damage`` (the isotropic damage of quasi-brittle solids, Mazars' law of
concrete) give an isotropic
material one of the behaviours of :mod:`morphogen.homogenization.laws` along loading
paths (a viscoelasticity and a hyperelasticity together: finite viscoelasticity; a
``damage`` of Lemaitre or of Kachanov goes with a ``plasticity``, whose effective
stress it degrades).
``plasticity`` (isotropic materials) makes it yield along
loading paths, ``porous_plasticity`` (isotropic materials) makes it a porous plastic
material, ``crystal_plasticity`` makes it slip on the systems of its lattice,
``mfront`` gives it an MFront behaviour along them
(:class:`~morphogen.homogenization.mfront.MFrontBehaviour`; its elastic parameters
remain those of the linear problems and of the reference media) and ``learned`` a law
learned from data (:class:`~morphogen.learning.behaviour.LearnedBehaviour`; likewise).
A void carries neither stress nor flux.
"""
young: float | None = None
poisson: float | None = None
conductivity: float | None = None
void: bool = False
stiffness: tuple | None = None
conductivities: tuple | None = None
symmetry: str = "isotropic"
expansion: float | tuple | None = None
density: float | None = None
plasticity: Plasticity | None = None
crystal_plasticity: CrystalPlasticity | None = None
mfront: object | None = None
porous_plasticity: PorousPlasticity | None = None
learned: object | None = None
electrical_conductivity: float | tuple | None = None
permittivity: float | tuple | None = None
permeability: float | tuple | None = None
diffusivity: float | tuple | None = None
refractive_index: complex | tuple | None = None
coupling: object | None = None
viscoelasticity: object | None = None
hyperelasticity: object | None = None
damage: object | None = None
swelling: float | tuple | None = None
def __post_init__(self) -> None:
if self.hyperelasticity is not None and self.young is None and not self.void:
self._elasticity_of_the_law()
others = [name for name in TRANSPORT.values() if name != "conductivity"]
params = (self.young, self.poisson, self.conductivity, self.stiffness,
self.conductivities, self.refractive_index,
*(getattr(self, name) for name in others)) # fmt: skip
if self.density is not None:
if not (math.isfinite(self.density) and self.density >= 0):
raise ValueError(f"density: must be non-negative, got {self.density!r}")
object.__setattr__(self, "density", float(self.density))
if self.void:
if any(v is not None for v in params) or self.expansion is not None:
raise ValueError("a void has no elastic or thermal parameters")
if self.swelling is not None:
raise ValueError("a void does not swell")
if (
self.plasticity is not None
or self.crystal_plasticity is not None
or self.porous_plasticity is not None
):
raise ValueError("a void has no plasticity")
if self.mfront is not None:
raise ValueError("a void has no MFront behaviour")
if self.learned is not None:
raise ValueError("a void has no learned law")
if self.coupling is not None:
raise ValueError("a void has no coupling coefficients")
if any(getattr(self, name) is not None for name in _ANALYTIC):
raise ValueError("a void has no behaviour")
if self.density:
raise ValueError("a void has no density")
return
if self.expansion is not None:
if not (self.young is not None or self.stiffness is not None):
raise ValueError("expansion: a material with elastic parameters")
object.__setattr__(self, "expansion", _expansion(self.expansion))
if self.swelling is not None:
if not (self.young is not None or self.stiffness is not None):
raise ValueError("swelling: a material with elastic parameters")
object.__setattr__(self, "swelling", _expansion(self.swelling, "swelling"))
if (self.young is None) != (self.poisson is None):
raise ValueError("give both 'young' and 'poisson' (or neither)")
if self.young is not None and self.stiffness is not None:
raise ValueError("give young/poisson (isotropic) or a stiffness matrix, not both")
if self.conductivity is not None and self.conductivities is not None:
raise ValueError("give a conductivity or a conductivity tensor, not both")
if all(v is None for v in params):
raise ValueError(
"a material needs elastic parameters, a transport coefficient (conductivity, "
f"{', '.join(others)}), or several of them"
)
for name in others:
if getattr(self, name) is not None:
object.__setattr__(self, name, _transport(getattr(self, name), name))
if self.refractive_index is not None:
object.__setattr__(self, "refractive_index", _index(self.refractive_index))
if self.young is not None:
if not (math.isfinite(self.young) and self.young > 0):
raise ValueError(f"young: must be positive, got {self.young!r}")
if not -1.0 < self.poisson < 0.5:
raise ValueError(f"poisson: must lie in (-1, 0.5), got {self.poisson!r}")
if self.conductivity is not None and not (
math.isfinite(self.conductivity) and self.conductivity > 0
):
raise ValueError(f"conductivity: must be positive, got {self.conductivity!r}")
if self.stiffness is not None:
object.__setattr__(self, "stiffness", _matrix(self.stiffness, (6, 6), "stiffness"))
if self.conductivities is not None:
object.__setattr__(
self, "conductivities", _matrix(self.conductivities, (3, 3), "conductivities")
)
if self.plasticity is not None:
object.__setattr__(self, "plasticity", Plasticity.from_config(self.plasticity))
if self.young is None:
raise ValueError(
"plasticity: an isotropic elastic material (young and poisson, or bulk and "
"shear)"
)
if self.crystal_plasticity is not None:
if self.plasticity is not None:
raise ValueError("give plasticity (von Mises) or crystal_plasticity, not both")
cp = CrystalPlasticity.from_config(self.crystal_plasticity)
object.__setattr__(self, "crystal_plasticity", cp)
if self.young is None and self.stiffness is None:
raise ValueError("crystal_plasticity: a material with elastic parameters")
cp.check_softening(self.matrix("elastic")) # of its cleavage planes
if self.mfront is not None:
from morphogen.homogenization.mfront import MFrontBehaviour
if self.plasticity is not None or self.crystal_plasticity is not None:
raise ValueError("give plasticity, crystal_plasticity or mfront, one of them")
if self.young is None and self.stiffness is None:
raise ValueError(
"mfront: a material with elastic parameters (the linear problems and "
"the reference media)"
)
object.__setattr__(self, "mfront", MFrontBehaviour.from_config(self.mfront))
if self.porous_plasticity is not None:
if (
self.plasticity is not None
or self.crystal_plasticity is not None
or (self.mfront is not None)
):
raise ValueError(
"give plasticity, porous_plasticity, crystal_plasticity or mfront, one of them"
)
pp = PorousPlasticity.from_config(self.porous_plasticity)
object.__setattr__(self, "porous_plasticity", pp)
if self.young is None:
raise ValueError(
"porous_plasticity: an isotropic elastic material (young and poisson)"
)
if self.learned is not None:
from morphogen.learning.behaviour import LearnedBehaviour
behaviours = (self.plasticity, self.crystal_plasticity, self.mfront,
self.porous_plasticity) # fmt: skip
if any(b is not None for b in behaviours):
raise ValueError(
"give plasticity, porous_plasticity, crystal_plasticity, mfront or learned, "
"one of them"
)
if self.young is None and self.stiffness is None:
raise ValueError(
"learned: a material with elastic parameters (the linear problems and the "
"reference media; morphogen.learning.learned_material takes those of the "
"model)"
)
object.__setattr__(self, "learned", LearnedBehaviour.from_config(self.learned))
if self.coupling is not None:
from morphogen.homogenization.coupled import Coupling
object.__setattr__(self, "coupling", Coupling.from_config(self.coupling))
self._analytic_laws()
tensors = [self.stiffness, self.conductivities]
tensors += [v for v in (getattr(self, name) for name in others) if isinstance(v, tuple)]
if all(t is None for t in tensors):
object.__setattr__(self, "symmetry", "isotropic")
elif self.symmetry == "isotropic":
object.__setattr__(self, "symmetry", "anisotropic")
def _elasticity_of_the_law(self) -> None:
"""Young's modulus and Poisson's ratio of a hyperelastic material given by its
law alone: those of its bulk and shear moduli at the natural state."""
from morphogen.homogenization.laws import Hyperelasticity
law = Hyperelasticity.from_config(self.hyperelasticity)
bulk, shear = law.initial_moduli()
if bulk is None or shear is None:
raise ValueError(
"hyperelasticity: give young and poisson, or the bulk modulus and the "
"parameters of the law that set its shear modulus"
)
young, poisson = young_poisson(bulk, shear)
object.__setattr__(self, "young", young)
object.__setattr__(self, "poisson", poisson)
def _analytic_laws(self) -> None:
"""The behaviours of :mod:`morphogen.homogenization.laws` of the material,
checked against its elasticity and its other behaviours."""
given = [name for name in _ANALYTIC if getattr(self, name) is not None]
if not given:
return
from morphogen.homogenization import laws
read = {"viscoelasticity": laws.Viscoelasticity.from_config,
"hyperelasticity": laws.Hyperelasticity.from_config,
"damage": laws.damage_from_config} # fmt: skip
for name in given:
object.__setattr__(self, name, read[name](getattr(self, name)))
# a damage of Lemaitre or of Kachanov is that of the plasticity of the material
coupled = isinstance(self.damage, laws.DuctileDamage)
others = (None if coupled else self.plasticity, self.crystal_plasticity, self.mfront,
self.porous_plasticity, self.learned) # fmt: skip
if any(b is not None for b in others) or ("damage" in given and len(given) > 1):
raise ValueError(
"give one behaviour: plasticity, porous_plasticity, crystal_plasticity, "
"mfront, learned, damage, or viscoelasticity and hyperelasticity (alone or "
"together); a damage of Lemaitre or of Kachanov (damage.law) goes with a "
"plasticity"
)
if self.young is None:
raise ValueError(f"{given[0]}: an isotropic elastic material (young and poisson)")
if self.hyperelasticity is not None:
bulk, shear = self.hyperelasticity.initial_moduli()
k0, g0 = bulk_shear(self.young, self.poisson)
for name, own, mine in (("bulk", bulk, k0), ("shear", shear, g0)):
if own is not None and not math.isclose(own, mine, rel_tol=1e-6):
raise ValueError(
f"hyperelasticity: its {name} modulus at the natural state, {own:.6g}, "
f"is not that of young and poisson, {mine:.6g} (the linear problems); "
"leave young and poisson out, or the parameter of the law"
)
if coupled: # its plasticity: von Mises' (and Norton's flow for Kachanov's law)
laws._PlasticDamage(self.plasticity, self.damage, self.young, self.poisson)
elif self.damage is not None:
self.damage.strains(self.young)
# -- constructors ----------------------------------------------------------------
@classmethod
def from_moduli(
cls, bulk: float, shear: float, conductivity: float | None = None, *, expansion=None
):
young, poisson = young_poisson(bulk, shear)
return cls(young=young, poisson=poisson, conductivity=conductivity, expansion=expansion)
[docs]
@classmethod
def cubic(
cls,
c11: float,
c12: float,
c44: float,
*,
conductivity: float | None = None,
expansion: float | None = None,
):
"""Cubic crystal (stiffness constants in its axes); its conductivity and thermal
expansion are isotropic."""
d = np.zeros((6, 6))
d[:3, :3] = c12
d[[0, 1, 2], [0, 1, 2]] = c11
d[[3, 4, 5], [3, 4, 5]] = c44
return cls(stiffness=d, conductivity=conductivity, symmetry="cubic", expansion=expansion)
[docs]
@classmethod
def hexagonal(
cls,
c11: float,
c12: float,
c13: float,
c33: float,
c44: float,
*,
conductivity=None,
expansion=None,
):
"""Hexagonal (transversely isotropic) crystal, axis c along the third crystal
axis; ``conductivity`` and ``expansion``: one value, or (basal plane, axis c)."""
d = np.zeros((6, 6))
d[0, 0] = d[1, 1] = c11
d[2, 2] = c33
d[0, 1] = d[1, 0] = c12
d[0, 2] = d[2, 0] = d[1, 2] = d[2, 1] = c13
d[3, 3] = d[4, 4] = c44
d[5, 5] = 0.5 * (c11 - c12)
k, kt = _thermal(conductivity, uniaxial=True)
if expansion is not None and np.shape(expansion) == (2,):
expansion = (expansion[0], expansion[0], expansion[1])
return cls(
stiffness=d,
conductivity=k,
conductivities=kt,
symmetry="hexagonal",
expansion=expansion,
)
[docs]
@classmethod
def anisotropic(cls, stiffness=None, *, conductivity=None, expansion=None):
"""Crystal of any symmetry: 6 x 6 elasticity matrix (Voigt order 11, 22, 33, 23,
31, 12, engineering shear strains), conductivity and thermal expansion (one value,
three principal values along the crystal axes, or a 3 x 3 tensor), in the axes of
the crystal."""
k, kt = _thermal(conductivity, uniaxial=False)
return cls(stiffness=stiffness, conductivity=k, conductivities=kt, expansion=expansion)
# -- properties ------------------------------------------------------------------
@property
def elastic(self) -> bool:
return self.young is not None or self.stiffness is not None
@property
def thermal(self) -> bool:
return self.conductivity is not None or self.conductivities is not None
[docs]
def has(self, physics: str) -> bool:
"""Whether the material has the parameters of ``physics`` (:data:`PHYSICS`):
elastic ones, or the coefficient of a transport phenomenon."""
if not transport_physics(physics):
return self.elastic
if physics == "thermal":
return self.thermal
return getattr(self, TRANSPORT[physics]) is not None
[docs]
def inert(self, physics: str) -> bool:
"""Whether the material carries nothing for ``physics``: a void, or a phase whose
transport coefficient is zero (an insulator), left out of that problem as a pore."""
if self.void:
return True
if physics in ("elastic", "thermal"):
return False
value = getattr(self, TRANSPORT[physics])
return value is not None and not isinstance(value, tuple) and value == 0.0
@property
def isotropic(self) -> bool:
return self.symmetry == "isotropic"
@property
def plastic(self) -> bool:
"""Whether the material yields (von Mises; nonlinear loading paths)."""
return self.plasticity is not None
@property
def crystal_plastic(self) -> bool:
"""Whether the material slips on its slip systems (crystal plasticity)."""
return self.crystal_plasticity is not None
@property
def porous(self) -> bool:
"""Whether the material is porous plastic (Gurson, Rousselier, elliptic)."""
return self.porous_plasticity is not None
@property
def analytic(self) -> bool:
"""Whether the material has a behaviour of :mod:`morphogen.homogenization.laws`
(viscoelasticity, hyperelasticity, damage)."""
return any(getattr(self, name) is not None for name in _ANALYTIC)
@property
def nonlinear(self) -> bool:
"""Whether the behaviour of the material is nonlinear (loading paths)."""
external = self.mfront is not None or self.learned is not None or self.analytic
return self.plastic or self.crystal_plastic or self.porous or external
@property
def expands(self) -> bool:
"""Whether the material has a (nonzero) thermal expansion."""
return self.expansion is not None and bool(np.any(np.asarray(self.expansion) != 0))
[docs]
def oriented(self, physics: str) -> bool:
"""Whether the behaviour for ``physics`` depends on the orientation (a learned law
runs in the axes of its material, unless it is not oriented)."""
if not transport_physics(physics):
return (
self.stiffness is not None
or isinstance(self.expansion, tuple)
or isinstance(self.swelling, tuple)
or self.crystal_plasticity is not None
or (self.learned is not None and self.learned.oriented)
)
if physics == "thermal":
return self.conductivities is not None
return isinstance(getattr(self, TRANSPORT[physics]), tuple)
[docs]
def expansion_tensor(self, euler=None) -> np.ndarray:
"""Thermal expansion tensor (3 x 3, zero without expansion) in the axes of the
sample: for the orientation ``euler`` (shape (3,) or (n, 3)), or of the crystal."""
a = self.expansion if self.expansion is not None else 0.0
if not isinstance(a, tuple):
base = float(a) * np.eye(3)
if euler is not None and np.ndim(euler) == 2:
return np.repeat(base[None], len(euler), axis=0)
return base
if euler is None:
return np.array(a)
return rotate_conductivity(np.array(a), euler) # a symmetric second-order tensor
@property
def lame(self) -> tuple[float, float]:
self._need_elastic()
if self.stiffness is not None:
raise ValueError("Lame coefficients: isotropic materials only")
return lame(self.young, self.poisson)
@property
def bulk(self) -> float:
"""Bulk modulus (isotropic), or of the Voigt average of a crystal."""
return self.moduli("voigt")[0]
@property
def shear(self) -> float:
"""Shear modulus (isotropic), or of the Voigt average of a crystal."""
return self.moduli("voigt")[1]
[docs]
def moduli(self, average: str = "voigt") -> tuple[float, float]:
"""Bulk and shear moduli: exact for isotropic materials; for crystals, the
``"voigt"``, ``"reuss"`` or ``"hill"`` average over uniform orientations."""
self._need_elastic()
if self.stiffness is None:
return bulk_shear(self.young, self.poisson)
if average == "voigt":
return voigt_average(self.stiffness)
if average == "reuss":
return reuss_average(self.stiffness)
if average == "hill":
(kv, gv), (kr, gr) = voigt_average(self.stiffness), reuss_average(self.stiffness)
return 0.5 * (kv + kr), 0.5 * (gv + gr)
raise ValueError("average: 'voigt', 'reuss' or 'hill'")
[docs]
def mean_conductivity(self, average: str = "voigt", physics: str = "thermal") -> float:
"""Conductivity (isotropic), or the arithmetic (``"voigt"``) or harmonic
(``"reuss"``) mean of the principal conductivities of a crystal; likewise the
coefficient of another transport ``physics`` (:data:`TRANSPORT`)."""
k = np.linalg.eigvalsh(self.matrix(physics))
if np.all(k == k[0]):
return float(k[0])
return float(k.mean() if average == "voigt" else 1.0 / np.mean(1.0 / k))
[docs]
def matrix(self, physics: str, euler=None) -> np.ndarray:
"""Elasticity matrix (6 x 6), or conductivity tensor (3 x 3; that of any transport
``physics`` of :data:`TRANSPORT`) in the axes of the sample: for the orientation
``euler`` (Bunge angles in degrees; shape (3,) or (n, 3) for n orientations), or in
the axes of the crystal."""
if physics == "elastic":
self._need_elastic()
base = (
isotropic_matrix(*lame(self.young, self.poisson))
if self.stiffness is None
else np.array(self.stiffness)
)
rotate = rotate_stiffness
elif physics == "thermal":
self._need_thermal()
base = (
self.conductivity * np.eye(3)
if self.conductivities is None
else np.array(self.conductivities)
)
rotate = rotate_conductivity
elif physics in TRANSPORT:
value = getattr(self, TRANSPORT[physics])
if value is None:
raise ValueError(f"this material has no {TRANSPORT[physics]}")
base = np.array(value) if isinstance(value, tuple) else value * np.eye(3)
rotate = rotate_conductivity
else:
raise ValueError(f"physics: one of {PHYSICS}, got {physics!r}")
if euler is None or not self.oriented(physics):
if euler is not None and np.ndim(euler) == 2:
return np.repeat(base[None], len(euler), axis=0)
return base
return rotate(base, euler)
def _need_elastic(self) -> None:
if not self.elastic:
raise ValueError("this material has no elastic parameters")
def _need_thermal(self) -> None:
if not self.thermal:
raise ValueError("this material has no conductivity")
# -- configuration ---------------------------------------------------------------
[docs]
def to_config(self):
if self.void:
return "void"
out = {}
if self.stiffness is not None:
d = np.array(self.stiffness)
if self.symmetry == "cubic":
out["cubic"] = [float(d[0, 0]), float(d[0, 1]), float(d[3, 3])]
elif self.symmetry == "hexagonal":
out["hexagonal"] = [
float(d[i, j]) for i, j in ((0, 0), (0, 1), (0, 2), (2, 2), (3, 3))
]
else:
out["stiffness"] = d.tolist()
for key in ("young", "poisson", "conductivity"):
if getattr(self, key) is not None:
out[key] = getattr(self, key)
if self.conductivities is not None:
out["conductivity"] = np.array(self.conductivities).tolist()
if self.expansion is not None:
out["expansion"] = np.array(self.expansion).tolist()
if self.swelling is not None:
out["swelling"] = np.array(self.swelling).tolist()
if self.density is not None:
out["density"] = self.density
if self.plasticity is not None:
out["plasticity"] = self.plasticity.to_config()
if self.crystal_plasticity is not None:
out["crystal_plasticity"] = self.crystal_plasticity.to_config()
if self.mfront is not None:
out["mfront"] = self.mfront.to_config()
if self.porous_plasticity is not None:
out["porous_plasticity"] = self.porous_plasticity.to_config()
if self.learned is not None:
out["learned"] = self.learned.to_config()
for name in TRANSPORT.values():
value = getattr(self, name)
if name != "conductivity" and value is not None:
out[name] = np.array(value).tolist()
if self.refractive_index is not None:
n = np.atleast_1d(self.refractive_index)
pairs = [[float(v.real), float(v.imag)] for v in n]
out["refractive_index"] = pairs[0] if np.ndim(self.refractive_index) == 0 else pairs
if self.coupling is not None:
out["coupling"] = self.coupling.to_config()
for name in _ANALYTIC:
if getattr(self, name) is not None:
out[name] = getattr(self, name).to_config()
return out
[docs]
@classmethod
def from_config(cls, spec) -> Material:
"""``"void"``, or a mapping with young/poisson or bulk/shear (isotropic), or
``cubic: [c11, c12, c44]``, ``hexagonal: [c11, c12, c13, c33, c44]`` or
``stiffness: 6 x 6`` (crystals); and/or ``conductivity`` (one value, three
principal values or a 3 x 3 tensor, in the axes of the crystal); and
``expansion``, the thermal expansion (likewise), ``swelling``, the strain of a unit
content of an absorbed species (likewise), ``density``, ``plasticity``
(:meth:`~morphogen.homogenization.behaviours.Plasticity.from_config`),
``porous_plasticity`` (:meth:`~morphogen.homogenization.porous.PorousPlasticity.
from_config`), ``crystal_plasticity`` (:meth:`~morphogen.homogenization.crystal.
CrystalPlasticity.from_config`), ``mfront`` (:meth:`~morphogen.homogenization.mfront.
MFrontBehaviour.from_config`) and ``learned`` (the file of a learned model,
:meth:`~morphogen.learning.behaviour.LearnedBehaviour.from_config`); or ``zmat``, a
material file of Z-mat (its path, or a
mapping ``file``, ``behaviour``, ``name``, ``native``, ``porosity``:
:func:`~morphogen.homogenization.zmat.zmat_material`), with a ``conductivity`` and a
``density``."""
if isinstance(spec, Material):
return spec
if isinstance(spec, dict) and "zmat" in spec:
import dataclasses
from morphogen.homogenization.zmat import zmat_material
extra = sorted(set(spec) - {"zmat", "conductivity", "density"})
if extra:
raise ValueError(
f"zmat: the other keys of the material are {extra}; allowed "
"beside it: conductivity, density"
)
options = spec["zmat"]
options = {"file": options} if isinstance(options, str) else dict(options)
known = {"file", "behaviour", "name", "native", "directory", "porosity"}
unknown = sorted(set(options) - known)
if unknown or "file" not in options:
raise ValueError("zmat: a path, or {file, behaviour, name, native, porosity}")
base = zmat_material(options.pop("file"), **options)
values = {k: float(spec[k]) for k in ("conductivity", "density") if k in spec}
return dataclasses.replace(base, **values) if values else base
late = (
"expansion",
"swelling",
"density",
"plasticity",
"crystal_plasticity",
"mfront",
"learned",
"porous_plasticity",
"coupling",
"refractive_index",
*_ANALYTIC,
*(name for name in TRANSPORT.values() if name != "conductivity"),
)
if isinstance(spec, dict) and (set(late) & set(spec)):
import dataclasses
extra = {k: spec[k] for k in late if k in spec}
rest = {k: v for k, v in spec.items() if k not in extra}
if not rest: # a material of transport coefficients only
return cls(**extra)
base = cls.from_config(rest)
return dataclasses.replace(base, **extra)
if isinstance(spec, str):
if spec.strip().lower() in ("void", "pore", "pores", "empty"):
return VOID
raise ValueError(f"unknown material {spec!r}; use 'void' or a mapping of parameters")
if not isinstance(spec, dict):
raise ValueError(f"a material is 'void' or a mapping, got {spec!r}")
allowed = {
"young",
"poisson",
"bulk",
"shear",
"conductivity",
"expansion",
"swelling",
"density",
"plasticity",
"crystal_plasticity",
"mfront",
"learned",
"porous_plasticity",
"coupling",
"refractive_index",
*_ANALYTIC,
*TRANSPORT.values(),
}
crystal = {"cubic", "hexagonal", "stiffness"}
unknown = sorted(set(spec) - allowed - crystal)
if unknown:
raise ValueError(
f"material: unknown keys {unknown}; allowed: {sorted(allowed | crystal)}"
)
conductivity = spec.get("conductivity")
kinds = [k for k in crystal if k in spec]
if kinds:
if len(kinds) > 1 or set(spec) & {"young", "poisson", "bulk", "shear"}:
raise ValueError(
"material: give one of cubic, hexagonal, stiffness, young/poisson, bulk/shear"
)
values = spec[kinds[0]]
if kinds[0] == "cubic":
if len(values) != 3:
raise ValueError("cubic: [c11, c12, c44]")
return cls.cubic(*map(float, values), conductivity=conductivity)
if kinds[0] == "hexagonal":
if len(values) != 5:
raise ValueError("hexagonal: [c11, c12, c13, c33, c44]")
return cls.hexagonal(*map(float, values), conductivity=conductivity)
return cls.anisotropic(values, conductivity=conductivity)
if conductivity is not None and np.ndim(conductivity) > 0:
k, kt = _thermal(conductivity, uniaxial=False)
iso = {k2: float(v) for k2, v in spec.items() if k2 != "conductivity"}
if iso:
raise ValueError("material: an anisotropic conductivity needs a crystal stiffness")
return cls(conductivity=k, conductivities=kt)
values = {k: float(v) for k, v in spec.items()}
if "bulk" in values or "shear" in values:
if "young" in values or "poisson" in values:
raise ValueError("material: give young/poisson or bulk/shear, not both")
if not ("bulk" in values and "shear" in values):
raise ValueError("material: give both 'bulk' and 'shear'")
return cls.from_moduli(values["bulk"], values["shear"], values.get("conductivity"))
return cls(
young=values.get("young"),
poisson=values.get("poisson"),
conductivity=values.get("conductivity"),
)
def _thermal(conductivity, *, uniaxial: bool):
"""(isotropic value, tensor) of a conductivity given as one value, principal values
(two for a uniaxial crystal: basal plane and axis), or a 3 x 3 tensor."""
if conductivity is None:
return None, None
c = np.asarray(conductivity, dtype=float)
if c.ndim == 0:
return float(c), None
if uniaxial and c.shape == (2,):
c = np.array([c[0], c[0], c[1]])
if c.shape == (3,):
if np.allclose(c, c[0]):
return float(c[0]), None
return None, np.diag(c)
if c.shape == (3, 3):
return None, c
raise ValueError("conductivity: one value, principal values or a 3 x 3 tensor")
VOID = Material(void=True)
[docs]
def any_oriented(materials: dict[int, Material]) -> bool:
"""Whether some material depends on the orientation of its grain (anisotropic
elasticity, conductivity or expansion, or slip systems): the grains and their
orientations are then needed."""
return any(not m.void and any(m.oriented(p) for p in PHYSICS) for m in materials.values())
[docs]
def materials_from_config(spec) -> dict[int, Material]:
"""Phase -> material mapping from a configuration mapping (keys may be strings)."""
if not isinstance(spec, dict) or not spec:
raise ValueError("materials: expected a mapping phase -> material")
out = {}
for key, value in spec.items():
try:
phase = int(key)
except (TypeError, ValueError):
raise ValueError(f"materials: phase keys must be integers, got {key!r}") from None
try:
out[phase] = Material.from_config(value)
except ValueError as exc:
raise ValueError(f"materials[{phase}]: {exc}") from None
return out
[docs]
@dataclass(frozen=True)
class MaterialTable:
"""Material of every element (voxel or tetrahedron) of a sample, for one physics.
``mat[e]`` indexes ``matrices`` (-1 for voids): elasticity matrices (n, 6, 6) or
conductivity tensors (n, 3, 3) in the axes of the sample; one per phase, or one per
grain for the oriented phases of a polycrystal. ``stat[e]`` indexes ``phases``.
``eigen`` (elasticity) holds the thermal strain of each material for a unit change of
temperature (Voigt order, engineering shears), ``rotations`` the orientation of each
material (``crystal = g @ sample``; the identity for the materials of the phases that
are not oriented).
"""
mat: np.ndarray
stat: np.ndarray
matrices: np.ndarray
phases: tuple[int, ...]
isotropic: bool
eigen: np.ndarray | None = None
rotations: np.ndarray | None = None
@property
def active(self) -> np.ndarray:
return self.mat >= 0
[docs]
def material_table(
phase, materials: dict[int, Material], physics: str, *, grains=None, orientations=None
) -> MaterialTable:
"""Materials of the elements of phases ``phase`` for ``physics`` (:data:`PHYSICS`:
'elastic', or a transport phenomenon such as 'thermal' or 'electrical'). Crystals are
turned by the orientation of their grain (``grains``: grain of each element,
``orientations``: Bunge angles of each grain); without them, their axes are those of
the sample. The phases inert for the physics (voids, insulators:
:meth:`Material.inert`) have no material (``mat`` -1)."""
from morphogen.orientations import euler_to_matrix
transport = transport_physics(physics)
phase = np.asarray(phase)
if phase.dtype.kind not in "iub":
raise ValueError("homogenization needs an integer phase image, not partial volumes")
phase = phase.ravel().astype(np.int64)
present = [int(v) for v in np.unique(phase)]
missing = [p for p in present if p not in materials]
if missing:
raise ValueError(f"no material for phase(s) {missing}; phases present: {present}")
phases = tuple(present)
lookup = np.full(max(phases, default=0) + 1, -1, dtype=np.int64)
lookup[list(phases)] = np.arange(len(phases))
stat = lookup[phase]
mat = np.full(phase.size, -1, dtype=np.int64)
blocks, eigen, rotations, count, isotropic = [], [], [], 0, True
oriented = grains is not None and orientations is not None
for p in phases:
m = materials[p]
if m.inert(physics):
continue
if not transport and not m.elastic:
raise ValueError(f"phase {p}: the material has no elastic parameters")
if transport and not m.has(physics):
raise ValueError(f"phase {p}: the material has no {TRANSPORT[physics]}")
sel = np.flatnonzero(phase == p)
# an MFront behaviour may be orthotropic (a crystal) whatever the elastic parameters
# of its material: its grains keep their rotations (unused by isotropic behaviours)
mfront = physics == "elastic" and m.mfront is not None
if m.oriented(physics) or mfront:
if m.oriented(physics):
isotropic = False
if oriented:
ids, inverse = np.unique(np.asarray(grains).ravel()[sel], return_inverse=True)
euler = np.asarray(orientations, dtype=float)[ids]
blocks.append(m.matrix(physics, euler))
eigen.append(m.expansion_tensor(euler))
rotations.append(euler_to_matrix(euler).reshape(-1, 3, 3))
mat[sel] = count + inverse
count += len(ids)
continue
if m.oriented(physics):
log.info("phase %d: crystal axes along the axes of the sample (no orientations)",
p) # fmt: skip
blocks.append(m.matrix(physics)[None])
eigen.append(m.expansion_tensor()[None])
rotations.append(np.eye(3)[None])
mat[sel] = count
count += 1
d = 3 if transport else 6
matrices = np.concatenate(blocks) if blocks else np.zeros((0, d, d))
strains = None
if not transport:
from morphogen.homogenization.elements import tensor_to_voigt
a = np.concatenate(eigen) if eigen else np.zeros((0, 3, 3))
strains = np.array([tensor_to_voigt(t, strain=True) for t in a]).reshape(-1, 6)
return MaterialTable(
mat=mat,
stat=stat,
matrices=np.ascontiguousarray(matrices),
phases=phases,
isotropic=isotropic,
eigen=None if strains is None else np.ascontiguousarray(strains),
rotations=np.ascontiguousarray(
np.concatenate(rotations) if rotations else np.zeros((0, 3, 3))
),
)