Lecture Notes Espresso Intro

=Getting Espresso up and running=

Release packages

 * Release packages can be found here: http://espressomd.org/wordpress/download/
 * These versions have received extra checking and are recommended for beginners

Development code

 * These versions have more up-to-date code and newer features, but might also have unresolved problems
 * They are recommended for those, who want to add features or who need stuff added since the last stable release
 * The Espresso code is managed using the Git version control system and hosted on www.github.com?espressomd
 * Get the code: git clone git://github.com/espressomd/espresso
 * Prepare the build system: cd espresso; ./bootstrap.sh (The Gnu Autotools need to be installed)
 * Install dependencies
 * tcl including development files
 * openmpi

Directories

 * Source directory: The directory containing the Espresso source files
 * Build directory: An (initially empty) directory in which the compiled executable and related files will be located

How to build

 * 1) Change to (empty) build directory
 * 2) sourceDirectory/configure
 * 3) make


 * Espresso is usually no installed system-side, because different simulations need differently compiled binaries.
 * To clean the build, but keep the configuration: make clean
 * To clean the build and remove the configuration: make distclean
 * To build the documentation: make doc
 * To run the test suite: make check

Configuring the build

 * At compile-time, certain features (and dependencies) are built into Espresso
 * The decision has to be made at compile time, because some features need external libraries. (E.g. parallel computing using MPI, GPU computing using CUDA, binary I/O using Hdf5)
 * Some features also make Espresso slower and should only be compiled in when used (Example: Integrating rotational degrees of freedom, Rigid body mechanics).


 * Two ways to configure the build:
 * Via options to the configure script (e.g., configure --without-cuda)
 * Via the myconfig.hpp file (myconfig-sample.hpp can serve as template)

Running Espresso

 * With a script: buildDirector/Espresso scriptName.tcl
 * Interactively: buildDirectory/Espresso (then, enter tcl commands. Use "exit" to quit)

=Simulating with Espresso=

Important Espresso commands

 * inter: Set up interactions between particles
 * part: Interact with particles
 * setmd: Set various parameters of the simulation, e.g., time step
 * thermostat: Control Langevin and other thermostats, set thermal energy and friction coefficient
 * integrate: Propagate the particles
 * analyze: Perform analysis on the system (energy, pair correlation function, density profiles...)

Important parts of a simulation

 * 1) Set up the simulation box (Size, boundary conditions)
 * 2) Set up the integrator parameters (skin, time step)
 * 3) Set up the thermostat
 * 4) Set up short-range interactions (non-bonded and bonded, no Coulomb interaction yet!)
 * 5) Place particles
 * 6) Get rid of overlaps between particles (so-called warm up)
 * 7) Set up long range interactions such as Coulomb.
 * 8) Thermalize
 * 9) Measure

Set up the simulation box (Size, boundary conditions

 * setmd box_l 10 10 10
 * setmd periodic 1 1 1

Set up the integrator parameters (skin, time step

 * setmd time_step 0.01
 * setmd skin 0.4
 * setmd max_num_cells 1000

Set up the thermostat

 * thermostat langevin 1 1

Set up short-range interactions (non-bonded and bonded, no Coulomb interaction yet!)

 * Non-bonded: act between all pairs of particles of given types (e.g., Lennard-Jones)
 * Bonded: Act only on explicitly specified pairs of particles (E.g., harmonic bonds between neighboring particles in a polymer chain)


 * inter 0 0 lennard-jones 1 1 [expor 2,pow(1./6.]) auto

Place particles

 * part 0 pos 0 0 0 type 0 q -1

Get rid of overlaps between particles (so-called warm up)

 * inter forcecap 10
 * Then iteratively integrate ~100 steps and increase forcecap
 * When particles don't overlap by more than 20%, turn off forcecap
 * inter forcecap 0

Set up long range interactions such as Coulomb

 * inter coulomb 1 p3m tune accuracy 1E-4

Thermalize

 * Integrate for ~100 relaxation times to equilibrate the system.
 * The relaxation time in simulation time units is approximately particle mass / gamma
 * The number of steps to integrate is = relaxation time / time step

Online visualization

 * Espresso uses vmd for online visualization
 * After particles have been placed, call: prepare_vmd_connection "simulation_name"
 * This writes the particle structure and a config script and launches vmd
 * After each integration update the particle positions in vmd using: imd position

Running Espresso on more than one Cpu core

 * Espresso is parallelized using MPI (i.e., distributed memory paradigm)
 * Hence, a simulation can make use of more than one computer
 * To run Espresso in parallel: mpiexec -n 4 ./Espresso script.tcl

Particle organization

 * Short-range interactions (Lennard-Jones...) only need to be calculated for particles closer than the largest cut-off
 * This lets us avoid the effort of order n^2 to calculate the interactions.

Cells

 * The particles are sorted into cells (domain decompositoin)
 * The cells have a minimum size of the largest cutoff (+ the skin, see below)
 * For a given particle, only particles in the same cell and in next neighboring cells are interaction partners
 * particles more than one cell apart do not interact

In practice:
 * More cels = less pairs of particles to consider
 * But also more book-keeping work for the cells
 * The number of cells to use in practice is therefore a trade-off. Rule of thumb: One per particle
 * Limit the minimum and maximum number of cells allowed via
 * setmd min_num_cells 100
 * setmd max_num_cells 10000

Verlet lists and skin

 * Using the cells, pairs of particles are still considered that are mor than the cut-off apart
 * Therefore, each particle has a "Verlet-list" of relevant interaction partners
 * All particles within a distance =cut-off +skin are considered
 * Then, this list remains valid, until any particle in the simulation has moved more than skin

In practice:
 * Larger skin: Verlet lists remain valid longer
 * But more pairs of non-interacting particles are considered
 * rule of thumb: skin=0.4 for particles with sigma=1
 * To set: setmd skin 0.4