suanPan

[!IMPORTANT] - Feature requests can be made via creating new issues. - Check out the VS Code extension for syntax highlighting and autocompletion. - Check out the documentation for a summary of all available functionalities. - Please star the project!

Introduction

suanPan is a finite element method (FEM) simulation platform for applications in fields such as solid mechanics and civil/structural/seismic engineering. suanPan is written in modern high-quality C++ code and is targeted to provide an efficient, concise, flexible and reliable FEM simulation platform.

suanPan is partially influenced by popular (non-)commercial FEA packages, such as ABAQUS UNIFIED FEA, ANSYS and OpenSees.

Features

The highlights of suanPan are

• fast, memory and thread safe
• shared memory parallelism support
• distributed memory parallelism support
• multi-architecture (amd64 and arm64) support
• rich collection of elements, materials, time integration methods, etc.
• open source and easy to extend
• modern language features

Quick Start

Execute the application out-of-the-box in terminal on Linux using one of the following commands depending on how the application is obtained. See details below.

```bash

in folder bin/ for linux portable tarball

./suanPan.sh

for linux packages and snap

suanPan

for flatpak

flatpak run io.github.tlcfem.suanPan ```

Or on Windows,

```powershell

in the folder containing suanPan.exe

.\suanPan.exe ```

First time users can use overview command to go through a quick introduction.

``text +--------------------------------------------------------+ | ____ suanPan is an open source | | ___ _ _| _ \ __ _ _ __ FEM framework (64-bit) | | / __| | | | |_) / _ | '_ \ Canopus (3.7.0) | | __ \ || | _/ (| | | | | by tlc @ c34df242 | | |_/_,|| _,|| || all rights reserved | | 10.5281/zenodo.1285221 | +--------------------------------------------------------+ | https://github.com/TLCFEM/suanPan | | https://tlcfem.github.io/suanPan-manual/latest | +--------------------------------------------------------+ | https://bit.ly/vsc-sp | +--------------------------------------------------------+

suanPan ~<> overview ```

Sample models are available for almost all models/commands. Please check the Example folder for details. Further details can be seen here regarding how to run model files.

Installation

[!WARNING] Only the 64-bit version is compiled. It is assumed that AVX2 is available thus if the program fails, please check if your CPU supports AVX2. Alternatively, you can try the no-avx version.

Windows

[!NOTE] The dependencies are bundled with the archive. One may also install the VC++ redistributable package. If the application prompts that some file, such as msvcp140.dll, is missing (unlikely), please install the redistributable package.

Binary Package

The archives of binaries are released under Release page.

1. suanpan-win-mkl-vtk.zip is the portable archive.
2. suanpan-win-mkl-vtk.exe is the installer.

Chocolatey

The binaries, which are compiled with Intel MKL and VTK, are available on Chocolatey, please use the following command to install the package.

1. Follow the instructions to install Chocolatey.

2. Use the following command to install suanPan.

ps choco install suanpan

1. It is recommended to use a modern terminal such as Windows Terminal for better output display.

The Chocolatey repo available to you may not be up-to-date. If the latest version is not available, please try alternatives, such as portable binaries or scoop.

Scoop

It is also possible to use Scoop to install the package.

1. Install Scoop.

ps Set-ExecutionPolicy RemoteSigned -scope CurrentUser iwr -useb get.scoop.sh | iex

1. Install suanPan.

ps scoop install suanpan

Linux

Linux users are recommended to obtain the binaries via snap or flatpak.

Snap

The snap supports visualisation via VTK and uses Intel MKL for linear algebra. The edge channel is in sync with the dev branch. The stable channel is in sync with the master branch.

Flatpak

Flatpak is also available if preferred. The beta channel is in sync with the dev branch. The stable channel is in sync with the master branch.

```bash

add repo

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

or the beta channel

flatpak remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo

install

flatpak install suanPan

define alias

echo "alias suanpan=\"flatpak run io.github.tlcfem.suanPan\"" >> ~/.bashrc ```

Docker

It is also possible to compile the package via docker, check the dockerfiles under the Script folder, for any questions please open an issue.

One can directly pull the image. Using Docker Hub.

bash docker pull tlcfem/suanpan

Using GitHub Container Registry.

bash docker pull ghcr.io/tlcfem/suanpan

Other Platforms

Precompiled binaries are provided via CI/CD on macOS, Windows, and Ubuntu. Please download the file from the release page.

A few flavors are available:

1. vtk --- visualisation support is enabled, with this you can record VTK files for postprocessing, however, OpenGL may be missing on server systems
2. mkl --- linear algebra operations are offloaded to MKL, which gives the optimal performance on Intel chips
3. openblas --- linear algebra operations are offloaded to OpenBLAS, which may outperform MKL on AMD platforms
4. aocl --- linear algebra operations are offloaded to AOCL, which is optimized for AMD platforms
5. no-avx --- AVX2 support is disabled, useful for older CPUs that do not support AVX2 instructions
6. win-gcc --- GCC is used to compile the binary
7. win --- MSVC is used to compile the binary

Advanced users can compile the program from source by themselves to enable GPU based solvers which require an available CUDA and/or MAGMA library.

Automation Related

VS Code

The VS Code extension is available here. It provides syntax highlighting, autocompletion, running the model using the specified executable or docker container.

Sublime Text

On Windows, a batch file named AddAssociation.bat is provided in the archive. It provides file associations and prepares a proper working environment (build system, autocompletion, highlighting) with Sublime Text. It also adds file associations with .sp and .supan files, please run the AddAssociation.bat file with administrator privilege. Sublime Text autocompletion and syntax highlighting files are also provided. Please install Sublime Text first and execute the batch file with the administrator privilege.

On Linux, a script file named as suanPan.sh is provided.

bash ./suanPan.sh --create-link

The above command adds Sublime Text autocompletion and syntax highlighting files to proper location if Sublime Text configuration folder is found. It also adds a command alias suanpan to ~/.local/bin and a desktop file to ~/.local/share/applications.

Dependency

Additional libraries used in suanPan are listed as follows.

• AMD Optimizing CPU Libraries (AOCL) version 5.1
• ARPACK
• Armadillo version 15.0.1
• CUDA version 12.9
• Catch2 version 3.10.0
• FEAST version 4.0
• HDF5 version 1.14.5
• MAGMA version 2.9.0
• OpenBLAS version 0.3.30
• SPIKE version 1.0
• SuperLU MT version 4.0.0
• SuperLU version 7.0.1
• TBB Threading Building Blocks version 2022.1.0
• VTK version 9.5.1
• argparse
• exprtk version 0.0.3
• ezp
• fmt version 10.2.1
• magic_enum version 0.9.7
• oneMKL version 2025.2.0
• whereami
• thread_pool abridged version of thread-pool

Those libraries may depend on other libraries such as zlib and Szip. Additional tools may be used by suanPan, they are

• UPX the Ultimate Packer for eXecutables

How To Compile

Please refer to the corresponding page in the manual for details.

Happy Modelling

Licence