SYMbolic ParticLE simulatoR

Download .zip Download .tar.gz View on GitHub

Data privacy statement (Datenschutzerklärung)

Injection moulding simulation Coarse grained simulation of Graphene



  • 9 Oct 2018: SYMPLER now uses cmake instead of the autotools for configuration. Please read carefully how to compile SYMPLER!

Why a SYMbolic ParticLE simulatoR ?

Because you are in need for a unified flexible and modular simulation tool allowing for the investigation of structural, thermodynamic, and dynamical properties of fluids and solids from microscopic over mesoscopic up to macroscopic time and length scales with suitable particle based simulation methods such as molecular dynamics, dissipative particle dynamics or smoothed particle hydrodynamics. The user should be enabled to define her/his own physical models without the need for recoding or code extensions.

Main features of SYMPLER

  • Modular object oriented structure that is passed to the user level and allows to easily switch among different integration algorithms, particle interaction forces, boundary conditions, etc.
  • Arbitrary number of particle-species for the simulation of complex multi-component systems
  • Arbitrary number of additional user-defined degrees of freedom per particle-species
  • Symbolic definition of runtime compiled mathematical expressions for particle interactions
  • Import of CAD-geometries in the STL-format

Compiling SYMPLER


Required tools for configuration and compilation:

  • CMake (minimal version required: 2.8)
  • a C++ compiler such as GNU g++
  • a C compiler such as GNU gcc

Required libraries:

  • GNU scientific library (GSL)
  • libxml2

NOTE: You usually also have to install the libraries for development. They have names such as libgsl*-dev, libsdl*-dev, and so on.

Optional libraries:

  • libcppunit: Provides unit tests (on Ubuntu: sudo apt install libcppunit-dev).
  • liblzma-dev & libz-dev: For the configure-option -Dstatic=1 (see below).
  • libsdl (1.2.0 or newer but not 2.0 or newer): Gives simple runtime visualisation with the modules MeterLive and MeterLiveColoured. If the library is installed it will usually be found and the modules will be compiled. If libsdl is not found, you will have to modify some include and/or library paths by hand. Can not be used with the -Dstatic=1 option.
  • libfreesteam: If found, provides modules, in which the freesteam library is used to compute thermodynamic variables based on the IAPWS-IF97 formulation. Consult for more information. Can not be used with the -Dstatic=1 option.
  • OpenMP: For partial but still quite inefficient shared memory parallelisation. Use the option -fopenmp during configuration (CXXFLAGS="... -fopenmp").
  • libtnt, libjama, libsuperlu: Use the options -Dtnt=1 -DIntegratorStaticLSE=1 during configuration. This provides:
    • coupling of particles to a linear system of equations solver with module IntegratorLSE
    • the module for velocity constraints VelConstraints
    • the integrator IntegratorVelocityVerletPressure
    • running successfully the testsuite (see also section "Contributing to SYMPLER" below)

Configuration and Compilation

All the commands invoked in the following have their own documentation. Please refer to it for more information. It follows first a standard method working on standard Linux systems such as Ubuntu 16.04. Below you find special instructions for MacOS and Intel compilers.

Configuration and Compilation for standard Linux-systems:

Assuming the complete path to the directory where you downloaded the SYMPLER source-code is given by $SOURCE-DIR.

Then, assuming the complete path to the directory where you want to compile SYMPLER is given by $BUILD-DIR (it might be the same as or different from $SOURCE-DIR):

$ CXXFLAGS="[cxxflags]" cmake [options] $SOURCE-DIR
$ make -jNUM

where NUM can be 1 to roughly 1.5 times your available CPU-cores for faster parallel compilation. (NOT execution of sympler! See option -fopenmp below.)

Useful [cxxflags] are (for more see the g++ documentation):

  • -O3: for optimised compilation with g++
  • -fopenmp: For compilation with OpenMP parallelisation (currently still inefficient)
  • -O0 -g -Wall: for debugging.

and useful [options] are:

  • -Dtnt=1: use tnt library and jama libraries
  • -DIntegratorStaticLSE=1: use superlu library to compile IntegratorStaticLSE module
  • -Dstatic=1: for a statically linked stand alone executable not requiring any dynamical linking of libraries (except for the glibc used during linking after compilation of SYMPLER; and the runtime compiled expressions of course). NOTE: the freesteam modules (using libfreesteam) and the MeterLive and MeterLiveColoured modules (using libsdl) can not be compiled statically and will hence be missing. NOTE: the libraries liblzma-dev and libz-dev (listed under optional libraries above) are required. Also libicu should be installed, but this is usually the case by default (for example libicu-dev and libicu55 on Ubuntu 16.04). Further note that on older linux-distributions (for example Ubuntu around 12, 13, 14), this option causes SYMPLER to crash very often. On newer distributions this issue has vanished. Further bug reports on this issue are welcome.

After successful compilation the executable "sympler" will be created in the directory $BUILD-DIR.

Configuration and Compilation on MacOS

This section is currently being updated. In the meantime, please try to deduce the necessary steps from the Linux instructions. It is generally recommended to install all required libraries with the package manager brew and to remove all affected libraries previously installed in any other way.

SYMPLER and Intel compilers:

A few hints when using icc (the Intel C++ compiler) for SYMPLER:

  • Set the environment variable LANG=C
  • If using autoparallelization, set LD_LIBRARY_PATH to the lib directory of icc
  • -ipo gave problems with linking

Otherwise, compilation worked fine. A good cmake invocation might look like (adapt the paths to your needs; for the meaning of $CODE-DIR see above):

export LANG=C;
export LD_LIBRARY_PATH=/simstorage/software/intel/cpp11/lib/intel64;
CXX=/simstorage/software/intel/cpp11/bin/intel64/icc \
CC=/simstorage/software/intel/cpp11/bin/intel64/icc LDFLAGS='-lstdc++ -lz' \
CXXFLAGS="-O3 -ip -parallel -funroll-loops -complex-limited-range \
-IPF-fma -IPF-fltacc -IPF-fp-relaxed -fp-model=fast -no-debug -xSSE4.1 \
-mcmodel=medium -falign-functions -opt-calloc -unroll-aggressive" \
cmake $CODE-DIR


A static executable will work, if your glibc is roughly the same as the one, which was used for compilation. Additionally executables are specific to 32 and 64 bit platforms, respectively. The modules MeterLive and MeterLiveColoured are not activated in a static version. Alternatively you can use a dynamically linked version.

A dynamic executable needs at least the following libraries installed:

  • gsl (GNU scientific library)
  • libxml2 (for parsing the input files)

Starting the executables

Assuming you have an executable with name sympler in the directory $BUILD-DIR, just type

$ $BUILD-DIR/sympler

and you will be told the further options you may try in order to really get useful out of the code. For example

$ $BUILD-DIR/sympler --help 

gives a general help text.

$ $BUILD-DIR/sympler --help all

lists the help text for all available modules

$ $BUILD-DIR/sympler --help [UNKNOWN]

gives you a list of all groups of modules you may request help for if [UNKNOWN] is an argument that sympler does not understand. For example you may get help for the Integrators with

$ $BUILD-DIR/sympler --help Integrators

To really start a simulation type


where [INPUT-FILE] is an input file in xml-format.

Input files

The code has a modular structure. This is reflected in the input files by using the XML-format (for further information on XML see: A quick glance at the input files and the online-help text of the executable should be enough to understand how it works. All modules and their attributes are described in the online-help. A bit of definition: The XML-expression shows you the difference between a module name, an attribute name and the value assigned to the latter. Compare this with the example given below. If you play around with parameters, be aware of possible simulation instabilities due to a timestep being to large for your chosen parameters. In this case you will obtain some message that a particle flew to far. The timestep can be modified in the module with the attribute dt. The number of timesteps can be changed with the attribute timesteps. All quantities have to be given in units of your choice for instance in such a way that the Boltzmann constant may be set to 1. All simulations are 3D. Quasi-2D-simulations can be performed by applying periodic boundary conditions. Real 2D simulations can be performed by enforcing interactions to happen only in 2D.

Here is a small example. The newest version of SYMPLER might complain because some modules or attributes are out-dated, but the general idea should become clear:

    simName="MDPD simulation"  
            name="L1" />
            name="L075" />
                    species="H" />
<!-- Fluid-fluid, attractive -->
            weightingFunction="L1" />
<!-- Fluid-fluid, repulsive -->
            weightingFunction="L075" />
            temperature = "15"
            dissipation = "5"
            species1 = "H"
            species2 = "H"
            weightingFunction = "L1" />
                            corner1 = "(10,10,18)"
                            corner2 = "(22,22,6)"
                            temperature = "5"
                            ellipsoid = "true" />
            nX="16" nY="16" nZ="16">
            <Pressure species="H"/>
                    columns = "H_pressure_mean" />

Besides reading the help text, another way to quickly find out which attributes are allowed for a specific module, is to type some non-sense which most likely does not correspond to any attribute.

Runtime compiled expressions

In the example file you see some of them. For example "...(ni+nj)*[rij]/rij*40" where 'n' is a user defined scalar symbol, [rij] is the distance vector [ri]-[rj] for particle pair (i,j) and 'rij' is its absolute value. Single indices 'i', 'j' denote a particle property while double indices 'ij' denote the property of the pair of particles. Type

$ $BUILD-DIR/sympler --help expressions

for a complete overview of possible elements of runtime compiled expressions. Help for the two module-groups Forces and Symbols that use runtime-compiled expressions the most you can get with

$ $BUILD-DIR/sympler --help Forces
$ $BUILD-DIR/sympler --help Symbols

Further check the PUBLICATIONS file for publications explaining further details.


SYMPLER produces output in various ASCII and binary formats, for example VTK, simple column data, or binary arrays of data. First of all you need Meters in your input file. Check

$ $BUILD-DIR/sympler --help Meters

In the above example we have two Meters, namely MeterPosVel and GridAveragerStructured. The thing is that a Meter itself usually does not create any output. It just collects data. GridAveragerStructured is even lazier and lets GridMeters do the work. Check

$ $BUILD-DIR/sympler --help GridMeters

GridMeters are also Meters. Hence they also collect data and nothing else. For output you have to attach PostProcessors to the Meters. In the aexample above you can find two of them: OutputVTK and OutputFile. Check

$ $BUILD-DIR/sympler --help Postprocessors

Contributing to SYMPLER

Feel free to contribute code-extensions by making a pull request on

You should follow these rules before making a pull request:

  • At the very least, run the test-script in the testsuite directory.
  • Think about adding an own test of your new features to the testsuite

Projects with SYMPLER

The following pages describe research projects where SYMPLER has been used:


Please cite the publications in the PUBLICATIONS file.


Funding by the DFG (Deutsche Forschungsgemeinschaft) in the framework of

  • SFB499 TPA4
  • Project KA 3482/2
  • Projects LI 1831/1-1,2


Copyright 2002-2018, David Kauzlaric and other authors listed in the AUTHORS file.
This program comes with ABSOLUTELY NO WARRANTY; for details see the LICENSE file.
This is free software, and you are welcome to redistribute it under certain conditions; for details see the LICENSE file.


Angaben gemäß § 5 TMG:

Gruppe Simulation
Georges-Koehler-Allee 103
79110 Freiburg, Germany


Telefon: +49-761-203-67479


Haftungsausschluss (Disclaimer)

Haftung für Inhalte

Als Diensteanbieter sind wir gemäß § 7 Abs.1 TMG für eigene Inhalte auf diesen Seiten nach den allgemeinen Gesetzen verantwortlich. Nach §§ 8 bis 10 TMG sind wir als Diensteanbieter jedoch nicht verpflichtet, übermittelte oder gespeicherte fremde Informationen zu überwachen oder nach Umständen zu forschen, die auf eine rechtswidrige Tätigkeit hinweisen. Verpflichtungen zur Entfernung oder Sperrung der Nutzung von Informationen nach den allgemeinen Gesetzen bleiben hiervon unberührt. Eine diesbezügliche Haftung ist jedoch erst ab dem Zeitpunkt der Kenntnis einer konkreten Rechtsverletzung möglich. Bei Bekanntwerden von entsprechenden Rechtsverletzungen werden wir diese Inhalte umgehend entfernen.

Haftung für Links

Unser Angebot enthält Links zu externen Webseiten Dritter, auf deren Inhalte wir keinen Einfluss haben. Deshalb können wir für diese fremden Inhalte auch keine Gewähr übernehmen. Für die Inhalte der verlinkten Seiten ist stets der jeweilige Anbieter oder Betreiber der Seiten verantwortlich. Die verlinkten Seiten wurden zum Zeitpunkt der Verlinkung auf mögliche Rechtsverstöße überprüft. Rechtswidrige Inhalte waren zum Zeitpunkt der Verlinkung nicht erkennbar. Eine permanente inhaltliche Kontrolle der verlinkten Seiten ist jedoch ohne konkrete Anhaltspunkte einer Rechtsverletzung nicht zumutbar. Bei Bekanntwerden von Rechtsverletzungen werden wir derartige Links umgehend entfernen.


Die durch die Seitenbetreiber erstellten Inhalte und Werke auf diesen Seiten unterliegen dem deutschen Urheberrecht. Die Vervielfältigung, Bearbeitung, Verbreitung und jede Art der Verwertung außerhalb der Grenzen des Urheberrechtes bedürfen der schriftlichen Zustimmung des jeweiligen Autors bzw. Erstellers. Downloads und Kopien dieser Seite sind nur für den privaten, nicht kommerziellen Gebrauch gestattet. Soweit die Inhalte auf dieser Seite nicht vom Betreiber erstellt wurden, werden die Urheberrechte Dritter beachtet. Insbesondere werden Inhalte Dritter als solche gekennzeichnet. Sollten Sie trotzdem auf eine Urheberrechtsverletzung aufmerksam werden, bitten wir um einen entsprechenden Hinweis. Bei Bekanntwerden von Rechtsverletzungen werden wir derartige Inhalte umgehend entfernen.

Quellverweis: eRecht24