"""Post-processing of apparent properties: compliance, engineering constants and
anisotropy of stiffness tensors, macroscopic values of porous media, normalized and
specific values.
Stiffness and compliance. Every output of an elastic stiffness ``C`` gives its compliance
``S = C^-1`` beside it, in the same notation (:data:`NOTATION`): morphoGen's Voigt order
``11, 22, 33, 23, 31, 12`` with engineering shears (``11, 22, 12`` for plane problems,
:data:`PLANE_NOTATION`), so that ``S_11 = 1/E_1``, ``S_12 = -nu_12/E_1 = -nu_21/E_2`` and
``S_44 = 1/G_23``, ``S_55 = 1/G_31``, ``S_66 = 1/G_12`` for an orthotropic material in its
axes (:func:`engineering_constants`). TFEL (MFront) and Abaqus order their shears ``12,
13, 23``: a component ``C_44`` of morphoGen is their ``C_66``. The Mandel form of a
stiffness is ``W C W``, ``W = diag(1, 1, 1, √2, √2, √2)``, and of a compliance ``W^-1 S
W^-1``.
Macroscopic values of porous media. Meshes (or images) without their pores give the
macroscopic stress as the average over the whole volume element, the pores carrying
none: ``Sigma = phi <sigma>_s``, the average over the solid times the solid fraction
``phi`` (as in the homogenization notice of Z-set). The macroscopic strain is not the
average over the solid: it is the prescribed strain, or the macroscopic unknowns solved
for under stress or mixed loadings (:func:`morphogen.homogenization.core.superpose`), as
the degrees of freedom of a periodic element. Solutions hold both (``Solution.strain``,
``Solution.stress``) and the averages over each phase (``Solution.phases``).
Normalized values. For a property ``P`` (bulk, shear or Young's modulus, conductivity)
of a microstructure of solid fraction ``phi``, whose solid phases have the properties
``P_i`` and the fractions ``f_i``:
* relative: ``P / P_s``, with ``P_s = sum f_i P_i / phi`` the property of the solid (of
its single phase for a porous medium);
* normalized: ``P / (phi P_s) = P / sum f_i P_i``, the property per unit of solid
fraction, relative to the Voigt bound (rule of mixtures), which bounds it by 1;
* specific: ``P / rho`` with the effective density ``rho = sum f_i rho_i``.
Relative properties against the relative density ``phi`` are the coordinates of the
normalized Ashby charts (:mod:`morphogen.results`); Gibson & Ashby (1997) scalings read
``E / E_s ~ phi^n`` (``n = 1`` stretching-dominated, 2 bending-dominated foams).
"""
from __future__ import annotations
import numpy as np
from morphogen.homogenization.materials import TRANSPORT, Material
#: Mandel weights of the Voigt order (sqrt(2) on the shears)
_W = np.array([1.0, 1.0, 1.0, np.sqrt(2.0), np.sqrt(2.0), np.sqrt(2.0)])
#: morphoGen's Voigt order of the rows and columns of stiffnesses and compliances, in space
#: and in the plane
VOIGT_ORDER = ("11", "22", "33", "23", "31", "12")
PLANE_ORDER = ("11", "22", "12")
#: The notation of a stiffness and of its compliance, stated by the outputs that give them
NOTATION = (
"Voigt, order 11 22 33 23 31 12 (TFEL and Abaqus: 11 22 33 12 13 23), engineering "
"shears; S = C^-1 in the same notation"
)
PLANE_NOTATION = "Voigt, order 11 22 12, engineering shear; S = C^-1 in the same notation"
#: The smallest eigenvalue of a stiffness, relative to its largest, at or below which the
#: stiffness is singular to round-off (a direction without stiffness, as across layers of
#: void, at 1e-17 of the rest), or not positive definite: it has no compliance
_ROUND_OFF = 10.0 * np.finfo(float).eps
[docs]
def compliance(stiffness) -> np.ndarray:
"""The compliance ``S = C^-1`` of a Voigt stiffness (6 x 6, order 11 22 33 23 31 12; 3
x 3, order 11 22 12, for plane problems; engineering shears), in the same notation:
``S_11 = 1/E_1``, ``S_12 = -nu_12/E_1``, ``S_44 = 1/G_23`` (see the module). A
stiffness singular to round-off (its smallest eigenvalue within 10 machine epsilons of
its largest, or negative: a direction without stiffness, as across layers of void) has
none: NaN, not the inverse of its round-off; an exactly singular one raises
:class:`numpy.linalg.LinAlgError`; one only badly scaled keeps its inverse (a design
stiff along its fibres, 3, whose plane is as stiff as its void, 1e-12: 1e-14)."""
c = np.asarray(stiffness, dtype=float)
if c.shape not in ((6, 6), (3, 3)):
raise ValueError(f"stiffness: a 6 x 6 matrix (3 x 3 in the plane), got shape {c.shape}")
s = np.linalg.inv(c)
if np.all(np.isfinite(c)):
w = np.linalg.eigvalsh(0.5 * (c + c.T))
if not w[0] > _ROUND_OFF * w[-1]:
return np.full_like(c, np.nan)
return s
[docs]
def notation(stiffness) -> str:
"""The notation of a stiffness and of its compliance (:data:`NOTATION`;
:data:`PLANE_NOTATION` for a 3 x 3 one)."""
return PLANE_NOTATION if np.shape(stiffness) == (3, 3) else NOTATION
[docs]
def matrix_entries(matrix, prefix: str) -> dict[str, float]:
"""The entries of the upper triangle of a symmetric matrix as ``<prefix><i><j>``, the
indices from 1 in the Voigt order (``C11`` ... ``C66``, ``S11`` ... ``S66``): the
columns of the tables of results."""
m = np.asarray(matrix, dtype=float)
n = len(m)
return {f"{prefix}{i + 1}{j + 1}": float(m[i, j]) for i in range(n) for j in range(i, n)}
[docs]
def engineering_constants(stiffness) -> dict[str, float]:
"""Young's moduli ``E1, E2, E3``, Poisson's ratios ``nu_ij`` (contraction along
``j`` under a stress along ``i``: ``-S_ij / S_ii``) and shear moduli ``G23, G31,
G12`` of a Voigt stiffness (order 11 22 33 23 31 12, engineering shears)."""
s = np.linalg.inv(np.asarray(stiffness, dtype=float))
out = {f"E{i + 1}": float(1.0 / s[i, i]) for i in range(3)}
for i in range(3):
for j in range(3):
if i != j:
out[f"nu{i + 1}{j + 1}"] = float(-s[i, j] / s[i, i])
for k, name in zip((3, 4, 5), ("G23", "G31", "G12"), strict=True):
out[name] = float(1.0 / s[k, k])
return out
#: The Voigt index of the shear of each plane of the axes
_SHEAR = {(0, 1): 5, (1, 2): 3, (0, 2): 4}
[docs]
def directional_modulus(stiffness, angles, *, plane=(0, 1), plane_strain: bool = True):
"""The Young's modulus ``1 / (n n : S : n n)`` along the directions ``n = cos(theta)
e_a + sin(theta) e_b`` of ``angles`` (radians) in the plane of the axes ``(a, b)`` of a
Voigt stiffness (6 x 6), under a uniaxial stress along ``n``: in plane strain (``S``
the inverse of the in-plane block ``a, b, ab`` of the stiffness: prisms across the
plane, as planar images one voxel thick) or in plane stress (``S`` the in-plane block
of the compliance, the other stresses free). A plane stiffness (3 x 3, Voigt 11, 22,
12) is taken in plane strain as it is. The ratio of its least to its largest value
over the angles is the elastic anisotropy ``eta_E = E_min / E_max`` of Both et al.
(2026)."""
c = np.asarray(stiffness, dtype=float)
a, b = sorted(int(v) for v in plane)
if c.shape == (3, 3):
s = np.linalg.inv(c)
elif c.shape == (6, 6):
if (a, b) not in _SHEAR:
raise ValueError("plane: two distinct axes among 0, 1 and 2")
k = [a, b, _SHEAR[(a, b)]]
s = np.linalg.inv(c[np.ix_(k, k)]) if plane_strain else np.linalg.inv(c)[np.ix_(k, k)]
else:
raise ValueError("stiffness: a Voigt matrix of 6 x 6, or 3 x 3 in the plane")
if tuple(int(v) for v in plane) == (b, a): # the angles from the second axis given
s = s[np.ix_([1, 0, 2], [1, 0, 2])]
t = np.asarray(angles, dtype=float)
v = np.stack([np.cos(t) ** 2, np.sin(t) ** 2, np.cos(t) * np.sin(t)], axis=-1)
return 1.0 / np.einsum("...i,ij,...j->...", v, s, v)
[docs]
def sphere_directions(count: int = 2000) -> np.ndarray:
"""``count`` unit vectors spread evenly over the half-sphere ``z > 0`` (a Fibonacci
lattice): the directions of space up to their sign, as axes of moduli."""
k = np.arange(int(count)) + 0.5
z = k / int(count)
phi = np.pi * (1.0 + np.sqrt(5.0)) * k
r = np.sqrt(1.0 - z * z)
return np.column_stack([r * np.cos(phi), r * np.sin(phi), z])
[docs]
def spatial_modulus(stiffness, directions) -> np.ndarray:
"""The Young's modulus ``1 / (n n : S : n n)`` along unit vectors ``n`` of space
(``(m, 3)``, normalized here) of a Voigt stiffness (6 x 6, engineering shears), under a
uniaxial stress along ``n``: the plane-stress :func:`directional_modulus` in every
plane. Its least and largest values over :func:`sphere_directions` give the elastic
anisotropy ``eta_E = E_min / E_max`` of a 3D sample (Both et al. 2026)."""
c = np.asarray(stiffness, dtype=float)
if c.shape != (6, 6):
raise ValueError("stiffness: a Voigt matrix of 6 x 6")
s = np.linalg.inv(c)
n = np.asarray(directions, dtype=float).reshape(-1, 3)
n = n / np.linalg.norm(n, axis=1, keepdims=True)
v = np.column_stack([n[:, 0] ** 2, n[:, 1] ** 2, n[:, 2] ** 2,
n[:, 1] * n[:, 2], n[:, 2] * n[:, 0], n[:, 0] * n[:, 1]]) # fmt: skip
return 1.0 / np.einsum("mi,ij,mj->m", v, s, v)
[docs]
def anisotropy(stiffness) -> dict[str, float]:
"""Voigt and Reuss bulk and shear moduli of a Voigt stiffness, the universal
anisotropy index ``A_U = 5 G_V / G_R + K_V / K_R - 6`` (Ranganathan & Ostoja-
Starzewski 2008, zero for isotropy), the Zener ratio ``2 C44 / (C11 - C12)`` of its
mean cubic part (1 for isotropy) and the relative distance to the nearest isotropic
stiffness (its Voigt average, in the Mandel norm)."""
c = np.asarray(stiffness, dtype=float)
s = np.linalg.inv(c)
a, b, d = np.trace(c[:3, :3]), c[0, 1] + c[0, 2] + c[1, 2], np.trace(c[3:, 3:])
kv, gv = (a + 2.0 * b) / 9.0, (a - b + 3.0 * d) / 15.0
a, b, d = np.trace(s[:3, :3]), s[0, 1] + s[0, 2] + s[1, 2], np.trace(s[3:, 3:])
kr, gr = 1.0 / (a + 2.0 * b), 15.0 / (4.0 * a - 4.0 * b + 3.0 * d)
c11 = np.trace(c[:3, :3]) / 3.0
c12 = (c[0, 1] + c[0, 2] + c[1, 2]) / 3.0
c44 = np.trace(c[3:, 3:]) / 3.0
iso = np.zeros((6, 6))
iso[:3, :3] = kv - 2.0 * gv / 3.0
iso[[0, 1, 2], [0, 1, 2]] += 2.0 * gv
iso[[3, 4, 5], [3, 4, 5]] = gv
mandel = _W[:, None] * _W[None, :]
return {
"bulk_voigt": float(kv),
"bulk_reuss": float(kr),
"shear_voigt": float(gv),
"shear_reuss": float(gr),
"universal_anisotropy": float(5.0 * gv / gr + kv / kr - 6.0),
"zener_ratio": float(2.0 * c44 / (c11 - c12)) if c11 != c12 else float("nan"),
"isotropy_distance": float(np.linalg.norm((c - iso) * mandel) / np.linalg.norm(c * mandel)),
}
[docs]
def solid_fraction(fractions: dict[int, float], materials: dict[int, Material]) -> float:
"""Volume fraction of the phases that are not voids."""
return float(sum(f for p, f in fractions.items() if not materials[p].void))
[docs]
def effective_density(fractions: dict[int, float], materials: dict[int, Material]):
"""``sum f_i rho_i`` (exact), or None when a solid phase has no density."""
solid = [p for p in fractions if not materials[p].void]
if not solid or any(materials[p].density is None for p in solid):
return None
return float(sum(fractions[p] * materials[p].density for p in solid))
def _property(material: Material, name: str) -> float | None:
"""Property of a phase: exact for isotropic materials, the Hill average of a crystal
(uniform orientations)."""
if name in _TRANSPORT: # the coefficient of a transport phenomenon
physics = _TRANSPORT[name]
if not material.has(physics):
return None
voigt = material.mean_conductivity("voigt", physics)
if voigt == 0.0: # an insulator
return 0.0
return 0.5 * (voigt + material.mean_conductivity("reuss", physics))
if not material.elastic:
return None
k, g = material.moduli("hill")
return {"bulk_modulus": k, "shear_modulus": g, "young": 9.0 * k * g / (3.0 * k + g)}[name]
#: the physics of the scalar property of each transport phenomenon
_TRANSPORT = {name: physics for physics, name in TRANSPORT.items()}
#: base property of the scalar results: apparent properties, and entries of tensors
_BASE = {
"bulk_modulus": "bulk_modulus",
"shear_modulus": "shear_modulus",
"conductivity": "conductivity",
"E1": "young",
"E2": "young",
"E3": "young",
"G23": "shear_modulus",
"G31": "shear_modulus",
"G12": "shear_modulus",
"mean": "conductivity",
}
def _base(key: str) -> str | None:
parts = key.split(".")
if parts[0] in ("bulk_modulus", "shear_modulus", *_TRANSPORT) and len(parts) == 2:
return parts[0]
if parts[0] == "stiffness" and len(parts) == 3 and parts[2] != "mean":
return _BASE.get(parts[2])
scalar = parts[0].removesuffix("_tensor") # the mean of the tensor of a transport
if scalar != parts[0] and scalar in _TRANSPORT and len(parts) == 3 and parts[2] == "mean":
return scalar
return None
[docs]
def normalized_values(
values: dict, fractions: dict[int, float], materials: dict[int, Material]
) -> dict[str, float]:
"""Solid fraction, effective density, and the relative, normalized and specific
values (see the module) of the apparent properties in ``values`` (keys
``<property>.<bc>``, and ``stiffness.<bc>.E1``... for the entries of tensors)."""
phi = solid_fraction(fractions, materials)
rho = effective_density(fractions, materials)
out: dict[str, float] = {"solid_fraction": phi}
if rho is not None:
out["density"] = rho
solid = [p for p in fractions if not materials[p].void and fractions[p] > 0]
for key, value in values.items():
base = _base(key)
if base is None or not isinstance(value, float):
continue
props = [_property(materials[p], base) for p in solid]
if not props or any(v is None for v in props):
continue
voigt = sum(fractions[p] * v for p, v in zip(solid, props, strict=True))
if voigt > 0 and phi > 0:
out[f"{key}.relative"] = value * phi / voigt
out[f"{key}.normalized"] = value / voigt
if rho:
out[f"{key}.specific"] = value / rho
return out