suanPan

Introduction

🧮 suanPan is a finite element method (FEM) simulation platform for applications in fields such as solid mechanics and civil/structural/seismic engineering. The name suanPan (in some places such as suffix it is also abbreviated as suPan) comes from the term Suan Pan (算盤), which is Chinese abacus. 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.

Please check documentation here and here for command references. Please consider starring ⭐ the project!

Features

The highlights of suanPan are

suanPan is fast, both memory and thread safe.
suanPan is designed based on the shared memory model and supports parallelism on heterogeneous architectures, for example multithreaded CPU + optional GPU. The parallelism is available for both element state updating and global matrix assembling.
suanPan is open source and easy to be extended to incorporate user-defined elements, materials, etc.
suanPan separates the FEA model part from the linear algebra operation part, which significantly reduces the complexity and cost of development of new models.
suanPan utilizes the new language features shipped with the latest standards (C++11 to C++20), such as new STL containers, smart pointers and many others.
suanPan supports simple visualization supported by VTK.

Quick Start

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

Only 64-bit version is compiled. It is assumed that AVX is available thus if the program fails, please check if your CPU supports AVX.

Windows

Binary Package

The archives of binaries are released under Release page.

suanpan-win-mkl-vtk.zip is the portable version.
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.

Follow the instructions to install Chocolatey.
Use the following command to install suanPan.
```
choco install suanpan
```
It is recommended to use a modern terminal such as Windows Terminal and Fluent Terminal for better output display.

Scoop

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

Install Scoop.

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

Install suanPan.
```
scoop install suanpan
```

Linux

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

Snap

The snap supports visualization via VTK and uses Intel MKL for linear algebra.

Flatpak

Flatpak is also available if preferred.

# add repo
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
# install
flatpak install flathub io.github.tlcfem.suanPan
# define alias
echo "alias suanpan=\"flatpak run io.github.tlcfem.suanPan\"" >> ~/.bashrc

Installation Packages

Alternatively, download the RPM (Fedora 35) or DEB (Ubuntu 22.04) package from the release page. The packages may not be compatible with older distributions (due to different version of libstdc++). It is also possible to compile the package via docker, check the dockerfiles under the Script folder, for any questions please open an issue.

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:

vtk --- visualization support is enabled, with this you can record VTK files for postprocessing, however, OpenGL may be missing on server systems
mkl --- linear algebra operations are offloaded to MKL, which gives optimal performance on Intel chips
openblas --- linear algebra operations are offloaded to OpenBLAS, which may outperform MKL on AMD platforms

Advanced users can compile the program from source by themselves in order to enable GPU based solvers which require available CUDA library.

Since CI/CD uses GCC 11 (on Linux) and Clang 13.0.1 (on MacOS), it may be required to update/install proper libstdc++ (or libc++) version. The easiest way is to install the same compiler. For example, on Ubuntu 22.04,

# Ubuntu
sudo apt install gcc g++ gfortran libomp5

For VTK enabled versions, it may be necessary to install OpenGL.

# Ubuntu
sudo apt install libglu1-mesa-dev freeglut3-dev mesa-common-dev libglvnd-dev

Automation Related

On Windows, a batch file named as 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. By executing

./suanPan.sh --create-link

It 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.

ARPACK
SPIKE version 1.0
FEAST version 4.0
SuperLU version 5.3.0 and SuperLU MT version 3.1
OpenBLAS version 0.3.15
TBB Threading Building Blocks version 2021.7.0
HDF5 version 1.10.6
MUMPS version 5.2.1
METIS version 5.1.0
VTK version 9.2.2
CUDA version 11.7
Armadillo version 11.4
ensmallen version 2.19.0
oneMKL version 2023.0.0
Catch2 version 2.13.10
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

xyuan/suanPan