Source code for tidy3d.plugins.autograd.invdes.symmetries

from __future__ import annotations

from collections.abc import Sequence
from typing import TYPE_CHECKING, Literal

import autograd.numpy as np

if TYPE_CHECKING:
    from numpy.typing import NDArray

MirrorSymmetrySide = Literal["low", "high"]
MirrorSymmetry = tuple[MirrorSymmetrySide | None, ...]


def _flip_axis(array: NDArray, axis: int) -> NDArray:
    """Flip an array along a given axis using slicing compatible with autograd."""
    index = [slice(None)] * array.ndim
    index[axis] = slice(None, None, -1)
    return array[tuple(index)]


[docs] def symmetrize_mirror(array: NDArray, axis: int | tuple[int, int]) -> NDArray: """ Symmetrizes the parameter array by averaging the mirrored parts of the array. The axis argument specifies the symmetry axis. Parameters ---------- array : NDArray The input array to be symmetrized. axis: int | tuple[int, int] The symmetry axis. This can either be a single axis (x=0 or y=1) or a tuple of both axes. Returns ------- NDArray The array after applying the mirror symmetrization. Example ------- >>> import autograd.numpy as np >>> from tidy3d.plugins.autograd.invdes.symmetries import symmetrize_mirror >>> arr = np.asarray([ ... [1, 2], ... [3, 4] ... ]) >>> res_x = symmetrize_mirror(arr, axis=0) >>> res_y = symmetrize_mirror(arr, axis=1) >>> assert np.all(np.isclose(res_x, np.asarray([ ... [2, 3], ... [2, 3] ... ]))) >>> assert np.all(np.isclose(res_y, np.asarray([ ... [1.5, 1.5], ... [3.5, 3.5] ... ]))) """ if isinstance(axis, int) and (axis != 0 and axis != 1): raise ValueError(f"Invalid axis: expected 0, 1, or Sequence thereof, but got {axis}") if array.ndim != 2: raise ValueError(f"Invalid array shape: {array.shape}. Need 2d array.") if isinstance(axis, Sequence) and ( len(axis) != 2 or axis[0] not in [0, 1] or axis[1] not in [0, 1] or axis[0] == axis[1] ): raise ValueError(f"Invalid axis: expected 0, 1, or Sequence thereof, but got {axis}") # Case 1: Symmetrize along both axes if isinstance(axis, Sequence): # Symmetrize along axis 0 array = (array + _flip_axis(array, 0)) / 2.0 # Symmetrize along axis 1 array = (array + _flip_axis(array, 1)) / 2.0 return array # Case 2: Symmetrize along a single axis return (array + _flip_axis(array, axis)) / 2.0
def expand_mirror_symmetry( array: NDArray, symmetry: MirrorSymmetry ) -> tuple[NDArray, tuple[slice, ...]]: """Expand an array across mirrored boundaries and return slices for the original domain. Parameters ---------- array : NDArray Input array defined on the reduced symmetric domain. symmetry : tuple[Literal["low", "high"] | None, ...] Per-axis mirror boundary specification. ``"low"`` mirrors the lower boundary of the axis, ``"high"`` mirrors the upper boundary, and ``None`` leaves the axis unchanged. Returns ------- tuple[NDArray, tuple[slice, ...]] The expanded array and slices that recover the original domain from the expanded result. """ if len(symmetry) != array.ndim: raise ValueError( f"Invalid symmetry specification: expected {array.ndim} axes, got {len(symmetry)}." ) expanded = array crop_slices = [slice(None)] * array.ndim for axis, side in enumerate(symmetry): if side is None: crop_slices[axis] = slice(0, expanded.shape[axis]) continue if side not in ("low", "high"): raise ValueError( f"Invalid symmetry side {side!r}; expected one of ('low', 'high', None)." ) axis_size = expanded.shape[axis] mirrored = _flip_axis(expanded, axis) if side == "low": expanded = np.concatenate((mirrored, expanded), axis=axis) crop_slices[axis] = slice(axis_size, 2 * axis_size) else: expanded = np.concatenate((expanded, mirrored), axis=axis) crop_slices[axis] = slice(0, axis_size) return expanded, tuple(crop_slices)
[docs] def symmetrize_rotation(array: NDArray) -> NDArray: """ Symmetrizes the parameter array by averaging over all four 90-degree rotations. The input array must be square. Parameters ---------- array : NDArray The input array to be symmetrized. Returns ------- NDArray The array after applying rotational symmetrization. Example ------- >>> import autograd.numpy as np >>> from tidy3d.plugins.autograd.invdes.symmetries import symmetrize_rotation >>> arr = np.asarray([ ... [0, 0, 0], ... [1, 5, 2], ... [8, 1, 8] ... ]) >>> res = symmetrize_rotation(arr) >>> assert np.all(np.isclose(res, np.asarray([ ... [4, 1, 4], ... [1, 5, 1], ... [4, 1, 4] ... ]))) """ if array.ndim != 2: raise ValueError(f"Invalid array shape: {array.shape}. Need 2d array.") if array.shape[0] != array.shape[1]: raise ValueError( f"Invalid array shape: {array.shape}. Array must be square for rotational symmetry." ) # Average the array with its 90, 180, and 270 degree rotations # We manually implement rotations using Transpose (.T) and Slicing ([::-1]) # to ensure full compatibility with autograd. # 0 degrees: array # 90 degrees CCW: Transpose -> Flip Rows (equivalent to array.T[::-1, :]) rot90 = array.T[::-1, :] # 180 degrees: Flip Rows -> Flip Cols (equivalent to array[::-1, ::-1]) rot180 = array[::-1, ::-1] # 270 degrees CCW: Transpose -> Flip Cols (equivalent to array.T[:, ::-1]) rot270 = array.T[:, ::-1] return (array + rot90 + rot180 + rot270) / 4.0
[docs] def symmetrize_diagonal(array: NDArray, anti: bool = False) -> NDArray: """ Symmetrizes the parameter array by averaging it with its transpose. Can symmetrize along the main diagonal or the anti-diagonal. Parameters ---------- array : NDArray The input array to be symmetrized. Must be square. anti : bool, optional If False (default), symmetrizes along the main diagonal (top-left to bottom-right). If True, symmetrizes along the anti-diagonal (top-right to bottom-left). Returns ------- NDArray The array after applying diagonal symmetrization. Example ------- >>> import autograd.numpy as np >>> from tidy3d.plugins.autograd.invdes.symmetries import symmetrize_diagonal >>> arr = np.asarray([ ... [1, 2], ... [4, 7], ... ]) >>> res = symmetrize_diagonal(arr) >>> res_anti = symmetrize_diagonal(arr, anti=True) >>> assert np.all(np.isclose(res, np.asarray([ ... [1, 3], ... [3, 7] ... ]))) >>> assert np.all(np.isclose(res_anti, np.asarray([ ... [4, 2], ... [4, 4] ... ]))) """ if array.ndim != 2: raise ValueError(f"Invalid array shape: {array.shape}. Need 2d array.") if array.shape[0] != array.shape[1]: raise ValueError( f"Invalid array shape: {array.shape}. Array must be square for diagonal symmetry." ) if anti: # Anti-diagonal symmetrization. # Mathematically equivalent to averaging A with the flip of A transposed. # np.flip(array.T) is equivalent to array.T[::-1, ::-1] anti_transpose = array.T[::-1, ::-1] return (array + anti_transpose) / 2.0 # Standard main diagonal symmetry: (A + A_transpose) / 2 return (array + array.T) / 2.0