Update PML documentation to include new parameters and examples for PML3D ( PML3DVISCOUS)

source/user/manual/model/elements/PML.rst

@@ -21,7 +21,7 @@ W. Zhang, E. Esmaeilzadeh Seylabi, E. Taciroglu,(2019), An ABAQUS toolbox for so
         element PML $eleTag $node1 $node2 $node3 $node4 $E $nu $rho $EleType $Thickness $m $R $RD_half_width_x $Depth $alpha $beta
 
     2. PML3D
-        element PML $eleTag $node1 $node2 $node3 $node4 $node5 $node6 $node7 $node8 $gamma $beta $eta $E $nu $rho $EleType $Thickness $m $R $RD_half_width_x $RD_half_width_y $Depth $alpha $beta
+        element PML $eleTag $node1 $node2 $node3 $node4 $node5 $node6 $node7 $node8 $matTag $PMLThickness meshType meshParams... [-Cp $Cp] [-m $m] [-R $R] [-alphabeta $alpha $beta] [-Newmark $gamma $beta $eta $keisi]
 
 1. **PML2D**
 
@@ -49,52 +49,80 @@ W. Zhang, E. Esmaeilzadeh Seylabi, E. Taciroglu,(2019), An ABAQUS toolbox for so
 2. **PML3D**
 
 .. csv-table:: 
-   :header: "Argument", "Type", "Description"
-   :widths: 10, 10, 90
+    :header: "Argument", "Type", "Description"
+    :widths: 10, 10, 90
+
+    "eleTag", "|integer|", "unique integer tag identifying element object"
+    "node1 node2 node3 node4 node5 node6 node7 node8", "8 |integer|", "the eight nodes defining the element input in counterclockwise order (-ndm 3 -ndf 9)"
+    "matTag", "|integer|", "material tag (must be an ElasticIsotropicMaterial)"
+    "PMLThickness", "|float|", "Thickness of the PML around regular domain"
+    "meshType", "|string|", "Mesh type defining the PML region (General, Box, Sphere, Cylinder)"
+    "meshParams...", "|float|", "Additional parameters depending on meshType (see below)"
+    "-Cp", "|float|", "PML parameter defining wave speed (default calculated from material properties)"
+    "-m", "|float|", "PML parameter (default m=2)"
+    "-R", "|float|", "PML parameter (default R=1e-8)"
+    "-alphabeta", "|float float|", "User-defined alpha and beta parameters"
+    "-Newmark", "|float float float float|", "Newmark integration parameters (gamma, beta, eta, keisi)"
+
+**Mesh Type Parameters**
+
+.. csv-table:: 
+    :header: "Mesh Type", "Required Parameters", "Description"
+    :widths: 20, 30, 50
+
+    General, "Xref, Yref, Zref, N1, N2, N3", "Reference point and normal vector components"
+    Box, "XC, YC, ZC, L, W, H", "Center coordinates at the surface and dimensions of the box (e.g., 20, 50, 0.0, widthX, widthY, depthZ)"
 
-   eleTag,|integer|,unique integer tag identifying element object
-   node1 node2 node3 node4 node5 node6 node7 $node8, 8 |integer|, the eight nodes defining the element input in counterclockwise order (-ndm 2 -ndf 5)
-   :math:`{\gamma}`, |float|, Newmark integration parameter
-    :math:`{\beta}`, |float|, Newmark integration parameter
-    :math:`{\eta}`, |float|, Newmark integration parameter
-   E,  |float| , Young's modulus
-   nu, |float| , Poisson's Ratio
-   rho, |float| , Density
-   EleType, |float|, Element type based on the region of the PML it can be 1 2 3 4 5 (you can choose any number the code automaticlly )
-   Thickness, |float|, Thickness of the PML around regular domain
-    m, |float|, PML parameter (m=2 is recommended)
-    R, |float|, PML parameter (R=1e-8 is recommended)
-    RD_half_width_x, |float|, Distance of the border of the PML and regular domain to the center of the domain at origin
-    Depth, |float|, Depth of the PML from the surface of the regular domain in the negative y direction
-    alpha, |float|, Rayleigh damping parameter for PML (alpha will be 0 even if you input a value)
-    beta, |float|, Rayleigh damping parameter for PML (beta will be 0 even if you input a value)
 
 .. note::
 
-    1. For 2D PML each node has 5 DOFs (2 translations and Sx, Sy, Sxy)
-    2. For 3D PML each node has 9 DOFs (3 translations and Sx, Sy, Sz, Sxy, Sxz, Syz)
-    3. There is no recorder for PML elements. The stresses can be obtained from the node recorders. 
-    4. When using PML 3D only newmark integration method can be used and the parameters using for the integration should be passed to the element(Example: :math:`{\gamma} = 1/2, {\beta} = 1/4, {\eta} =1/12`)
-    5. The center of the regular domian should be at the origin of the global coordinate system (0,0,0)
+    1. For PML 2D, each node has 5 DOFs (2 translations and Sx, Sy, Sxy)
+    2. For PML 3D, each node has 9 DOFs (3 translations and Sx, Sy, Sz, Sxy, Sxz, Syz)
+    3. For PML 2D, the center of the regular domian should be at the origin of the global coordinate system (0,0,0)
+    4. There is no recorder for PML elements. The stresses can be obtained from the node recorders. 
+    5. When using PML 3D, only the Newmark integration method can be used. If the parameters for the integration are not passed to the element, the default parameters will be used (Example: :math:`\gamma = 0.5, \beta = 0.25, \eta = 0.0833333333333333, \xi = 0.0208333333333333`).
     6. It is highly recommended to use the same mesh for the PML and the regular domain
     7. It is highly recommended to use the same material for the PML and the regular domain
-    8. It is highly recommended to use uniform and square mesh for the PML elements.
+    8. It is highly recommended to use uniform and square mesh for the PML elements
+    9. If the user provides the alpha and beta parameters explicitly using the `-alphabeta` flag, the following formulas for calculating `alpha_0` and `beta_0` are skipped, and the user-defined parameters are used instead:
+
+        .. math::
+            \begin{aligned}
+                C_p &= \sqrt{\frac{E \cdot (1 - \nu)}{\rho \cdot (1 + \nu) \cdot (1 - 2 \cdot \nu)}} \\
+                PML_b &= \frac{\text{PMLThickness}}{1.0} \\
+                \alpha_0 &= \frac{(m_{\text{coeff}} + 1) \cdot PML_b}{2.0 \cdot PML_b} \cdot \log_{10}\left(\frac{1}{R}\right) \\
+                \beta_0 &= \frac{(m_{\text{coeff}} + 1) \cdot C_p}{2.0 \cdot PML_b} \cdot \log_{10}\left(\frac{1}{R}\right)
+            \end{aligned}
+
+
+.. admonition:: Example 
+
+    The following example constructs a PML 3D element with tag **1** between nodes **1, 2, 3, 4, 5, 6, 7, 8** using material tag **1**, PML thickness **1.0**, and a box-type mesh with parameters **10.0, 10.0, 5.0 20 20 20**.
+
+    1. **Tcl Code**
+
+    .. code-block:: tcl
+
+        element PML 1 1 2 3 4 5 6 7 8 1 1.0 Box 10.0 10.0 5.0 20.0 20.0 20.0 -m 2 -R 1e-8 -Newmark 0.5 0.25 0.0833333333333333 0.0208333333333333
+
+    2. **Python Code**
+
+    .. code-block:: python
 
+        element('PML', 1, 1, 2, 3, 4, 5, 6, 7, 8, 1, 1.0, 'Box', 10.0, 10.0, 5.0, 20.0, 20.0, 20.0, '-m', 2, '-R', 1e-8, '-Newmark', 0.5, 0.25, 0.0833333333333333, 0.0208333333333333)
 
 .. admonition:: Example 
 
-   The following example constructs a PML3D element with tag **1** between nodes **1, 2, 3, 4, 5, 6, 7, 8** with the properties **E=1e6, nu=0.3, rho=1.0, EleType=1, Thickness=1.0, m=2, R=1e-8, RD_half_width_x=10.0, RD_half_width_y=10.0, Depth=5.0, alpha=0.0, beta=0.0**.
-
-   1. **Tcl Code**
+    The following example constructs a PML 2D element with tag **2** between nodes **1, 2, 3, 4** using Young's modulus **3000**, Poisson's ratio **0.3**, density **2500**, element type **1**, thickness **1.0**, and PML parameters **2, 1e-8, 5.0, 10.0, 0.0, 0.0**.
 
-   .. code-block:: tcl
+    1. **Tcl Code**
 
-      element PML 1 1 2 3 4 5 6 7 8 1 0.5 0.25 0.0833333333333333 1e6 0.3 1.0 1 1.0 2 1e-8 10.0 10.0 5.0 0.0 0.0
+    .. code-block:: tcl
 
-   2. **Python Code**
+        element PML 2 1 2 3 4 3000 0.3 2500 1 1.0 2 1e-8 5.0 10.0 0.0 0.0
 
-   .. code-block:: python
+    2. **Python Code**
 
-      element('PML', 1, 1, 2, 3, 4, 5, 6, 7, 8, 1, 0.5, 0.25, 0.0833333333333333, 1e6, 0.3, 1.0, 1, 1.0, 2, 1e-8, 10.0, 10.0, 5.0, 0.0, 0.0)
+    .. code-block:: python
 
-Code Developed by: W. Zhang, E. Taciroglu, A. Pakzad, P. Arduino (UCLA, UW)
+        element('PML', 2, 1, 2, 3, 4, 3000, 0.3, 2500, 1, 1.0, 2, 1e-8, 5.0, 10.0, 0.0, 0.0)