Source code for morphogen.viz.workflow

"""Figures and videos of the realizations of a run (the ``visualization`` section of the
configurations): the chain from the morphological model to its voxel image, its
conforming mesh and the fields of its homogenization.

A view shows one object of each realization (``of``):

* ``image``: the voxel image; figures: its three middle sections (``kind: sections``) or
  the surface of a ``phase`` (``surface``, VTK); videos: the three sections moving
  together (``orthoslices``, the default, as in Avizo), a section sweeping along ``axis``
  (``sections``) or the surface of a phase turning (``surface``);
* ``labels``: the cell labels of tessellations and grain structures (sections,
  orthoslices);
* ``mesh``: the conforming mesh coloured by phase (``color: none``: uniform); figures: a
  view; videos: a turntable (``turntable``) or a cross-section sweeping along ``axis``
  (``sweep``);
* a result of the homogenization, ``<property>.<bc>`` (bulk_modulus, shear_modulus,
  conductivity), ``<loading>.<bc>`` or ``<path>.<bc>``: the field ``color`` (by default the
  von Mises stress, or the norm of the heat flux) on the mesh deformed by its displacement
  magnified ``magnification`` times (by default the largest displacement drawn as a tenth
  of the mesh, and the true deformation along loading paths in finite strains; ``part:
  fluctuation`` removes the macroscopic part ``E x``), cut by the plane ``section: (axis,
  fraction)``; on the voxels of the FFT solver, the sections of the field. Videos of
  properties and loadings grow the load (``wave: ramp``) or make it oscillate (``wave:
  sine``); those of loading paths follow their steps from the natural state (``frames``:
  interpolated between the steps). Figures of loading paths draw their curves (``kind:
  curves``, the default) or their field at the end (``kind: field``).

The fields are named as in the files of the fields: ``von_mises``, ``energy_density``,
``stress_11`` ... ``stress_12`` and ``strain_11`` ... (Voigt order 11, 22, 33, 23, 31, 12),
``displacement`` (its norm); ``flux``, ``gradient`` (norms), ``flux_1`` ...,
``dissipation``, ``temperature``; along paths ``p`` (cumulated plastic strain) and
``plastic_strain_11`` ...

Files: ``<stem>_<name>.<format>``, with the name given (``name``) or made of the object,
the kind and the field: ``spheres_0000_image_orthoslices.mp4``,
``spheres_0000_shear_modulus_periodic_von_mises.png``.
"""

from __future__ import annotations

import importlib.util
import logging
from pathlib import Path

import numpy as np

log = logging.getLogger("morphogen")

COMPONENTS = ("11", "22", "33", "23", "31", "12")
_TENSORS = tuple(f"{n}_{c}" for n in ("stress", "strain") for c in COMPONENTS)
#: The fields colouring the views of the results, by kind of result
FIELDS = {
    "elastic": ("von_mises", "energy_density", "displacement", *_TENSORS),
    "thermal": (
        "flux",
        "gradient",
        "dissipation",
        "temperature",
        *(f"flux_{d}" for d in "123"),
        *(f"gradient_{d}" for d in "123"),
    ),
    "path": (
        "von_mises",
        "p",
        "displacement",
        *_TENSORS,
        *(f"plastic_strain_{c}" for c in COMPONENTS),
        # of the crystals that twin or cleave
        "twin_fraction",
        "twin_reoriented",
        "twin_misorientation",
        "cleavage_opening",
        "cleavage_damage",
        "cleavage_microdamage",
        # of the cells whose interfaces debond, and of the fatigue of a cycle
        "interface_damage",
        "interface_opening",
        "fatigue_utilization",
        "fatigue_equivalent",
        "fatigue_amplitude",
        "fatigue_hydrostatic_max",
        # of the criterion of cleavage of Beremin
        "beremin_stress",
    ),
}
DEFAULT_FIELD = {"elastic": "von_mises", "thermal": "flux", "path": "von_mises"}
#: The fields of the nodes of finite element meshes (the displacement of the loading
#: paths of the FFT solver is at the centres of the voxels)
NODAL = ("displacement", "temperature")
#: The kinds of the figures and of the videos of each object, the first ones the defaults
KINDS = {
    "image": (("sections", "surface"), ("orthoslices", "sections", "surface")),
    "labels": (("sections",), ("orthoslices", "sections")),
    "mesh": (("view",), ("turntable", "sweep")),
    "result": (("field",), ("field",)),
    "path": (("curves", "field"), ("field",)),
}
_VECTORS = ("displacement", "flux", "gradient")


[docs] def von_mises(stress) -> np.ndarray: """Von Mises stress of stresses in the Voigt order (last axis; tensor shears).""" s = np.asarray(stress, dtype=float) mean = s[..., :3].sum(axis=-1) / 3.0 dev2 = np.sum((s[..., :3] - mean[..., None]) ** 2, axis=-1) dev2 += 2.0 * np.sum(s[..., 3:] ** 2, axis=-1) return np.sqrt(1.5 * dev2)
[docs] def element_arrays(fields: dict, physics: str) -> dict[str, np.ndarray]: """The element fields of a solution (``Solution.fields``) by name: energy density, von Mises stress, stress and strain components; or dissipation, flux and gradient components.""" out: dict[str, np.ndarray] = {} if physics == "elastic": eps, sig = fields["strain"], fields["stress"] out["energy_density"] = fields["energy"] out["von_mises"] = von_mises(sig) for i, name in enumerate(COMPONENTS): out[f"stress_{name}"] = sig[..., i] for i, name in enumerate(COMPONENTS): out[f"strain_{name}"] = eps[..., i] else: grad, flux = fields["gradient"], fields["flux"] out["dissipation"] = fields["dissipation"] for d in range(3): out[f"flux_{d + 1}"] = flux[..., d] for d in range(3): out[f"gradient_{d + 1}"] = grad[..., d] return out
[docs] def solution_fields(solution) -> dict[str, np.ndarray]: """All the named fields of a solution kept with ``fields=True``: those of :func:`element_arrays`, the nodal displacement or temperature of finite elements, and the flux and gradient vectors.""" fields = solution.fields out = element_arrays(fields, solution.physics) if solution.physics == "elastic": if "displacement" in fields: out["displacement"] = np.asarray(fields["displacement"]) else: out["flux"] = np.asarray(fields["flux"]) out["gradient"] = np.asarray(fields["gradient"]) if "temperature" in fields: out["temperature"] = np.asarray(fields["temperature"]) return out
[docs] def path_fields(arrays: dict) -> dict[str, np.ndarray]: """The named fields of a loading path at one time (``PathResult.fields[t]``).""" out = {"von_mises": np.asarray(arrays["mises"]), "p": np.asarray(arrays["p"])} for name in ("stress", "strain", "plastic_strain"): values = np.asarray(arrays[name]) for i, c in enumerate(COMPONENTS): out[f"{name}_{c}"] = values[..., i] if "displacement" in arrays: out["displacement"] = np.asarray(arrays["displacement"]) for name in FIELDS["path"]: # the other scalar fields that a solver or a study adds if name in arrays and name not in out: out[name] = np.asarray(arrays[name]) return out
[docs] def field_values(named: dict, name: str) -> np.ndarray: """The values of the field ``name`` among the named fields (vectors by their norm).""" if name not in named: raise ValueError(f"visualization: no field {name!r} here (fields: {', '.join(named)})") values = np.asarray(named[name], dtype=float) if name in _VECTORS and values.shape[-1] == 3: values = np.linalg.norm(values, axis=-1) return values
[docs] def requirements(spec) -> set[str]: """What the views of a :class:`~morphogen.config.VisualizationSpec` need: ``"vtk"`` (3D views), ``"ffmpeg"`` (.mp4), ``"matplotlib"`` (figures).""" out = {"matplotlib"} if spec.views else set() # the colormaps if any(view.vtk for view in spec.views): out.add("vtk") if any("mp4" in v.formats for v in spec.videos): out.add("ffmpeg") return out
[docs] def check(spec) -> None: """Raise an error naming what the views need and is missing (before a run).""" from morphogen.viz.video import ffmpeg_path, vtk_can_render missing = [] for need in sorted(requirements(spec)): if need == "ffmpeg": if ffmpeg_path() is None: missing.append( "ffmpeg for .mp4 videos (on the PATH, MORPHOGEN_FFMPEG, or pip install " "imageio-ffmpeg; or the format gif)" ) elif importlib.util.find_spec(need) is None: missing.append( "VTK for the 3D views (pip install 'morphogen[video]')" if need == "vtk" else "matplotlib for the figures (pip install 'morphogen[plot]')" ) elif need == "vtk" and not vtk_can_render(): missing.append( "a display for the 3D views of VTK (X, EGL or OSMesa; on a headless machine, " "run under xvfb-run)" ) if missing: raise RuntimeError("visualization: missing " + "; ".join(missing))
# -- views ------------------------------------------------------------------------------- def _camera(spec) -> dict: """The camera of the 3D views of a visualization section.""" return {"elevation": spec.elevation, "azimuth": spec.azimuth} def _save_rgb(rgb: np.ndarray, path: Path) -> Path: from PIL import Image path.parent.mkdir(parents=True, exist_ok=True) options = {"compression": "tiff_lzw"} if path.suffix.lower() in (".tif", ".tiff") else {} Image.fromarray(np.ascontiguousarray(rgb[..., :3])).save(path, **options) return path def _source(view, image, labels): source = labels if view.of == "labels" else image if source is None: what = "cell labels (tessellations, grain structures)" if view.of == "labels" else "image" raise ValueError(f"visualization: this realization has no {what}") return source def _result(results, key: str): if not results or key not in results: raise ValueError( f"visualization: no result {key!r} (results: {', '.join(sorted(results or {}))})" ) return results[key] def _points(support) -> np.ndarray: """The nodes of a mesh, or the centres of the voxels of an image (nx, ny, nz, 3).""" from morphogen.mesh.tetra import TetMesh if isinstance(support, TetMesh): return support.nodes axes = [ support.origin[d] + (np.arange(n) + 0.5) * support.spacing[d] for d, n in enumerate(support.data.shape) ] return np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1) def _macro(res, time) -> np.ndarray: """The macroscopic strain (displacement gradient in finite strains) of a result.""" from morphogen.homogenization.paths import PathResult if not isinstance(res, PathResult): return np.asarray(res.solution.strain, dtype=float) k = int(np.argmin(np.abs(np.asarray(res.times) - time))) if res.finite: from morphogen.homogenization.finite import gradient_of return np.asarray(gradient_of(res.strain[k]), dtype=float).reshape(3, 3) from morphogen.homogenization.elements import voigt_to_tensor return voigt_to_tensor(res.strain[k], strain=True) def _snapshot(res, view, time=None): """The support, the named fields and the displacement (``None`` without one) of a result (of a loading path: at ``time``).""" from morphogen.homogenization.paths import PathResult if isinstance(res, PathResult): if time not in res.fields: raise ValueError(f"visualization: {view.of} kept no fields at time {time}") support, named = res.support, path_fields(res.fields[time]) else: sol = res.solution if sol.fields is None: raise ValueError(f"visualization: {view.of} kept no fields") support, named = sol.support, solution_fields(sol) u = named.get("displacement") if u is not None and view.part == "fluctuation": u = u - _points(support) @ _macro(res, time).T return support, named, u def _magnification(view, res): from morphogen.homogenization.paths import PathResult if view.magnification is None and isinstance(res, PathResult) and res.finite: return 1.0 if view.part == "total" else None # the true deformation return view.magnification def _figure(spec, view, path: Path, image, labels, mesh, results) -> Path: from morphogen.homogenization.paths import PathResult from morphogen.mesh.tetra import TetMesh from morphogen.viz import video as vv from morphogen.viz.export import save_figure from morphogen.viz.figures import field_figure, path_figure, slices_figure cmap = view.cmap or spec.cmap if view.of in ("image", "labels"): source = _source(view, image, labels) if view.kind == "surface": frame = vv.turntable_frames( source, phase=view.phase, frames=1, size=spec.size, **_camera(spec) )[0] return _save_rgb(frame, path) return save_figure(slices_figure(source, labels=view.of == "labels"), path, dpi=spec.dpi) if view.of == "mesh": if mesh is None: raise ValueError("visualization: this realization has no conforming mesh") field = None if view.color == "none" else "phase" return _save_rgb(vv.deformed_view(mesh, None, field, size=spec.size, **_camera(spec)), path) res = _result(results, view.of) title = f"{view.of}: {view.color}" if view.kind == "field" else view.of if isinstance(res, PathResult) and view.kind == "curves": return save_figure(path_figure(res, title=title), path, dpi=spec.dpi) time = max(res.fields) if isinstance(res, PathResult) and res.fields else None support, named, u = _snapshot(res, view, time) values = field_values(named, view.color) if isinstance(support, TetMesh): rgb = vv.deformed_view( support, u, values, magnification=_magnification(view, res), section=view.section, size=spec.size, **_camera(spec), cmap=cmap, clim=view.clim, title=view.color, ) return _save_rgb(rgb, path) fig = field_figure(values, cmap=cmap, clim=view.clim, title=title, label=view.color) return save_figure(fig, path, dpi=spec.dpi) def _natural(values: np.ndarray) -> np.ndarray: """The natural state of a field: zero, NaN kept (the pores of images).""" return np.where(np.isnan(values), np.nan, 0.0) def _frames(spec, view, image, labels, mesh, results) -> list[np.ndarray]: from morphogen.homogenization.paths import PathResult from morphogen.mesh.tetra import TetMesh from morphogen.viz import video as vv cmap = view.cmap or spec.cmap if view.of in ("image", "labels"): source = _source(view, image, labels) flags = {"labels": True} if view.of == "labels" else {} if view.kind == "orthoslices": size = max(spec.size) // 2 return vv.orthoslice_frames( source, frames=view.frames or 48, size=size, cmap=cmap, **flags ) if view.kind == "sections": return vv.section_frames(source, view.axis, size=max(spec.size), cmap=cmap, **flags) return vv.turntable_frames( source, phase=view.phase, frames=view.frames or 72, size=spec.size, **_camera(spec) ) if view.of == "mesh": if mesh is None: raise ValueError("visualization: this realization has no conforming mesh") field = None if view.color == "none" else "phase" if view.kind == "turntable": return vv.turntable_frames( mesh, field=field, frames=view.frames or 72, size=spec.size, **_camera(spec) ) return vv.section_sweep_frames( mesh, field, axis=view.axis, frames=view.frames or 48, size=spec.size, **_camera(spec) ) res = _result(results, view.of) clim = view.clim if isinstance(res, PathResult): times = sorted(res.fields) if not times: raise ValueError(f"visualization: {view.of} kept no fields") snaps = [_snapshot(res, view, t) for t in times] support = snaps[0][0] values = [field_values(named, view.color) for _, named, _ in snaps] values.insert(0, _natural(values[0])) captions = [f"t = {t:g}" for t in (float(res.times[0]), *times)] if isinstance(support, TetMesh): us = [np.zeros_like(support.nodes) if u is None else u for _, _, u in snaps] us.insert(0, np.zeros_like(support.nodes)) return vv.history_frames( support, us, values, frames=view.frames, magnification=_magnification(view, res), section=view.section, size=spec.size, **_camera(spec), cmap=cmap, clim=clim, title=view.color, captions=captions, ) lo, hi = clim or (None, None) return vv.time_section_frames( values, view.axis, size=max(spec.size), cmap=cmap, vmin=lo, vmax=hi, captions=captions, label=view.color, ) support, named, u = _snapshot(res, view) values = field_values(named, view.color) if isinstance(support, TetMesh): if u is None: # conduction: no deformation, a cross-section sweeping through return vv.section_sweep_frames( support, values, axis=view.axis, frames=view.frames or 48, size=spec.size, **_camera(spec), cmap=cmap, clim=clim, title=view.color, ) return vv.field_frames( support, u, values, magnification=view.magnification, frames=view.frames or 48, wave=view.wave, section=view.section, size=spec.size, **_camera(spec), cmap=cmap, clim=clim, title=view.color, scaling=vv.field_scaling(view.color), ) lo, hi = clim or (None, None) return vv.section_frames( values, view.axis, size=max(spec.size), cmap=cmap, vmin=lo, vmax=hi, labels=False, bar=True, label=view.color, )
[docs] def visualize(spec, stem: str, outdir, *, image=None, labels=None, mesh=None, results=None): """Write the figures and videos of ``spec`` (a :class:`~morphogen.config.VisualizationSpec`) for one realization: its voxel ``image``, cell ``labels``, conforming ``mesh`` and the ``results`` of its homogenization (kept with their fields); returns the paths written.""" from morphogen.viz.video import write_video outdir = Path(outdir) written = [] for view in spec.figures: for fmt in view.formats: path = outdir / f"{stem}_{view.label}.{fmt}" written.append(_figure(spec, view, path, image, labels, mesh, results)) log.info("figure %s", path.name) for view in spec.videos: frames = _frames(spec, view, image, labels, mesh, results) for fmt in view.formats: path = outdir / (f"{stem}_{view.label}" + ("_frames" if fmt == "frames" else f".{fmt}")) fps = view.fps or spec.fps written.append(write_video(frames, path, fps=fps, mode=view.mode, repeat=view.repeat)) log.info("video %s (%d frames)", path.name, len(frames)) return written