Obtain Application

Docker Image

A docker image is available at Docker Hub. Both amd64 and arm64 architectures are available. To use it, docker needs to be installed first. See this page for details.

Once docker is installed, it is possible to pull the image via:

docker pull tlcfem/suanpan

Then it is possible to run the container in an interactive manner via:

docker run -it --rm tlcfem/suanpan

Within the container, one can use one of the following commands to invoke the application.

suanPan
suanpan
sp

One can also attach volume to the container to access files in the host machine. This may be the main use case. Assume there is a model file under the path /path/to/host/folder/example.model.sp, to run the analysis under this folder, one can use the following command.

docker run --rm -v /path/to/host/folder:/dirty -w /dirty tlcfem/suanpan sp -f example.model.sp

Docker image is convenient on machines with older kernels or limited by other factors that does not allow execution of precompiled binaries.

This is now supported by the VS Code extension.

The following shall be noted.

  1. For maximum compatibility, the image is compiled without AVX support.

  2. On amd64, Intel MKL is used. On arm64, OpenBLAS is used.

If necessary, one can build images with different configurations to enable AVX and AVX2 support and/or AOCL support on AMD platforms.

Precompiled Binaries

The binaries are published on GitHub.https://github.com/TLCFEM/suanPan/releases

Binaries on Windows, Ubuntu and macOS are compiled and deployed automatically on the master branch. The precompiled binaries are compiled on the following OS versions.

Platform
Version

Windows

Windows Server 2022

Linux

Ubuntu 22.04

macOS

Ventura 13

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.

Currently, the following package managers can be used to install the program.

Platform
Package Manager
Command

Windows

Chocolatey

choco install suanpan

Windows

scoop

scoop install suanpan

Linux

snap

snap install suanpan

Linux

flatpak

flatpak install flathub io.github.tlcfem.suanPan

The binaries are tested in standard environments: fresh newWin10/11 images, docker images Ubuntu and Fedora, and macOS GitHub image.

Chocolatey

snap

flatpak

To run the application, one shall use the following command in terminal.

flatpak run io.github.tlcfem.suanPan

Since no shim is created, it would be convenient to create alias such that

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

Then it is possible to use suanpan to invoke the application.

Execute Program

By default, the AVX2 support is turned on to utilize CPU capability. For CPUs that do not support AVX2, the application cannot be successfully executed. Users can either compile the program by themselves or request a specific version by filing an issue.

The name of the executable is suanPan, however, snap/chocolatey/scoop will create shim executable named assuanpan. Depending on how the application is installed, one may use suanpan or suanPan to invoke the application.

The parallelization is enabled mostly by the TBB library and <execution> header (C++17). If the program is compiled with SUANPAN_MT macro, parallelization is used by default. The OpenMP is enabled in several parts of the program, users can set environment variable OMP_NUM_THREADS to customize some OpenMP based parallelization. To do so, users can, for example, in Windows, use the following command.

set OMP_NUM_THREADS=6

On Linux, the dynamic loading path needs to be set so that dynamic libraries such as libtbb.so can be successfully found. If the application is installed via snap/apt/dnf, it is automatically done.

# current path contains suanPan
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/../lib
./suanPan

Alternatively, users can execute the program via the provided suanPan.sh script.

# create links to the executables
# the script assumes ~/.local/bin is in the path and creates a symbolic link to the executable
./suanPan.sh --create-link
# cd to other folders and execute the program
cd ~
suanpan

CLI Mode

By running the program without any parameters, it enters CLI mode by default. Users can create models in an interactive manner.

+--------------------------------------------------------+
|             ____             suanPan is an open source |
|   ___ _   _|  _ \ __ _ _ __     FEM framework (64-bit) |
|  / __| | | | |_) / _` | '_ \           Canopus (3.7.0) |
|  \__ \ |_| |  __/ (_| | | | |        by tlc @ 427eefcb |
|  |___/\__,_|_|   \__,_|_| |_|      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 ~<>

A command named as example is available to automatically create an example model and perform the analysis.

+--------------------------------------------------------+
|             ____             suanPan is an open source |
|   ___ _   _|  _ \ __ _ _ __     FEM framework (64-bit) |
|  / __| | | | |_) / _` | '_ \           Canopus (3.7.0) |
|  \__ \ |_| |  __/ (_| | | | |        by tlc @ 427eefcb |
|  |___/\__,_|_|   \__,_|_| |_|      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 ~<> example
====================================================
-> A Minimum Example: Elastic Truss Under Tension <-
====================================================
--> create two nodes at (0,0) and (2,0):
        node 1 0 0
        node 2 2 0
--> create material model (elastic modulus 52):
        material Elastic1D 1 52
--> create a truss element connecting nodes 1 and 2:
        element T2D2 1 1 2 1 93
--> define boundary condition and load:
        fix 1 1 1
        fix 2 2 1 2
        displacement 1 0 1.4 1 2
--> define a static step:
        step static 1
--> perform the analysis:
        analyze
[WARNING] BandMat.hpp:62 ~> The storage requirement for the banded matrix is larger than that of a full matrix, consider using a full/sparse matrix instead.
>> Current Analysis Time: 1.00000.

--> check nodal force (P=UEA/L=1.4*52*93/2=3385.2):
        peek node 2
Node 2:
Coordinate:
  2.0000e+00  0.0000e+00
Displacement:
  1.4000e+00  0.0000e+00
Resistance:
  3.3852e+03  0.0000e+00

--> clean up and it's your turn!
====================================================
suanPan ~<>

Batch Mode

To analyze the model written in a model file named as for example example.supan, the -f or --file parameter can be used. First we create the file example.supan with exit command.

echo exit > example.supan

Then we can run it by the following command.

suanpan -f ./example.supan

Or on Windows,

./suanPan.exe -f example.supan

If the model has been prechecked, it is possible to run the analysis without output. It is known that printing strings to terminals slows down the analysis. Users can use the -np or --noprint option to suppress output.

./suanPan.exe -np -f example.supan

In the CLI mode, it is possible to use file command to load the file.

+--------------------------------------------------+
|   __        __         suanPan is an open source |
|  /  \      |  \           FEM framework (64-bit) |
|  \__       |__/  __   __      Betelgeuse (2.3.0) |
|     \ |  | |    |  \ |  |      maintained by tlc |
|  \__/ |__| |    |__X |  |    all rights reserved |
|                           10.5281/zenodo.1285221 |
+--------------------------------------------------+
|  https://github.com/TLCFEM/suanPan               |
|  https://github.com/TLCFEM/suanPan-manual        |
+--------------------------------------------------+
|  https://gitter.im/suanPan-dev/community         |
+--------------------------------------------------+

suanPan ~<> file example.supan

VS Code

The VS Code extension is available here. It provides syntax highlighting and code completion.

The plugin also provides functionalities to invoke the analysis in docker containers.

demo

Sublime Text Workspace

I personally use Sublime Text as my model editor. Other tools like VS Code can also be used.

Syntax Highlighting

Create a new syntax file via Tools -> Developer -> New Syntax..., copy and paste the following sample content into the new file and save as suanPan.sublime-syntax under the default path. It provides syntax highlighting for comments only. Other components can be added accordingly.

%YAML 1.2
---
file_extensions:
  - supan
  - sp
scope: source.supan
contexts:
  main:
    - match: '^[#!].*'
      scope: comment.line
    - match: '!.*'
      scope: comment.line

A syntax file with (almost) all commands is provided as suanPan.sublime-syntax in the archive. Please feel free to use/modify it. It may be necessary to manually search for the file if the application is installed via some package manager.

Autocomplete

All keywords used are stored in the JSON file suanPan.sublime-completions. Place the file in folder ~/.config/sublime-text-3/Packages/User/ (Linux) or %appdata%\Sublime Text 3\Packages\User (Windows) and you are good to go with the previous syntax file. The new path has been changed to ~/.config/sublime-text/Packages/User/ ( Linux) and %appdata%\Sublime Text\Packages\User (Windows) in Sublime Text 4.

Build System

In order to render ANSI color codes correctly in Linux like systems, you may wish to install ANSIescape package. Now define a new build system via Tools -> Build System -> New Build System..., copy and paste the following contents in the file and save it as suanPan.sublime-build. You may need to replace command suanpan with the full path of the executable.

{
  "cmd": [
    "suanpan",
    "-f",
    "$file"
  ],
  "selector": "source.supan",
  "file_patterns": [
    "*.supan",
    "*.sp"
  ],
  "target": "ansi_color_build",
  "syntax": "Packages/ANSIescape/ANSI.sublime-syntax"
}

Now models can be run in Sublime Text via the shortcut Ctrl+B.

To disable coloured output, use -nc (no colour) option such as

suanpan -nc -f model_file.supan

Automation

Windows

A batch file named as AddAssociation.bat is provided in the archive. It associates *.sp and *.supan files with the program and copies configuration files to default folder if Sublime Text is installed. If the package is installed via package managers, pleas manually search for and execute this file.

Admin privilege is required.

Linux

A bash script named as suanPan.sh is provided in the archive to set up the above configurations automatically. The script can be used to both execute the program and create symbolic links.

For the first time use, the following commands create a soft link under $HOME/.local/bin so that users can execute the program anywhere by invoking command suanpan in any folder. The Sublime Text configuration files are copied to the default folder if Sublime Text is installed.

# current path contains suanPan
chmod +x suanPan.sh
./suanPan.sh --create-link
# cd to other places such as folders that contain models
# now invoke the program
suanpan

Check the following recording.

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

PreviousIntroductionNextConfigure Application

Last updated