/*
*/
SYMPLER: SYMbolic ParticLE simulatoR
Contents of this file:
Field of application:
The 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:
Compiling SYMPLER:
++ CMake (minimal version required: 2.8) ++ a C++ compiler such as GNU g++ ++ a C compiler such as GNU gcc
++ 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.
++ 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 http://freesteam.sourceforge.net/ 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)
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 12.04 or newer. 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):
$ cd $BUILD-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
!!!NOTE!!! These instructions are currently outdated and will NOT work with the current distribution requiring CMAKE instead of the autotools. They should still work with older distributions which use the autotools. An update of the MacOS documentation is under construction. 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.
The following instructions were last successfully tested on Mac OS X 10.11.6 (based on older instructions by Andreas Greiner, Tobias Wondratsch, Oliver Grünert).
The libxml2 library comes already preinstalled by Apple but caused trouble during the SYMPLER installation. You may give the preinstalled libxml2 a try or immediately go and get an alternative version and the two remaining libraries by using one of the packaging-systems for Mac OS.
One of the best packaging-systems is homebrew. How to install homebrew is described on https://brew.sh. Two nice properties of homebrew are, that it is easy to install and very easy to UNINSTALL, meaning that your operating system will be the same as before, without any old header or binary files lying around.
After homebrew is installed, you are ready to install the GSL and the SDL library. But first, on a fresh system, you might still be lacking
$ brew install gcc $ brew install libtool $ brew install autoconf $ brew install automake
To install GSL type
$ brew install gsl
into your terminal. Then, to install SDL type
$ brew install sdl
into your terminal.
If you have to, also install libxml2
$ brew install libxml2
Similarly for further libraries which you might need (see Linux section).
Make sure the symbolic link used to find the libraries is set to your version installed by brew. Usually you use a command
$ brew link ...
for that.
Try first to skip this paragraph because the next step is only necessary if you run into trouble with your already preinstalled command-line tool gm4 (a macro processor used by aclocal). Then you need to replace it with a newer version, since the old version which came from Apple was broken. This was the case for example in MacOS 10.6.2. You can grab the most recent version from http://ftp.gnu.org/gnu/m4/. Now drag the old gm4 tool in /usr/bin to a backup folder (for example your Desktop) and replace it with the newer version (you will be asked to enter your root password).
Now you are ready to compile SYMPLER! So grab the SYMPLER source code into a code directory (called $CODE-DIR here) and create a new build directory (called $BUILD-DIR here) into which you will compile. Then in your terminal (adapt the paths to your needs):
$ cd $CODE-DIR $ autoreconf --install --force $ cd $BUILD-DIR $ $CODE-DIR/configure CXXFLAGS="-O3" $ make -j[1 to roughly the number of available cores]
After successful compilation the executable "sympler" will be created in the directory src/
For further compile options see the Linux section.
If you get a compile error related to cppunit, then try to switch in the CXXFLAGS to a different C++ standard than the default one of your compiler. For example
$ $CODE-DIR/configure CXXFLAGS="-O3 -std=c++14"
A known problem that may occur is a conflict with a libxml2 version previously installed in MacOS, for example due to a previous installation of Xcode. Just find a way to clean your system from this old libxml2 version and the SYMPLER installation should work fine by using the brew version of libxml2. Or try the command
$ brew link ...
mentioned above.
++ SYMPLER and Intel compilers:
!!!NOTE!!! These instructions are currently outdated and will NOT work literally with the current distribution requiring CMAKE instead of the autotools. They should still work with older distributions which use the autotools, and the flags and variables can still beset similarly. An update of the documentation for compiling with the Intel compile is under construction.
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
Running SYMPLER
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 just like the Freesteam modules. 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)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 s.th. 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
$ $BUILD-DIR/sympler [INPUT-FILE]
where [INPUT-FILE] is an input file in xml-format.
The code has a modular structure. This is reflected in the input files by using the XML-format (for further information
on XML see: http://www.w3schools.com/xml/default.asp). 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
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:
<?xml version="1.0"?> <!DOCTYPE Simulation SYSTEM "/home/lieneman/Projekte/NanoSAVE/Moldyn/moldyn.dtd"> <Simulation simName="MDPD simulation" inputFromResults="yes"> <Square cutoff="1" name="L1" /> <Square cutoff="0.75" name="L075" /> <Controller timesteps="100000" statusEvery="10" dt="0.001"> <IntegratorVelocityVerlet species="H" /> <ValCalculatorRho symbol="n" weightingFunction="L1" species1="H" species2="H" selfContribution="false"/>
<FPairVels
species1="H"
species2="H"
pairFactor="-1/4.7746*[rij]/rij*750"
weightingFunction="L1" />
<!-- Fluid-fluid, repulsive -->
<FPairVels
species1="H"
species2="H"
pairFactor="3.14159265*0.75^4/15*(ni+nj)*[rij]/rij*40"
weightingFunction="L075" />
<ThermostatPetersIso
temperature = "15"
dissipation = "5"
species1 = "H"
species2 = "H"
weightingFunction = "L1" />
<Phase>
<LinkedListCreator/>
<BoundaryCuboid
boxX="32"
boxY="32"
boxZ="32"
periodicX="yes"
periodicY="yes"
periodicZ="no">
<ReflectorThermalize
temperature="15"
oneHit="true"/>
<ParticleCreatorStatic
density="20"
species="H"
corner1 = "(10,10,18)"
corner2 = "(22,22,6)"
temperature = "5"
ellipsoid = "true" />
</BoundaryCuboid>
</Phase>
<MeterPosVel
measureEvery="1000"
species="H">
<OutputVTK
fileName="results/posvel_prepare.vtk"
format="ascii"></OutputVTK>
</MeterPosVel>
<GridAveragerStructured
avgOver="50"
measureEvery="1000"
nX="16" nY="16" nZ="16">
<Pressure species="H"/>
<OutputFile
fileName="results/gas_pressure.dat"
multipleFiles="yes"
columns = "H_pressure_mean" />
</GridAveragerStructured>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.
In the example file you see some of them. For example "...(ni+nj)[rij]/rij40 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.
Postprocessing
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 example 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 https://github.com/kauzlari/sympler
You should follow these rules before making a pull request: