Source code for morphogen.homogenization.core

"""Types shared by the solvers: boundary conditions, loadings, solutions."""

from __future__ import annotations

import dataclasses
import time
from dataclasses import dataclass, field

import numpy as np

from morphogen.homogenization.elements import tensor_to_voigt
from morphogen.homogenization.materials import TRANSPORT
from morphogen.homogenization.solvers import SolveInfo

BOUNDARY_CONDITIONS = ("kubc", "subc", "mixed", "periodic")
_ALIASES = {
    "kubc": "kubc",
    "dirichlet": "kubc",
    "kinematic": "kubc",
    "utg": "kubc",
    "subc": "subc",
    "neumann": "subc",
    "static": "subc",
    "uhf": "subc",
    "mixed": "mixed",
    "mbc": "mixed",
    "mtbc": "mixed",
    "periodic": "periodic",
    "pbc": "periodic",
}


[docs] def boundary_condition(name: str) -> str: """Canonical name of a boundary condition (accepts aliases such as 'pbc', 'utg').""" key = str(name).strip().lower() if key not in _ALIASES: raise ValueError( f"unknown boundary condition {name!r}; use one of {BOUNDARY_CONDITIONS} " "(aliases: dirichlet, utg, neumann, uhf, mbc, mtbc, pbc)" ) return _ALIASES[key]
#: Names of the Voigt components (elasticity) and of the vector components (conduction). VOIGT_NAMES = ("11", "22", "33", "23", "31", "12") VECTOR_NAMES = ("1", "2", "3") _ALIASES_VOIGT = {"32": "23", "13": "31", "21": "12"}
[docs] @dataclass(frozen=True) class Loading: """Macroscopic loading. ``kind`` is ``strain`` or ``stress`` (6 Voigt components, order 11 22 33 23 31 12, engineering shear strains) for elasticity, ``gradient`` or ``flux`` (3 components) for the transport phenomena of a scalar potential (heat or electrical conduction, dielectric or magnetic polarization, diffusion), or ``mixed``: component ``i`` is a strain (gradient) where ``controls[i]`` is true, a stress (flux) where it is false. The components of the macroscopic strain are then unknowns of the problem, dual to those of the macroscopic stress (their reactions are ``V Sigma``), as the degrees of freedom of the periodic element of Z-set (see :func:`superpose`). ``temperature`` is a uniform change of temperature from the stress-free state (elasticity: thermal strains of the materials that expand). ``physics``: ``"elastic"`` for the loadings of 6 components; for those of 3, the transport phenomenon they load (:data:`~morphogen.homogenization.materials.TRANSPORT`, ``"thermal"`` by default): a problem takes the gradients and fluxes of any of them, and :func:`~morphogen. homogenization.apparent.homogenize` solves each named loading with the problem of its physics. """ kind: str value: tuple[float, ...] controls: tuple[bool, ...] | None = None temperature: float = 0.0 physics: str | None = None def __post_init__(self) -> None: sizes = {"strain": 6, "stress": 6, "gradient": 3, "flux": 3, "mixed": (3, 6)} if self.kind not in sizes: raise ValueError(f"loading kind: one of {tuple(sizes)}, got {self.kind!r}") v = tuple(float(x) for x in np.asarray(self.value, dtype=float).ravel()) n = sizes[self.kind] if (len(v) not in n) if isinstance(n, tuple) else len(v) != n: raise ValueError(f"a {self.kind} loading has {n} components") if not all(np.isfinite(v)): raise ValueError("loading values must be finite") object.__setattr__(self, "value", v) if self.kind == "mixed": if self.controls is None or len(self.controls) != len(v): raise ValueError("a mixed loading tells which component is a strain (controls)") object.__setattr__(self, "controls", tuple(bool(c) for c in self.controls)) elif self.controls is not None: raise ValueError("controls: mixed loadings only") elastic = len(v) == 6 if self.physics is None: object.__setattr__(self, "physics", "elastic" if elastic else "thermal") elif self.physics not in (("elastic",) if elastic else tuple(TRANSPORT)): allowed = "'elastic'" if elastic else f"one of {tuple(TRANSPORT)}" raise ValueError( f"physics of a loading of {len(v)} components: {allowed}, got {self.physics!r}" ) t = float(self.temperature) if not np.isfinite(t): raise ValueError("temperature: a finite change of temperature") if t and not elastic: raise ValueError("temperature: a change of temperature loads elastic problems") object.__setattr__(self, "temperature", t)
[docs] @classmethod def strain(cls, value, *, temperature: float = 0.0) -> Loading: """Imposed strain: a 3 x 3 tensor or 6 Voigt components (engineering shears).""" v = np.asarray(value, dtype=float) v = tensor_to_voigt(v, strain=True) if v.shape == (3, 3) else v return cls("strain", v, temperature=temperature)
@classmethod def stress(cls, value, *, temperature: float = 0.0) -> Loading: v = np.asarray(value, dtype=float) v = tensor_to_voigt(v, strain=False) if v.shape == (3, 3) else v return cls("stress", v, temperature=temperature)
[docs] @classmethod def gradient(cls, value, *, physics: str = "thermal") -> Loading: """Imposed gradient of the potential of a transport phenomenon (3 components).""" return cls("gradient", value, physics=physics)
[docs] @classmethod def flux(cls, value, *, physics: str = "thermal") -> Loading: """Imposed flux of a transport phenomenon (3 components; ``flux = -K gradient``).""" return cls("flux", value, physics=physics)
[docs] @classmethod def mixed( cls, strain=None, stress=None, *, gradient=None, flux=None, temperature: float = 0.0, physics: str | None = None, ) -> Loading: """Strain prescribed on some components, stress on the others (or gradient and flux): each as a mapping (``{"11": 0.01, "23": 0}``; conduction ``{"1": ...}``) or a sequence with ``None`` where the other one is prescribed. Every component must be prescribed exactly once. Example, uniaxial tension along 1 with free lateral contraction: ``Loading.mixed(strain={"11": 0.01}, stress={"22": 0, "33": 0, "23": 0, "31": 0, "12": 0})``.""" elastic = gradient is None and flux is None if not elastic and (strain is not None or stress is not None): raise ValueError("a mixed loading: strain and stress, or gradient and flux") names = VOIGT_NAMES if elastic else VECTOR_NAMES first, second = (strain, stress) if elastic else (gradient, flux) a, b = _components(first, names), _components(second, names) both = [n for n, x, y in zip(names, a, b, strict=True) if x is not None and y is not None] neither = [n for n, x, y in zip(names, a, b, strict=True) if x is None and y is None] if both or neither: raise ValueError( f"mixed loading: components {both} prescribed twice, {neither} not prescribed" ) values = [x if x is not None else y for x, y in zip(a, b, strict=True)] controls = [x is not None for x in a] return cls( "mixed", values, controls=tuple(controls), temperature=temperature, physics=physics )
[docs] @classmethod def uniaxial(cls, axis: int, *, strain=None, stress=None, temperature: float = 0.0): """Tension along ``axis``: its strain (or stress) prescribed, the other stress components zero (free lateral contraction).""" if (strain is None) == (stress is None): raise ValueError("uniaxial loading: give the strain or the stress along the axis") name = VOIGT_NAMES[int(axis)] free = {n: 0.0 for n in VOIGT_NAMES if n != name} if strain is not None: return cls.mixed(strain={name: strain}, stress=free, temperature=temperature) values = [stress if n == name else 0.0 for n in VOIGT_NAMES] return cls.stress(values, temperature=temperature)
[docs] @classmethod def from_spec(cls, spec) -> Loading: """Loading of a configuration mapping: ``strain`` and/or ``stress`` (elasticity) or ``gradient`` and/or ``flux`` (a transport phenomenon: ``physics``, thermal by default), each a mapping of components or a full list, and ``temperature``. Components not given are free: zero stress (flux). ``{"strain": {"11": 0.01}}`` is a uniaxial tension, ``{"temperature": 1}`` a free thermal expansion, ``{"physics": "electrical", "gradient": {"1": 1}}`` a potential gradient along x, the currents across it free.""" if isinstance(spec, Loading): return spec if not isinstance(spec, dict): raise ValueError(f"a loading is a mapping, got {spec!r}") unknown = set(spec) - {"strain", "stress", "gradient", "flux", "temperature", "physics"} if unknown: raise ValueError(f"loading: unknown keys {sorted(unknown)}") physics = spec.get("physics") elastic = not ({"gradient", "flux"} & set(spec)) and physics in (None, "elastic") if not elastic and ({"strain", "stress"} & set(spec)): raise ValueError("a loading: strain and stress, or gradient and flux") names = VOIGT_NAMES if elastic else VECTOR_NAMES first = _components(spec.get("strain" if elastic else "gradient"), names) second = _components(spec.get("stress" if elastic else "flux"), names) values, controls = [], [] for name, a, b in zip(names, first, second, strict=True): if a is not None and b is not None: raise ValueError(f"loading: component {name} prescribed twice") values.append(a if a is not None else (b or 0.0)) controls.append(a is not None) temperature = float(spec.get("temperature", 0.0)) if all(controls): kind = "strain" if elastic else "gradient" elif not any(controls): kind = "stress" if elastic else "flux" else: kind = "mixed" return cls( kind, values, controls=tuple(controls) if kind == "mixed" else None, temperature=temperature, physics=physics, )
[docs] @classmethod def parse(cls, text: str) -> Loading: """Loading of a compact text: ``E11=0.01 S22=0 dT=10`` (strain ``E``, stress ``S``), ``G1=1 Q2=0`` (gradient, flux; of the transport phenomenon ``physics=electrical``, thermal by default); components not given are free.""" spec: dict = {} keys = {"E": "strain", "S": "stress", "G": "gradient", "Q": "flux"} for item in text.replace(",", " ").split(): name, _, value = item.partition("=") if not value: raise ValueError(f"loading: expected NAME=VALUE, got {item!r}") if name.lower() == "physics": spec["physics"] = value elif name.lower() in ("dt", "temperature"): spec["temperature"] = float(value) elif name[:1].upper() in keys and name[1:]: spec.setdefault(keys[name[:1].upper()], {})[name[1:]] = float(value) else: raise ValueError(f"loading: unknown component {name!r} (E11, S12, G1, Q3, dT)") return cls.from_spec(spec)
@property def array(self) -> np.ndarray: return np.array(self.value) @property def strain_controlled(self) -> np.ndarray: """Components prescribed as strains (gradients); the others are stresses (fluxes).""" if self.kind == "mixed": return np.array(self.controls) return np.full(len(self.value), self.kind in ("strain", "gradient"))
[docs] def to_dict(self) -> dict: out = {"kind": self.kind, "value": list(self.value)} if self.controls is not None: out["controls"] = list(self.controls) if self.temperature: out["temperature"] = self.temperature if self.physics not in ("elastic", "thermal"): out["physics"] = self.physics return out
def _components(spec, names) -> list: """Values of the named components (None where not given).""" out = [None] * len(names) if spec is None: return out if isinstance(spec, dict): for key, value in spec.items(): name = _ALIASES_VOIGT.get(str(key), str(key)) if name not in names: raise ValueError(f"unknown component {key!r}; use {list(names)}") out[names.index(name)] = None if value is None else float(value) return out values = list(spec) if len(values) != len(names): raise ValueError(f"expected {len(names)} components (None where not prescribed)") return [None if v is None else float(v) for v in values]
[docs] def superpose(problem, loading: Loading) -> tuple[np.ndarray, np.ndarray, SolveInfo]: """Solution of a loading that mixes the components a boundary condition prescribes (``problem.native``: strains, or stresses for static conditions) with their duals. The macroscopic native components are the extra unknowns of the problem, dual to the others: their reactions are the volume times the averages of the dual field, ``R = V Sigma`` for strain components. A linear problem condenses them exactly: the responses to unit native loadings (``problem._unit(j)``, cached) and to a unit change of temperature give the matrix ``M`` (the apparent stiffness, or compliance) and the vector ``r`` of ``dual = M x + r dT``; the unknown components of ``x`` solve the prescribed rows, and the field is the sum of the unit fields. Returns ``x``, the field and the work done.""" n = len(loading.value) native = problem.native_mask(loading) values = loading.array dt = loading.temperature x = np.where(native, values, 0.0) unknown = ~native need = np.flatnonzero(unknown | (x != 0)) units = {int(j): problem._unit(int(j)) for j in need} m = np.zeros((n, n)) for j, (_, response, _) in units.items(): m[:, j] = response r = np.zeros(n) thermal = problem._unit(-1) if dt else None if thermal is not None: r = thermal[1] if unknown.any(): rhs = values[unknown] - m[np.ix_(unknown, native)] @ x[native] - r[unknown] * dt x[unknown] = np.linalg.solve(m[np.ix_(unknown, unknown)], rhs) parts = [(x[j], units[j][0]) for j in units if x[j] != 0] if thermal is not None: parts.append((dt, thermal[0])) state = sum((c * f for c, f in parts[1:]), parts[0][0] * parts[0][1]) if parts else None infos = [u[2] for u in units.values()] + ([thermal[2]] if thermal is not None else []) info = SolveInfo( infos[0].method if infos else "none", infos[0].n_dofs if infos else 0, sum(i.iterations for i in infos), max((i.residual for i in infos), default=0.0), sum(i.setup_s for i in infos), 0.0, ) return x, state, info
[docs] @dataclass class PhaseStatistics: """Volume fraction, means and standard deviations of the fields in one phase.""" phase: int fraction: float mean: dict[str, np.ndarray] std: dict[str, np.ndarray]
[docs] def to_dict(self) -> dict: return { "phase": self.phase, "fraction": self.fraction, "mean": {k: np.asarray(v).tolist() for k, v in self.mean.items()}, "std": {k: np.asarray(v).tolist() for k, v in self.std.items()}, }
[docs] @dataclass class Solution: """Volume averages over the box of one solved problem. Elasticity: ``strain`` is the macroscopic strain ``E`` (imposed, or the average strain under SUBC), ``stress`` the average stress ``Sigma`` (voids count as zero), both 3 x 3 tensors, and ``energy`` the average of ``sigma : eps`` (twice the elastic energy density). Conduction, and every transport phenomenon of a scalar potential (``physics``: :data:`~morphogen.homogenization.materials.TRANSPORT`): ``strain`` is the macroscopic gradient ``G``, ``stress`` the average flux ``Q`` (``q = -k grad T``) and ``energy`` the average of ``k grad T . grad T``. """ physics: str bc: str loading: Loading strain: np.ndarray stress: np.ndarray energy: float material_fraction: float phases: list[PhaseStatistics] info: SolveInfo #: local fields (with ``fields=True``): element means of strain and stress (or #: gradient and flux) and energy density, plus the nodal displacement (temperature) #: of finite element solutions fields: dict[str, np.ndarray] | None = field(default=None, repr=False) #: the mesh (TetMesh, porous phases removed) or image (VoxelImage) of the fields support: object | None = field(default=None, repr=False)
[docs] def to_dict(self) -> dict: return { "physics": self.physics, "bc": self.bc, "loading": self.loading.to_dict(), "strain": self.strain.tolist(), "stress": self.stress.tolist(), "energy": self.energy, "material_fraction": self.material_fraction, "phases": [p.to_dict() for p in self.phases], "info": self.info.to_dict(), }
[docs] class MacroscopicLoadings: """Solution of macroscopic loadings by a problem that solves for the components its boundary condition prescribes (``_field(x, dt)``) and evaluates the averages of a field (``_dual``, ``_evaluate``); other components are condensed by :func:`superpose`.""" physics = "" bc = "" @property def native(self) -> str: """What the boundary condition prescribes: strains (gradients), or stresses (fluxes) for static conditions.""" if self.bc == "subc": return "stress" if self.physics == "elastic" else "flux" return "strain" if self.physics == "elastic" else "gradient"
[docs] def native_mask(self, loading: Loading) -> np.ndarray: """Components of a loading that the boundary condition prescribes directly.""" if (loading.physics == "elastic") != (self.physics == "elastic"): raise ValueError(f"the loading is {loading.physics}, the problem {self.physics}") strain = loading.strain_controlled return strain if self.native in ("strain", "gradient") else ~strain
def _unit(self, j: int): """Field, dual response and work of the unit native loading ``j`` (``-1``: a unit change of temperature), cached.""" if j not in self._units: x = np.zeros(6 if self.physics == "elastic" else 3) dt = 0.0 if j >= 0: x[j] = 1.0 else: dt = 1.0 state, info = self._field(x, dt) self._units[j] = (state, self._dual(state, x, dt), info) return self._units[j]
[docs] def solve(self, loading: Loading, *, fields: bool = False) -> Solution: """Solve for a macroscopic loading: what the boundary condition prescribes (strains, or stresses under ``subc``), or any mix of strain and stress components under ``kubc``, ``periodic`` and ``subc``, by condensation of the macroscopic unknowns (:func:`superpose`).""" t0 = time.perf_counter() native = self.native_mask(loading) if self.empty: return self._empty_solution(loading, t0) dt = loading.temperature if native.all(): x = loading.array unit = np.flatnonzero(x) if dt == 0.0 and unit.size == 1 and x[unit[0]] == 1.0: # e.g. tensors: cached state, _, info = self._unit(int(unit[0])) info = dataclasses.replace(info) elif dt == 1.0 and not x.any(): state, _, info = self._unit(-1) info = dataclasses.replace(info) else: state, info = self._field(x, dt) else: if self.bc == "mixed": raise ValueError( "mixed boundary conditions prescribe a strain (gradient): stress or mixed " "loadings need kubc, periodic or subc conditions" ) x, state, info = superpose(self, loading) return self._evaluate(loading, state, x, dt, info, fields, t0)