"""The window method for tensors: the stiffness and the conductivity of the windows of one
large periodic realization.
The realization is solved once per unit macroscopic load by the FFT solver
(:mod:`morphogen.homogenization.fft`): the six unit strains ``E^(k)`` (Voigt order 11 22 33
23 31 12, engineering shears); the three in-plane ones ``E_11, E_22, E_12`` of a planar
image (``nz = 1``: the plane stiffness, Voigt order 11 22 12); the three unit gradients of
the conductivity. The tensor of a window ``w`` is the matrix of the window means of the
mutual energy densities of these solutions,
C^w_kl = <eps^(k) : C : eps^(l)>_w (K^w_kl = <grad T^(k) . K grad T^(l)>_w),
integrated over the Gauss points of its voxels as the solver integrates the energy. It is
symmetric, to the bit (its upper triangle is computed, then mirrored), and positive
semi-definite: ``a . C^w a`` is the mean energy over the window of the solution
``sum_k a_k u^(k)``. Over windows tiling the box, its mean is the box's mean energy to
round-off, which Hill's lemma ``<sigma : eps> = Sigma : E`` makes the box's apparent
stiffness ``C_kl = E^(k) . <sigma^(l)>`` (that of
:func:`~morphogen.homogenization.stiffness_tensor`; the conductivity of
:func:`~morphogen.homogenization.conductivity_tensor`), to the tolerance of the solver: the
energy is stationary at the solution, its error of the second order in that of the fields,
that of the mean stresses of the first. Its diagonal is the energy estimate of the apparent
moduli (Dirrenberger et al. 2014, eqs. 64 and 66).
This definition rather than the window means of the stresses under the unit strains,
``<sigma^(l)>_w`` (Kanit et al. 2003): those tile the box as exactly, but are neither
symmetric (``C A`` at a point, ``A`` the concentration of the strains: 16 % off on random
voxels of a contrast of 10) nor positive (their symmetric part indefinite at voxels of that
contrast, in windows of 2 voxels at a contrast of 1000), and in a laminate their components
across the layers are those of the box in every window, the tractions being continuous: no
scatter, whatever the window. ``<sigma>_w <eps>_w^-1``, the
window's own apparent tensor, is neither symmetric nor tiling, and is undefined where the
mean strain of a window is singular (a rigid inclusion). In a laminate, whose strains are
uniform in each layer (``eps = A_p E``), the window tensor is ``sum_p f_p^w A_p^T C_p A_p``,
``f_p^w`` the fraction of the layers ``p`` in the window.
The windows are the cubes of ``w`` voxels that tile the image from its origin, the
remainder left out, as in :func:`morphogen.rve.scaling.window_statistics` (squares of ``w``
pixels across a planar image, whose measure is then their area). Their statistics per size
are those of the ensemble method, the windows as realizations
(:class:`~morphogen.rve.study.TensorStatistics`, ``method="windows"``): the mean ``Cbar``
and the standard deviation of each component, ``S = Cbar^-1`` and the mean of the
compliances of the windows, the RVE size of each component. A window without stiffness in
some direction (within a pore) has no compliance (NaN, as a singular realization).
Shifted tilings (``shifts > 1``, as in :func:`~morphogen.rve.scaling.window_statistics`):
the tilings shifted by the offsets ``k w // shifts`` voxels along each axis, all their
combinations, wrapping around the periodic image. They take the fields already solved,
each tiling one more pass of the kernel over the image (a few percent of a solve). Each is
a translate of the first on the periodic image, its windows of the law of the unshifted
ones: the statistics of a size are the means over all the windows of all its tilings (over
each tiling of the box, the box's tensor), the variances pooled within the tilings and the
counts of one tiling, the independent windows (:mod:`morphogen.rve.scaling`).
"""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from numba import njit, prange
from morphogen.homogenization.kernels import CORNERS
from morphogen.rve.scaling import _offsets, _shift_count
from morphogen.rve.study import (
TRANSPORT_TENSORS,
StudyOptions,
TensorStatistics,
_tensor_statistics,
tensor_notation,
)
#: The tensors of the window method and the physics of their problems: the stiffness, and
#: the tensor of each transport phenomenon (``conductivity_tensor``,
#: ``electrical_conductivity_tensor``, ``permittivity_tensor``, ``permeability_tensor``,
#: ``diffusivity_tensor``)
WINDOW_TENSORS = {"stiffness": "elastic", **TRANSPORT_TENSORS}
#: The tasks of one call of the kernel (windows times their planes along x): its memory
_TASKS = 1 << 16
@njit(parallel=True, cache=True)
def _window_sums(
nx, ny, nz, nd, mat, dmat, w, u_loc, b_gauss, weight, ext, counts, offset, first, out
):
"""``out[t, p]``: the integral over the plane ``i`` (along x) of the window ``m`` (``t =
(m - first) ext[0] + i``) of the mutual energy density ``eps_s . D eps_u`` of the loads
``(s, u)``, ``s <= u``, row by row (``p``). The windows of ``ext`` voxels are numbered
``m = (a counts[1] + b) counts[2] + c`` on the grid of ``counts`` shifted by ``offset``
voxels, wrapping around the periodic image; ``w[s]`` holds the periodic nodal
fluctuation of the load ``s`` (``nd`` per node), ``u_loc[s]`` its affine part at the
corners of a voxel, ``b_gauss`` the measures (strains, gradients) of the Gauss points,
``dmat[mat_e]`` the matrix of voxel ``e`` (-1: a void, no energy)."""
n_load = w.shape[0]
n_rows = b_gauss.shape[1]
n_cols = b_gauss.shape[2]
ex, ey, ez = ext[0], ext[1], ext[2]
cy, cz = counts[1], counts[2]
for t in prange(out.shape[0]):
m = first + t // ex
i = (offset[0] + (m // (cy * cz)) * ex + t % ex) % nx
j0 = offset[1] + ((m // cz) % cy) * ey
k0 = offset[2] + (m % cz) * ez
nodes = np.empty(8, dtype=np.int64)
ue = np.empty((n_load, n_cols))
eps = np.empty((n_load, n_rows))
sig = np.empty((n_load, n_rows))
acc = np.zeros(out.shape[1])
for jj in range(j0, j0 + ey):
j = jj % ny
for kk in range(k0, k0 + ez):
k = kk % nz
e = (i * ny + j) * nz + k
g = mat[e]
if g < 0:
continue
for q in range(8):
a = (i + CORNERS[q, 0]) % nx
b = (j + CORNERS[q, 1]) % ny
c = (k + CORNERS[q, 2]) % nz
nodes[q] = (a * ny + b) * nz + c
for s in range(n_load):
for q in range(8):
for r in range(nd):
ue[s, nd * q + r] = u_loc[s, nd * q + r] + w[s, nd * nodes[q] + r]
d = dmat[g]
for gp in range(8):
for s in range(n_load):
for r in range(n_rows):
v = 0.0
for col in range(n_cols):
v += b_gauss[gp, r, col] * ue[s, col]
eps[s, r] = v
for r in range(n_rows):
v = 0.0
for col in range(n_rows):
v += d[r, col] * eps[s, col]
sig[s, r] = v
p = 0
for s in range(n_load):
for u in range(s, n_load):
v = 0.0
for r in range(n_rows):
v += eps[s, r] * sig[u, r]
acc[p] += v
p += 1
for p in range(out.shape[1]):
out[t, p] = weight * acc[p]
[docs]
@dataclass
class WindowTensors:
"""The tensors of the windows of one realization (see the module documentation).
``property``: ``stiffness`` or ``conductivity_tensor``; ``edges``: the window edges
(voxels), ``volumes`` their measures (their areas across a planar image, ``dimension``
2) and ``tensors[k]`` the tensors of the windows of edge ``edges[k]``, ``(n_k, d, d)``:
in morphoGen's Voigt order 11 22 33 23 31 12 with engineering shears (11 22 12 in the
plane), the axes 1 2 3 for the conductivity (:attr:`notation`). ``box``: the tensor of
the whole realization by the same definition, the mean of the windows that tile it;
``apparent``: its apparent tensor from its mean stresses (fluxes), symmetrized, as
:func:`~morphogen.homogenization.homogenize` gives it: ``box`` to the tolerance of the
solver. ``offsets[k]``: with shifted tilings, the offsets (voxels, ``(t_k, 3)``) of the
``t_k`` tilings of the size ``k``, the unshifted one first, ``tensors[k]`` then the
windows of all of them, tiling by tiling; None: one tiling of each size.
"""
property: str
edges: np.ndarray
volumes: np.ndarray
tensors: list[np.ndarray]
box: np.ndarray
apparent: np.ndarray
bc: str = "periodic"
dimension: int = 3
offsets: list[np.ndarray] | None = None
@property
def key(self) -> str:
return f"{self.property}.{self.bc}"
@property
def notation(self) -> str:
"""The notation of the tensors (:func:`~morphogen.rve.study.tensor_notation`)."""
return tensor_notation(self.property, self.box)
@property
def tilings(self) -> np.ndarray:
"""The number of tilings of each size (1 without shifts)."""
if self.offsets is None:
return np.ones(len(self.edges), dtype=int)
return np.array([len(o) for o in self.offsets])
[docs]
def statistics(self, options: StudyOptions | None = None) -> TensorStatistics:
"""Their statistics per size, the windows as realizations: the mean tensor and the
standard deviation of each component, its inverse and the mean of the inverses of
the windows, the RVE size of each component (``options``: those of the study,
without bootstrap; the windows of non-finite tensors left out, as the realizations
of :func:`~morphogen.rve.study.tensor_statistics`); with shifted tilings, the means
over all their windows, the variances pooled within the tilings, the counts of one
(see the module)."""
groups = []
for k, (v, t) in enumerate(zip(self.volumes, self.tensors, strict=True)):
finite = np.isfinite(t).all(axis=(1, 2))
if self.offsets is None:
groups.append((v, t[finite]))
else: # the tiling of each window, the windows tiling by tiling
count = len(self.offsets[k])
tiles = np.repeat(np.arange(count), len(t) // count)
groups.append((v, t[finite], tiles[finite]))
groups = [g for g in groups if len(g[1])]
if not groups:
raise ValueError(f"{self.key}: no finite tensor of a window")
return _tensor_statistics(self.property, self.bc, groups, options, method="windows",
dimension=self.dimension) # fmt: skip
def _loads(prop: str, planar: bool) -> tuple[int, ...]:
"""The unit macroscopic loads solved: the components of the strain (Voigt) or of the
gradient."""
if prop in TRANSPORT_TENSORS:
return (0, 1, 2)
return (0, 1, 5) if planar else tuple(range(6))
def _apparent(problem, prop: str, loads) -> np.ndarray:
"""The apparent tensor of the sample from its mean stresses (fluxes) under the loads,
symmetrized (the unit solutions cached by the problem)."""
from morphogen.homogenization import Loading, conductivity_tensor
from morphogen.homogenization.elements import tensor_to_voigt
if prop in TRANSPORT_TENSORS:
return conductivity_tensor(problem)[0]
c = np.zeros((len(loads), len(loads)))
for col, j in enumerate(loads):
unit = np.zeros(6)
unit[j] = 1.0
stress = tensor_to_voigt(problem.solve(Loading.strain(unit)).stress, strain=False)
c[:, col] = stress[list(loads)]
return 0.5 * (c + c.T)
def _means(problem, fields, u_loc, b_gauss, ext, offset=(0, 0, 0)) -> np.ndarray:
"""The window means of the mutual energies of the loads, ``(n_windows, n_pairs)``, over
the windows of ``ext`` voxels that tile the image from its origin, or from the voxel
``offset`` around the periodic image (by chunks of windows: the memory of ``_TASKS``
rows)."""
nx, ny, nz = problem.shape
counts = np.array([nx // ext[0], ny // ext[1], nz // ext[2]], dtype=np.int64)
n_windows = int(np.prod(counts))
n_pairs = len(fields) * (len(fields) + 1) // 2
dmat = np.ascontiguousarray(problem.table.matrices, dtype=np.float64)
weight = float(problem.element.weight)
sums = np.empty((n_windows, n_pairs))
step = max(1, _TASKS // ext[0])
shift = np.asarray(offset, dtype=np.int64)
for first in range(0, n_windows, step):
stop = min(n_windows, first + step)
out = np.zeros(((stop - first) * ext[0], n_pairs))
_window_sums(nx, ny, nz, problem.nd, problem.mat, dmat, fields, u_loc, b_gauss, weight,
np.asarray(ext, dtype=np.int64), counts, shift, first, out) # fmt: skip
sums[first:stop] = out.reshape(stop - first, ext[0], n_pairs).sum(axis=1)
return sums / (float(np.prod(ext)) * problem.element.volume)
def _symmetric(means: np.ndarray, d: int) -> np.ndarray:
"""The symmetric matrices ``(n, d, d)`` of their upper triangles, row by row."""
out = np.empty((len(means), d, d))
rows, cols = np.triu_indices(d)
out[:, rows, cols] = means
out[:, cols, rows] = means
return out
[docs]
def window_tensors(
image,
materials,
window_sizes,
*,
property: str = "stiffness",
tol: float = 1e-8,
maxiter: int | None = None,
grains=None,
orientations=None,
device: str = "cpu",
shifts: int = 1,
) -> WindowTensors:
"""The tensors of the windows of a periodic voxel image (see the module documentation):
``property`` ``stiffness`` (six unit strains; three in the plane of a planar image) or
``conductivity_tensor`` (three unit gradients), solved once each by the FFT solver
(``tol``, ``maxiter``, ``device``; crystals turned by the orientations of their
``grains``, see :func:`~morphogen.homogenization.make_problem`), then averaged over the
windows of each edge of ``window_sizes`` (voxels): of the tiling from the origin, or
with ``shifts > 1`` of the tilings shifted by ``k w // shifts`` voxels along each axis
(``k < shifts``, all their combinations, wrapping around the image), from the same
solutions. :meth:`WindowTensors.statistics` gives their statistics per size."""
from morphogen.homogenization import make_problem
from morphogen.image import VoxelImage
if property not in WINDOW_TENSORS:
raise ValueError(f"property: one of {list(WINDOW_TENSORS)}, got {property!r}")
if not isinstance(image, VoxelImage):
raise TypeError(f"window_tensors: a VoxelImage (FFT solver), got {type(image).__name__}")
shifts = _shift_count(shifts, image.periodic)
problem = make_problem(image, materials, WINDOW_TENSORS[property], "periodic", tol=tol,
maxiter=maxiter, grains=grains, orientations=orientations,
device=device) # fmt: skip
shape = problem.shape
planar = shape[2] == 1
edges = sorted({int(w) for w in window_sizes})
for w in edges:
if w < 1 or w > min(shape[:2] if planar else shape):
raise ValueError(f"window size {w} does not fit in the image {shape}")
loads = _loads(property, planar)
element = problem.element
if WINDOW_TENSORS[property] == "elastic":
units = np.eye(6)[list(loads)]
u_loc = np.array([element.affine_displacement(e) for e in units])
b_gauss = element.b_gauss
else:
u_loc = np.array([element.affine_temperature(e) for e in np.eye(3)])
b_gauss = element.g_gauss
fields = np.ascontiguousarray(np.stack([problem._unit(j)[0] for j in loads]))
u_loc = np.ascontiguousarray(u_loc)
d = len(loads)
tensors, volumes, offsets = [], [], []
h = element.spacing
for w in edges:
ext = (w, w, 1 if planar else w)
tiles = _offsets(w, shifts, planar) # (0, 0, 0) first
means = [_means(problem, fields, u_loc, b_gauss, ext, o) for o in tiles]
tensors.append(_symmetric(np.concatenate(means), d))
volumes.append(w * w * h[0] * h[1] * (1.0 if planar else w * h[2]))
offsets.append(tiles)
(box,) = _symmetric(_means(problem, fields, u_loc, b_gauss, shape), d)
return WindowTensors(
property=property,
edges=np.array(edges),
volumes=np.array(volumes),
tensors=tensors,
box=box,
apparent=_apparent(problem, property, loads),
dimension=2 if planar else 3,
offsets=offsets if shifts > 1 else None,
)