Perfect Periodic BC

.gitignore

@@ -8,3 +8,4 @@ test/examples/ref/**/*.json
 .DS_Store
 .gitlab-ci-local
 Manifest.toml
+.vscode/

docs/make.jl

@@ -38,7 +38,7 @@ makedocs(
             "examples/examples.md",
             "examples/spheres.md",
             "examples/rings.md",
-            "examples/cavity.md",
+            "examples/cylinder.md",
             "examples/coaxial.md",
             "examples/cpw.md"
         ],

docs/src/config/boundaries.md

@@ -56,6 +56,10 @@
     [
         ...
     ],
+    "Periodic":
+    [
+        ...
+    ],
     "Postprocessing":
     {
         "Side": <string>,
@@ -121,6 +125,9 @@ surface.
 electrostatic simulations. Entries of the capacitance matrix are extracted corresponding to
 each terminal boundary.
 
+`"Periodic"` :  Array of objects for configuring periodic boundary conditions. This imposes
+periodicity on boundary surfaces that have identical meshes, meaning they are topologically periodic.
+
 `"Postprocessing"` :  Top-level object for configuring boundary postprocessing.
 
 `"Side" ["SmallerRefractiveIndex"]` :  Defines the postprocessing side for internal
@@ -512,6 +519,31 @@ to index the computed capacitance matrix.
 `"Attributes" [None]` :  Integer array of mesh boundary attributes for this terminal
 boundary.
 
+## `boundaries["Periodic"]`
+
+```json
+"Periodic":
+[
+    {
+        "DonorAttributes": [<int array>],
+        "ReceiverAttributes": [<int array>],
+        "Translation": [<float array>]
+    },
+    ...
+]
+```
+
+with
+
+`"DonorAttributes" [None]` :  Integer array of the donor attributes of the mesh boundary
+attributes for this periodic boundary.
+
+`"ReceiverAttributes" [None]` :  Integer array of the receiver attributes of the mesh boundary
+attributes for this periodic boundary.
+
+`"Translation" [None]` :  Defines the distance between the donor and receiver attributes in
+mesh units.
+
 ## `boundaries["Postprocessing"]["SurfaceFlux"]`
 
 ```json

docs/src/examples/cavity.md → docs/src/examples/cylinder.md

@@ -3,14 +3,16 @@
 <!--- SPDX-License-Identifier: Apache-2.0 --->
 ```
 
-# Eigenmodes of a Cylindrical Cavity
+# Eigenmodes of a Cylinder
 
 !!! note
 
     The files for this example can be found in the
-    [`examples/cavity/`](https://github.com/awslabs/palace/blob/main/examples/cavity)
+    [`examples/cylinder/`](https://github.com/awslabs/palace/blob/main/examples/cylinder)
     directory of the *Palace* source code.
 
+## Cavity
+
 This example demonstrates *Palace*'s eigenmode simulation type to solve for the lowest
 frequency modes of a cylindrical cavity resonator. In particular, we consider a cylindrical
 cavity filled with Teflon (``\varepsilon_r = 2.08``,
@@ -55,12 +57,12 @@ where ``k=\omega\sqrt{\mu\varepsilon}``, ``\eta=\sqrt{\mu/\varepsilon}``, and
 ``\beta=l\pi/d``.
 
 The initial Gmsh mesh for this problem, from
-[`mesh/cavity_prism.msh`](https://github.com/awslabs/palace/blob/main/examples/cavity/mesh/cavity_prism.msh),
+[`mesh/cavity_prism.msh`](https://github.com/awslabs/palace/blob/main/examples/cylinder/mesh/cavity_prism.msh),
 is shown below. We use quadratic triangular prism elements. There are also two other
 included mesh files,
-[`mesh/cavity_tet.msh`](https://github.com/awslabs/palace/blob/main/examples/cavity/mesh/cavity_tet.msh)
+[`mesh/cavity_tet.msh`](https://github.com/awslabs/palace/blob/main/examples/cylinder/mesh/cavity_tet.msh)
 and
-[`mesh/cavity_hex.msh`](https://github.com/awslabs/palace/blob/main/examples/cavity/mesh/cavity_hex.msh),
+[`mesh/cavity_hex.msh`](https://github.com/awslabs/palace/blob/main/examples/cylinder/mesh/cavity_hex.msh),
 which use curved tetrahedral and hexahedral elements, respectively.
 
 ```@raw html
@@ -70,9 +72,9 @@ which use curved tetrahedral and hexahedral elements, respectively.
 ```
 
 There are two configuration files for this problem,
-[`cavity_pec.json`](https://github.com/awslabs/palace/blob/main/examples/cavity/cavity_pec.json)
+[`cavity_pec.json`](https://github.com/awslabs/palace/blob/main/examples/cylinder/cavity_pec.json)
 and
-[`cavity_impedance.json`](https://github.com/awslabs/palace/blob/main/examples/cavity/cavity_impedance.json).
+[`cavity_impedance.json`](https://github.com/awslabs/palace/blob/main/examples/cylinder/cavity_impedance.json).
 
 In both, the [`config["Problem"]["Type"]`](../config/problem.md#config%5B%22Problem%22%5D)
 field is set to `"Eigenmode"`, and we use the mesh shown above. The material properties for
@@ -188,10 +190,10 @@ for the ``\text{TE}_{011}`` mode is shown below.
 </p>
 ```
 
-## Mesh convergence
+### Mesh convergence
 
 The effect of mesh size can be investigated for the cylindrical cavity resonator using
-[`convergence_study.jl`](https://github.com/awslabs/palace/blob/main/examples/cavity/convergence_study.jl).
+[`convergence_study.jl`](https://github.com/awslabs/palace/blob/main/examples/cylinder/convergence_study.jl).
 For a polynomial order of solution and refinement level, a mesh is generated using Gmsh
 using polynomials of the same order to resolve the boundary geometry. The eigenvalue
 problem is then solved for ``f_{\text{TM},010}`` and ``f_{\text{TE},111}``, and the
@@ -215,6 +217,53 @@ maximum convergence rate is ``2p`` [[2]](#References). The figures demonstrate t
 increasing the polynomial order of the solution will give reduced error, however the effect
 may only become significant on sufficiently refined meshes.
 
+## Waveguide
+
+This example demonstrates the eigenmode simulation type in  *Palace* to solve for the
+eigenfrequencies of a circular waveguide. We consider the interior material to be vacuum
+with parameters ``\varepsilon_r = 1.0`` and ``\tan\delta = 0``, and with radius
+``a = 2.74\text{ cm}`` and height ``d = 2a``.
+Periodic boundary conditions (BCs) are applied in the $z$-direction with the wavelength $\lambda = d$.
+According to [[1]](#References), the propagation constants of the ``\text{TE}_{nm}`` and ``\text{TM}_{nm}``
+modes are given by
+
+```math
+\beta_{nm} = \frac{2 \pi}{\lambda} = \sqrt{\left( 2\pi f\sqrt{\mu\varepsilon} \right)^2 - \left(\frac{p^\prime_{nm}}{a}\right)^2}
+```
+
+where $p^\prime_{nm}$ is defined in [[1]](#References). Thus, the corresponding analytical
+eigenfrequencies are given by
+
+```math
+f_{nm} = \sqrt{\frac{\frac{1}{\lambda^2} + \left(\frac{p^\prime_{nm}}{2\pi a}\right)^2}{\mu\varepsilon}}
+```
+
+For this problem, we use curved tetrahedral elements from the mesh file
+[`mesh/cavity_tet.msh`](https://github.com/awslabs/palace/blob/main/examples/cylinder/mesh/cavity_tet.msh),
+and the configuration file
+[`waveguide.json`](https://github.com/awslabs/palace/blob/main/examples/cylinder/waveguide.json).
+
+The main difference between this configuration file and those used in the cavity example is in the
+`"Boundaries"` object. In `cavity_pec.json` and `cavity_impedance.json`, either a perfect electric
+conductor or impedance boundary condition is prescribed on all boundaries.
+In contrast, `waveguide.json` specifies a perfect electric conductor ("PEC") boundary condition for
+the exterior surface and a periodic boundary condition (`"Periodic"`) on the cross-sections of the
+cylinder (in the $z-$ direction). The periodic attribute pairs are defined by `"DonorAttributes"`
+and `"ReceiverAttributes"`, and the distance between them is given by the `"Translation"` vector
+in mesh units.
+
+After running `waveguide.json`, we find that some of the frequencies listed in `postpro/waveguide/eig.csv`
+are close to those computed using the above formula. The differences between the analytical and numerical
+mode frequencies are summarized in the table below:
+
+| ``\text{mode}``    | ``f_{\text{analytical}}`` | ``f_{\text{numerical}}`` | ``\text{relative error}`` |
+|:------------------ | -------------------------:| ------------------------:| -------------------------:|
+| ``\text{TM}_{01}`` | ``6.89438\text{ GHz}``    | ``6.895697\text{ GHz}``  | ``0.01911\text{ \%}``     |
+| ``\text{TE}_{11}`` | ``6.34515\text{ GHz}``    | ``6.346605\text{ GHz}``  | ``0.02288\text{ \%}``     |
+| ``\text{TE}_{21}`` | ``7.63480\text{ GHz}``    | ``7.635135\text{ GHz}``  | ``0.00434\text{ \%}``     |
+
+Note that the spurious frequencies in `postpro/waveguide/eig.csv` have been ignored.
+
 ## References
 
 [1] D. M. Pozar, _Microwave Engineering_, Wiley, Hoboken, NJ, 2012.\

docs/src/examples/examples.md

@@ -18,6 +18,6 @@ more details.
 
   - [Capacitance Matrix for Two Spheres](spheres.md)
   - [Inductance Matrix for a Pair of Concentric Rings](rings.md)
-  - [Eigenmodes of a Cylindrical Cavity](cavity.md)
+  - [Eigenmodes of a Cylinder](cylinder.md)
   - [Signal Propagation in a Coaxial Cable](coaxial.md)
   - [Crosstalk Between Coplanar Waveguides](cpw.md)

examples/cavity/cavity.jl → examples/cylinder/cavity.jl

@@ -25,7 +25,7 @@ include(joinpath(@__DIR__, "mesh", "mesh.jl"))
 
 Solve the cavity mode problem, with an automatically generated Gmsh mesh
 
-See also [`generate_cylindrical_cavity_mesh`](@ref)
+See also [`generate_cylindrical_mesh`](@ref)
 
 # Arguments
 
@@ -34,8 +34,8 @@ See also [`generate_cylindrical_cavity_mesh`](@ref)
   - geo_order - the polynomial order used in the mesh representation
   - refinement - the level of mesh refinement
   - mesh_type - 0 = tetrahedral mesh, 1 = prism mesh, 2 = hexahedral mesh
-  - radius - the radius of the cavity resonator
-  - aspect_ratio - the ratio of the DIAMETER of the cavity to the height
+  - radius - the radius of the cylinder
+  - aspect_ratio - the ratio of the DIAMETER of the cylinder to the height
   - num_processors - number of processors to use for the simulation
   - cleanup_files - delete temporary mesh and configuration files after simulation
 """
@@ -56,10 +56,10 @@ function solve_cavity_resonator(
     @assert mesh_type ∈ [0, 1, 2]
 
     # Generate a mesh
-    cavity_dir = @__DIR__
+    cylinder_dir = @__DIR__
     file_root = string("cavity_p", order, "_h", refinement)
     mesh_filename = string(file_root, ".msh")
-    generate_cylindrical_cavity_mesh(
+    generate_cylindrical_mesh(
         filename=mesh_filename,
         refinement=refinement,
         order=geo_order,
@@ -71,14 +71,14 @@ function solve_cavity_resonator(
 
     # Generate solver parameter file
     params["Solver"]["Order"] = order
-    params["Model"]["Mesh"] = joinpath(cavity_dir, "mesh", mesh_filename)
+    params["Model"]["Mesh"] = joinpath(cylinder_dir, "mesh", mesh_filename)
     json_filename = string(file_root, ".json")
-    open(joinpath(cavity_dir, json_filename), "w") do f
+    open(joinpath(cylinder_dir, json_filename), "w") do f
         return JSON.print(f, params)
     end
 
     # Call the solver, storing the terminal output
-    call_command = Cmd(`palace -np $num_processors $json_filename`, dir=cavity_dir)
+    call_command = Cmd(`palace -np $num_processors $json_filename`, dir=cylinder_dir)
     log_file = read(call_command, String)
     # println(log_file)
 
@@ -89,13 +89,14 @@ function solve_cavity_resonator(
     dof = parse(Int, filter(isdigit, log_file[start_ind:end_ind]))
 
     # Extract the top two frequency modes
-    eig_df = CSV.read(joinpath(cavity_dir, "postpro", "convergence", "eig.csv"), DataFrame)
+    eig_df =
+        CSV.read(joinpath(cylinder_dir, "postpro", "convergence", "eig.csv"), DataFrame)
     eig = Matrix(eig_df[:, 2:end])[:, 1]
 
     # Clean up the parameter and mesh file
     if cleanup_files
-        rm(joinpath(cavity_dir, "mesh", mesh_filename))
-        rm(joinpath(cavity_dir, json_filename))
+        rm(joinpath(cylinder_dir, "mesh", mesh_filename))
+        rm(joinpath(cylinder_dir, json_filename))
     end
 
     return dof, eig
@@ -212,14 +213,14 @@ function generate_cavity_convergence_data(;
     num_processors::Integer = 1
 )
     # Load the default JSON script (the file contains comments and we need to sanitize them)
-    cavity_dir = @__DIR__
-    params = open(joinpath(cavity_dir, "cavity_pec.json"), "r") do f
+    cylinder_dir = @__DIR__
+    params = open(joinpath(cylinder_dir, "cavity_pec.json"), "r") do f
         return JSON.parse(join(getindex.(split.(eachline(f), "//"), 1), "\n"))
     end
 
     # Update the dictionary
     params["Problem"]["Verbose"] = 2
-    params["Problem"]["Output"] = joinpath(cavity_dir, "postpro", "convergence")
+    params["Problem"]["Output"] = joinpath(cylinder_dir, "postpro", "convergence")
     params["Model"]["Refinement"]["UniformLevels"] = 0 # Don't perform any mesh refinement
     params["Solver"]["Eigenmode"]["Save"] = 0 # Don't write any fields to file
     params["Solver"]["Eigenmode"]["N"] = 4 # Look only for the top 4 modes

examples/cavity/cavity_impedance.json → examples/cylinder/cavity_impedance.json

@@ -3,11 +3,11 @@
   {
     "Type": "Eigenmode",
     "Verbose": 2,
-    "Output": "postpro/impedance"
+    "Output": "postpro/cavity_impedance"
   },
   "Model":
   {
-    "Mesh": "mesh/cavity_prism.msh",
+    "Mesh": "mesh/cylinder_prism.msh",
     "L0": 1.0e-2,  // cm
     "Refinement":
     {
@@ -41,7 +41,7 @@
     "Impedance":
     [
       {
-        "Attributes": [2],
+        "Attributes": [2, 3, 5],
         "Rs": 0.0184   // Ω, surface resistance of Cu @ 5 GHz
       }
     ]

examples/cavity/cavity_pec.json → examples/cylinder/cavity_pec.json

@@ -3,11 +3,11 @@
   {
     "Type": "Eigenmode",
     "Verbose": 2,
-    "Output": "postpro/pec"
+    "Output": "postpro/cavity_pec"
   },
   "Model":
   {
-    "Mesh": "mesh/cavity_prism.msh",
+    "Mesh": "mesh/cylinder_prism.msh",
     "L0": 1.0e-2,  // cm
     "Refinement":
     {
@@ -40,7 +40,7 @@
   {
     "PEC":
     {
-      "Attributes": [2]
+      "Attributes": [2, 3, 5]
     }
   },
   "Solver":

examples/cavity/convergence_study.jl → examples/cylinder/convergence_study.jl

@@ -112,8 +112,8 @@ for mesh_type ∈ [0, 1, 2]
     println("k_f_TM_010 =", map(x -> round.(x, digits=2), k_f_TM_010))
     println("k_f_TE_111 =", map(x -> round.(x, digits=2), k_f_TE_111))
 
-    cavity_dir = @__DIR__
-    output_dir = joinpath(cavity_dir, "postpro", "convergence")
+    cylinder_dir = @__DIR__
+    output_dir = joinpath(cylinder_dir, "postpro", "convergence")
     lmesh_name = lowercase(mesh_name)
 
     savefig(pp, joinpath(output_dir, string("cavity_error_", lmesh_name, ".png")))