Merge pull request #693 from awslabs/simlapointe/floquet-port-clean

Add Floquet port boundary condition

Author: simlapointe

CHANGELOG.md

@@ -42,6 +42,9 @@ The format of this changelog is based on
     validation and can be used to re-run the same simulation deterministically; it can also
     be printed without running via `--dry-run` [PR 719](https://github.com/awslabs/palace/pull/719).
   - Enable S-parameters calculations when both lumped and wave ports are present [PR 743](https://github.com/awslabs/palace/pull/743).
+  - Added Floquet port boundary conditions for frequency-domain driven simulations on
+    periodic structures, with support for oblique incidence, multi-order diffraction,
+    TE/TM/circular polarization, and adaptive frequency sweeps. [PR 693](https://github.com/awslabs/palace/pull/693).
 
 #### Interface Changes
 

docs/make.jl

@@ -99,7 +99,8 @@ makedocs(
             "examples/cylinder.md",
             "examples/coaxial.md",
             "examples/cpw.md",
-            "examples/cpw2d.md"
+            "examples/cpw2d.md",
+            "examples/dielectric_grating.md"
         ],
         "faq.md",
         "For Developers" => Any[

docs/src/assets/examples/dielectric_grating_geometry.png

@@ -42,6 +42,10 @@ SPDX-License-Identifier: Apache-2.0
     {
         ...
     },
+    "FloquetPort":
+    [
+        ...
+    ],
     "SurfaceCurrent":
     [
         ...
@@ -121,6 +125,15 @@ wave port boundary mode analysis, overriding any other boundary condition assign
 attributes. Only relevant when wave port boundaries are specified under
 [`config["Boundaries"]["WavePort"]`](#boundaries%5B%22WavePort%22%5D).
 
+`"FloquetPort"` :  Array of objects for configuring Floquet port boundary conditions for
+periodic structures. Floquet ports provide absorbing boundary conditions for diffraction
+gratings and other periodic electromagnetic devices, enabling the computation of
+diffraction efficiencies (S-parameters) for multiple propagating orders. Floquet port
+boundaries are only available for frequency domain driven simulations and **require periodic
+boundary conditions** to be configured under
+[`config["Boundaries"]["Periodic"]`](#boundaries%5B%22Periodic%22%5D) with exactly two
+`"BoundaryPairs"` (periodicity in two transverse directions).
+
 `"SurfaceCurrent"` :  Array of objects for configuring surface current boundary conditions.
 This boundary prescribes a unit source surface current excitation on the given boundary in
 order to excite a frequency or time domain driven simulation or magnetostatic simulation.
@@ -482,6 +495,62 @@ with
 impedance, absorbing, or conductivity boundary condition that may be assigned to the same
 attributes for the purpose of the 2D wave port boundary mode problem.
 
+## `boundaries["FloquetPort"]`
+
+```json
+"FloquetPort":
+[
+    {
+        "Index": <int>,
+        "Attributes": [<int array>],
+        "Excitation": <bool>,
+        "IncidentPolarization": <string>,
+        "MaxOrder": <int>
+    },
+    ...
+]
+```
+
+with
+
+`"Index" [None]` :  Index of this Floquet port, used in postprocessing output files.
+
+`"Attributes" [None]` :  Integer array of mesh boundary attributes for this Floquet port
+boundary. The port face must be planar and lie on the true boundary of the computational
+domain (one-sided, like wave ports). The medium adjacent to the port must be homogeneous
+and isotropic.
+
+!!! note "Periodic boundary conditions required"
+
+    Floquet ports require periodic boundary conditions
+    ([`config["Boundaries"]["Periodic"]`](#boundaries%5B%22Periodic%22%5D)) with exactly
+    two `"BoundaryPairs"` defining periodicity in the two transverse directions. The
+    `"FloquetWaveVector"` in the periodic configuration determines the angle of incidence:
+    zero for normal incidence, nonzero for oblique. The wave vector is specified in radians
+    per mesh length unit.
+
+`"Excitation" [false]` :  Turns on or off port excitation for this Floquet port boundary.
+When excited, a plane wave in the specular (0,0) diffraction order is injected with unit
+power.
+
+`"IncidentPolarization" ["TE"]` :  Polarization of the incident plane wave. Available
+options are:
+
+  - `"TE"` :  Transverse electric (s-polarization). Electric field perpendicular to the
+    plane of incidence.
+  - `"TM"` :  Transverse magnetic (p-polarization). Electric field in the plane of
+    incidence.
+  - `"RHC"` :  Right-hand circular polarization. Equal superposition of TE and TM with
+    90° phase shift: ``\mathbf{E} = (\hat{e}_\text{TE} + j\hat{e}_\text{TM})/\sqrt{2}``.
+  - `"LHC"` :  Left-hand circular polarization. Equal superposition of TE and TM with
+    -90° phase shift: ``\mathbf{E} = (\hat{e}_\text{TE} - j\hat{e}_\text{TM})/\sqrt{2}``.
+
+`"MaxOrder" [-1]` :  Maximum diffraction order index to include. With `MaxOrder = M`, all
+orders ``(m, n)`` with ``|m| \leq M`` and ``|n| \leq M`` are included, each with both TE
+and TM polarizations. A value of `-1` (default) enables automatic selection. A value of `0`
+includes only the specular (0,0) order. Higher values are needed when the periodic cell
+supports propagating higher-order diffraction.
+
 ## `boundaries["SurfaceCurrent"]`
 
 ```json
@@ -599,6 +668,7 @@ boundary.
 "Periodic":
 {
     "FloquetWaveVector": [<float array>],
+    "FloquetReferenceFrequency": <float>,
     "BoundaryPairs":
     [
         {
@@ -631,7 +701,28 @@ to the receiver attribute in mesh units. If neither `"Translation"` or `"AffineT
 specified, the transformation between donor and receiver boundaries is automatically detected.
 
 `"FloquetWaveVector" [None]` :  Optional floating point array defining the phase delay between the
-periodic boundaries in the X/Y/Z directions in radians per mesh unit.
+periodic boundaries in the X/Y/Z directions in radians per mesh unit. When used with
+`"FloquetReferenceFrequency"`, it is defined at the reference frequency.
+
+For a Floquet port, this is the tangential component of the incident wave vector. For example,
+for a port normal to z with periodicity in x and y, the `"FloquetWaveVector"`,
+``\bm{k}_{F,\mathrm{ref}}``, can be computed from the incidence and azimuthal angles as
+
+```math
+k_{F,\mathrm{ref},x} = k_\mathrm{ref}\sin\theta\cos\phi,\qquad
+k_{F,\mathrm{ref},y} = k_\mathrm{ref}\sin\theta\sin\phi,
+```
+
+where ``k_\mathrm{ref} = \frac{2\pi f_\mathrm{ref}}{c_0}\sqrt{\mu_r\varepsilon_r},``, where
+``f_\mathrm{ref}`` is the `"FloquetReferenceFrequency"`, ``\theta`` is the incidence angle away
+from the port normal, and ``\phi`` is the azimuthal direction in the periodic plane.
+
+`"FloquetReferenceFrequency" [None]` :  Optional frequency in GHz at which the
+`"FloquetWaveVector"` is defined. When specified, the Bloch wave vector scales linearly with
+frequency during a driven simulation frequency sweep,
+``\bm{k}_F(f) = \bm{k}_{F,\mathrm{ref}} f / f_\mathrm{ref}``, preserving the incidence
+angles across the sweep. When not specified (default), the wave vector is held constant
+across all frequencies. Only supported for driven simulations.
 
 ## `boundaries["Postprocessing"]["SurfaceFlux"]`
 

docs/src/assets/examples/dielectric_grating_reflection.png

@@ -0,0 +1,71 @@
+```@raw html
+<!---
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+--->
+```
+
+# Floquet Ports for a Dielectric Grating
+
+!!! note
+
+    The files for this example can be found in the
+    [`examples/dielectric_grating/`](https://github.com/awslabs/palace/blob/main/examples/dielectric_grating)
+    directory of the *Palace* source code.
+
+This example demonstrates the use of Floquet port boundary conditions for computing
+diffraction efficiencies (S-parameters) of a 3D periodic dielectric grating. A TE-polarized
+plane wave is incident at 30° oblique incidence on a unit cell containing a dielectric bar,
+and the reflected and transmitted power in each diffraction order is computed over a
+frequency sweep.
+
+The computational domain is a single unit cell of a doubly-periodic structure with periods
+``a = 4\text{ cm}`` in x and ``b = 1\text{ cm}`` in y. The total domain height is
+``2L = 8\text{ cm}`` in z. A dielectric bar (``\varepsilon_r = 7``) of dimensions
+``2 \times 0.5 \times 0.5\text{ cm}`` is centered at the origin, surrounded by vacuum
+(``\varepsilon_r = 1``). Floquet port boundaries are placed at ``z = \pm 4\text{ cm}`` and
+periodic boundary conditions with a Bloch phase shift are applied on the x and y faces. The
+Floquet wave vector ``\bm{k}_F = (0, 1.0479, 0)\text{ cm}^{-1}`` at the reference
+frequency of ``10\text{ GHz}`` corresponds to 30° oblique incidence, and scales linearly
+with frequency to maintain a constant incidence angle across the sweep.
+
+The unit cell geometry is shown below. The translucent blue volume is vacuum
+(``\varepsilon_r = 1``), and the orange volume is the dielectric bar
+(``\varepsilon_r = 7``).
+
+```@raw html
+<br/><p align="center">
+  <img src="../../assets/examples/dielectric_grating_geometry.png" width="60%" />
+</p><br/>
+```
+
+The domain is discretized with a structured hexahedral mesh generated by
+[`mesh/mesh.jl`](https://github.com/awslabs/palace/blob/main/examples/dielectric_grating/mesh/mesh.jl)
+using Gmsh. A second-order finite element approximation (``p = 2``) is used for the
+solution. Two configuration files are provided:
+
+  - [`dielectric_grating_uniform.json`](https://github.com/awslabs/palace/blob/main/examples/dielectric_grating/dielectric_grating_uniform.json):
+    Uniform sweep from 2 to 12 GHz with ``\Delta f = 2.0\text{ GHz}`` (6 frequency points).
+  - [`dielectric_grating_adaptive.json`](https://github.com/awslabs/palace/blob/main/examples/dielectric_grating/dielectric_grating_adaptive.json):
+    Adaptive fast frequency sweep from 2 to 12 GHz with initial step
+    ``\Delta f = 0.05\text{ GHz}`` and tolerance ``10^{-3}``.
+
+The S-parameter magnitudes from the uniform (markers) and adaptive (lines) sweeps are shown
+below:
+
+```@raw html
+<br/><p align="center">
+  <img src="../../assets/examples/dielectric_grating_reflection.png" width="70%" />
+  <img src="../../assets/examples/dielectric_grating_transmission.png" width="70%" />
+</p><br/>
+```
+
+The adaptive sweep captures the sharp spectral features with high fidelity while using only
+a modest number of frequency samples, and agrees well with the uniform sweep results.
+
+Below the Rayleigh anomaly at 8.66 GHz (dashed line), only the specular (0,0)TE mode carries
+power — the grating behaves as a partially reflecting dielectric slab. Above 8.66 GHz, the
+first-order (±1,0) diffraction modes become propagating and appear as additional reflection and
+transmission channels. Near the Rayleigh anomaly, a sharp *Fano resonance* appears around
+8.3 GHz: the incident wave couples to a leaky guided mode of the dielectric slab, producing
+a characteristic asymmetric lineshape with a sharp reflection peak and transmission dip.

docs/src/assets/examples/dielectric_grating_transmission.png

@@ -25,3 +25,4 @@ more details.
   - [Signal Propagation in a Coaxial Cable](coaxial.md)
   - [Crosstalk Between Coplanar Waveguides](cpw.md)
   - [2D Coplanar Waveguide Mode Analysis](cpw2d.md)
+  - [Floquet Ports for a Dielectric Grating](dielectric_grating.md)

docs/src/config/boundaries.md

@@ -151,6 +151,35 @@ for implementation details.
         points from the signal attribute toward the ground attribute. Lightweight
         polarity-only alternative to `"VoltagePath"` (no GSLIB).
 
+  - [`config["Boundaries"]["FloquetPort"]`](../config/boundaries.md#boundaries%5B%22FloquetPort%22%5D) :
+    Floquet ports are available for frequency domain driven simulations on periodic
+    structures (gratings, metasurfaces, photonic crystals). They provide an absorbing
+    boundary condition that decomposes the scattered field into Floquet diffraction orders
+    and extracts power-normalized S-parameters for each propagating order.
+
+    Floquet ports require periodic boundary conditions to be configured under
+    [`config["Boundaries"]["Periodic"]`](../config/boundaries.md#boundaries%5B%22Periodic%22%5D).
+    The `"FloquetWaveVector"` in the periodic configuration specifies the tangential
+    component of the incident wave vector, which determines the angle of incidence. For
+    normal incidence, set the wave vector to zero. For frequency sweeps at a fixed angle
+    of incidence, set `"FloquetReferenceFrequency"` to the frequency (in GHz) at which the
+    wave vector is defined. The wave vector then scales linearly with frequency according
+    to ``\bm{k}_F(f) = \bm{k}_{F,\mathrm{ref}} f / f_\mathrm{ref}``, where
+    ``\bm{k}_{F,\mathrm{ref}}`` is `"FloquetWaveVector"` and ``f_\mathrm{ref}`` is
+    `"FloquetReferenceFrequency"`, maintaining a constant incidence angle across the sweep.
+
+    The incident field is a plane wave in the specular (0,0) diffraction order with
+    user-specified polarization (TE, TM, or circular RHC/LHC). S-parameters are extracted
+    for all propagating diffraction orders within `"MaxOrder"` and reported in the
+    `port-floquet-S.csv` output file. Each mode is labeled as
+    `S[P<port>(<m>,<n>)<pol>][<exc>]` where `<port>` is the port index, `(<m>,<n>)` is
+    the diffraction order, `<pol>` is the polarization (TE/TM or RHC/LHC for circular
+    excitation), and `<exc>` is the excitation index. Values of `nan` are given to non-propagating
+    modes.
+
+    The port boundary must be planar and on the true boundary of the computational domain.
+    The medium adjacent to the port must be homogeneous and isotropic.
+
 For each port, the excitation is normalized to have unit incident power over the port boundary
 surface.
 
@@ -182,9 +211,10 @@ can only be part of one excitation.
 
     Any `"Index"` of [`"LumpedPort"`](../config/boundaries.md#boundaries%5B%22LumpedPort%22%5D),
     [`"WavePort"`](../config/boundaries.md#boundaries%5B%22WavePort%22%5D),
+    [`"FloquetPort"`](../config/boundaries.md#boundaries%5B%22FloquetPort%22%5D),
     [`"SurfaceCurrent"`](../config/boundaries.md#boundaries%5B%22SurfaceCurrent%22%5D), or
     [`"Terminal"`](../config/boundaries.md#boundaries%5B%22Terminal%22%5D) must be unique, including between
-    different boundary conditions types (e.g. you can not have an lumped port and wave port both with
+    different boundary conditions types (e.g. you can not have a lumped port and wave port both with
     `Index: 5`).
 
 ## Surface current excitation