v3.4 (#61)

.github/workflows/dev.yml

@@ -8,6 +8,7 @@ permissions:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'Bump')"
     steps:
       - name: Clone
         uses: actions/checkout@v4
@@ -20,11 +21,13 @@ jobs:
         run: |
           sudo apt-get install doxygen graphviz -y
           pip install -e .
+          sudo ln -s $(pwd)/suanPan-linux-openblas-no-avx/bin/suanPan.sh /usr/bin/suanpan
+          suanpan -v
       - name: Publish
         run: |
           git fetch origin
           git config --global user.name "Theodore Chang"
           git config --global user.email "tlcfem@gmail.com"
           git pull
-          mike deploy 3.3
+          mike deploy 3.4
           git push origin gh-pages

.gitignore

@@ -12,3 +12,4 @@ suanPan-manual.py
 suanPan-manual.spec
 venv
 working
+suanPan-linux*

.readthedocs.yaml

@@ -17,6 +17,10 @@ build:
     - libx11-6
     - libxcursor1
     - graphviz
+  jobs:
+    post_install:
+      - ln -s $(pwd)/suanPan-linux-openblas-no-avx/bin/suanPan.sh /home/docs/.asdf/shims/suanpan
+      - suanpan -v
 python:
   install:
     - method: pip

docs/Basic/Obtain.md

@@ -17,19 +17,22 @@ Then it is possible to run the container in an interactive manner via:
 docker run -it --rm tlcfem/suanpan
 ```
 
-Within the container, the `suanPan` executable is available. To run, type:
+Within the container, one can use one of the following commands to run the program.
 
 ```bash
 suanPan
+suanpan
+sp
 ```
 
-One can also attach volume to the container to access the files in the host machine. And then run the file inside 
-the container.
+One can also attach volume to the container to access the files in the host machine.
+This may be the main use case.
+And then run the file inside the container.
 
 ```bash
 docker run -it --rm -v /path/to/host/folder:/path/to/container/folder tlcfem/suanpan
 cd /path/to/container/folder
-suanPan -f example.model.sp
+suanpan -f example.model.sp
 ```
 
 Docker image is convenient on machines with older kernels or limited by other factors that does not allow 
@@ -46,13 +49,11 @@ precompiled binaries are compiled on the following OS versions.
 | Platform | Version             |
 |----------|---------------------|
 | Windows  | Windows Server 2022 |
-| Ubuntu   | Ubuntu 22.04        |
-| Fedora   | Fedora 36           |
-| macOS    | Big Sur 11          |
+| Linux    | Ubuntu 22.04        |
+| macOS    | Ventura 13          |
 
-The `.deb` and `.rpm` packages are tested on the same platforms. They do not include `updater`, which checks for new 
-versions on startup. For older versions or other flavours of Linux, successful execution is not guaranteed. Please 
-consider compiling the binaries manually.
+For older versions or other flavours of Linux, successful execution is not guaranteed.
+Please consider compiling the binaries manually.
 
 In order to enable `CUDA` backed solvers, the program shall be compiled locally with preinstalled external libraries.
 See this page [Compile](Compile.md).
@@ -65,13 +66,11 @@ Currently, the following package managers can be used to install the program.
 | Windows  | [scoop](https://scoop.sh/)                                           | `scoop install suanpan`                            |
 | Linux    | [snap](https://snapcraft.io/suanpan)                                 | `snap install suanpan`                             |
 | Linux    | [flatpak](https://flathub.org/apps/details/io.github.tlcfem.suanPan) | `flatpak install flathub io.github.tlcfem.suanPan` |
-| Ubuntu   | `apt` (not available in official repo)                               | `sudo apt install ./suanPan-x.x.x-1.x86_64.deb`    |
-| Fedora   | `dnf` (not available in official repo)                               | `sudo dnf install ./suanPan-x.x.x-1.x86_64.rpm`    |
 
 The binaries are tested in standard environments: fresh new
 [Win10/11](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/) images,
 docker images [Ubuntu](https://hub.docker.com/_/ubuntu) and [Fedora](https://hub.docker.com/_/fedora),
-and [macOS](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md) GitHub image.
+and [macOS](https://github.com/actions/runner-images/blob/main/images/macos/macos-13-Readme.md) GitHub image.
 
 ### Chocolatey
 

docs/Basic/Performance.md

@@ -38,9 +38,52 @@ Here are some tips that may improve the performance.
    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.
+   See following for details.
 6. The performance of various sparser solver can vary significantly.
    It is recommended to try different solvers to find the best one.
 
+## Mixed-Precision Algorithm
+
+On some platforms, the performance of the mixed-precision algorithm can be significantly better than the full-precision
+algorithm.
+The mixed-precision algorithm converts the full-precision matrix to a lower precision matrix, and then solves the system
+using the lower precision matrix.
+Typically, only two to three iterations are required as each iteration reduces the relative error by a factor around
+machine epsilon of the lower precision.
+
+The built-in tests consist of benchmarks for mixed-precision algorithms.
+One can execute the following command to run the tests.
+
+```bash
+suanpan -ctest
+```
+
+One can find the following information.
+
+```text
+-------------------------------------------------------------------------------
+Large Mixed Precision
+-------------------------------------------------------------------------------
+
+benchmark name                       samples       iterations    est run time
+                                     mean          low mean      high mean
+                                     std dev       low std dev   high std dev
+-------------------------------------------------------------------------------
+Band N=1024 NZ=3234 NE=10240 Full              100             1    39.4709 ms
+                                        423.471 us    409.755 us    449.776 us
+                                        93.2939 us     56.394 us    148.874 us
+
+Band N=1024 NZ=3234 NE=10240 Mixed             100             1    11.4429 ms
+                                        156.697 us    147.096 us    166.771 us
+                                        50.2275 us    47.5325 us    54.2532 us
+```
+
+The mixed-precision algorithm is around three times faster than the full-precision algorithm.
+Note the results are obtained with MKL on a platform with a 13-th generation Intel CPU.
+For platforms that have a slow memory bandwidth, the performance gain may not be as significant.
+
+One could always benchmark the platform to find the best algorithm.
+
 ## Tweaks
 
 It is possible to tweak the performance in the following ways, which may or may not improve the performance.

docs/Example/Structural/Dynamics/elemental-damping.md

@@ -3,7 +3,7 @@
 In this example, we demonstrate how to apply elemental damping to the system.
 The model can be [downloaded](elemental-damping.sp).
 
-## Reference
+## References
 
 Some damping models are only valid at global level as they may depend on some attributes of the global matrices.
 They are inherently not applicable at element level.
@@ -18,7 +18,7 @@ fundamental model.
 It can be expressed in a form that can be expressed as a linear combination of mass and stiffness matrices.
 
 The [10.1016/j.compstruc.2023.107152](https://doi.org/10.1016/j.compstruc.2023.107152) discusses the application of the
-damping model at element level and investigates the relationship between the elemental adn global damping ratio.
+damping model at element level and investigates the relationship between the elemental and global damping ratio.
 
 To use the model, the [`ElementalLee`](../../../Library/Element/Modifier/ElementalLee.md) modifier and
 the [`LeeElementalNewmark`](../../../Library/Integrator/Newmark/LeeElementalNewmark.md) integrator shall be used.
@@ -62,7 +62,7 @@ The second part assigns damping ratio multipliers to each element via
 the [`ElementalLee`](../../../Library/Element/Modifier/ElementalLee.md) modifier.
 The actual damping applied to each element is the product of the multiplier and the reference damping curve.
 
-Here, for illustration, we apply $$\eta=0.05$$ and $$\eta=0,2$$ to the two elements, respectively.
+Here, for illustration, we apply $$\eta=0.05$$ and $$\eta=0.2$$ to the two elements, respectively.
 
 ```text
 modifier ElementalLee 1 .05 1 2

docs/Library/Element/Beam/B31OS.BENCHMARK.ipynb

@@ -15,7 +15,7 @@
     "\n",
     "### Angle Section\n",
     "\n",
-    "![cantilever beam with angle section](Angle.svg)\n",
+    "![cantilever beam with angle section](https://raw.githubusercontent.com/TLCFEM/suanPan-manual/dev/docs/Library/Element/Beam/Angle.svg)\n",
     "\n",
     "The cantilever beam with the angle section under an axial load applied at the shear centre.\n",
     "\n",
@@ -49,8 +49,8 @@
     }
    ],
    "source": [
-    "from subprocess import run\n",
     "import shutil\n",
+    "from subprocess import run\n",
     "\n",
     "from sectionproperties.post.fibre import to_fibre_section\n",
     "from sectionproperties.pre import Geometry\n",
@@ -155,7 +155,7 @@
     "\n",
     "for exe in executable:\n",
     "    if shutil.which(exe):\n",
-    "        run([exe, '-f', 'angle.analysis.sp'])\n",
+    "        run([exe, '-nu', '-np', '-f', 'angle.analysis.sp'])\n",
     "        is_run = True\n",
     "        break\n",
     "\n",
@@ -184,7 +184,7 @@
    "source": [
     "### Flat Bar\n",
     "\n",
-    "![cantilever beam with flat bar](Flat.svg)"
+    "![cantilever beam with flat bar](https://raw.githubusercontent.com/TLCFEM/suanPan-manual/dev/docs/Library/Element/Beam/Flat.svg)"
    ]
   },
   {
@@ -278,7 +278,9 @@
     "\n",
     "hdf5recorder 1 Node U 5\n",
     "\n",
-    "step arclength 1 5 2 .001\n",
+    "refload 1 0 .001 2 5\n",
+    "\n",
+    "step arclength 1\n",
     "set ini_step_size 1\n",
     "set fixed_step_size true\n",
     "\n",
@@ -300,7 +302,7 @@
     "\n",
     "for exe in executable:\n",
     "    if shutil.which(exe):\n",
-    "        run([exe, '-f', 'flat.analysis.sp'])\n",
+    "        run([exe, '-nu', '-np', '-f', 'flat.analysis.sp'])\n",
     "        is_run = True\n",
     "        break\n",
     "\n",
@@ -427,7 +429,7 @@
     "\n",
     "for exe in executable:\n",
     "    if shutil.which(exe):\n",
-    "        run([exe, '-f', 'flat2.analysis.sp'])\n",
+    "        run([exe, '-nu', '-np', '-f', 'flat2.analysis.sp'])\n",
     "        is_run = True\n",
     "        break\n",
     "\n",

docs/Library/Element/Beam/B31OS.md

@@ -5,7 +5,7 @@
 * Number of Nodes: 2
 * Number of DoFs: 7 (Translation, Translation, Translation, Rotation, Rotation, Rotation, Warping)
 
-## Reference
+## References
 
 1. [Distributed plasticity analysis of steel building structural systems](https://www.proquest.com/dissertations-theses/distributed-plasticity-analysis-steel-building/docview/304696456/se-2)
 

docs/Library/Element/Beam/F31.md

@@ -5,7 +5,7 @@
 * Number of Nodes: 2
 * Number of DoFs: 6 (Translation, Translation, Translation, Rotation, Rotation, Rotation)
 
-## Reference
+## References
 
 1. [10.1016/0045-7949(95)00103-N](https://doi.org/10.1016/0045-7949(95)00103-N)
 

docs/Library/Element/Beam/NMB21.md

@@ -5,7 +5,7 @@
 * Number of Nodes: 2
 * Number of DoFs: 3 (Translation, Translation, Rotation)
 
-## Reference
+## References
 
 1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 

docs/Library/Element/Beam/NMB21E.md

@@ -5,7 +5,7 @@
 * Number of Nodes: 2
 * Number of DoFs: 3 (Translation, Translation, Rotation)
 
-## Reference
+## References
 
 1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 

docs/Library/Element/Beam/NMB31.md

@@ -5,7 +5,7 @@
 * Number of Nodes: 2
 * Number of DoFs: 6 (Translation, Translation, Translation, Rotation, Rotation, Rotation)
 
-## Reference
+## References
 
 1. [10.1061/JSENDH.STENG-12176](http://dx.doi.org/10.1061/JSENDH.STENG-12176)
 

docs/Library/Element/Cube/CIN3D8.md

@@ -2,7 +2,7 @@
 
 Linear Infinite Cube/Brick
 
-## Reference
+## References
 
 1. [https://doi.org/10.1016/0045-7949(84)90019-1](https://doi.org/10.1016/0045-7949(84)90019-1)
 

docs/Library/Element/Membrane/CS.md

@@ -5,7 +5,7 @@ Couple Stress Mixed Triangle/Quadrilateral
 * Number of Nodes: 3, 4, 5, 6, 7, 8
 * Number of DoFs: 3 (Translation, Translation, Rotation)
 
-## Reference
+## References
 
 1. [arXiv:2207.02544](https://arxiv.org/abs/2207.02544)
 

docs/Library/Element/Membrane/Drilling/GQ12.md

@@ -10,7 +10,7 @@ Quadrilateral With Drilling DoFs
 
 ![encoding](../../PIC/Q4.svg)
 
-## Reference
+## References
 
 1. [10.1016/0045-7949(94)90356-5](https://doi.org/10.1016/0045-7949(94)90356-5)
 

docs/Library/Element/Membrane/Mixed/PS.md

@@ -10,7 +10,7 @@ Pian-Sumihara Quadrilateral Element
 
 ![encoding](../../PIC/Q4.svg)
 
-## Reference
+## References
 
 1. [https://doi.org/10.1002/nme.1620200911](https://doi.org/10.1002/nme.1620200911)
 2. [https://doi.org/10.1002/nme.6066](https://doi.org/10.1002/nme.6066)

docs/Library/Element/Membrane/Mixed/QE2.md

@@ -10,7 +10,7 @@ Mixed Four-Node Quadrilateral Element
 
 ![encoding](../../PIC/Q4.svg)
 
-## Reference
+## References
 
 1. [https://doi.org/10.1002/nme.1620381102](https://doi.org/10.1002/nme.1620381102)
 

docs/Library/Element/Membrane/PFM/DCP3.md

@@ -9,7 +9,7 @@ Constant Strain Triangle With Crack Phase
 
 ![encoding](../../PIC/T3.svg)
 
-## Reference
+## References
 
 There are a lot of papers on the phase-field model. A staggered scheme with maximum strain energy is adopted as an
 illustration of implementation.

docs/Library/Element/Membrane/Plane/CINP4.md

@@ -5,7 +5,7 @@ Bilinear Infinite Quadrilateral
 * Number of Nodes: 4
 * Number of DoFs: 2 (Translation, Translation)
 
-## Reference
+## References
 
 1. [https://doi.org/10.1016/0045-7949(84)90019-1](https://doi.org/10.1016/0045-7949(84)90019-1)
 

docs/Library/Element/Modifier/ElementalLee.md

@@ -2,7 +2,7 @@
 
 Elemental Damping Using Lee's Formulation
 
-## Reference
+## References
 
 1. [10.1016/j.compstruc.2023.107152](https://doi.org/10.1016/j.compstruc.2023.107152)
 

docs/Library/Element/Modifier/ElementalNonviscous.md

@@ -2,7 +2,7 @@
 
 Nonviscous Elemental Damping
 
-## Reference
+## References
 
 1. [10.1016/j.ymssp.2024.111156](https://doi.org/10.1016/j.ymssp.2024.111156)
 
@@ -12,7 +12,7 @@ $$
 g(t)=\sum_{i=1}^n m_i\exp(-s_it)
 $$
 
-The parameters $m_i$ and $s_i$ are complex numbers.
+The parameters $$m_i$$ and $$s_i$$ are complex numbers.
 
 ## Syntax
 

docs/Library/Element/Special/Damper02.md

@@ -5,7 +5,7 @@ Maxwell Model
 The `Damper02` and `Damper04` are Maxwell models that use **displacement** and **velocity** as inputs, that is, 
 element length is not used to compute strain or strain rate.
 
-## Reference
+## References
 
 The Maxwell model allows combinations of nonlinear springs and dampers. The algorithm implemented is documented in the
 following paper.