v3.3 (#23)

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/dev.yml

@@ -12,7 +12,7 @@ jobs:
       - name: Clone
         uses: actions/checkout@v4
       - name: Setup
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.10'
           cache: 'pip'
@@ -26,5 +26,5 @@ jobs:
           git config --global user.name "Theodore Chang"
           git config --global user.email "tlcfem@gmail.com"
           git pull
-          mike deploy 3.2
+          mike deploy 3.3
           git push origin gh-pages

docs/Basic/Compile.md

@@ -70,18 +70,27 @@ To compile `Release` version, please
 
 2. Make sure CUDA is installed. The environment variable `$(CUDA_PATH)` is used to locate headers.
 
-3. Make sure VTK is available. Then define two system environment variables `$(VTK_INC)` and `$(VTK_LIB)`, which point
-   to include and library folders. On my machine, they are
+3. Make sure VTK is available. Then define a system environment variable `$(VTK_DIR)`, which points
+   to the root folder of VTK library. On my machine, it is
 
    ```powershell
-   VTK_INC=C:\Program Files\VTK\include\vtk-9.2
-   VTK_LIB=C:\Program Files\VTK\lib
+   VTK_DIR=C:\Program Files\VTK\
    ```
 
    For versions other than 9.2, names of the linked libraries shall be manually changed as they contain version numbers.
    Thus, it is not a good idea to switch to a different version. Precompiled VTK library is also available in
    this [repository](https://github.com/TLCFEM/prebuilds).
 
+4. Make sure MAGMA is available. Then define a system environment variable `$(MAGMA_DIR)`, which points
+   to the root folder of MAGMA library. On my machine, it is
+
+   ```powershell
+   MAGMA_DIR=C:\Program Files\MAGMA\
+   ```
+
+   You probably need to compile MAGMA yourself. You can manually remove all magma related settings in the solution file
+   if you don't want to use it.
+
 Alternatively, `CMake` can be used to generate solution files if some external packages are not available.
 
 ### Ubuntu

docs/Basic/Obtain.md

@@ -364,3 +364,26 @@ suanpan
 Check the following recording.
 
 [![asciicast](https://asciinema.org/a/418408.svg)](https://asciinema.org/a/418408)
+
+## Changes Made to the System
+
+The application itself does **not** write any files to folders other than the current working directory.
+
+There are some exceptions though.
+
+1. If the [`terminal`](../Collection/Process/terminal.md) command is used, one can change files in the file system.
+2. If one decides to download new versions via the bundled updater, the archive is downloaded to the current working
+   directory. The updater is not always bundled.
+
+The script `suanPan.sh` writes the following files to the system.
+
+1. `$HOME/.local/share/applications/suanPan.desktop`
+2. `$HOME/.local/bin/suanpan`
+3. `$HOME/.config/sublime-text/Packages/User/suanPan.sublime-build`
+4. `$HOME/.config/sublime-text/Packages/User/suanPan.sublime-completions`
+5. `$HOME/.config/sublime-text/Packages/User/suanPan.sublime-syntax`
+
+The script `AddAssociation.bat` changes the following settings.
+
+1. Associate `*.sp` and `*.supan` files with the program.
+2. Copy configuration files to default folder if Sublime Text is installed.

docs/Basic/Performance.md

@@ -1,4 +1,4 @@
-# Performance Considerations
+# Performance
 
 `suanPan` prioritizes performance and designs the analysis logic in a parallel context.
 
@@ -20,8 +20,26 @@ leads to a lower value of GFLOPS.
 In the nonlinear context, it is even more complicated. Several additional factors, such as the complexity of the 
 material models used, the use of constraints, the element type, can all affect the performance.
 
-Nevertheless, experience has shown that the performance is generally good enough and for most cases. Users are 
-encouraged to `perf` the performance of various analysis types.
+Nevertheless, experience has shown that the performance is generally good enough for most cases.
+Users are encouraged to `perf` the performance of various analysis types.
+
+## Analysis Configurations
+
+Here are some tips that may improve the performance.
+
+1. If the analysis is known to be linear elastic, use `set linear_system true` to skip convergence test and iteration.
+   Note the analysis should be both material and geometric linear.
+2. If the global system is known to be symmetric, use `set symm_mat true` to use a symmetric storage.
+   Analyses involving 1D materials are mostly (**_not always_**) symmetric.
+   Analyses involving 2D and 3D materials are mostly (**_not always_**) **_not_** symmetric.
+3. Consider a proper stepping strategy. A fixed stepping size may be unnecessarily expensive.
+   A proper adaptive stepping strategy can significantly improve the performance.
+4. Prefer a dense solver over a sparse solver if the system is small.
+   A dense solver is generally faster than a sparse solver for small systems.
+5. Prefer a mixed-precision algorithm `set precision mixed` over a full-precision algorithm if the system is large.
+   A mixed-precision algorithm is generally faster than a full-precision algorithm for large systems.
+6. The performance of various sparser solver can vary significantly.
+   It is recommended to try different solvers to find the best one.
 
 ## Tweaks
 

docs/Collection/Process/upsampling.md

@@ -7,10 +7,11 @@ Minimum version: v2.6
 ## Syntax
 
 ```text
-upsampling (1) (2) [3]
+upsampling (1) (2) [3] [4]
 # (1) string, file path of the seismogram file
 # (2) integer, upsampling rate
 # [3] string, window type, default: 'Hamming'
+# [4] integer, window length, default: 0
 ```
 
 ## Remarks
@@ -29,4 +30,5 @@ The window type can be one of the following:
 - BlackmanHarris
 - FlatTop
 
-If the upsampling rate is denoted as $$L$$, the window length is $$8L+1$$.
+If the upsampling rate is denoted as $$L$$, the window length is $$nL+1$$.
+The parameter $$n$$ is controlled by the last parameter.

docs/Library/Element/Beam/NMB21.md

@@ -7,7 +7,7 @@
 
 ## Reference
 
-1. [10.1061/JSENDH/STENG-12176](http://dx.doi.org/10.1061/JSENDH/STENG-12176)
+1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 
 ## Syntax
 

docs/Library/Element/Beam/NMB21E.md

@@ -7,7 +7,7 @@
 
 ## Reference
 
-1. [10.1061/JSENDH/STENG-12176](http://dx.doi.org/10.1061/JSENDH/STENG-12176)
+1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 
 ## Syntax
 

docs/Library/Element/Beam/NMB31.md

@@ -7,7 +7,7 @@
 
 ## Reference
 
-1. [10.1061/JSENDH/STENG-12176](http://dx.doi.org/10.1061/JSENDH/STENG-12176)
+1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 
 ## Syntax
 

docs/Library/Element/Modifier/ElementalNonviscous.md

@@ -0,0 +1,47 @@
+# ElementalNonviscous
+
+Nonviscous Elemental Damping
+
+## Reference
+
+1. [10.1016/j.ymssp.2024.111156](https://doi.org/10.1016/j.ymssp.2024.111156)
+
+The kernel function is defined as a summation of exponential functions.
+
+$$
+g(t)=\sum_{i=1}^n m_i\exp(-s_it)
+$$
+
+The parameters $m_i$ and $s_i$ are complex numbers.
+
+## Syntax
+
+```text
+modifier ElementalNonviscous (1) (2) ((3) (4) (5) (6)...)
+# (1) int, unique modifier tag
+# (2) int, element tag
+# (3) double, real part of `m_i`
+# (4) double, imaginary part of `m_i`
+# (5) double, real part of `s_i`
+# (6) double, imaginary part of `s_i`
+
+modifier ElementalNonviscousGroup (1) (2) ((3) (4) (5) (6)...)
+# (1) int, unique modifier tag
+# (2) int, element group tag
+# (3) double, real part of `m_i`
+# (4) double, imaginary part of `m_i`
+# (5) double, real part of `s_i`
+# (6) double, imaginary part of `s_i`
+```
+
+## Example
+
+```text
+modifier ElementalNonviscous 1 1 8. 0 2. 0 4. 0 1. 0
+```
+
+This defines a kernel function of the following form.
+
+$$
+g(t)=8\exp(-2t)+4\exp(-t)
+$$

docs/Library/Integrator/Newmark/.pages

@@ -4,5 +4,6 @@ nav:
   - WilsonPenzienNewmark.md
   - LeeNewmark.md
   - LeeNewmarkFull.md
+  - LeeNewmarkIterative.md
   - LeeElementalNewmark.md
   - NonviscousNewmark.md

docs/Library/Integrator/Newmark/LeeNewmarkIterative.md

@@ -0,0 +1,38 @@
+# LeeNewmarkIterative
+
+## Syntax
+
+```
+integrator LeeNewmarkIterative (1) (2) (3) ((4) (5) (6) [7...]...)
+# (1) int, unique integrator tag
+# (2) double, alpha in Newmark method
+# (3) double, beta in Newmark method
+# (4) string, type identifier
+# (5) double, \zeta_p
+# (6) double, \omega_p
+# (7...) double/int, parameters associated with the mode
+```
+
+## Remarks
+
+1. The definition of parameters is **identical** to that of [`LeeNewmarkFull`](LeeNewmarkFull.md).
+2. Instead of unrolling all modes into a single sparse damping matrix, this integrator uses an iterative procedure to
+   solve system. The convergence rate is **linear**.
+3. Since the convergence rate is linear even with [`Newton`](../../Solver/Newton.md) method, one may use
+   the [`(L)BFGS`](../../Solver/BFGS.md) method to achieve a super-linear convergence rate.
+
+It is recommended to use a dense matrix storage for the system with a [`(L)BFGS`](../../Solver/BFGS.md) solver.
+For example,
+
+```text
+step dynamic 1 10
+solver LBFGS 1 50
+# the following are the default
+set banded_mat true
+set symm_mat false
+set sparse_mat false
+
+integrator LeeNewmarkIterative 1 .25 .5 ...
+```
+
+This configuration can maximize the performance.

docs/Library/Integrator/Newmark/NonviscousNewmark.md

@@ -2,19 +2,26 @@
 
 Newmark Time Integration With Nonviscous Damping
 
+## Reference
+
+1. [10.1016/j.ymssp.2024.111156](https://doi.org/10.1016/j.ymssp.2024.111156)
+
 ## Syntax
 
 ```
 integrator NonviscousNewmark (1) (2) (3) ((4) (5) (6) (7)...)
 # (1) int, unique tag
 # (2) double, alpha, typical: 0.25
 # (3) double, beta, typical: 0.5
-# (4-7) double, real and imaginary parts of m and s
+# (4) double, real part of `m_i`
+# (5) double, imaginary part of `m_i`
+# (6) double, real part of `s_i`
+# (7) double, imaginary part of `s_i`
 ```
 
 ## Theory
 
-The parameters $$m$$ and $$s$$ are two complex numbers that define the kernel function.
+The parameters $$m_i$$ and $$s_i$$ are two complex numbers that define the kernel function.
 
 $$
 g(t)=\sum_{i=1}^nm_ie^{-s_it}.

docs/Library/Material/Material1D/Concrete/ConcreteTsai.md

@@ -6,34 +6,18 @@ The `ConcreteTsai` model is a simple concrete model using Tsai's equation.
 
 ## Syntax
 
-Depending on the number of parameters provided (8 to 11), the model can be defined in two ways.
-
 ```
-material ConcreteTsai (1) (2) (3) (4) (5) (6) (7) [8] [9] [10] [11]
+material ConcreteTsai (1) (2) (3) (4) (5) (6) (7) (8) (9) [10]
 # (1) int, unique material tag
-# (2) double, compression strength, should be negative but sign insensitive
-# (3) double, tension strength, should be positive but sign insensitive
-# (4) double, MC
+# (2) double, elastic modulus
+# (3) double, compression strength, should be negative but sign insensitive
+# (4) double, tension strength, should be positive but sign insensitive
 # (5) double, NC
-# (6) double, MT
-# (7) double, NT
-# (8) double, middle point, typical: 0.2
-# (9) double, strain at compression strength, typical: -2E-3
-# (10) double, strain at tension strength, typical: 1E-4
-# [11] double, density, default: 0.0
-```
-
-```
-material ConcreteTsai (1) (2) (3) (4) (5) [6] [7] [8] [9]
-# (1) int, unique material tag
-# (2) double, compression strength, should be negative but sign insensitive
-# (3) double, tension strength, should be positive but sign insensitive
-# (4) double, M
-# (5) double, N
-# (6) double, middle point, typical: 0.2
-# (7) double, strain at compression strength sign insensitive, typical: -2E-3
-# (8) double, strain at tension strength sign insensitive, typical: 1E-4
-# [9] double, density, default: 0.0
+# (6) double, NT
+# (7) double, middle point, typical: 0.2
+# (8) double, strain at compression strength, typical: -2E-3
+# (9) double, strain at tension strength, typical: 1E-4
+# [10] double, density, default: 0.0
 ```
 
 ## History Variable Layout
@@ -50,15 +34,15 @@ variable layout.
 ## Usage
 
 ```
-material ConcreteTsai 1 30 20 2 2 2 2 .8 2E-3 2E-3
+material ConcreteTsai 1 3E4 30 20 2 2 .8 2E-3 2E-3
 materialTest1D 1 1E-4 50 100 120 140 160 180
 exit
 ```
 
 ![example one](ConcreteTsai.EX1.svg)
 
 ```
-material ConcreteTsai 1 30 20 2 2 2 2 .1 2E-3 2E-3
+material ConcreteTsai 1 3E4 30 20 2 2 .1 2E-3 2E-3
 materialTest1D 1 1E-4 50 100 120 140 160 180
 exit
 ```

docs/Library/Material/Material1D/Viscosity/Nonviscous01.md

@@ -2,4 +2,37 @@
 
 Uniaxial Nonviscous Damping Material
 
+## Reference
+
+1. [10.1016/j.ymssp.2024.111156](https://doi.org/10.1016/j.ymssp.2024.111156)
+
+The kernel function is defined as a summation of exponential functions.
+
+$$
+g(t)=\sum_{i=1}^n m_i\exp(-s_it)
+$$
+
+The parameters $m_i$ and $s_i$ are complex numbers.
+
 ## Syntax
+
+```text
+material Nonviscous01 (1) ((2) (3) (4) (5)...)
+# (1) int, unique material tag
+# (2) double, real part of `m_i`
+# (3) double, imaginary part of `m_i`
+# (4) double, real part of `s_i`
+# (5) double, imaginary part of `s_i`
+```
+
+## Example
+
+```text
+material Nonviscous01 2 8. 0 2. 0 4. 0 1. 0
+```
+
+This defines a kernel function of the following form.
+
+$$
+g(t)=8\exp(-2t)+4\exp(-t)
+$$