Merge pull request #40 from awslabs/sjg/release-0.11.1

Release v0.11.1

Author: sebastiangrimberg

CHANGELOG.md

@@ -11,6 +11,22 @@ The format of this changelog is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.11.1] - 2023-05-03
+
+  - Fixed a bug for interface dielectric loss postprocessing including when using
+    `--dry-run`.
+  - Fixed a regression bug affecting second-order absorbing boundary conditions.
+  - Fixed a bug when the number of processors was large enough that some subdomains own no
+    true dofs.
+  - Fixed memory bug in destruction of SuperLU solver.
+  - Fixed some typos in the documentation.
+  - Fixed a bug in the cavity convergence study example for the coarsest hexahedral mesh
+    case, as well as some other minor Julia fixes in the `examples/` and `scripts/`
+    directories.
+  - Added updates to superbuild including better ARPACK support, though still experimental
+    compared to SLEPc.
+  - Added updated submodules for superbuild.
+
 ## [0.11.0] - 2023-01-26
 
   - Initial public release on GitHub.
@@ -40,13 +56,14 @@ The format of this changelog is based on
     eventually. Geometric multigrid is turned on by default.
   - Added structured simulation metadata output in the form of a JSON file `palace.json`
     written to the directory specified by `config["Problem"]["Output"]`.
-  - Added JSON schema files for the configuration file format as well as a helper script
+  - Added JSON Schema files for the configuration file format as well as a helper script
     to check a provided configuration file against the schema.
   - Added optional interface to GSLIB library which enables `"Probe"` functionality to
     sample the computed electric and magnetic fields at points in space.
-  - Prepared to support builds using Spack. This includes an option in the build system for
-    user-supplied dependencies as an alternative to the superbuild configuration.
-  - Updated submodules for superbuild, fixing a bug in SuperLU_DIST solver causing
+  - Added preliminary support for builds using Spack. This includes an option in the build
+    system for user-supplied dependencies as an alternative to the superbuild
+    configuration.
+  - Added updated submodules for superbuild, fixing a bug in SuperLU_DIST solver causing
     communication hangs for certain numbers of processors.
 
 ## [0.10.0] - 2022-10-04
@@ -72,7 +89,7 @@ The format of this changelog is based on
   - Fixed issues when compiling with Intel or Clang compilers.
   - Added CI test builds to test various build options and added easier default build
     options in CMake configuration.
-  - Add `clang-format` and `JuliaFormatter` configurations for automated C++, Julia, and
+  - Added `clang-format` and `JuliaFormatter` configurations for automated C++, Julia, and
     Markdown code formatting.
 
 ## [0.9.0] - 2022-07-11

CMakeLists.txt

@@ -14,7 +14,7 @@ if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
 endif()
 
 # Initialize the project
-project(palace-superbuild LANGUAGES CXX C VERSION 0.11.0)
+project(palace-superbuild LANGUAGES CXX C VERSION 0.11.1)
 
 # Define build settings and defaults
 set(PALACE_WITH_64BIT_INT OFF CACHE BOOL "Use 64 bit integers")

docs/make.jl

@@ -22,6 +22,7 @@ makedocs(
             "guide/guide.md",
             "guide/problem.md",
             "guide/model.md",
+            "guide/boundaries.md",
             "guide/postprocessing.md"
         ],
         "Configuration File" => Any[

docs/src/config/boundaries.md

@@ -16,6 +16,10 @@
     {
         ...
     },
+    "Impedance":
+    [
+        ...
+    ],
     "Absorbing":
     {
         ...
@@ -24,10 +28,6 @@
     [
         ...
     ],
-    "Impedance":
-    [
-        ...
-    ],
     "LumpedPort":
     [
         ...
@@ -83,17 +83,17 @@ conditions (zero tangential electric field).
 conditions (zero tangential magnetic field). Also imposes symmetry of the electric field
 across the boundary surface.
 
+`"Impedance"` :  Array of objects for configuring surface impedance boundary conditions. A
+surface impedance boundary relates the tangential electric and magnetic fields on the
+boundary using a user specified surface impedance.
+
 `"Absorbing"` : Top-level object for configuring absorbing boundary conditions. These are
 artificial scattering boundary conditions at farfield boundaries.
 
 `"Conductivity"` :  Array of objects for configuring finite conductivity surface impedance
 boundary conditions. Finite conductivity boundaries are only available for the frequency
 domain driven simulation type.
 
-`"Impedance"` :  Array of objects for configuring surface impedance boundary conditions. A
-surface impedance boundary relates the tangential electric and magnetic fields on the
-boundary using a user specified surface impedance.
-
 `"LumpedPort"` :  Array of objects for configuring lumped port boundary conditions. Lumped
 ports can be specified on boundaries which are internal to the computational domain.
 
@@ -105,7 +105,7 @@ frequency domain driven simulation type.
 `"WavePortPEC"` :  Top-level object for configuring PEC boundary conditions for boundary
 mode analysis performed on the wave port boundaries. Thus, this object is only relevant
 when wave port boundaries are specified under [`config["Boundaries"]["WavePort"]`]
-(#boundaries["WavePort"]).
+(#boundaries[%5B%22WavePort%22%5D]).
 
 `"SurfaceCurrent"` :  Array of objects for configuring surface current boundary conditions.
 This boundary prescribes a unit source surface current excitation on the given boundary in
@@ -162,6 +162,35 @@ with
 `"Attributes" [None]` :  Integer array of mesh boundary attributes at which to apply the
 PMC boundary condition.
 
+## `boundaries["Impedance"]`
+
+```json
+"Impedance":
+[
+    {
+        "Attributes": [<int array>],
+        "Rs": <float>,
+        "Ls": <float>,
+        "Cs": <float>
+    },
+    ...
+]
+```
+
+with
+
+`"Attributes" [None]` :  Integer array of mesh boundary attributes for this surface
+impedance boundary.
+
+`"Rs" [0.0]` :  Surface resistance used for computing this surface impedance boundary's
+impedance per square, ``\Omega``/sq.
+
+`"Ls" [0.0]` :  Surface inductance used for computing this surface impedance boundary's
+impedance per square, H/sq.
+
+`"Cs" [0.0]` :  Surface capacitance used computing this surface impedance boundary's
+impedance per square, F/sq.
+
 ## `boundaries["Absorbing"]`
 
 ```json
@@ -174,8 +203,8 @@ PMC boundary condition.
 
 with
 
-`"Attributes" [None]` :  Integer array of mesh boundary attributes at which to apply this
-boundary condition.
+`"Attributes" [None]` :  Integer array of mesh boundary attributes at which to apply
+farfield absorbing boundary conditions.
 
 `"Order" [1]` :  Specify a first- or second-order approximation for the farfield absorbing
 boundary condition. Second-order absorbing boundary conditions are only available for the
@@ -210,35 +239,6 @@ S/m.
 specified in mesh length units. Activates a finite conductivity boundary condition which
 accounts for nonzero metal thickness.
 
-## `boundaries["Impedance"]`
-
-```json
-"Impedance":
-[
-    {
-        "Attributes": [<int array>],
-        "Rs": <float>,
-        "Ls": <float>,
-        "Cs": <float>
-    },
-    ...
-]
-```
-
-with
-
-`"Attributes" [None]` :  Integer array of mesh boundary attributes for this surface
-impedance boundary.
-
-`"Rs" [0.0]` :  Surface resistance used for computing this surface impedance boundary's
-impedance per square, ``\Omega``/sq.
-
-`"Ls" [0.0]` :  Surface inductance used for computing this surface impedance boundary's
-impedance per square, H/sq.
-
-`"Cs" [0.0]` :  Surface capacitance used computing this surface impedance boundary's
-impedance per square, F/sq.
-
 ## `boundaries["LumpedPort"]`
 
 ```json
@@ -310,13 +310,13 @@ parameters, and not with any of the circuit parameters `"R"`, `"L"`, or `"C"`.
 impedance, F/sq. This option should only be used along with the corresponding `"Rs"` and
 `"Ls"` parameters, and not with any of the circuit parameters `"R"`, `"L"`, or `"C"`.
 
-`"Elements"[]."Attributes" [None]` :  This option is for multielement lumped ports and
+`"Elements"[]["Attributes"] [None]` :  This option is for multielement lumped ports and
 should not be combined with the `"Attributes"` field described above. Each element of a
 multielement lumped port can be described by its own unique integer array of mesh boundary
 attributes, which are specified here. The elements of a multielement port add in parallel.
 
-`"Elements"[]."Direction" [None]` :  This option is for multielement lumped ports and should
-not be combined with the `"Direction"` field described above. Each element of a
+`"Elements"[]["Direction"] [None]` :  This option is for multielement lumped ports and
+should not be combined with the `"Direction"` field described above. Each element of a
 multielement lumped port can be described by its own unique direction, which is specified
 here. The elements of a multielement port add in parallel.
 
@@ -349,8 +349,8 @@ driven simulation types.
 `"Mode" [1]` :  Mode index (1-based) for the characteristic port mode of this wave port
 boundary. Ranked in order of decreasing wave number.
 
-`"Offset" [0.0]` :  Offset distance used for S-parameter de-embedding for this wave port
-boundary, specified in mesh length units.
+`"Offset" [0.0]` :  Offset distance used for scattering parameter de-embedding for this wave
+port boundary, specified in mesh length units.
 
 ## `boundaries["WavePortPEC"]`
 
@@ -364,8 +364,8 @@ boundary, specified in mesh length units.
 with
 
 `"Attributes" [None]` :  Integer array of mesh boundary attributes to consider along with
-those specified under `["Boundaries"]["PEC"]["Attributes"]` as PEC when performing wave
-port boundary mode analysis.
+those specified under [`config["Boundaries"]["PEC"]["Attributes"]`]
+(#boundaries%5B%22PEC%22%5D) as PEC when performing wave port boundary mode analysis.
 
 ## `boundaries["SurfaceCurrent"]`
 
@@ -395,22 +395,22 @@ with
 files.
 
 `"Attributes" [None]` :  Integer array of mesh boundary attributes for this surface current
-boundary. If this boundary is to be a multielement boundary which distributes the source
+boundary. If this source is to be a multielement source which distributes the source
 across more than a single lumped element, use the `"Elements"` array described below.
 
 `"Direction" [None]` :  Defines the source current direction for this surface current
 boundary. The available options are the same as under
-`["Boundaries"]["LumpedPort"]["Direction"]`. If this boundary is to be a multielement
-boundary which distributes the source across more than a single lumped element, use the
-`"Elements"` array described below.
+[`config["Boundaries"]["LumpedPort"]["Direction"]`](#boundaries%5B%22LumpedPort%22%5D). If
+this source is to be a multielement source which distributes the source across more than a
+single lumped element, use the `"Elements"` array described below.
 
-`["Elements"][]["Attributes"] [None]` :  This option is for multielement surface current
+`"Elements"[]["Attributes"] [None]` :  This option is for multielement surface current
 boundaries should not be combined with the `"Attributes"` field described above. Each
 element of a multielement current source can be described by its own unique integer array of
 mesh boundary attributes, which are specified here. The elements of a multielement source
 add in parallel to give the same total current as a single-element source.
 
-`["Elements"][]["Direction"] [None]` :  This option is for multielement surface current
+`"Elements"[]["Direction"] [None]` :  This option is for multielement surface current
 boundaires and should not be combined with the `"Direction"` field described above. Each
 element of a multielement current source can be described by its own unique direction,
 which is specified here. The elements of a multielement source add in parallel to give the

docs/src/guide/boundaries.md

@@ -0,0 +1,122 @@
+```@raw html
+<!--- Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. --->
+<!--- SPDX-License-Identifier: Apache-2.0 --->
+```
+
+# Boundary Conditions
+
+## Perfect electric conductor (PEC) boundary
+
+The perfect electric conductor (PEC) boundary condition (zero tangential electric field) is
+specified using the `"PEC"` boundary keyword under
+[`config["Boundaries"]`](../config/boundaries.md#boundaries%5B%22PEC%22%5D). It is a
+homogeneous Dirichlet boundary condition for the frequency or time domain finite element
+formulation, as well as the magnetostatic formulation.
+
+For electrostatic simulations, the homogeneous Dirichlet boundary condition is prescribed
+using the [`"Ground"`](../config/boundaries.md#boundaries%5B%22Ground%22%5D) boundary
+keyword which prescribes zero voltage at the boundary.
+
+## Perfect magnetic conductor (PMC) boundary
+
+The perfect magnetic conductor (PMC) boundary condition (zero tangential magnetic field) is
+a homogenous Neumann boundary condition for the frequency or time domain finite element
+formulation, as well as the magnetostatic formulation. It is the natural boundary condition
+and thus it has the same effect as not specifying any additional boundary condition on
+external boundary surfaces. It can also be explicitly specified using the `"PMC"` boundary
+keyword under [`config["Boundaries"]`](../config/boundaries.md#boundaries%5B%22PMC%22%5D).
+
+Likewise, for electrostatic simulations, the homogeneous Neumann boundary condition implies
+a zero-charge boundary, and thus zero gradient of the voltage in the direction normal to the
+boundary. This is specified using the `"ZeroCharge"` boundary keyword under
+[`config["Boundaries"]`](../config/boundaries.md#boundaries%5B%22ZeroCharge%22%5D).
+
+## Impedance boundary
+
+The impedance boundary condition is a mixed (Robin) boundary condition and is available for
+the frequency or time domain finite element formulations and thus for eigenmode or frequency
+or time domain driven simulation types. It is specified using the [`"Impedance"`]
+(../config/boundaries.md#boundaries%5B%22Impedance%22%5D) boundary keyword. The surface
+impedance relating the tangential electric and magnetic fields on the boundary is computed
+from the parallel impedances due to the specified resistance, inductance, and capacitance
+per square.
+
+## Absorbing (scattering) boundary
+
+Absorbing boundary conditions at farfield boundaries, also referred to as scattering
+boundary conditions, can be applied using the `"Absorbing"` boundary keyword under
+[`config["Boundaries"]`](../config/boundaries.md#boundaries%5B%22Absorbing%22%5D). The
+first-order absorbing boundary condition is a special case of the above impedance boundary
+and is available for eigenmode or frequency or time domain driven simulation types. The
+second-order absorbing boundary condition is only available for frequency domain driven
+simulations.
+
+[Perfectly matched layer (PML)](https://en.wikipedia.org/wiki/Perfectly_matched_layer)
+boundaries for frequency and time domain electromagnetic formulations are not yet
+implemented, but are [common]
+(https://www.sciencedirect.com/science/article/abs/pii/S0021999112000344) in solvers for
+computational electromagnetics and will be a useful addition.
+
+## Finite conductivity boundary
+
+A finite conductivity boundary condition can be specified using the [`"Conductivty"`]
+(../config/boundaries.md#boundaries%5B%22Conductivity%22%5D) boundary keyword. This boundary
+condition models the effect of a boundary with non-infinite conductivity (an imperfect
+conductor) for conductors with thickness much larger than the skin depth. It is available
+only for frequency domain driven simulations.
+
+## Lumped and wave port excitation
+
+  - [`config["Boundaries"]["LumpedPort"]`]
+    (../config/boundaries.md#boundaries["LumpedPort"]) :  A lumped port applies a similar
+    boundary condition to a [surface impedance](#Impedance-boundary) boundary, but takes on
+    a special meaning for each simulation type.
+    
+    For frequency domain driven simulations, ports are used to provide a lumped port
+    excitation and postprocess voltages, currents, and scattering parameters. Likewise, for
+    transient simulations, they perform a similar purpose but for time domain computed
+    quantities.
+    
+    For eigenmode simulations where there is no excitation, lumped ports are used to specify
+    properties and postprocess energy-participation ratios (EPRs) corresponding to
+    linearized circuit elements.
+    
+    Note that a single lumped port (given by a single integer `"Index"`) can be made up of
+    multiple boundary attributes in the mesh in order to model, for example, a multielement
+    lumped port.
+
+  - [`config["Boundaries"]["WavePort"]`]
+    (../config/boundaries.md#boundaries["WavePort"]) :  Numeric wave ports are available for
+    frequency domain driven simulations. In this case, a port boundary condition is applied
+    with an optional excitation using a modal field shape which is computed by solving a 2D
+    boundary mode eigenproblem on each wave port boundary. This allows for more accurate
+    scattering parameter calculations when modeling waveguides or transmission lines with
+    arbitrary cross sections.
+    
+    The homogenous Dirichlet boundary conditions for the wave port boundary mode analysis
+    are taken from the `"PEC"` boundaries of the full 3D model, as well as any optional
+    additional boundary attributes given under `"WavePortPEC"`. Any boundary of the wave
+    port not labeled with with a PEC condition has the natural boundary condition for zero
+    tangential magnetic field prescribed for the purpose of port mode calculation.
+    
+    Unlike lumped ports, wave port boundaries cannot be defined internal to the
+    computational domain and instead must exist only on the outer boundary of the domain
+    (they are to be  "one-sided" in the sense that mesh elements only exist on one side of
+    the boundary).
+
+The incident field excitation at a lumped or wave port is controlled by setting
+[`config["Boundaries"]["LumpedPort"][]["Excitation"]: true`]
+(../config/boundaries.md#boundaries["LumpedPort"]) or
+[`config["WavePort"][]["Excitation"]: true`]
+(../config/boundaries.md#boundaries%5B%22WavePort%22%5D) for that port. The excitation for
+each port is defined to have unit incident power over the port boundary surface.
+
+## Surface current excitation
+
+An alternative source excitation to lumped or wave ports for frequency and time domain
+driven simulations is a surface current excitation, specified under
+[`config["Boundaries"]["SurfaceCurrent"]`]
+(../config/boundaries.md#boundaries["SurfaceCurrent"]). This is the excitation used for
+magnetostatic simulation types as well. This option prescribes a unit source surface current
+excitation on the given boundary in order to excite the model. It does does not prescribe
+any boundary condition to the model and only affects the source term on the right hand side.