suanPan

An Open Source, Parallel and Heterogeneous Finite Element Analysis Framework

📖 Documentation · 🧪 Examples · 📦 Releases · 💡 Request a Feature · 🐛 Report a Bug

Important

• Feature requests can be made by creating new issues.
• Check out the VS Code extension for syntax highlighting and autocompletion.
• Check out the documentation for an overview of all available functionality.
• Please star ⭐ the project!

---

📖 Table of Contents

• suanPan
  • 📖 Table of Contents
  • Introduction
  • ✨ Features
    • At a Glance
  • 🚀 Quick Start
  • 📥 Installation
    • Windows
      • Binary Package
      • Chocolatey
      • Scoop
    • Code Signing Policy
    • Linux
      • Snap
      • Flatpak
    • macOS
    • Docker
    • Other Platforms
  • 🛠 Automation & Tooling
    • VS Code [Recommended]
    • Sublime Text [Deprecated]
  • 📚 Dependencies
  • 🔨 How To Compile
  • 🎉 Happy Modelling
  • 🤝 Contributing
  • 📝 Citation
  • ⚖ Licence

---

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++ and aims to provide an efficient, concise, flexible and reliable FEM simulation platform.

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

✨ Features

The highlights of suanPan are:

• ⚡ fast, thread-safe and memory-safe
• 🧠 built with modern C++ language features
• 🌐 supports both shared-memory and distributed-memory parallelism
• 🖥 cross-platform with multi-arch support (amd64 & arm64)
• 🧩 rich library of elements, materials and time-integration schemes
• 🔧 highly expressive and easily extensible

At a Glance

Domain	What you get
Analysis	static, dynamic, arc-length, frequency, buckling and optimization steps
Elements	beams, trusses, membranes, plates, shells, 3D solids, contact, joints, embedded, mass, springs and more
Materials	elasticity, metal plasticity (von Mises/J2, Drucker–Prager, Cam-Clay, sand), concrete damage (CDP/CDPM2), orthotropic (Hoffman, Tsai–Wu, Hill), hysteresis, viscosity and user-defined models
Sections	structural (I/H/T/box/circle), fibre, NM section models and code-based design (EU/US/NZ)
Constraints	MPC, rigid/restitution walls, particle collision, embedding, node-line/facet and gap constraints
Integrators	implicit (Newmark, generalized-α, Bathe, GSSSS) and explicit (Bathe, Tchamwa, GSSE, WAT2) schemes
Parallelism	shared-memory (TBB), distributed-memory (MPI) and GPU acceleration (CUDA / MAGMA)

Tip

A complete, searchable catalogue of every command, element, material, section and solver lives in the manual.

🚀 Quick Start

Execute the application out of the box in a terminal using one of the following commands, depending on how the application was obtained. See the details below.

# in folder bin/ for linux portable tarball
./suanPan.sh
# for linux packages and snap
suanPan
# for flatpak
flatpak run io.github.tlcfem.suanPan

# for windows
# in the folder containing suanPan.exe
.\suanPan.exe

First-time users can use the overview command for a quick introduction.

+--------------------------------------------------------+
|             ____             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 and commands. Please check the Example folder for details. Further details on how to run model files can be found here.

📥 Installation

Tip

Daily debug builds can be downloaded via this page.

Warning

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

Windows

Note

The dependencies are bundled with the archive. You may also install the VC++ redistributable package. If the application reports that a file such as msvcp140.dll is missing (unlikely), please install the redistributable package.

Binary Package

Binary archives are released on the Releases page. All are portable archives; simply unpack and run the application.

Chocolatey

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

   choco install suanpan

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

The Chocolatey repository 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.

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

2. Install suanPan.

   scoop install suanpan

Code Signing Policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

This program will not transfer any information to other networked systems unless specifically requested by the user or by the person installing or operating it.

Linux

Linux users are encouraged 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.

# 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

macOS

The portable binary archives are provided for macOS 14 and 15 on both amd64 and arm64 architectures. The archives are self-contained and can also be run on earlier versions of macOS.

Caution

The binaries are not signed. It is necessary to run sudo xattr -dr com.apple.quarantine <downloaded/archive/folder> to remove the extended attribute.

DOWNLOAD_URL="https://github.com/TLCFEM/suanPan/releases/download/suanPan-v3.9.3/suanPan-macos-15-amd64-openblas-avx.tar.gz"
curl -L "$DOWNLOAD_URL" -o suanPan-latest.tar.gz
mkdir -p suanPan && tar -xzf suanPan-latest.tar.gz -C suanPan && cd suanPan
sudo xattr -dr com.apple.quarantine .
./suanPan.sh

The download link should be replaced with one appropriate for your system and requirements.

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.

You can also pull the image directly. Using Docker Hub:

docker pull tlcfem/suanpan

Using GitHub Container Registry:

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; this allows you to record VTK files for postprocessing, although OpenGL may be missing on server systems
2. mkl --- linear algebra operations are offloaded to MKL, which gives the best 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, which is 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 to enable GPU-based solvers, which require an available CUDA and/or MAGMA library.

🛠 Automation & Tooling

VS Code [Recommended]

The VS Code extension is available here. It provides syntax highlighting and autocompletion, and can run models using the specified executable or Docker container.

Sublime Text [Deprecated]

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

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

./suanPan.sh --install

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

📚 Dependencies

Additional libraries used in suanPan are listed below.

Click to expand the full dependency list

• AMD Optimizing CPU Libraries (AOCL) version 5.3
• ARPACK
• Armadillo version 15.6.2
• CUDA version 12.9
• Catch2 version 3.16.1
• FEAST version 4.0
• HDF5 version 2.2.0
• MAGMA version 2.9.0
• OpenBLAS version 0.3.34
• SPIKE version 1.0
• SuperLU MT version 4.0.0
• SuperLU version 7.0.1
• TBB Threading Building Blocks version 2023.1.0
• VTK version 9.7.1
• argparse
• exprtk version 0.0.3
• ezp
• fmt version 12.2.0
• magic_enum version 0.9.8
• oneMKL version 2026.1.1
• whereami
• thread_pool abridged version of thread-pool

🔨 How To Compile

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

🎉 Happy Modelling

🤝 Contributing

Contributions of all kinds are welcome — bug reports, feature requests, documentation improvements and pull requests. Please read the contribution guide before opening a pull request, and feel free to start a discussion for larger changes.

📝 Citation

If suanPan contributes to your research, please cite it using the metadata in CITATION.cff:

@software{suanPan,
  author    = {Chang, Theodore},
  title     = {suanPan --- An Open Source, Parallel and Heterogeneous Finite Element Analysis Framework},
  doi       = {10.5281/zenodo.1285221},
  url       = {https://github.com/TLCFEM/suanPan},
  license   = {GPL-3.0}
}

⚖ Licence

Distributed under the GNU General Public License v3.0 or later.

⬆ back to top