Source code for morphogen.homogenization.paths

"""Loading paths: macroscopic loadings that vary in time, and the responses to them.

A path gives, at increasing times, the value of each macroscopic component, prescribed
as a strain or as a stress (the other one is then an unknown, solved for), and the
change of temperature; values vary linearly in time between them. The first time is
the natural state: zero strain, stress and change of temperature. Uniaxial tension at
a strain rate, creep under a stress, relaxation, cycles or thermal histories are
paths.
"""

from __future__ import annotations

import itertools
import math
from dataclasses import dataclass, field

import numpy as np

from morphogen.homogenization.core import _ALIASES, _ALIASES_VOIGT, VOIGT_NAMES


def _index(key) -> int:
    """Voigt index of a component name (``"11"`` ... ``"12"``, or ``"21"`` ...)."""
    name = _ALIASES_VOIGT.get(str(key), str(key))
    if name not in VOIGT_NAMES:
        raise ValueError(f"unknown component {key!r}; use {list(VOIGT_NAMES)}")
    return VOIGT_NAMES.index(name)


def _series(value, n_times: int, name: str) -> list[float]:
    """Values of a component at the times: a list (the first one may be omitted, it is
    zero), or one value reached at the end of the first segment and held."""
    if np.ndim(value) == 0:
        v = float(value)
        return [0.0] + [v] * (n_times - 1)
    values = [float(v) for v in value]
    if len(values) == n_times - 1:
        values = [0.0, *values]
    if len(values) != n_times:
        raise ValueError(f"{name}: one value per time ({n_times}), or one value held")
    return values


[docs] @dataclass(frozen=True) class LoadingPath: """History of a macroscopic loading of elasticity. At the ``times`` (increasing; the first one is the natural state), ``values`` gives the six Voigt components (11, 22, 33, 23, 31, 12; engineering shear strains), prescribed as strains where ``controls`` is true and as stresses elsewhere, and ``temperature`` the change of temperature. Each segment between two times is divided into ``increments`` steps (the solver divides a step further when it does not converge). """ times: tuple[float, ...] values: tuple[tuple[float, ...], ...] controls: tuple[bool, ...] temperature: tuple[float, ...] = () increments: tuple[int, ...] = () def __post_init__(self) -> None: times = tuple(float(t) for t in self.times) if len(times) < 2 or not all(math.isfinite(t) for t in times): raise ValueError("times: at least two finite times") if any(b <= a for a, b in itertools.pairwise(times)): raise ValueError("times: strictly increasing") values = np.asarray(self.values, dtype=float) if values.shape != (len(times), 6) or not np.all(np.isfinite(values)): raise ValueError("values: six finite components at each time") if np.any(values[0] != 0): raise ValueError("a path starts from the natural state: zero values at the first time") controls = tuple(bool(c) for c in self.controls) if len(controls) != 6: raise ValueError("controls: one per component (true: strain, false: stress)") temps = tuple(float(t) for t in self.temperature) or (0.0,) * len(times) if len(temps) != len(times) or not all(math.isfinite(t) for t in temps): raise ValueError("temperature: one finite value per time") if temps[0] != 0.0: raise ValueError("temperature: zero change at the first time (natural state)") incs = self.increments or (10,) incs = tuple(int(i) for i in (incs * (len(times) - 1) if len(incs) == 1 else incs)) if len(incs) != len(times) - 1 or min(incs) < 1: raise ValueError("increments: a positive number per segment (or one for all)") object.__setattr__(self, "times", times) object.__setattr__(self, "values", tuple(tuple(row) for row in values.tolist())) object.__setattr__(self, "controls", controls) object.__setattr__(self, "temperature", temps) object.__setattr__(self, "increments", incs) # -- construction -------------------------------------------------------------------
[docs] @classmethod def from_spec(cls, spec) -> LoadingPath: """Path of a configuration mapping: ``times``, ``increments`` (one per segment, or one for all), ``strain`` and ``stress`` (component -> values at the times, or one value reached at the end of the first segment and held; the first value, zero, may be omitted) and ``temperature`` (likewise). Components not given are free: zero stress. ``{"times": [0, 10], "strain": {"11": 0.02}}`` is a uniaxial tension at the strain rate 0.002.""" if isinstance(spec, LoadingPath): return spec if not isinstance(spec, dict): raise ValueError(f"a path is a mapping, got {spec!r}") unknown = set(spec) - {"times", "increments", "strain", "stress", "temperature"} if unknown: raise ValueError(f"path: unknown keys {sorted(unknown)}") if "times" not in spec: raise ValueError("path: give the times") times = [float(t) for t in spec["times"]] n = len(times) def series(key): raw = spec.get(key) or {} if not isinstance(raw, dict): raise ValueError(f"path.{key}: a mapping component -> values") return {_index(k): _series(v, n, f"path.{key}.{k}") for k, v in raw.items()} strains, stresses = series("strain"), series("stress") twice = sorted(set(strains) & set(stresses)) if twice: raise ValueError(f"path: components {[VOIGT_NAMES[i] for i in twice]} given twice") values = np.zeros((n, 6)) controls = [False] * 6 for i, v in strains.items(): values[:, i] = v controls[i] = True for i, v in stresses.items(): values[:, i] = v temperature = spec.get("temperature") temps = () if temperature is None else tuple(_series(temperature, n, "path.temperature")) incs = spec.get("increments", 10) incs = (int(incs),) if np.ndim(incs) == 0 else tuple(int(i) for i in incs) return cls(times, values, controls, temps, incs)
[docs] @classmethod def parse(cls, text: str) -> LoadingPath: """Path of a compact text: ``t=0,10,20 n=10 E11=0,0.02,0 S12=0 dT=0,50,50``: the times ``t``, the increments ``n`` (one, or one per segment), strain ``E`` and stress ``S`` components and the change of temperature ``dT`` at the times (or one value reached at the end of the first segment and held); the components not given are free (zero stress).""" spec: dict = {} for item in text.replace(";", " ").split(): name, _, value = item.partition("=") if not value: raise ValueError(f"path: expected NAME=VALUES, got {item!r}") numbers = [float(v) for v in value.split(",") if v.strip()] one = numbers[0] if len(numbers) == 1 else numbers if name == "t": spec["times"] = numbers elif name == "n": spec["increments"] = [int(v) for v in numbers] if len(numbers) > 1 else int(one) elif name.lower() in ("dt", "temperature"): spec["temperature"] = one elif name[:1] in ("E", "S") and name[1:]: key = "strain" if name[0] == "E" else "stress" spec.setdefault(key, {})[name[1:]] = one else: raise ValueError(f"path: unknown item {name!r} (t, n, E11, S12, dT)") return cls.from_spec(spec)
[docs] @classmethod def uniaxial( cls, axis: int, *, times, strain=None, stress=None, increments=10, temperature=None ) -> LoadingPath: """Tension (compression) along ``axis``: its strain (or stress) at the ``times``, the other stress components zero.""" if (strain is None) == (stress is None): raise ValueError("uniaxial path: give the strain or the stress along the axis") name = VOIGT_NAMES[int(axis)] spec = {"times": list(times), "increments": increments} spec["strain" if strain is not None else "stress"] = { name: strain if strain is not None else stress } if temperature is not None: spec["temperature"] = temperature return cls.from_spec(spec)
# -- evaluation -------------------------------------------------------------------- @property def strain_controlled(self) -> np.ndarray: return np.array(self.controls) @property def duration(self) -> float: return self.times[-1] - self.times[0]
[docs] def at(self, t: float) -> tuple[np.ndarray, float]: """Values of the components and change of temperature at the time ``t``.""" values = np.asarray(self.values) v = np.array([np.interp(t, self.times, values[:, i]) for i in range(6)]) return v, float(np.interp(t, self.times, self.temperature))
[docs] def schedule(self) -> np.ndarray: """Times at the end of the planned steps.""" ends = [ np.linspace(a, b, n + 1)[1:] for a, b, n in zip(self.times[:-1], self.times[1:], self.increments, strict=True) ] return np.concatenate(ends)
[docs] def to_dict(self) -> dict: series = {n: [r[i] for r in self.values] for i, n in enumerate(VOIGT_NAMES)} strain = {n: v for i, (n, v) in enumerate(series.items()) if self.controls[i]} stress = {n: v for i, (n, v) in enumerate(series.items()) if not self.controls[i]} out = {"times": list(self.times), "increments": list(self.increments)} if strain: out["strain"] = strain if stress: out["stress"] = stress if any(self.temperature): out["temperature"] = list(self.temperature) return out
[docs] @dataclass class PathResult: """Macroscopic response of a volume element (or of a material point) along a path. ``times`` (n), ``strain`` and ``stress`` (n x 6, Voigt; engineering shear strains), ``temperature`` and ``plastic`` (the mean cumulated plastic strain of the material) at each converged step, the first one the natural state; ``phases``: for each phase, its mean ``stress``, ``strain`` and ``plastic`` strain at each step; ``iterations``: Newton iterations of each step; ``fields``: element fields at some times (``time -> name -> array``) on ``support``. In finite strains (``kinematics="finite"``), ``strain`` holds the components 11, 22, 33, 23, 13, 12 of the upper triangular macroscopic displacement gradient ``F - I`` (nominal strains and simple shears) and ``stress`` those of the mean first Piola-Kirchhoff stress (nominal stresses); ``cauchy`` holds the Cauchy (true) stress and ``log_strain`` the logarithmic (true) strain, and each phase its mean ``cauchy`` stress. With porous plastic materials, ``porosity`` holds the mean porosity of their points at each step, and each porous phase its mean ``porosity``. ``series``: the other curves that a solver records at each step (name -> values: the area in contact of the walls of a cell that close, :class:`~morphogen.contact.periodic.ContactCell`), columns of :meth:`rows` and quantities of :meth:`value` as the others. ``orientation``: for a material point that is a crystal, in finite strains or where its twins turn it, the Bunge angles (degrees) of its lattice at each step (n x 3; the columns ``phi1``, ``Phi`` and ``phi2`` of :meth:`rows`). The lattices of the crystals of a volume element are in its ``fields`` (``orientation``): :meth:`texture`. """ name: str bc: str path: LoadingPath times: np.ndarray strain: np.ndarray stress: np.ndarray temperature: np.ndarray plastic: np.ndarray phases: dict = field(default_factory=dict) iterations: np.ndarray = field(default_factory=lambda: np.zeros(0, dtype=int)) info: dict = field(default_factory=dict) fields: dict = field(default_factory=dict, repr=False) support: object | None = field(default=None, repr=False) kinematics: str = "small" cauchy: np.ndarray | None = None log_strain: np.ndarray | None = None porosity: np.ndarray | None = None series: dict = field(default_factory=dict) #: other scalar results of the path, by name (the fatigue of its cycle): final values #: (:meth:`components`) and quantities of :meth:`value` scalars: dict = field(default_factory=dict) orientation: np.ndarray | None = None @property def n_steps(self) -> int: return len(self.times) - 1 @property def finite(self) -> bool: return self.kinematics == "finite" def _true(self, k: int) -> dict[str, float]: """Logarithmic strains ``LE11 ...`` and Cauchy stresses ``TS11 ...`` of step ``k`` (finite strains).""" if self.log_strain is None or self.cauchy is None: return {} out = {f"LE{n}": float(v) for n, v in zip(VOIGT_NAMES, self.log_strain[k], strict=True)} out.update({f"TS{n}": float(v) for n, v in zip(VOIGT_NAMES, self.cauchy[k], strict=True)}) return out def _row(self, k: int) -> dict: """The curves at step ``k`` (see :meth:`rows`).""" row = {"time": float(self.times[k])} strain, stress = self.strain[k], self.stress[k] row.update({f"E{n}": float(v) for n, v in zip(VOIGT_NAMES, strain, strict=True)}) row.update({f"S{n}": float(v) for n, v in zip(VOIGT_NAMES, stress, strict=True)}) row.update(self._true(k)) row["temperature"] = float(self.temperature[k]) row["p"] = float(self.plastic[k]) if self.porosity is not None: row["f"] = float(self.porosity[k]) for phase, series in self.phases.items(): for n, v in zip(VOIGT_NAMES, series["stress"][k], strict=True): row[f"S{n}_{phase}"] = float(v) if "cauchy" in series: for n, v in zip(VOIGT_NAMES, series["cauchy"][k], strict=True): row[f"TS{n}_{phase}"] = float(v) row[f"p_{phase}"] = float(series["plastic"][k]) if "porosity" in series: row[f"f_{phase}"] = float(series["porosity"][k]) row.update({name: float(values[k]) for name, values in self.series.items()}) if self.orientation is not None: angles = zip(("phi1", "Phi", "phi2"), self.orientation[k], strict=True) row.update({name: float(v) for name, v in angles}) return row
[docs] def rows(self) -> list[dict]: """The curves, one row per step: time, ``E11 ... E12``, ``S11 ... S12``, in finite strains the logarithmic strains ``LE11 ...`` and the Cauchy stresses ``TS11 ...``, the change of temperature, the mean cumulated plastic strain (and porosity ``f``), the mean stress (and Cauchy stress) and plastic strain (and porosity) of each phase, and the other curves recorded (``series``).""" return [self._row(k) for k in range(len(self.times))]
[docs] def driven(self) -> int: """The component of the loading: that whose prescribed strain varies most along the path (of its prescribed stresses, without a prescribed strain).""" values = np.asarray(self.path.values) controls = self.path.strain_controlled spans = np.ptp(values, axis=0) if controls.any(): spans = np.where(controls, spans, -1.0) return int(np.argmax(spans))
[docs] def texture(self, time: float | None = None): """The lattices of the crystals at a time of the path (the nearest of those of its fields; the last one by default): their orientations (Bunge angles in degrees, m x 3) and their volumes (m), for the pole figures of :mod:`morphogen.texture`. The crystals are the elements of a mesh or the voxels of an image whose fields have an ``orientation`` (crystals in finite strains, or whose twins turn their lattices; the paths run with ``fields``), or the material point of :attr:`orientation`.""" if self.orientation is not None and not self.fields: k = len(self.times) - 1 if time is None else int(np.argmin(np.abs(self.times - time))) return self.orientation[k : k + 1].copy(), np.ones(1) if not self.fields: raise ValueError("texture: the path kept no fields (run it with fields)") at = max(self.fields) if time is None else min(self.fields, key=lambda t: abs(t - time)) arrays = self.fields[at] if "orientation" not in arrays: raise ValueError( "texture: the fields have no orientation of the lattices (those of crystals " "in finite strains, or whose twins turn them)" ) euler = np.asarray(arrays["orientation"], dtype=float).reshape(-1, 3) volumes = getattr(self.support, "volumes", None) weights = np.asarray(volumes(), dtype=float) if callable(volumes) else np.ones(len(euler)) if weights.shape != (len(euler),): raise ValueError("texture: the fields and their support do not match") crystals = ~np.isnan(euler).any(axis=1) return euler[crystals], weights[crystals]
[docs] def strength(self, component: int | None = None, upto: int | None = None) -> float: """The largest stress (in absolute value) reached along the path, up to the step ``upto``, of a component: by default that of the loading (:meth:`driven`). The strength of a volume element that softens (damage, fracture), its flow stress otherwise.""" c = self.driven() if component is None else int(component) stop = len(self.times) if upto is None else int(upto) + 1 return float(np.abs(self.stress[:stop, c]).max())
[docs] def work(self, upto: int | None = None) -> float: """The work of the macroscopic stress per unit volume along the path, ``int Sigma : dE`` (trapezoids over the steps; nominal stresses and strains in finite strains), up to the step ``upto``: the energy stored and dissipated; at the end of a path that breaks the volume element, its work of fracture.""" stop = len(self.times) if upto is None else int(upto) + 1 mean = 0.5 * (self.stress[1:stop] + self.stress[: stop - 1]) return float(np.einsum("ti,ti->", mean, np.diff(self.strain[:stop], axis=0)))
[docs] def value(self, name: str, time: float | None = None) -> float: """Value of a quantity of the curves (a column of :meth:`rows`: ``E11``, ``S11``, ``TS11``, ``p``, ``S11_1``...) at the end of the path, or at ``time``: the end of one of its steps; or ``strength`` and ``work``, the largest stress of the loading and the work done up to there (:meth:`strength`, :meth:`work`).""" k = len(self.times) - 1 if time is not None: hits = np.flatnonzero(np.isclose(self.times, float(time), rtol=1e-9, atol=1e-12)) if hits.size == 0: raise ValueError(f"path {self.name!r}: no step ends at the time {time:g}") k = int(hits[-1]) if name == "strength": return self.strength(upto=k) if name == "work": return self.work(upto=k) if name in self.scalars: return float(self.scalars[name]) row = self._row(k) if name not in row or name == "time": columns = [c for c in row if c != "time"] + ["strength", "work"] raise ValueError(f"path {self.name!r}: unknown quantity {name!r}; use one of {columns}") return row[name]
[docs] def components(self) -> dict[str, float]: """Final values: ``E11 ... E12``, ``S11 ... S12`` (in finite strains also ``LE11 ...`` and ``TS11 ...``), the mean cumulated plastic strain ``p`` and the other curves recorded (``series``).""" out = {f"E{n}": float(v) for n, v in zip(VOIGT_NAMES, self.strain[-1], strict=True)} out.update({f"S{n}": float(v) for n, v in zip(VOIGT_NAMES, self.stress[-1], strict=True)}) out.update(self._true(len(self.times) - 1)) out["p"] = float(self.plastic[-1]) if self.porosity is not None: out["f"] = float(self.porosity[-1]) out.update({name: float(values[-1]) for name, values in self.series.items()}) out.update({name: float(value) for name, value in self.scalars.items()}) return out
[docs] def row(self) -> dict: """Summary record (long format): final values and solver data.""" out = {"property": self.name, "bc": self.bc, **self.components()} out["steps"] = self.n_steps out["iterations"] = int(np.sum(self.iterations)) out.update(self.info) return out
[docs] @dataclass(frozen=True) class PathQuantity: """A quantity of the curves of a loading path, for the statistics of RVE studies: a column of :meth:`PathResult.rows` (``S11``, ``TS11``, ``p``, ``S11_1``...) at the end of the path, or at ``time``, the end of one of its steps (the flow stress at a given strain, say), under every boundary condition, or under ``bc`` only. Written ``<path>.<quantity>`` or ``<path>.<quantity>@<time>``: ``tension.S11@5`` is ``S11`` of the path ``tension`` at the time 5; ``.<bc>`` follows for one boundary condition (``tension.S11@5.periodic``). """ path: str quantity: str time: float | None = None bc: str | None = None @classmethod def parse(cls, text) -> PathQuantity: name = str(text).strip() bc = None head, dot, tail = name.rpartition(".") if dot and tail.lower() in _ALIASES: name, bc = head, _ALIASES[tail.lower()] body, at, when = name.partition("@") path, dot, quantity = body.partition(".") if not (dot and path and quantity) or "." in quantity: raise ValueError( f"{text!r}: a quantity of a path is <path>.<quantity>[@<time>][.<bc>], " "e.g. tension.S11@5" ) time = None if at: try: time = float(when) except ValueError: raise ValueError(f"{text!r}: a time after @, e.g. tension.S11@5") from None return cls(path, quantity, time, bc) @property def name(self) -> str: """Name of the series of the quantity (without the boundary condition).""" name = f"{self.path}.{self.quantity}" return name if self.time is None else f"{name}@{self.time:.12g}" @property def key(self) -> str: return self.name if self.bc is None else f"{self.name}.{self.bc}"
[docs] def of(self, result: PathResult) -> float: """The quantity in a response to the path.""" return result.value(self.quantity, self.time)