Source code for morphogen.homogenization.fft

"""FFT-based homogenization of periodic voxel images.

Each voxel is a trilinear hexahedron and the fluctuation ``w`` of ``u = E x + w``
(``T = G . x + w``) is periodic on the grid. The equilibrium equations ``K w = f`` are
solved by conjugate gradients without assembling ``K`` (each product loops over the
voxels), preconditioned by the inverse of the stiffness ``K0`` of a homogeneous
reference medium. ``K0`` is a circulant operator: it is diagonal (3 x 3 blocks in
elasticity) in Fourier space, and its inverse costs a few FFTs (Schneider, Merkert &
Kabel 2017, "FFT-based homogenization for microstructures discretized by linear
hexahedral elements", Int. J. Numer. Meth. Engng 109, 1461-1489). This is a
Lippmann-Schwinger scheme whose discrete Green operator is that of trilinear elements:
the fields have no ringing artefacts, and pores (zero stiffness) are handled without an
ersatz material.

The number of iterations grows with the contrast between the phases (as its square
root, at worst); the memory is a few vectors of the size of the grid. With
``device="gpu"`` the conjugate gradients run on the GPU (:mod:`morphogen.homogenization.
gpu`); the solutions are those of the CPU to the tolerance of the iterations.
"""

from __future__ import annotations

import logging
import time

import numpy as np
from numba import njit, prange
from scipy import fft as sfft

from morphogen import gpu, settings
from morphogen.homogenization import kernels
from morphogen.homogenization.core import (
    Loading,
    MacroscopicLoadings,
    PhaseStatistics,
    Solution,
    boundary_condition,
)
from morphogen.homogenization.elements import hex_element, voigt_to_tensor
from morphogen.homogenization.materials import Material, material_table, transport_physics
from morphogen.homogenization.solvers import NEGLIGIBLE, SolveInfo, conjugate_gradient, norm
from morphogen.image import VoxelImage

log = logging.getLogger("morphogen")


[docs] @njit(parallel=True, cache=True) def apply_operator(nx, ny, nz, nd, group, mats, w, out): """out = K w on the periodic grid; ``mats[g]`` is the element matrix of material ``g`` of the voxels with ``group`` g (-1: no stiffness). Loops over nodes, so no atomics are needed.""" corners = kernels.CORNERS size = 8 * nd for n in prange(nx * ny * nz): k = n % nz j = (n // nz) % ny i = n // (ny * nz) acc = np.zeros(3) we = np.empty(size) for a in range(2): ei = i - a if i - a >= 0 else nx - 1 for b in range(2): ej = j - b if j - b >= 0 else ny - 1 for c in range(2): ek = k - c if k - c >= 0 else nz - 1 g = group[(ei * ny + ej) * nz + ek] if g < 0: continue ln = kernels.CORNER_INDEX[a, b, c] for q in range(8): qi = ei + corners[q, 0] qj = ej + corners[q, 1] qk = ek + corners[q, 2] if qi == nx: qi = 0 if qj == ny: qj = 0 if qk == nz: qk = 0 m = (qi * ny + qj) * nz + qk for c2 in range(nd): we[q * nd + c2] = w[m * nd + c2] mat = mats[g] for r in range(nd): row = ln * nd + r s = 0.0 for col in range(size): s += mat[row, col] * we[col] acc[r] += s for r in range(nd): out[n * nd + r] = acc[r]
def _stencil(k: np.ndarray, nd: int) -> np.ndarray: """Blocks (3, 3, 3, nd, nd) of the homogeneous operator of element matrix ``k`` for node offsets -1, 0, 1.""" blocks = np.zeros((3, 3, 3, nd, nd)) corners = kernels.CORNERS for ln in range(8): for q in range(8): off = corners[q] - corners[ln] + 1 rows = slice(ln * nd, ln * nd + nd) cols = slice(q * nd, q * nd + nd) blocks[off[0], off[1], off[2]] += k[rows, cols] return blocks
[docs] class FourierPreconditioner: """Inverse of a homogeneous reference operator, applied in Fourier space: the element matrix ``coef_a * ka + coef_b * kb`` (see :meth:`from_element`).""" def __init__(self, shape, ka, kb, coef_a: float, coef_b: float, nd: int): self._build(shape, coef_a * np.asarray(ka) + coef_b * np.asarray(kb), nd)
[docs] @classmethod def from_element(cls, shape, k_ref, nd: int) -> FourierPreconditioner: """Preconditioner of the homogeneous medium of element matrix ``k_ref``.""" self = cls.__new__(cls) self._build(shape, np.asarray(k_ref, dtype=float), nd) return self
def _build(self, shape, k, nd: int) -> None: self.shape = tuple(int(s) for s in shape) self.nd = nd self.blocks = np.ascontiguousarray(_stencil(k, nd)) nx, ny, nz = self.shape # the mean of the fluctuation is set to zero: the inverse is zero at frequency 0 self.inverse = np.empty((nx, ny, nz // 2 + 1, nd, nd), dtype=np.complex128) kernels.fourier_inverse(nx, ny, nz, self.blocks, self.inverse) def __call__(self, r: np.ndarray) -> np.ndarray: nd, shape = self.nd, self.shape field = r.reshape(*shape, nd) workers = settings.workers() hat = sfft.rfftn(field, axes=(0, 1, 2), workers=workers) hat = np.einsum("...ij,...j->...i", self.inverse, hat) return sfft.irfftn(hat, s=shape, axes=(0, 1, 2), workers=workers).reshape(-1)
class _FFTProblem(MacroscopicLoadings): physics = "" nd = 0 def __init__( self, image: VoxelImage, materials: dict[int, Material], bc: str = "periodic", *, tol: float = 1e-8, maxiter: int | None = None, reference: tuple[float, float] | None = None, grains=None, orientations=None, device: str = "cpu", physics: str | None = None, ): if not isinstance(image, VoxelImage): raise TypeError("the FFT solver needs a VoxelImage") if physics is not None: self._set_physics(physics) self.device = gpu.device_of(device) if boundary_condition(bc) != "periodic": raise ValueError( "the FFT solver of voxel images uses periodic boundary conditions; for " "kubc, mixed or subc conditions, mesh the microstructure (finite elements, " "see morphogen.mesh.conforming)" ) if image.data.dtype.kind not in "iub": raise ValueError("homogenization needs an integer phase image") if not image.periodic: log.info("FFT solver: the image is treated as the cell of a periodic medium") if grains is not None: grains = np.asarray(grains.data if isinstance(grains, VoxelImage) else grains) if grains.shape != image.shape: raise ValueError("grains: one grain label per voxel of the image") self.bc = "periodic" self.image = image self.shape = image.shape self.box_volume = float(image.volume) self.table = material_table( image.data, materials, self.physics, grains=grains, orientations=orientations ) # material of every voxel (-1: void), phase of every voxel (statistics) self.mat = np.ascontiguousarray(self.table.mat) self.stat = np.ascontiguousarray(self.table.stat) self.active = self.mat >= 0 self.empty = not np.any(self.active) or not np.any(self.table.matrices) if self.empty: log.warning("no load-carrying material in the sample: its apparent properties are zero") self.element = hex_element(tuple(image.spacing)) self.element_matrices = self._element_matrices(self.table.matrices) self.counts = np.bincount(self.mat[self.active], minlength=len(self.table.matrices)) self.tol = float(tol) self.maxiter = maxiter self.reference = reference self._preconditioner = None self._units: dict = {} def _set_physics(self, physics: str) -> None: """The physics of the problem, among those its class solves (elasticity; any of the transport phenomena of a scalar potential for the thermal problems).""" if transport_physics(physics) != (self.nd == 1): kind = "a transport phenomenon" if self.nd == 1 else "'elastic'" raise ValueError(f"{type(self).__name__}: physics {kind}, got {physics!r}") self.physics = physics def _element_matrices(self, matrices) -> np.ndarray: raise NotImplementedError def _reference_element(self) -> np.ndarray: raise NotImplementedError def _load_scale(self, loads) -> float: """Norm of the element loads (without cancellation between elements).""" return float(np.sqrt(np.sum(self.counts * np.sum(loads * loads, axis=1)))) def _solve(self, rhs, scale: float): nx, ny, nz = self.shape nd = self.nd if norm(np.ravel(rhs)) <= NEGLIGIBLE * scale: return np.zeros_like(rhs), SolveInfo("fft", rhs.size, 0, 0.0, 0.0, 0.0) if self._preconditioner is None and self.device != "gpu": self._preconditioner = FourierPreconditioner.from_element( self.shape, self._reference_element(), nd ) mats = self.element_matrices def apply(v): out = np.empty_like(v) apply_operator(nx, ny, nz, nd, self.mat, mats, v, out) return out maxiter = self.maxiter or 20 * int(max(self.shape)) + 1000 t0 = time.perf_counter() if self.device == "gpu": from morphogen.homogenization import gpu as gpu_solver x, it, res = gpu_solver.solve_linear(self, rhs, self.tol, maxiter) else: x, it, res = conjugate_gradient(apply, self._preconditioner, rhs, self.tol, maxiter) if res > self.tol: log.warning("FFT solver stopped at relative residual %.2e after %d iterations", res, it) method = "fft-gpu" if self.device == "gpu" else "fft" return x, SolveInfo(method, rhs.size, it, res, 0.0, time.perf_counter() - t0) def _phase_statistics(self, sums, n_mean, names, sizes) -> list[PhaseStatistics]: out = [] vol_index = sums.shape[1] - 1 for g, phase in enumerate(self.table.phases): vol = sums[g, vol_index] if vol <= 0: continue mean, std, pos = {}, {}, 0 for name, size in zip(names, sizes, strict=True): m = sums[g, pos : pos + size] / vol sq = sums[g, n_mean + pos : n_mean + pos + size] / vol mean[name] = m std[name] = np.sqrt(np.maximum(sq - m * m, 0.0)) pos += size out.append(PhaseStatistics(phase, float(vol / self.box_volume), mean, std)) return out def _empty_solution(self, loading: Loading, t0: float) -> Solution: elastic = self.physics == "elastic" values = np.where(loading.strain_controlled, loading.array, 0.0) # the phases inert for the physics (voids, insulators) fill the image strain = voigt_to_tensor(values, strain=True) if elastic else values return Solution( physics=self.physics, bc=self.bc, loading=loading, strain=strain, stress=np.zeros((3, 3)) if elastic else np.zeros(3), energy=0.0, material_fraction=0.0, phases=[], info=SolveInfo("none", 0, 0, 0.0, 0.0, time.perf_counter() - t0), ) #: Mandel weights: sqrt(2) on the shear components _MANDEL = np.array([1.0, 1.0, 1.0, np.sqrt(2.0), np.sqrt(2.0), np.sqrt(2.0)])
[docs] def reference_moduli(matrices, isotropic: bool) -> tuple[float, float]: """Lame coefficients of the isotropic reference medium of the FFT preconditioner: the mean of the extreme moduli of the materials (bulk moduli and shear stiffnesses of the crystals).""" d = np.asarray(matrices, dtype=float) if isotropic: lam, mu = d[:, 0, 1], d[:, 3, 3] return 0.5 * (lam.min() + lam.max()), 0.5 * (mu.min() + mu.max()) m = d * _MANDEL[None, :, None] * _MANDEL[None, None, :] n = np.array([1.0, 1.0, 1.0, 0.0, 0.0, 0.0]) / np.sqrt(3.0) bulk = np.einsum("i,mij,j->m", n, m, n) / 3.0 proj = np.eye(6) - np.outer(n, n) dev = np.linalg.eigvalsh(proj @ m @ proj)[:, 1:] / 2.0 # without the hydrostatic mode k0 = 0.5 * (bulk.min() + bulk.max()) mu0 = 0.5 * (dev.min() + dev.max()) return k0 - 2.0 * mu0 / 3.0, mu0
[docs] class FFTElasticProblem(_FFTProblem): """Periodic linear elasticity of a voxel image (FFT-preconditioned CG); crystals are turned by the orientations of their grains (``grains``: label image).""" physics = "elastic" nd = 3 def _element_matrices(self, matrices) -> np.ndarray: b = self.element.b_gauss k = self.element.weight * np.einsum("gri,mrs,gsj->mij", b, matrices, b, optimize=True) return np.ascontiguousarray(0.5 * (k + np.swapaxes(k, 1, 2))) def _reference_element(self) -> np.ndarray: if self.reference is not None: lam, mu = self.reference else: used = self.table.matrices[self.counts > 0] lam, mu = reference_moduli(used, self.table.isotropic) return self.element.stiffness(lam, mu) def _thermal_loads(self) -> np.ndarray: """Element load vectors of a unit change of temperature, ``int B^T D alpha``.""" el = self.element sig = np.einsum("mrs,ms->mr", self.table.matrices, self.table.eigen) return el.weight * np.einsum("grc,mr->mc", el.b_gauss, sig) def _field(self, x: np.ndarray, dt: float): """Periodic fluctuation for the macroscopic strain ``x`` (Voigt order) and the change of temperature ``dt``.""" nx, ny, nz = self.shape u_loc = self.element.affine_displacement(x) loads = self.element_matrices @ u_loc if dt: loads = loads - dt * self._thermal_loads() loads = np.ascontiguousarray(loads) dof = np.arange(3 * nx * ny * nz, dtype=np.int64) rhs = kernels.element_load(nx, ny, nz, True, self.mat, dof, 3, loads, dof.size) return self._solve(rhs, self._load_scale(loads)) def _sums(self, w, x, dt) -> np.ndarray: el = self.element nx, ny, nz = self.shape return kernels.elastic_sums( nx, ny, nz, True, self.mat, self.stat, len(self.table.phases), self.table.matrices, self.table.eigen, float(dt), w, el.affine_displacement(x), el.b_gauss, el.weight, ) def _dual(self, w, x, dt) -> np.ndarray: return self._sums(w, x, dt).sum(axis=0)[6:12] / self.box_volume def _evaluate(self, loading, w, x, dt, info, fields, t0) -> Solution: el = self.element nx, ny, nz = self.shape sums = self._sums(w, x, dt) total = sums.sum(axis=0) fld = None if fields: e_strain, e_stress, e_energy = kernels.elastic_fields( nx, ny, nz, True, self.mat, self.table.matrices, self.table.eigen, float(dt), w, el.affine_displacement(x), el.b_mean, el.b_gauss, ) fld = { "strain": e_strain.reshape(*self.shape, 6), "stress": e_stress.reshape(*self.shape, 6), "energy": e_energy.reshape(self.shape), } info.solve_s = time.perf_counter() - t0 return Solution( physics="elastic", bc=self.bc, loading=loading, strain=voigt_to_tensor(x, strain=True), stress=voigt_to_tensor(total[6:12] / self.box_volume, strain=False), energy=float(total[12] / self.box_volume), material_fraction=float(total[26] / self.box_volume), phases=self._phase_statistics(sums, 13, ("strain", "stress", "energy"), (6, 6, 1)), info=info, fields=fld, support=self.image if fields else None, )
[docs] class FFTThermalProblem(_FFTProblem): """Periodic steady heat conduction of a voxel image (FFT-preconditioned CG), or with ``physics`` any other transport phenomenon of a scalar potential (:data:`~morphogen.homogenization.materials.TRANSPORT`: ``"electrical"``, ``"dielectric"``, ``"magnetic"``, ``"diffusion"``), with the coefficient of the materials for it; the phases whose coefficient is zero (insulators) are voids.""" physics = "thermal" nd = 1 def _element_matrices(self, matrices) -> np.ndarray: g = self.element.g_gauss k = self.element.weight * np.einsum("gdi,mde,gej->mij", g, matrices, g, optimize=True) return np.ascontiguousarray(0.5 * (k + np.swapaxes(k, 1, 2))) def _reference_element(self) -> np.ndarray: if self.reference is not None: k0 = self.reference[0] else: used = self.table.matrices[self.counts > 0] eig = np.linalg.eigvalsh(used) k0 = 0.5 * (eig.min() + eig.max()) return k0 * self.element.k_thermal def _field(self, x: np.ndarray, dt: float = 0.0): """Periodic fluctuation of temperature for the macroscopic gradient ``x``.""" nx, ny, nz = self.shape t_loc = self.element.affine_temperature(x) loads = np.ascontiguousarray(self.element_matrices @ t_loc) dof = np.arange(nx * ny * nz, dtype=np.int64) rhs = kernels.element_load(nx, ny, nz, True, self.mat, dof, 1, loads, dof.size) return self._solve(rhs, self._load_scale(loads)) def _sums(self, t, x) -> np.ndarray: el = self.element nx, ny, nz = self.shape return kernels.thermal_sums( nx, ny, nz, True, self.mat, self.stat, len(self.table.phases), self.table.matrices, t, el.affine_temperature(x), el.g_gauss, el.weight, ) def _dual(self, t, x, dt=0.0) -> np.ndarray: return self._sums(t, x).sum(axis=0)[3:6] / self.box_volume def _evaluate(self, loading, t, x, dt, info, fields, t0) -> Solution: el = self.element nx, ny, nz = self.shape sums = self._sums(t, x) total = sums.sum(axis=0) fld = None if fields: e_grad, e_flux, e_diss = kernels.thermal_fields( nx, ny, nz, True, self.mat, self.table.matrices, t, el.affine_temperature(x), el.g_mean, el.g_gauss, ) fld = { "gradient": e_grad.reshape(*self.shape, 3), "flux": e_flux.reshape(*self.shape, 3), "dissipation": e_diss.reshape(self.shape), } info.solve_s = time.perf_counter() - t0 return Solution( physics=self.physics, bc=self.bc, loading=loading, strain=np.array(x, dtype=float), stress=total[3:6] / self.box_volume, energy=float(total[6] / self.box_volume), material_fraction=float(total[14] / self.box_volume), phases=self._phase_statistics(sums, 7, ("gradient", "flux", "dissipation"), (3, 3, 1)), info=info, fields=fld, support=self.image if fields else None, )