"""Bloch waves in periodic cells: the dispersion of elastic, acoustic and electromagnetic
waves and the band gaps of architected materials (phononic, sonic and photonic crystals).
A Bloch wave ``u(x) = û(x) exp(i k·x)``, ``û`` periodic, is a free vibration of the
periodic medium at the wave vector ``k``. On a cell meshed by tetrahedra (the finite
elements of :mod:`morphogen.homogenization.fe`, 4 or 10 nodes),
``u(x + n∘L) = u(x) exp(i k·(n∘L))`` ties each node of the upper faces to its image on
the lower ones: ``w = T(k) w_masters``, the periodic map of the fluctuations, each of
its weights times the phase of the period between the node and that master. The angular
frequencies ``ω`` are those of the Hermitian problem ``T^H K T φ = ω² T^H M T φ`` (the
stiffness ``K`` and the consistent mass ``M`` of the cell), the lowest found by
shift-invert Lanczos on its real form of twice the size (each frequency twice). Along
the edges of the irreducible Brillouin zone (Γ–X–M–Γ–R for a cubic cell) the bands give
the dispersion; a range between two bands free of waves along the path is a band gap
(complete if the path holds the extrema of the bands, as for most cells of cubic
symmetry).
**Scalar waves.** A field ``u`` that obeys ``div(a grad u) + ω² b u = 0`` has the same
Bloch problem with one unknown per node, the "stiffness" of the coefficient ``a`` and the
"mass" of ``b`` (:func:`scalar_band_structure`). :data:`SCALAR_WAVES` names those of the
materials (:func:`wave_coefficients`):
============== ======================= ================ ================
waves field ``u`` ``a`` ``b``
============== ======================= ================ ================
``acoustic`` pressure of a fluid ``1 / rho`` ``1 / K``
``shear`` antiplane displacement ``mu`` ``rho``
``tm`` electric field ``E_z`` ``1 / mu_m`` ``epsilon``
``te`` magnetic field ``H_z`` ``1 / epsilon`` ``mu_m``
============== ======================= ================ ================
(``rho``: density, ``K``: bulk modulus, ``mu``: shear modulus, ``epsilon``: permittivity,
``mu_m``: magnetic permeability). The antiplane shear waves and the two polarizations of
the electromagnetic waves are those of a medium invariant along the third axis (a cell
one voxel thick) for wave vectors in its plane: the photonic crystals of rods and of
holes. In three dimensions the shear waves are those of the elastic solid (``"elastic"``)
and the electromagnetic waves are vector waves, ``curl(curl H / epsilon) = ω² mu_m H``,
solved by plane waves on the voxels of an image (``"electromagnetic"``,
:mod:`morphogen.homogenization.photonic`): the photonic crystals of spheres, of rods
stacked across each other, of any morphology, and the waves that leave the plane of a
crystal of rods. A phase whose coefficient ``a`` is zero is left out, its boundary free of
flux: the rigid scatterers of a sonic crystal (``1 / rho = 0``), the perfect conductors of
``te`` waves. At long wavelengths the first band is that of the homogenized medium, ``ω² =
k . a* . k / <b>`` (:func:`long_wavelength_speeds`: Wood's law for the sound of mixtures,
the effective index of a photonic crystal).
"""
from __future__ import annotations
import math
from dataclasses import dataclass
from itertools import product
import numpy as np
import scipy.sparse as sp
from scipy.sparse.linalg import LinearOperator, eigsh, splu
from morphogen.homogenization.fe import FEElasticProblem, FEThermalProblem, periodic_map
from morphogen.homogenization.materials import Material
from morphogen.image import VoxelImage
from morphogen.mesh.tetra import TET_EDGES, TetMesh
#: Corners of the Brillouin zone of an orthorhombic cell, in units of ``pi / L`` per axis.
POINTS = {
"G": (0.0, 0.0, 0.0),
"X": (1.0, 0.0, 0.0),
"Y": (0.0, 1.0, 0.0),
"Z": (0.0, 0.0, 1.0),
"M": (1.0, 1.0, 0.0),
"R": (1.0, 1.0, 1.0),
}
#: The scalar waves of the materials: the field, and the coefficients ``a`` and ``b`` of
#: ``div(a grad u) + ω² b u = 0`` (see :func:`wave_coefficients`)
SCALAR_WAVES = {
"acoustic": ("pressure", "1 / density", "1 / bulk modulus"),
"shear": ("antiplane displacement", "shear modulus", "density"),
"tm": ("electric field along the axis", "1 / permeability", "permittivity"),
"te": ("magnetic field along the axis", "1 / permittivity", "permeability"),
}
#: The scalar waves of a medium invariant along the third axis, for wave vectors in its
#: plane; in three dimensions: ``"elastic"`` and ``"electromagnetic"``
PLANE_WAVES = ("shear", "tm", "te")
#: The waves of :func:`band_structure`
WAVES = ("elastic", *SCALAR_WAVES, "electromagnetic")
def _monomial_integral(exponents) -> float:
"""``∫ λ0^a λ1^b λ2^c λ3^d dV / V`` over a tetrahedron (barycentric coordinates)."""
num = 6.0 * math.prod(math.factorial(int(a)) for a in exponents)
return num / math.factorial(int(sum(exponents)) + 3)
def _p2_mass() -> np.ndarray:
"""Consistent mass matrix of the 10-node tetrahedron over its volume (corners, then
the mid-edge nodes in ``TET_EDGES`` order)."""
shapes = []
for i in range(4): # λi (2 λi - 1)
two = [0, 0, 0, 0]
two[i] = 2
one = [0, 0, 0, 0]
one[i] = 1
shapes.append({tuple(two): 2.0, tuple(one): -1.0})
for a, b in TET_EDGES: # 4 λa λb
e = [0, 0, 0, 0]
e[a] += 1
e[b] += 1
shapes.append({tuple(e): 4.0})
m = np.zeros((10, 10))
for i, j in product(range(10), range(10)):
m[i, j] = sum(
ci * cj * _monomial_integral(np.add(ei, ej))
for ei, ci in shapes[i].items()
for ej, cj in shapes[j].items()
)
return m
#: Consistent mass matrices of the 4- and 10-node tetrahedra over their volume.
MASS = {1: (np.ones((4, 4)) + np.eye(4)) / 20.0, 2: _p2_mass()}
[docs]
def mass_matrix(mesh: TetMesh, density) -> sp.csr_matrix:
"""Consistent mass matrix (nodes x nodes) of a tetrahedral mesh, ``density`` the
density of each element."""
ref = MASS[mesh.order]
e = mesh.elements
m = e.shape[1]
rows = np.repeat(e, m, axis=1).ravel()
cols = np.tile(e, (1, m)).ravel()
vals = (np.asarray(density, dtype=float) * np.abs(mesh.volumes()))[:, None] * ref.ravel()
return sp.csr_matrix((vals.ravel(), (rows, cols)), shape=(mesh.n_nodes, mesh.n_nodes))
[docs]
def voxel_tet_mesh(image: VoxelImage, phases=None) -> TetMesh:
"""Six tetrahedra per voxel of an image (the Kuhn triangulation of its grid, whose
opposite faces match), each with the phase of its voxel; ``phases``: those kept (the
solid of a lattice, say)."""
from morphogen.mesh.conforming import background_mesh
lower = np.asarray(image.origin, dtype=float)
upper = lower + image.size
nodes, tets, _, _ = background_mesh(image.shape, lower, upper)
phase = np.tile(np.asarray(image.data).ravel(), 6) # six blocks of all the cubes
mesh = TetMesh(nodes, tets, phase, lower, upper, periodic=bool(image.periodic))
return mesh.subset(phases) if phases is not None else mesh
[docs]
def brillouin_path(size, path=("G", "X", "M", "G", "R"), points: int = 12):
"""Wave vectors along the segments between the corners ``path`` (names of
:data:`POINTS` or points in units of ``pi / L``) of the Brillouin zone of a cell of
edges ``size``, ``points`` per segment: the wave vectors (n x 3), their distance along
the path and the positions and names of the corners."""
size = np.asarray(size, dtype=float)
names = [("Γ" if p == "G" else p) if isinstance(p, str) else str(tuple(p)) for p in path]
corners = [
np.asarray(POINTS[p] if isinstance(p, str) else p, dtype=float) * np.pi / size for p in path
]
ks, dist = [corners[0]], [0.0]
labels = [(0.0, names[0])]
for a, b, name in zip(corners[:-1], corners[1:], names[1:], strict=True):
start, length = dist[-1], float(np.linalg.norm(b - a))
for t in np.linspace(0.0, 1.0, int(points) + 1)[1:]:
ks.append(a + t * (b - a))
dist.append(start + t * length)
labels.append((dist[-1], name))
return np.array(ks), np.array(dist), labels
[docs]
@dataclass
class BandStructure:
"""The angular frequencies (``frequencies``: wave vectors x bands, increasing) of
the Bloch waves at the ``wavevectors``, their ``distance`` along the path and the
positions and names of its corners (``labels``)."""
wavevectors: np.ndarray
distance: np.ndarray
frequencies: np.ndarray
labels: list
[docs]
def gaps(self, relative: float = 1e-3) -> list[tuple[int, float, float]]:
"""The band gaps along the path: ``(n, low, high)`` between the bands ``n`` and
``n + 1`` (counted from 1), wider than ``relative`` times their mid-frequency."""
out = []
for n in range(self.frequencies.shape[1] - 1):
low, high = float(self.frequencies[:, n].max()), float(self.frequencies[:, n + 1].min())
if high - low > relative * 0.5 * (high + low):
out.append((n + 1, low, high))
return out
[docs]
def normalized(self, length: float, speed: float) -> np.ndarray:
"""The frequencies in units of ``2 pi speed / length`` (``ω L / 2π c``)."""
return self.frequencies * length / (2.0 * np.pi * speed)
[docs]
def plot(self, ax=None, *, scale: float = 1.0, ylabel: str = "ω"):
"""Draw the bands (times ``scale``) along the path with its corners and the band
gaps shaded (matplotlib, without pyplot); returns the axes (``ax.figure.savefig``)."""
if ax is None:
from morphogen.viz.figures import _figure
ax = _figure(5.0, 4.0).subplots()
for _, low, high in self.gaps():
ax.axhspan(low * scale, high * scale, color="0.88", lw=0)
for position, _ in self.labels:
ax.axvline(position, color="0.6", lw=0.6)
ax.plot(self.distance, self.frequencies * scale, color="C0", lw=1.2)
if self.labels:
ax.set_xticks([d for d, _ in self.labels], [n for _, n in self.labels])
ax.set_xlim(self.distance[0], self.distance[-1])
ax.set_ylim(bottom=0.0)
ax.set_ylabel(ylabel)
return ax
def _scalar(value, name: str, phase) -> float:
"""An isotropic coefficient of a material for the scalar waves."""
if value is None:
raise ValueError(f"waves: give the {name} of phase {phase}")
if isinstance(value, tuple):
raise ValueError(f"waves: an isotropic {name} (phase {phase})")
return float(value)
[docs]
def wave_coefficients(waves: str, materials: dict[int, Material]) -> tuple[dict, dict]:
"""The coefficients ``a`` and ``b`` of each phase for the scalar ``waves`` of
:data:`SCALAR_WAVES`, from the materials: their ``density`` and elastic moduli
(``acoustic``: the pressure waves of fluids, of bulk modulus ``K``; ``shear``:
antiplane shear waves), or their ``permittivity`` and ``permeability`` (``tm``,
``te``; a permeability left out is that of the units, 1). Voids are left out; give
the coefficients themselves to :func:`scalar_band_structure` for the phases that the
materials do not describe (a fluid has no shear modulus)."""
if waves not in SCALAR_WAVES:
raise ValueError(f"waves: one of {WAVES}, got {waves!r}")
a, b = {}, {}
for phase, m in materials.items():
if m.void:
a[phase] = b[phase] = 0.0
continue
if waves in ("acoustic", "shear"):
density = _scalar(m.density, "density", phase)
if m.young is None:
raise ValueError(f"waves: isotropic elastic moduli (phase {phase})")
lam, mu = m.lame
if waves == "acoustic":
a[phase], b[phase] = 1.0 / density, 1.0 / (lam + 2.0 * mu / 3.0)
else:
a[phase], b[phase] = mu, density
else:
eps = _scalar(m.permittivity, "permittivity", phase)
mu = 1.0 if m.permeability is None else _scalar(m.permeability, "permeability", phase)
if not (eps > 0.0 and mu > 0.0):
raise ValueError(f"waves: positive permittivity and permeability (phase {phase})")
a[phase], b[phase] = (1.0 / mu, eps) if waves == "tm" else (1.0 / eps, mu)
return a, b
[docs]
def electromagnetic_coefficients(materials: dict[int, Material]) -> tuple[dict, dict]:
"""The permittivity and the permeability of each phase for the electromagnetic waves
(numbers, or 3 x 3 tensors in the axes of the cell), from the materials: their
``permittivity`` and ``permeability`` (left out: that of the units, 1). A void holds
no wave in the scalar problems; here every phase carries the field: give the vacuum
its permittivity."""
eps, mu = {}, {}
for phase, m in materials.items():
if m.void or m.permittivity is None:
raise ValueError(
f"waves: give the permittivity of phase {phase} (1 for the vacuum: every phase "
"carries the electromagnetic field)"
)
eps[phase] = (
np.array(m.permittivity) if isinstance(m.permittivity, tuple) else m.permittivity
)
value = 1.0 if m.permeability is None else m.permeability
mu[phase] = np.array(value) if isinstance(value, tuple) else value
return eps, mu
def _default_path(sample, path):
"""The path of a cell when none is given: Γ–X–M–Γ in the plane of a cell one voxel
thick, Γ–X–M–Γ–R otherwise."""
if path is not None:
return path
planar = isinstance(sample, VoxelImage) and sample.shape[2] == 1
return ("G", "X", "M", "G") if planar else ("G", "X", "M", "G", "R")
def _check_plane(sample, path, points: int, waves: str) -> None:
"""The waves of a medium invariant along the third axis: a cell that does not vary
along it, and wave vectors in its plane."""
other = "'elastic'" if waves == "shear" else "'electromagnetic'"
if isinstance(sample, VoxelImage) and sample.shape[2] > 1:
data = np.asarray(sample.data)
if np.any(data != data[:, :, :1]):
raise ValueError(
f"waves {waves!r}: those of a cell invariant along z (one voxel thick); the "
f"waves of a three-dimensional cell: {other}"
)
if isinstance(path, np.ndarray) and path.ndim == 2:
ks = np.asarray(path, dtype=float)
else:
ks, _, _ = brillouin_path(sample.size, path, points)
if np.any(np.abs(ks[:, 2]) > 1e-12 * max(float(np.abs(ks).max()), 1e-300)):
raise ValueError(
f"waves {waves!r}: wave vectors in the plane x-y of the cell (a path such as G X M "
f"G); the waves that leave it: {other}"
)
def _wave_mesh(sample, order: int, phases) -> TetMesh:
mesh = voxel_tet_mesh(sample, phases) if isinstance(sample, VoxelImage) else sample
if int(order) == 2:
return mesh.quadratic().straight() # the mass matrices are those of straight edges
if int(order) == 1:
return mesh.linear()
raise ValueError("order: 1 or 2")
def _path(mesh: TetMesh, path, points: int):
if isinstance(path, np.ndarray) and path.ndim == 2:
ks = np.asarray(path, dtype=float)
dist = np.concatenate([[0.0], np.cumsum(np.linalg.norm(np.diff(ks, axis=0), axis=1))])
return ks, dist, []
return brillouin_path(mesh.size, path, points)
def _bands(stiffness, mass, mesh: TetMesh, nd: int, ks, bands: int) -> np.ndarray:
"""The lowest Bloch frequencies of the matrices of a cell (``nd`` unknowns per node)
at the wave vectors ``ks``."""
t, masters, _ = periodic_map(mesh)
t = t.tocsr()
# the periods between each node and each of its masters (interpolated ones included)
rows = np.repeat(np.arange(t.shape[0]), np.diff(t.indptr))
delta = mesh.nodes[rows] - mesh.nodes[masters[t.indices]]
periods = np.rint(delta / mesh.size) * mesh.size
scale = float(np.median(stiffness.diagonal()) / np.median(mass.diagonal()))
sigma = -1e-6 * scale
n = int(bands)
if not 0 < n < t.shape[1] * nd:
raise ValueError(
f"band_structure: between 1 and {t.shape[1] * nd - 1} bands (the unknowns of the "
f"cell, less one), got {n}"
)
freqs = np.zeros((len(ks), n))
for i, k in enumerate(ks):
tk = sp.csr_matrix(
(t.data * np.exp(1j * (periods @ k)), t.indices, t.indptr), shape=t.shape
)
tn = sp.kron(tk, sp.identity(nd), format="csr") if nd > 1 else tk
kr = _real(tn.getH() @ stiffness @ tn)
mr = _real(tn.getH() @ mass @ tn)
# minimum degree on A + A^T: a quarter of the fill of SuperLU's default ordering
lu = splu((kr - sigma * mr).tocsc(), permc_spec="MMD_AT_PLUS_A")
inverse = LinearOperator(kr.shape, matvec=lu.solve, dtype=float)
values = eigsh(kr, 2 * n, mr, sigma=sigma, OPinv=inverse, return_eigenvectors=False)
values = np.sort(values)
freqs[i] = np.sqrt(np.clip(0.5 * (values[0::2] + values[1::2]), 0.0, None))
return freqs
[docs]
def scalar_band_structure(
sample,
stiffness: dict[int, float],
mass: dict[int, float],
path=("G", "X", "M", "G", "R"),
*,
bands: int = 8,
points: int = 12,
order: int = 2,
phases=None,
) -> BandStructure:
"""The lowest ``bands`` Bloch frequencies of the scalar waves ``div(a grad u) + ω² b
u = 0`` of a periodic cell (mesh or voxel image, as :func:`band_structure`): ``a``
the ``stiffness`` coefficient of each phase and ``b`` its ``mass`` coefficient (the
table of the module: acoustic, antiplane shear and electromagnetic waves). The phases
whose ``a`` is zero are left out (rigid scatterers), their boundaries free of flux."""
mesh = _wave_mesh(sample, order, phases)
present = sorted({int(p) for p in mesh.phase})
missing = [p for p in present if p not in stiffness or p not in mass]
if missing:
raise ValueError(f"scalar_band_structure: no coefficients for phase(s) {missing}")
bad = [p for p in present if stiffness[p] < 0.0 or (stiffness[p] > 0.0 and not mass[p] > 0.0)]
if bad:
raise ValueError(
f"scalar_band_structure: positive coefficients (a >= 0, b > 0) for phase(s) {bad}"
)
mats = {
p: Material(conductivity=float(stiffness[p])) if stiffness[p] > 0.0 else Material(void=True)
for p in present
}
problem = FEThermalProblem(mesh, mats, bc="periodic")
if problem.empty:
raise ValueError("scalar_band_structure: no phase carries the waves")
mesh = problem.mesh
weight = np.array([mass[int(p)] for p in mesh.phase], dtype=float)
ks, dist, labels = _path(mesh, path, points)
matrix = problem._stiffness().tocsr()
freqs = _bands(matrix, mass_matrix(mesh, weight), mesh, 1, ks, bands)
return BandStructure(ks, dist, freqs, labels)
[docs]
def long_wavelength_speeds(
sample, stiffness: dict[int, float], mass: dict[int, float], **options
) -> dict:
"""The speeds of the scalar waves of a periodic cell at long wavelengths, those of the
homogenized medium: ``c_i = sqrt(a*_ii / <b>)`` along each axis, with the effective
tensor ``a*`` of the coefficient ``a`` (a conduction problem: the FFT solver of a
voxel image, finite elements on a mesh) and the mean of ``b`` (over the whole cell,
the phases left out included: they hold no wave). Returns ``"tensor"`` (``a*``, 3 x
3), ``"mass"`` (``<b>``) and ``"speeds"`` (3,). For the sound of a mixture of fluids
this is Wood's law (``1 / K* = <1 / K>``) with the effective density ``(a*)^-1``; for
light, ``c / n*``. ``options``: those of :func:`~morphogen.homogenization.apparent.
make_problem`."""
from morphogen.analysis import phase_fractions
from morphogen.homogenization.apparent import conductivity_tensor, make_problem
mats = {
p: Material(conductivity=float(a)) if a > 0.0 else Material(void=True)
for p, a in stiffness.items()
}
problem = make_problem(sample, mats, "thermal", "periodic", **options)
tensor, _ = conductivity_tensor(problem)
if isinstance(sample, VoxelImage):
fractions = phase_fractions(sample)
else:
volumes = np.abs(sample.volumes())
fractions = {
int(p): float(volumes[sample.phase == p].sum() / np.prod(sample.size))
for p in np.unique(sample.phase)
}
mean = float(sum(f * mass[p] for p, f in fractions.items() if stiffness.get(p, 0.0) > 0.0))
return {"tensor": tensor, "mass": mean, "speeds": np.sqrt(np.diag(tensor) / mean)}
[docs]
def band_structure(
sample,
materials: dict[int, Material],
path=None,
*,
bands: int = 12,
points: int = 12,
order: int = 2,
phases=None,
waves: str = "elastic",
coarsen: int = 1,
) -> BandStructure:
"""The lowest ``bands`` Bloch frequencies of a periodic cell (a
:class:`~morphogen.mesh.tetra.TetMesh`, or a :class:`~morphogen.image.VoxelImage`
cut into six tetrahedra per voxel, keeping ``phases``) along ``path`` (corners of the
Brillouin zone, ``points`` per segment; or an array of wave vectors; by default
Γ–X–M–Γ–R, Γ–X–M–Γ in the plane of an image one voxel thick), with elements of
``order`` 1 or 2. The materials need a ``density``; void phases are left out, as the
clusters of elements that touch no face of the box. ``waves``: ``"elastic"`` (the
vector waves of the solid); the scalar waves of :data:`SCALAR_WAVES` (``"acoustic"``,
and ``"shear"``, ``"tm"``, ``"te"`` in the plane of a cell invariant along z) with
the coefficients of the materials (:func:`wave_coefficients`,
:func:`scalar_band_structure`); or ``"electromagnetic"``, the vector waves of light in
a voxel image of any morphology, by plane waves on its voxels or on a grid
``coarsen`` times coarser (:func:`~morphogen.homogenization.photonic.
electromagnetic_band_structure`; ``order`` and ``phases`` do not apply)."""
if waves not in WAVES:
raise ValueError(f"waves: one of {WAVES}, got {waves!r}")
path = _default_path(sample, path)
if waves == "electromagnetic":
from morphogen.homogenization.photonic import electromagnetic_band_structure
eps, mu = electromagnetic_coefficients(materials)
return electromagnetic_band_structure(
sample, eps, path, permeability=mu, bands=bands, points=points, coarsen=coarsen
)
if waves != "elastic":
a, b = wave_coefficients(waves, materials)
if waves in PLANE_WAVES:
_check_plane(sample, path, points, waves)
return scalar_band_structure(
sample, a, b, path, bands=bands, points=points, order=order, phases=phases
)
mesh = voxel_tet_mesh(sample, phases) if isinstance(sample, VoxelImage) else sample
if int(order) == 2:
mesh = mesh.quadratic().straight() # the mass matrices are those of straight edges
elif int(order) == 1:
mesh = mesh.linear()
else:
raise ValueError("order: 1 or 2")
problem = FEElasticProblem(mesh, materials, bc="periodic")
if problem.empty:
raise ValueError("band_structure: no material in the cell")
mesh = problem.mesh
missing = sorted({int(p) for p in mesh.phase if materials[int(p)].density is None})
if missing:
raise ValueError(f"band_structure: give the density of phase(s) {missing}")
density = np.array([materials[int(p)].density for p in mesh.phase], dtype=float)
stiffness = problem._stiffness().tocsr()
mass = sp.kron(mass_matrix(mesh, density), sp.identity(3), format="csr")
ks, dist, labels = _path(mesh, path, points)
freqs = _bands(stiffness, mass, mesh, 3, ks, bands)
return BandStructure(ks, dist, freqs, labels)
def _real(h: sp.spmatrix) -> sp.csc_matrix:
"""The real symmetric matrix ``[[A, -B], [B, A]]`` of a Hermitian ``A + iB``: each
eigenvalue twice, so that the symmetric Lanczos of ARPACK applies (the complex
Hermitian one is that of nonsymmetric matrices)."""
h = 0.5 * (h + h.getH())
return sp.bmat([[h.real, -h.imag], [h.imag, h.real]], format="csc")