Merge pull request #90 from ax3l/topic-bnd-sm

Field Boundaries: Silver-Mueller

Author: ax3l

PICMI_Python/fields.py

@@ -205,10 +205,10 @@ class PICMI_Cartesian1DGrid(_ClassWithInit):
         Position of the node at the upper bound [m]
 
     lower_boundary_conditions: vector of strings
-        Conditions at lower boundaries, periodic, open, dirichlet, or neumann
+        Conditions at lower boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     upper_boundary_conditions: vector of strings
-        Conditions at upper boundaries, periodic, open, dirichlet, or neumann
+        Conditions at upper boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     nx: integer
         Number of cells along X (number of nodes=nx+1)
@@ -220,10 +220,10 @@ class PICMI_Cartesian1DGrid(_ClassWithInit):
         Position of last node along X [m]
 
     bc_xmin: vector of strings
-        Boundary condition at min X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_xmax: vector of strings
-        Boundary condition at max X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     moving_window_velocity: vector of floats, optional
         Moving frame velocity [m/s]
@@ -263,6 +263,18 @@ class PICMI_Cartesian1DGrid(_ClassWithInit):
 
     pml_cells: vector of integers, optional
         Number of Perfectly Matched Layer (PML) cells along each direction
+
+    References
+    ----------
+    - absorbing_silver_mueller: A local absorbing boundary condition that works best under normal incidence angle.
+      Based on the Silver-Mueller Radiation Condition, e.g., in
+      - A. K. Belhora and L. Pichon, "Maybe Efficient Absorbing Boundary Conditions for the Finite Element Solution of 3D Scattering Problems," 1995,
+        https://doi.org/10.1109/20.376322
+      - B Engquist and A. Majdat, "Absorbing boundary conditions for numerical simulation of waves," 1977,
+        https://doi.org/10.1073/pnas.74.5.1765
+      - R. Lehe, "Electromagnetic wave propagation in Particle-In-Cell codes," 2016,
+        US Particle Accelerator School (USPAS) Summer Session, Self-Consistent Simulations of Beam and Plasma Systems
+        https://people.nscl.msu.edu/~lund/uspas/scs_2016/lec_adv/A1b_EM_Waves.pdf
     """
     # Note for implementations, as a matter of convenience and flexibility, the user interface allows
     # specifying various quantities using either the individual named attributes (such as nx) or a
@@ -397,10 +409,10 @@ class PICMI_CylindricalGrid(_ClassWithInit):
         Position of the node at the upper bound [m]
 
     lower_boundary_conditions: vector of strings
-        Conditions at lower boundaries, periodic, open, dirichlet, or neumann
+        Conditions at lower boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     upper_boundary_conditions: vector of strings
-        Conditions at upper boundaries, periodic, open, dirichlet, or neumann
+        Conditions at upper boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     nr: integer
         Number of cells along R (number of nodes=nr+1)
@@ -424,16 +436,16 @@ class PICMI_CylindricalGrid(_ClassWithInit):
         Position of last node along Z [m]
 
     bc_rmin: vector of strings
-        Boundary condition at min R: One of open, dirichlet, or neumann
+        Boundary condition at min R: One of open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_rmax: vector of strings
-        Boundary condition at max R: One of open, dirichlet, or neumann
+        Boundary condition at max R: One of open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_zmin: vector of strings
-        Boundary condition at min Z: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min Z: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_zmax: vector of strings
-        Boundary condition at max Z: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max Z: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     moving_window_velocity: vector of floats, optional
         Moving frame velocity [m/s]
@@ -485,6 +497,18 @@ class PICMI_CylindricalGrid(_ClassWithInit):
 
     pml_cells: vector of integers, optional
         Number of Perfectly Matched Layer (PML) cells along each direction
+
+    References
+    ----------
+    - absorbing_silver_mueller: A local absorbing boundary condition that works best under normal incidence angle.
+      Based on the Silver-Mueller Radiation Condition, e.g., in
+      - A. K. Belhora and L. Pichon, "Maybe Efficient Absorbing Boundary Conditions for the Finite Element Solution of 3D Scattering Problems," 1995,
+        https://doi.org/10.1109/20.376322
+      - B Engquist and A. Majdat, "Absorbing boundary conditions for numerical simulation of waves," 1977,
+        https://doi.org/10.1073/pnas.74.5.1765
+      - R. Lehe, "Electromagnetic wave propagation in Particle-In-Cell codes," 2016,
+        US Particle Accelerator School (USPAS) Summer Session, Self-Consistent Simulations of Beam and Plasma Systems
+        https://people.nscl.msu.edu/~lund/uspas/scs_2016/lec_adv/A1b_EM_Waves.pdf
     """
     # Note for implementations, as a matter of convenience and flexibility, the user interface allows
     # specifying various quantities using either the individual named attributes (such as nr and nz) or a
@@ -620,10 +644,10 @@ class PICMI_Cartesian2DGrid(_ClassWithInit):
         Position of the node at the upper bound [m]
 
     lower_boundary_conditions: vector of strings
-        Conditions at lower boundaries, periodic, open, dirichlet, or neumann
+        Conditions at lower boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     upper_boundary_conditions: vector of strings
-        Conditions at upper boundaries, periodic, open, dirichlet, or neumann
+        Conditions at upper boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     nx: integer
         Number of cells along X (number of nodes=nx+1)
@@ -644,16 +668,16 @@ class PICMI_Cartesian2DGrid(_ClassWithInit):
         Position of last node along Y [m]
 
     bc_xmin: vector of strings
-        Boundary condition at min X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_xmax: vector of strings
-        Boundary condition at max X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_ymin: vector of strings
-        Boundary condition at min Y: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min Y: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_ymax: vector of strings
-        Boundary condition at max Y: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max Y: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     moving_window_velocity: vector of floats, optional
         Moving frame velocity [m/s]
@@ -705,6 +729,18 @@ class PICMI_Cartesian2DGrid(_ClassWithInit):
 
     pml_cells: vector of integers, optional
         Number of Perfectly Matched Layer (PML) cells along each direction
+
+    References
+    ----------
+    - absorbing_silver_mueller: A local absorbing boundary condition that works best under normal incidence angle.
+      Based on the Silver-Mueller Radiation Condition, e.g., in
+      - A. K. Belhora and L. Pichon, "Maybe Efficient Absorbing Boundary Conditions for the Finite Element Solution of 3D Scattering Problems," 1995,
+        https://doi.org/10.1109/20.376322
+      - B Engquist and A. Majdat, "Absorbing boundary conditions for numerical simulation of waves," 1977,
+        https://doi.org/10.1073/pnas.74.5.1765
+      - R. Lehe, "Electromagnetic wave propagation in Particle-In-Cell codes," 2016,
+        US Particle Accelerator School (USPAS) Summer Session, Self-Consistent Simulations of Beam and Plasma Systems
+        https://people.nscl.msu.edu/~lund/uspas/scs_2016/lec_adv/A1b_EM_Waves.pdf
     """
     # Note for implementations, as a matter of convenience and flexibility, the user interface allows
     # specifying various quantities using either the individual named attributes (such as nx and ny) or a
@@ -841,10 +877,10 @@ class PICMI_Cartesian3DGrid(_ClassWithInit):
         Position of the node at the upper bound [m]
 
     lower_boundary_conditions: vector of strings
-        Conditions at lower boundaries, periodic, open, dirichlet, or neumann
+        Conditions at lower boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     upper_boundary_conditions: vector of strings
-        Conditions at upper boundaries, periodic, open, dirichlet, or neumann
+        Conditions at upper boundaries, periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     nx: integer
         Number of cells along X (number of nodes=nx+1)
@@ -874,22 +910,22 @@ class PICMI_Cartesian3DGrid(_ClassWithInit):
         Position of last node along Z [m]
 
     bc_xmin: string
-        Boundary condition at min X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_xmax: string
-        Boundary condition at max X: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max X: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_ymin: string
-        Boundary condition at min Y: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min Y: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_ymax: string
-        Boundary condition at max Y: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max Y: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_zmin: string
-        Boundary condition at min Z: One of periodic, open, dirichlet, or neumann
+        Boundary condition at min Z: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     bc_zmax: string
-        Boundary condition at max Z: One of periodic, open, dirichlet, or neumann
+        Boundary condition at max Z: One of periodic, open, dirichlet, absorbing_silver_mueller, or neumann
 
     moving_window_velocity: vector of floats, optional
         Moving frame velocity [m/s]
@@ -953,6 +989,18 @@ class PICMI_Cartesian3DGrid(_ClassWithInit):
 
     pml_cells: vector of integers, optional
         Number of Perfectly Matched Layer (PML) cells along each direction
+
+    References
+    ----------
+    - absorbing_silver_mueller: A local absorbing boundary condition that works best under normal incidence angle.
+      Based on the Silver-Mueller Radiation Condition, e.g., in
+      - A. K. Belhora and L. Pichon, "Maybe Efficient Absorbing Boundary Conditions for the Finite Element Solution of 3D Scattering Problems," 1995,
+        https://doi.org/10.1109/20.376322
+      - B Engquist and A. Majdat, "Absorbing boundary conditions for numerical simulation of waves," 1977,
+        https://doi.org/10.1073/pnas.74.5.1765
+      - R. Lehe, "Electromagnetic wave propagation in Particle-In-Cell codes," 2016,
+        US Particle Accelerator School (USPAS) Summer Session, Self-Consistent Simulations of Beam and Plasma Systems
+        https://people.nscl.msu.edu/~lund/uspas/scs_2016/lec_adv/A1b_EM_Waves.pdf
     """
     # Note for implementations, as a matter of convenience and flexibility, the user interface allows
     # specifying various quantities using either the individual named attributes (such as nx, ny, and nz) or a