Introduce arbitrary orientation for lumped ports

CHANGELOG.md

@@ -28,6 +28,11 @@ The format of this changelog is based on
     on libCEED for non-tensor product element meshes. This option is disabled by default,
     but can be activated using `config["Solver"]["PartialAssemblyOrder"]` set to some number
     less than `"Order"` and `config["Solver"]["Device"]: "ceed-cpu"`.
+  - Added support for non axis aligned lumped ports and current sources. Key words `"X"`,
+    `"Y"`, `"Z"` and `"R"`, with optional prefix `"+"` or `"-"` still work, but now
+    directions can be specified as vectors with 3 components. Users will be warned, and
+    ultimately errored, if the specified directions do not agree with axis directions
+    discovered from the geometry.
   - Added build dependencies on [libCEED](https://github.com/CEED/libCEED) and
     [LIBXSMM](https://github.com/libxsmm/libxsmm) to support operator partial assembly (CPU-
     based for now).

docs/src/config/boundaries.md

@@ -247,7 +247,8 @@ accounts for nonzero metal thickness.
     {
         "Index": <int>,
         "Attributes": [<int array>],
-        "Direction": <string>,
+        "Direction": <string> or [<float array>],
+        "CoordinateSystem": <string>,
         "Excitation": <bool>,
         "R": <float>,
         "L": <float>,
@@ -258,8 +259,9 @@ accounts for nonzero metal thickness.
         "Elements":
         [
             {
-                "Attributes": [<int array>],
-                "Direction": <string>
+                "Attributes": <string> or [<float array>],
+                "Direction": <string>,
+                "CoordinateSystem": <string>
             },
             ...
         ]
@@ -277,11 +279,18 @@ boundary. If this port is to be a multielement lumped port with more than a sing
 element, use the `"Elements"` array described below.
 
 `"Direction" [None]` :  Direction to define the polarization direction of the port field
-mode on this lumped port boundary. Lumped ports must be axis-aligned unless the port is a
-coaxial port. The available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`,
-`"+R"`, `"-R"` (`"R"` is for a coaxial lumped port). If this port is to be a multielement
-lumped port with more than a single lumped element, use the `"Elements"` array described
-below.
+mode on this lumped port boundary. Axis aligned lumped ports can be specified using
+keywords: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`, while coaxial lumped ports can be
+specified using `"+R"`, `"-R"`. The direction can alternatively be specified as a
+normalized array of three values, for example `[0, 1, 0]`. If a vector direction is
+specified, the `"CoordinateSystem"` value specifies the coordinate system it is expressed
+in. If this port is to be a multielement lumped port with more than a single lumped
+element, use the `"Elements"` array described below.
+
+`"CoordinateSystem" ["Cartesian"]` : Coordinate system used to express the `"Direction"`
+vector, the options are `"Cartesian"` and `"Cylindrical"`. If a keyword argument is used
+for `"Direction"` this value is ignored, and the appropriate coordinate system is used
+instead.
 
 `"Excitation" [false]` :  Turns on or off port excitation for this lumped port boundary for
 driven or transient simulation types.
@@ -320,6 +329,11 @@ should not be combined with the `"Direction"` field described above. Each elemen
 multielement lumped port can be described by its own unique direction, which is specified
 here. The elements of a multielement port add in parallel.
 
+`"Elements"[]["CoordinateSystem"] ["Cartesian"]` :  This option is for multielement lumped
+ports and should not be combined with the `"CoordinateSystem"` field described above. Each
+element of a multielement lumped port can be described by its own unique direction, and
+corresponding coordinate system.
+
 ## `boundaries["WavePort"]`
 
 ```json
@@ -375,12 +389,14 @@ those specified under [`config["Boundaries"]["PEC"]["Attributes"]`]
     {
         "Index": <int>,
         "Attributes": [<int array>],
-        "Direction": <string>
+        "Direction": <string> or [<float array>],
+        "CoordinateSystem": <string>,
         "Elements":
         [
             {
                 "Attributes": [<int array>],
-                "Direction": <string>
+                "Direction": <string> or [<float array>],
+                "CoordinateSystem": <string>,
             },
             ...
         ]
@@ -404,18 +420,29 @@ boundary. The available options are the same as under
 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.
 
+`"CoordinateSystem" ["Cartesian"]` :  Defines the coordinate system for the source current
+direction for this surface current boundary. The available options are the same as under
+[`config["Boundaries"]["LumpedPort"]["CoordinateSystem"]`](#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
 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
-boundaires and should not be combined with the `"Direction"` field described above. Each
+boundaries 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
 same total current as a single-element source.
 
+`"Elements"[]["CoordinateSystem"] ["Cartesian"]` :  This option is for multielement surface current
+boundaries and should not be combined with the `"CoordinateSystem"` field described above. Each
+element of a multielement current source can be described by its own unique
+direction, and corresponding coordinate system.
+
 ## `boundaries["Ground"]`
 
 ```json
@@ -516,7 +543,10 @@ postprocessing boundary.
 
 `"Direction" [None]` :  Defines the global direction with which to orient the surface
 normals with computing the magnetic flux for this inductance postprocessing boundary. The
-available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
+available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`. The direction can
+alternatively be specified as a normalized array of three values, for example `[0, 1, 0]`.
+The true surface normal is used in the calculation, `"Direction"` is only used to ensure
+the correct choice of orientation of the normal.
 
 ## `boundaries["Postprocessing"]["Dielectric"]`
 
@@ -528,7 +558,7 @@ available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
         {
             "Index": <int>,
             "Attributes": [<int array>],
-            "Side": <string>,
+            "Side": <string> or [<float array>],
             "Thickness": <float>,
             "Permittivity": <float>,
             "PermittivityMA": <float>,
@@ -539,7 +569,7 @@ available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
             [
                 {
                     "Attributes": [<int array>],
-                    "Side": <string>
+                    "Side": <string> or [<float array>]
                 },
                 ...
             ]
@@ -561,12 +591,13 @@ use the `"Elements"` array described below.
 `"Side" [None]` :  Defines the postprocessing side when this dielectric interface is an
 internal boundary surface (and thus the electric field on the boundary is in general
 double-valued). The available options are: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
-If the boundary is not axis-aligned, the field value is taken from the side which is
-oriented along the specified direction. If no `"Side"` is specified, the field solution is
-taken from the neighboring element with the smaller electrical permittivity, which is an
-attempt to get the field in the domain corresponding to vacuum. If the interface consists
-of multiple elements with different `"Side"` values, use the `"Elements"` array described
-below.
+The direction can alternatively be specified as a normalized array of three values, for
+example `[0, 1, 0]`. If the boundary is not axis-aligned, the field value is taken from the
+side which is oriented along the specified direction. If no `"Side"` is specified, the
+field solution is taken from the neighboring element with the smaller electrical
+permittivity, which is an attempt to get the field in the domain corresponding to vacuum.
+If the interface consists of multiple elements with different `"Side"` values, use the
+`"Elements"` array described below.
 
 `"Thickness" [None]` :  Thickness of this dielectric interface, specified in mesh length
 units.

docs/src/examples/rings.md

@@ -50,15 +50,16 @@ The configuration file for the *Palace* simulation is [`rings.json`]
 surface current to drive the inner or outer ring. The rest of the ring boundaries are
 labeled as `"PEC"` boundaries, which prescibes a zero magnetic flux, or magnetic
 insulation, boundary condition. The farfield is also prescribed the `"PEC"` boundary
-condition. We seek a second-order solution and use the geometric multigrid AMS solver.
+condition. We seek a second-order solution and use the geometric multigrid AMS
+solver.
 
 The computed inductance matrix is saved to disk as `postpro/terminal-M.csv`, and below we
 show its contents:
 
 ```
             i,             M[i][1] (H),             M[i][2] (H)
- 1.000000e+00,        +4.258505069e-11,        +1.958488699e-12
- 2.000000e+00,        +1.958488699e-12,        +7.126907323e-10
+ 1.000000e+00,        +4.272291158e-11,        +1.959927760e-12
+ 2.000000e+00,        +1.959927760e-12,        +7.131293160e-10
 ```
 
 According to the analytic expressions above, for this geometry we should have
@@ -76,8 +77,8 @@ M_{bb} &= 707.2050\text{ pH}
 \end{aligned}
 ```
 
-for the self inductances. Thus, the *Palace* solution has approximately ``0.78\%`` error in
-the mutual inductance ``1.9\%`` and ``0.78\%`` errors in the self inductances versus the
+for the self inductances. Thus, the *Palace* solution has approximately ``0.71\%`` error in
+the mutual inductance and ``2.2\%`` and ``0.84\%`` errors in the self inductances versus the
 analytic solutions.
 
 The typical approach used by *Palace* for lumped parameter extraction uses the computed
@@ -89,8 +90,8 @@ file. The resulting postprocessed values are written to `postpro/surface-M.csv`:
 
 ```
             i,                M[1] (H),                M[2] (H)
- 1.000000e+00,        +4.246208372e-11,        +1.858193591e-12
- 2.000000e+00,        +1.954077499e-12,        +7.125811940e-10
+ 1.000000e+00,        +4.257285432e-11,        +1.832374026e-12
+ 2.000000e+00,        +1.955250721e-12,        +7.130247545e-10
 ```
 
 The values computed using the flux integral method are in close agreement to those above, as