"""Electromagnetic Bloch waves of three-dimensional photonic crystals, by plane waves.
In a periodic medium of permittivity ``ε(x)`` and permeability ``μ(x)``, a harmonic field
without sources obeys ``curl(ε⁻¹ curl H) = ω² B`` with ``B = μ H`` and ``div B = 0``. At
the wave vector ``k`` the induction of a Bloch wave is a sum of plane waves over the
reciprocal vectors ``G`` of the cell,
B(x) = Σ_G (b¹_G e¹_G + b²_G e²_G) exp(i (k + G)·x),
with two amplitudes per plane wave on the unit vectors ``e¹, e²`` normal to ``q = k + G``
(``(e¹, e², q/|q|)`` direct): the fields are divergence-free by construction, and the
gradients, which the curl ignores and which clutter the spectrum of the nodal
discretizations with zero frequencies, are left out (Ho, Chan & Soukoulis 1990; Johnson &
Joannopoulos 2001). The frequencies are those of the Hermitian problem
Pᴴ μ⁻¹ C ε⁻¹ C μ⁻¹ P b = ω² Pᴴ μ⁻¹ P b, C = i q ×,
``P`` the map of the amplitudes to the plane waves. The curls are taken on the plane
waves and the products by ``ε⁻¹`` and ``μ⁻¹`` on the grid of the cell, a pair of fast
Fourier transforms apart, so that the matrices are never formed: the lowest frequencies
are found by a block Davidson method (the Rayleigh-Ritz values of a subspace that the
preconditioned residuals of its lowest waves extend, restarted from them and from those
of the step before), from the waves of the previous wave vector; small cells are
diagonalized. The preconditioner is the operator of the inverse medium, ``Pᴴ μ C⁻¹ ε C⁻¹
μ P`` with ``C⁻¹ = i q × / |q|²`` on the transverse waves (Johnson & Joannopoulos 2001):
the inverse of the operator but for the projections, whatever the contrast of the
phases. A uniform permeability leaves the standard problem ``Pᴴ C ε⁻¹ C P h = ω² μ h`` of
the dielectric crystals. The Galerkin projection on the transverse waves is exact: the
residual of an eigenvector is transverse and orthogonal to the transverse waves in the
product of ``μ⁻¹``.
The grid of the plane waves is that of the voxels, or one ``coarsen`` times coarser
whose cells hold several voxels. A cell that an interface cuts then takes the tensor of
Meade et al. (1993), as averaged by Johnson & Joannopoulos (2001),
ε̃⁻¹ = <ε⁻¹> n ⊗ n + <ε>⁻¹ (1 - n ⊗ n),
the harmonic mean for the field normal to the interface and the arithmetic mean along
it (the effective tensor of the layers that the interface draws in the cell), ``n`` the
sum of the gradients of the permittivity over the voxels of the cell. The stairs of the
voxels cost the frequencies an error of first order in the size of the cells; this
average brings it back to the second order: voxelize three or four times finer than
the plane waves.
With relative permittivities and permeabilities the frequencies are in units of the
speed of light over the unit of length (``ω a / 2π c``: :meth:`~morphogen.homogenization.
bloch.BandStructure.normalized`). A cell one voxel thick is a crystal invariant along
that axis: its waves in the plane are the two polarizations ``"tm"`` and ``"te"`` of
:func:`~morphogen.homogenization.bloch.scalar_band_structure` together, and those that
leave the plane (a wave vector with a component along the axis) are found here only.
"""
from __future__ import annotations
import logging
import numpy as np
from scipy import fft as sfft
from scipy.linalg import eigh
from morphogen import settings
from morphogen.image import VoxelImage
log = logging.getLogger(__name__)
#: Up to this number of unknowns (two per plane wave) the matrices are formed and
#: diagonalized
DENSE_LIMIT = 1800
#: The amplitudes of a block handled at once (bounds the memory of the transforms)
BLOCK_VALUES = 6_000_000
#: The subspace of the Davidson method, in blocks of the waves sought, before a restart
SUBSPACE = 5
_AXES = (-3, -2, -1)
def _tensor_field(values: dict, data: np.ndarray, name: str):
"""The field of a coefficient of the phases on the voxels: an array of the shape of
the image (isotropic phases) or ``(3, 3) + shape`` (a tensor in one phase at least)."""
phases = np.unique(data)
missing = [int(p) for p in phases if int(p) not in values]
if missing:
raise ValueError(f"electromagnetic waves: no {name} for phase(s) {missing}")
tensors = {}
for p in phases:
v = np.asarray(values[int(p)], dtype=float)
if v.shape == (3,):
v = np.diag(v)
if v.shape not in ((), (3, 3)) or not np.all(np.isfinite(v)):
raise ValueError(f"electromagnetic waves: a {name} or a 3 x 3 tensor (phase {int(p)})")
low = float(v) if v.ndim == 0 else float(np.linalg.eigvalsh(0.5 * (v + v.T)).min())
if not low > 0.0:
raise ValueError(
f"electromagnetic waves: a positive {name} (phase {int(p)}; 1 for the vacuum: "
"perfect conductors and absorbing phases are not covered)"
)
tensors[int(p)] = v
if all(v.ndim == 0 for v in tensors.values()):
lookup = np.zeros(int(phases.max()) + 1)
for p, v in tensors.items():
lookup[p] = float(v)
return lookup[data]
lookup = np.zeros((int(phases.max()) + 1, 3, 3))
for p, v in tensors.items():
lookup[p] = v * np.eye(3) if v.ndim == 0 else 0.5 * (v + v.T)
return np.moveaxis(lookup[data], (-2, -1), (0, 1))
def _invert(field: np.ndarray) -> np.ndarray:
if field.ndim == 3:
return 1.0 / field
return np.moveaxis(np.linalg.inv(np.moveaxis(field, (0, 1), (-2, -1))), (-2, -1), (0, 1))
def _blocks(field: np.ndarray, factors) -> np.ndarray:
"""The mean of a field of the voxels over the cells of ``factors`` voxels per axis."""
n = field.shape
shape = (n[0] // factors[0], factors[0], n[1] // factors[1], factors[1], n[2] // factors[2])
return field.reshape(*shape, factors[2]).mean(axis=(1, 3, 5))
[docs]
def smoothed_inverse(field: np.ndarray, coarsen: int = 1) -> np.ndarray:
"""The inverse of an isotropic coefficient of the voxels (``field``: the permittivity)
on a grid ``coarsen`` times coarser along each axis (the axes of one voxel are kept):
``1 / field`` on the voxels themselves, else the tensor ``<1/ε> n ⊗ n + (1 - n ⊗ n) /
<ε>`` of each cell (``(3, 3) + shape``; see the module). The normal ``n`` is the sum
of the gradients of the field over the voxels of the cell (central differences: the
normal of a plane that cuts the cell, whatever its stairs), or, where they cancel (a
layer thinner than the cell, with its two faces), their principal direction; the
cells that hold one value keep it."""
field = np.asarray(field, dtype=float)
s = int(coarsen)
if s < 1:
raise ValueError("coarsen: a positive integer")
if s == 1:
return 1.0 / field
factors = tuple(1 if n == 1 else s for n in field.shape)
if any(n % f for n, f in zip(field.shape, factors, strict=True)):
raise ValueError(f"coarsen: {s} does not divide the voxels {field.shape} of the cell")
mean = _blocks(field, factors)
harmonic = _blocks(1.0 / field, factors)
gradient = [
np.zeros_like(field)
if field.shape[a] == 1
else 0.5 * (np.roll(field, -1, axis=a) - np.roll(field, 1, axis=a))
for a in range(3)
]
total = np.stack([_blocks(g, factors) for g in gradient])
length = np.sqrt((total**2).sum(axis=0))
spread = _blocks(np.sqrt(sum(g * g for g in gradient)), factors) # the mean norm
structure = np.zeros((3, 3, *mean.shape))
for i in range(3):
for j in range(i, 3):
structure[i, j] = structure[j, i] = _blocks(gradient[i] * gradient[j], factors)
_, vectors = np.linalg.eigh(np.moveaxis(structure, (0, 1), (-2, -1)))
normal = np.moveaxis(vectors[..., -1], -1, 0) # that of the largest eigenvalue
single = length > 0.3 * spread # one interface: its gradients add up
normal = np.where(single, total / np.where(length > 0.0, length, 1.0), normal)
projector = normal[:, None] * normal[None, :]
inverse = (harmonic - 1.0 / mean) * projector
for i in range(3):
inverse[i, i] += 1.0 / mean
return inverse
def _multiply(tensor: np.ndarray, field: np.ndarray) -> np.ndarray:
"""A coefficient of the grid (isotropic, or ``(3, 3) + shape``) times fields ``(p, 3)
+ shape``."""
if tensor.ndim == 3:
return tensor * field
return np.einsum("ijxyz,pjxyz->pixyz", tensor, field)
[docs]
class PlaneWaves:
"""The plane waves of a periodic cell of edges ``size`` on the grid of the inverse
coefficients ``inverse_permittivity`` and ``inverse_permeability`` (arrays of the
shape of the grid, or ``(3, 3) + shape``; the permeability a number when uniform),
and the Maxwell operators at a wave vector (:meth:`at`)."""
def __init__(self, inverse_permittivity, size, inverse_permeability=1.0) -> None:
self.inverse_permittivity = np.asarray(inverse_permittivity, dtype=float)
self.permittivity = _invert(self.inverse_permittivity)
self.shape = self.inverse_permittivity.shape[-3:]
self.size = np.asarray(size, dtype=float)
mu = np.asarray(inverse_permeability, dtype=float)
self.uniform = mu.ndim == 0
self.inverse_permeability = float(mu) if self.uniform else mu
self.permeability = 1.0 / float(mu) if self.uniform else _invert(mu)
self.g = np.stack(
np.meshgrid(
*[
2.0 * np.pi * sfft.fftfreq(n, d=length / n)
for n, length in zip(self.shape, self.size, strict=True)
],
indexing="ij",
)
)
#: the unit of the eigenvalues: the square of the first reciprocal vector
self.scale = float((self.size.max() / (2.0 * np.pi)) ** 2)
self.count = int(np.prod(self.shape))
@property
def unknowns(self) -> int:
return 2 * self.count
[docs]
def at(self, wavevector) -> PlaneWaves:
"""Set the wave vector: the vectors ``q = k + G``, their norms and their
transverse unit vectors ``e1`` and ``e2``."""
k = np.asarray(wavevector, dtype=float).reshape(3, 1, 1, 1)
self.q = self.g + k
norm = np.sqrt((self.q**2).sum(axis=0))
zero = norm == 0.0
u = self.q / np.where(zero, 1.0, norm)
e1 = np.stack([-u[1], u[0], np.zeros_like(norm)]) # z × u
length = np.sqrt((e1**2).sum(axis=0))
along = length < 1e-6 # u along z (or zero): x, less its part along u
if np.any(along):
e1[:, along] = np.array([1.0, 0.0, 0.0])[:, None] - u[0][along] * u[:, along]
length[along] = np.sqrt((e1[:, along] ** 2).sum(axis=0))
e1 /= length
e2 = np.cross(u, e1, axis=0)
e2[:, zero] = np.array([0.0, 1.0, 0.0])[:, None]
self.norm, self.e1, self.e2 = norm, e1, e2
self.inverse_norm = np.where(zero, 0.0, 1.0 / np.where(zero, 1.0, norm))
return self
# -- the maps between amplitudes, plane waves and the grid ----------------------------
def _fields(self, c: np.ndarray) -> np.ndarray:
return c[:, 0, None] * self.e1 + c[:, 1, None] * self.e2
def _project(self, f: np.ndarray) -> np.ndarray:
return np.stack([(f * self.e1).sum(axis=1), (f * self.e2).sum(axis=1)], axis=1)
def _on_grid(self, tensor, f: np.ndarray) -> np.ndarray:
if np.ndim(tensor) == 0:
return tensor * f
workers = settings.workers()
f = sfft.ifftn(f, axes=_AXES, workers=workers)
return sfft.fftn(_multiply(tensor, f), axes=_AXES, workers=workers)
def _curl(self, f: np.ndarray) -> np.ndarray:
q = self.q
return 1j * np.stack(
[
q[1] * f[:, 2] - q[2] * f[:, 1],
q[2] * f[:, 0] - q[0] * f[:, 2],
q[0] * f[:, 1] - q[1] * f[:, 0],
],
axis=1,
)
def _stiffness(self, c: np.ndarray) -> np.ndarray:
if self.uniform: # the curl of a transverse wave: i |q| (c1 e2 - c2 e1)
d = self.norm * (c[:, 0, None] * self.e2 - c[:, 1, None] * self.e1)
e = self._on_grid(self.inverse_permittivity, d)
out = np.stack([(e * self.e2).sum(axis=1), -(e * self.e1).sum(axis=1)], axis=1)
return (self.scale * self.inverse_permeability) * self.norm * out
h = self._on_grid(self.inverse_permeability, self._fields(c))
e = self._on_grid(self.inverse_permittivity, self._curl(h))
return self.scale * self._project(self._on_grid(self.inverse_permeability, self._curl(e)))
def _mass(self, c: np.ndarray) -> np.ndarray:
return self._project(self._on_grid(self.inverse_permeability, self._fields(c)))
def _precondition(self, c: np.ndarray) -> np.ndarray:
inverse = self.inverse_norm
if self.uniform: # the inverse curls of the transverse waves, as the curls above
f = inverse * (c[:, 0, None] * self.e2 - c[:, 1, None] * self.e1)
f = self._on_grid(self.permittivity, f)
out = np.stack([(f * self.e2).sum(axis=1), -(f * self.e1).sum(axis=1)], axis=1)
return (self.permeability / self.scale) * inverse * out
f = self._curl(self._on_grid(self.permeability, self._fields(c))) * inverse**2
f = self._curl(self._on_grid(self.permittivity, f)) * inverse**2
return self._project(self._on_grid(self.permeability, f)) / self.scale
def _blockwise(self, function, x: np.ndarray) -> np.ndarray:
"""``function`` of the columns of ``x`` (unknowns x p), a few at a time."""
x = np.asarray(x, dtype=complex)
single = x.ndim == 1
columns = x.reshape(self.unknowns, -1).T.reshape(-1, 2, *self.shape)
step = max(1, BLOCK_VALUES // (3 * self.count))
out = np.concatenate(
[function(columns[i : i + step]) for i in range(0, len(columns), step)]
)
out = out.reshape(len(columns), self.unknowns).T
return out[:, 0] if single else out
[docs]
def stiffness(self, x: np.ndarray) -> np.ndarray:
"""``Pᴴ μ⁻¹ C ε⁻¹ C μ⁻¹ P`` times the amplitudes ``x`` (unknowns, or unknowns x p),
in units of the square of the first reciprocal vector."""
return self._blockwise(self._stiffness, x)
[docs]
def mass(self, x: np.ndarray) -> np.ndarray:
"""``Pᴴ μ⁻¹ P`` times the amplitudes (the identity for a uniform permeability,
which the stiffness then carries)."""
return np.asarray(x, dtype=complex) if self.uniform else self._blockwise(self._mass, x)
[docs]
def precondition(self, x: np.ndarray) -> np.ndarray:
"""The operator of the inverse medium, ``Pᴴ μ C⁻¹ ε C⁻¹ μ P``, times the amplitudes:
the inverse of the stiffness but for the projections on the transverse waves."""
return self._blockwise(self._precondition, x)
# -- the frequencies -------------------------------------------------------------------
def _orthonormal(self, x: np.ndarray, mx: np.ndarray):
"""The columns of ``x`` made orthonormal in the product of the mass (``mx``: the
mass times them), those that depend on the others left out."""
gram = x.conj().T @ mx
values, vectors = eigh(0.5 * (gram + gram.conj().T))
keep = values > 1e-12 * values[-1]
t = vectors[:, keep] / np.sqrt(values[keep])
return x @ t, mx @ t
def _davidson(self, x: np.ndarray, bands: int, tol: float, maxiter: int):
"""The lowest waves of the pencil of the stiffness and the mass from the block
``x``: the Rayleigh-Ritz values of a subspace that grows by the preconditioned
residuals of the waves not yet within ``tol`` (those asked for: the first
``bands``), restarted from the waves and from those of the step before."""
block = x.shape[1]
v, mv = self._orthonormal(x, self.mass(x))
kv = self.stiffness(v)
before = None # the waves of the step before, in the basis
for iteration in range(1, maxiter + 1):
h = v.conj().T @ kv
values, c = eigh(0.5 * (h + h.conj().T))
values, c = values[:block], c[:, :block]
x, kx, mx = v @ c, kv @ c, mv @ c
norms = np.sqrt((np.abs(kx - mx * values) ** 2).sum(axis=0))
worst = float(norms[:bands].max())
active = norms > tol
if worst <= tol or iteration == maxiter or not np.any(active):
break
w = self.precondition((kx - mx * values)[:, active])
if v.shape[1] + w.shape[1] > SUBSPACE * block: # restart
both = c if before is None else np.hstack([c, before])
t, _ = np.linalg.qr(both)
v, kv, mv = v @ t, kv @ t, mv @ t
c = t.conj().T @ c
before = np.vstack([c, np.zeros((w.shape[1], c.shape[1]), dtype=c.dtype)])
for _ in range(2): # against the subspace, twice (Gram-Schmidt)
w -= v @ (mv.conj().T @ w)
w, mw = self._orthonormal(w, self.mass(w))
if w.shape[1] == 0:
break
if w.shape[1] < before.shape[0] - c.shape[0]:
before = before[: c.shape[0] + w.shape[1]]
v, mv = np.hstack([v, w]), np.hstack([mv, mw])
kv = np.hstack([kv, self.stiffness(w)])
return values, x, worst, iteration
[docs]
def frequencies(self, wavevector, bands: int, *, guess=None, tol: float = 1e-4,
maxiter: int = 300): # fmt: skip
"""The lowest ``bands`` angular frequencies at a wave vector and their amplitudes
(unknowns x block; a ``guess`` for them: those of a neighbouring wave vector)."""
self.at(wavevector)
n = self.unknowns
if not 0 < bands <= n:
raise ValueError(f"bands: between 1 and {n} (two per plane wave), got {bands}")
if n <= DENSE_LIMIT or bands > n // 8:
identity = np.eye(n, dtype=complex)
k = self.stiffness(identity)
m = None if self.uniform else self.mass(identity)
values, vectors = eigh(
0.5 * (k + k.conj().T), None if m is None else 0.5 * (m + m.conj().T)
)
return self._frequency(values[:bands]), vectors[:, :bands]
block = bands + max(3, bands // 4)
rng = np.random.default_rng(0)
x = rng.standard_normal((n, block)) + 1j * rng.standard_normal((n, block))
long_waves = 1.0 / (self.norm**2 * self.scale + 1.0)
x *= np.concatenate([long_waves.ravel(), long_waves.ravel()])[:, None]
if guess is not None and guess.shape == (n, block):
# the waves of the neighbouring wave vector, with a part of all the others: a
# block that misses one of the lowest waves altogether would never find it
x = guess + 0.1 * x * (np.linalg.norm(guess, axis=0) / np.linalg.norm(x, axis=0))
values, x, worst, iterations = self._davidson(x, bands, tol, maxiter)
if worst > tol:
log.warning(
"electromagnetic waves: the bands are within %.1e after %d iterations (asked: "
"%.1e)", worst, iterations, tol,
) # fmt: skip
return self._frequency(values[:bands]), x
def _frequency(self, values: np.ndarray) -> np.ndarray:
return np.sqrt(np.clip(values.real, 0.0, None) / self.scale)
def _crystal(sample, permittivity: dict, permeability, coarsen: int) -> PlaneWaves:
if not isinstance(sample, VoxelImage):
raise TypeError(
"electromagnetic waves: a voxel image (the plane waves are those of its grid; "
"voxelize a morphology, rather than mesh it)"
)
if not sample.periodic:
log.info("electromagnetic waves: the image is taken as the cell of a periodic medium")
data = np.asarray(sample.data)
if data.dtype.kind not in "iu":
raise ValueError("electromagnetic waves: an image of phases (integers)")
eps = _tensor_field(permittivity, data, "permittivity")
if eps.ndim == 3:
inverse = smoothed_inverse(eps, coarsen)
elif int(coarsen) != 1:
raise ValueError(
"coarsen: the average of the cells that the interfaces cut is that of isotropic "
"phases; with a tensor of permittivity the plane waves are those of the voxels"
)
else:
inverse = _invert(eps)
if isinstance(permeability, dict):
present = [permeability.get(int(p)) for p in np.unique(data)]
if all(v is not None and np.ndim(v) == 0 for v in present) and len(set(present)) == 1:
permeability = float(present[0]) # the same in every phase
if isinstance(permeability, dict):
mu = _tensor_field(permeability, data, "permeability")
if mu.ndim == 3:
inverse_mu = smoothed_inverse(mu, coarsen)
elif int(coarsen) != 1:
raise ValueError("coarsen: isotropic phases (see the permittivity)")
else:
inverse_mu = _invert(mu)
else:
if not float(permeability) > 0.0:
raise ValueError("electromagnetic waves: a positive permeability")
inverse_mu = 1.0 / float(permeability)
return PlaneWaves(inverse, sample.size, inverse_mu)
[docs]
def electromagnetic_band_structure(
sample,
permittivity: dict,
path=("G", "X", "M", "G", "R"),
*,
permeability=1.0,
bands: int = 8,
points: int = 12,
coarsen: int = 1,
tol: float = 1e-4,
):
"""The lowest ``bands`` frequencies of the electromagnetic Bloch waves of a periodic
cell (a :class:`~morphogen.image.VoxelImage` of phases) along ``path`` (corners of
the Brillouin zone, ``points`` per segment; or an array of wave vectors), by plane
waves (see the module): ``permittivity``, that of each phase (a number, three
principal values or a 3 x 3 tensor in the axes of the cell), and ``permeability`` (a
number for the whole cell, or those of the phases likewise). ``coarsen``: the plane
waves on a grid that many times coarser than the voxels, whose cells cut by the
interfaces take the averaged tensor of Meade et al. (isotropic phases). ``tol``: the
residual of the bands, in units of the square of the first reciprocal vector (the
squares of the frequencies are then within about its square). Returns a
:class:`~morphogen.homogenization.bloch.BandStructure`; at the centre of the zone the
first two frequencies are zero (the uniform fields)."""
from morphogen.homogenization.bloch import BandStructure, brillouin_path
crystal = _crystal(sample, permittivity, permeability, coarsen)
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))])
labels = []
else:
ks, dist, labels = brillouin_path(crystal.size, path, points)
freqs = np.zeros((len(ks), int(bands)))
guess = None
for i, k in enumerate(ks):
freqs[i], guess = crystal.frequencies(k, int(bands), guess=guess, tol=tol)
return BandStructure(ks, dist, freqs, labels)