• 1. Introduction
  • 1.1. Guiding principles
  • 1.2. Basic program structure
  • 1.3. Basic python simulation script
  • 1.4. Tutorials
  • 1.5. Sample scripts
  • 1.6. On units
  • 1.7. Available simulation methods
  • 1.8. Intended interface compatibility between ESPResSo versions
• 2. Installation
  • 2.1. Requirements
    • 2.1.1. Installing Requirements on Ubuntu 16.04 LTS
    • 2.1.2. Installing Requirements on Mac OS X
    • 2.1.3. Installing python dependencies
  • 2.2. Quick installation
  • 2.3. Configuring
    • 2.3.1. myconfig.hpp: Activating and deactivating features
    • 2.3.2. Features
    • 2.3.3. Features marked as experimental
    • 2.3.4. cmake
    • 2.3.5. ccmake
  • 2.4. make: Compiling, testing and installing
  • 2.5. Running ESPResSo
  • 2.6. Debugging ESPResSo
• 3. Setting up the system
  • 3.1. Setting global variables in Python
    • 3.1.1. Accessing module states
  • 3.2. Cellsystems
    • 3.2.1. Global properties
    • 3.2.2. Domain decomposition
    • 3.2.3. N-squared
    • 3.2.4. Layered cell system
  • 3.3. Thermostats
    • 3.3.1. Langevin thermostat
    • 3.3.2. Dissipative Particle Dynamics (DPD)
    • 3.3.3. Isotropic NPT thermostat
  • 3.4. CUDA
    • 3.4.1. GPU Acceleration with CUDA
    • 3.4.2. List available CUDA devices
    • 3.4.3. Selection of CUDA device
• 4. Setting up particles
  • 4.1. Overview of the relevant Python classes
  • 4.2. Adding particles
  • 4.3. Accessing particle properties
    • 4.3.1. Vectorial properties
  • 4.4. Interacting with groups of particles
  • 4.5. Deleting particles
  • 4.6. Iterating over particles and pairs of particles
  • 4.7. Exclusions
  • 4.8. Create particular particle configurations
    • 4.8.1. Setting up polymer chains
    • 4.8.2. Setting up diamond polymer networks
  • 4.9. Virtual sites
    • 4.9.1. Rigid arrangements of particles
    • 4.9.2. Inertialess lattice Boltzmann tracers
  • 4.10. Particle number counting feature
  • 4.11. Self-propelled swimmers
    • 4.11.1. Langevin swimmers
    • 4.11.2. Lattice Boltzmann (LB) swimmers
• 5. Running the simulation
  • 5.1. Integrator
  • 5.2. Run steepest descent minimization
  • 5.3. Multi-timestepping
  • 5.4. Integrating rotational degrees of freedom
• 6. Non-bonded interactions
  • 6.1. Isotropic non-bonded interactions
    • 6.1.1. Tabulated interaction
    • 6.1.2. Lennard-Jones interaction
    • 6.1.3. Generic Lennard-Jones interaction
    • 6.1.4. Lennard-Jones cosine interaction
    • 6.1.5. Smooth step interaction
    • 6.1.6. BMHTF potential
    • 6.1.7. Morse interaction
    • 6.1.8. Buckingham interaction
    • 6.1.9. Soft-sphere interaction
    • 6.1.10. Membrane-collision interaction
    • 6.1.11. Hat interaction
    • 6.1.12. Hertzian interaction
    • 6.1.13. Gaussian
    • 6.1.14. DPD interaction
    • 6.1.15. Thole correction
  • 6.2. Anisotropic non-bonded interactions
    • 6.2.1. Gay-Berne interaction
    • 6.2.2. Affinity interaction
• 7. Bonded interactions
  • 7.1. Distance-dependent bonds
    • 7.1.1. FENE bond
    • 7.1.2. Harmonic bond
    • 7.1.3. Harmonic Dumbbell Bond
    • 7.1.4. Bonded Coulomb
    • 7.1.5. Subtract P3M short-range bond
    • 7.1.6. Subtracted Lennard-Jones bond
    • 7.1.7. Rigid bonds
    • 7.1.8. Tabulated bond interactions
    • 7.1.9. Virtual bonds
  • 7.2. Object-in-fluid interactions
    • 7.2.1. OIF local forces
    • 7.2.2. OIF global forces
    • 7.2.3. Out direction
  • 7.3. Bond-angle interactions
  • 7.4. Dihedral interactions
  • 7.5. Thermalized distance bond
• 8. Electrostatics
  • 8.1. Coulomb P3M
    • 8.1.1. Tuning Coulomb P3M
    • 8.1.2. Coulomb P3M on GPU
  • 8.2. Debye-Hückel potential
  • 8.3. Dielectric interfaces with the ICC\(\star\) algorithm
  • 8.4. MMM2D
  • 8.5. Electrostatic Layer Correction (ELC)
  • 8.6. MMM1D
  • 8.7. Scafacos Electrostatics
• 9. Magnetostatics / Dipolar interactions
  • 9.1. Dipolar interaction
    • 9.1.1. Dipolar P3M
    • 9.1.2. Dipolar Layer Correction (DLC)
  • 9.2. Dipolar direct sum
  • 9.3. Barnes-Hut octree sum on gpu
  • 9.4. Scafacos Magnetostatics
• 10. System manipulation
  • 10.1. Changing the box volume
  • 10.2. Stopping particles
  • 10.3. Fixing the center of mass
  • 10.4. Capping the force during warmup
  • 10.5. Galilei Transform and Particle Velocity Manipulation
• 11. Single particle forces (constraints)
  • 11.1. Shaped-based constraints
  • 11.2. Adding shape-based constraints to the system
    • 11.2.1. Deleting a constraint
    • 11.2.2. Getting the currently defined constraints
    • 11.2.3. Getting the force on a constraint
    • 11.2.4. Getting the minimal distance to a constraint
    • 11.2.5. Available Shapes
    • 11.2.6. Available options
  • 11.3. Creating a harmonic trap
  • 11.4. External Fields
    • 11.4.1. Constant fields
    • 11.4.2. Interpolated Force and Potential fields
• 12. Lattice Boltzmann
  • 12.1. Setting up a LB fluid
  • 12.2. Checkpointing LB
  • 12.3. LB as a thermostat
  • 12.4. Reading and setting properties of single lattice nodes
  • 12.5. Removing total fluid momentum
  • 12.6. Output for visualization
  • 12.7. Choosing between the GPU and CPU implementations
  • 12.8. Electrohydrodynamics
  • 12.9. Using shapes as lattice Boltzmann boundary
    • 12.9.1. Minimal usage example
    • 12.9.2. Setting up boundary conditions
• 13. Analysis
  • 13.1. Direct analysis routines
    • 13.1.1. Energies
    • 13.1.2. Momentum of the System
    • 13.1.3. Minimal distances between particles
    • 13.1.4. Particles in the neighborhood
    • 13.1.5. Particle distribution
    • 13.1.6. Cylindrical Average
    • 13.1.7. Radial distribution function
    • 13.1.8. Structure factor
    • 13.1.9. Center of mass
    • 13.1.10. Moment of inertia matrix
    • 13.1.11. Gyration tensor
    • 13.1.12. Pressure
    • 13.1.13. Stress Tensor
    • 13.1.14. Local Stress Tensor
    • 13.1.15. Chains
  • 13.2. Observables and correlators
    • 13.2.1. Creating an observable
    • 13.2.2. Available observables
    • 13.2.3. Correlations
    • 13.2.4. Details of the multiple tau correlation algorithm
  • 13.3. Accumulators
    • 13.3.1. Mean-variance calculator
  • 13.4. Cluster analysis
• 14. Input and Output
  • 14.1. No generic checkpointing
  • 14.2. (Almost) generic checkpointing in Python
  • 14.3. Writing H5MD-files
  • 14.4. Writing MPI-IO binary files
  • 14.5. Writing VTF files
    • 14.5.1. writevsf: Writing the topology
    • 14.5.2. writevcf: Writing the coordinates
    • 14.5.3. espressomd.io.writer.vtf.vtf_pid_map()
  • 14.6. Writing various formats using MDAnalysis
  • 14.7. Parsing PDB Files
• 15. Online-visualization
  • 15.1. General usage
  • 15.2. Common methods for OpenGL and Mayavi
  • 15.3. Mayavi visualizer
  • 15.4. OpenGL visualizer
    • 15.4.1. Running the visualizer
    • 15.4.2. Screenshots
    • 15.4.3. Colors and Materials
    • 15.4.4. Visualize vectorial properties
    • 15.4.5. Controls
    • 15.4.6. Dragging particles
  • 15.5. Visualization example scripts
• 16. Advanced Methods
  • 16.1. Creating bonds when particles collide
  • 16.2. Swimmer Reactions
  • 16.3. Lees-Edwards boundary conditions
  • 16.4. Immersed Boundary Method for soft elastic objects
  • 16.5. Object-in-fluid
    • 16.5.1. Triangulations of elastic objects
    • 16.5.2. Description of sample script
    • 16.5.3. Visualization in ParaView
    • 16.5.4. Available Object-in-fluid (OIF) classes
  • 16.6. Electrokinetics
    • 16.6.1. Electrokinetic Equations
    • 16.6.2. Setup
    • 16.6.3. Output
  • 16.7. Particle polarizability with thermalized cold Drude oscillators
    • 16.7.1. Canceling intramolecular electrostatics
  • 16.8. Reaction Ensemble
    • 16.8.1. Converting tabulated reaction constants to internal units in Espresso
    • 16.8.2. Wang-Landau Reaction Ensemble
    • 16.8.3. Constant pH simulation using the Reaction Ensemble
    • 16.8.4. Grand canonical ensemble simulation using the Reaction Ensemble
    • 16.8.5. Widom Insertion (for homogeneous systems)
• 17. Under the hood
  • 17.1. Internal particle organization
• 18. Contributing
  • 18.1. Community support and mailing lists
  • 18.2. Contributing your own code
  • 18.3. Building the User’s guide
• 19. Appendix
  • 19.1. The MMM family of algorithms
    • 19.1.1. Introduction
    • 19.1.2. MMM2D theory
    • 19.1.3. MMM1D theory
    • 19.1.4. ELC theory
    • 19.1.5. Errors

[And80]

Andersen. Molecular-Dynamics Simulations At Constant Pressure And/Or Temperature. J. Chem. Phys, 72(4):2384-2393, 1980.

[And83]

Hans C. Andersen. Rattle: a “velocity” version of the shake algorithm for molecular dynamics calculations. J. Comp. Phys., 51:24–34, 1983.

[AH05]

A. Arnold and C. Holm. MMM1D: A method for calculating electrostatic interactions in 1D periodic geometries. J. Chem. Phys., 123(12):144103, 2005.

[AH02a]

Axel Arnold and Christian Holm. A novel method for calculating electrostatic interactions in 2D periodic slab geometries. Chem. Phys. Lett., 354:324–330, 2002.

[AH02b]

Axel Arnold and Christian Holm. MMM2D: a fast and accurate summation methodlimnb for electrostatic interactions in 2d slab geometries. Comput. Phys. Commun., 148(3):327–348, 2002. arXiv:cond-mat/0202265.

[ALK+ed]

Axel Arnold, Olaf Lenz, Stefan Kesselheim, Rudolf Weeber, Florian Fahrenberger, Dominic Roehm, Peter Kosovan, and Christian Holm. ESPResSo 3.1 – molecular dynamics software for coarse-grained models. In Michael Griebel, Christian Rieger, and Marc Alexander Schweitzer, editors, Proceedings of the Sixth International Workshop on Meshfree Methods for Partial Differential Equations, Lecture Notes in Computational Science and Engineering. Springer, Berlin, Germany, submitted.

[AdeJoannisH02]

Axel Arnold, Jason de Joannis, and Christian Holm. Electrostatics in Periodic Slab Geometries I+II. J. Chem. Phys., 117:2496–2512, 2002. arXiv:cond-mat/0202399 and cond-mat/0202400.

[BAC09]

V. Ballenegger, A. Arnold, and J. J. Cerda. Simulations of non-neutral slab systems with long-range electrostatic interactions in two-dimensional periodic boundary conditions. J. Chem. Phys., 131(9):094107, 2009. URL: http://link.aip.org/link/?JCP/131/094107/1, doi:10.1063/1.3216473.

[BP07]

RE Belardinelli and VD Pereyra. Fast algorithm to calculate density of states. Physical Review E, 75(4):046701, 2007.

[Ber15]

Tristan Bereau. Multi-timestep integrator for the modified andersen barostat. Physics Procedia, 68:7–15, 2015.

[Bro04]

A. Brodka. Ewald summation method with electrostatic layer correction for interactions of point dipoles in slab geometry. Chem. Phys. Lett., 400:62–67, 2004.

[BN95]

David Brown and Sylvie Neyertz. A general pressure tensor calculation for molecular dynamics simulations. Molecular Physics, 84(3):577–595, 1995.

[CerdaBLH08]

Juan J. Cerdà, V. Ballenegger, O. Lenz, and Ch. Holm. P3M algorithm for dipolar interactions. Journal of Chemical Physics, 129:234104, 2008. doi:10.1063/1.3000389.

[CBLCHolm08]

Juan J. Cerda, V. Ballenegger, O. Lenz, and C.Holm. P3M algorithm for dipolar interactions. J. Chem. Phys., 129:234104, 2008. arXiv:cond-mat/????

[CimrakGJanvcigova14]

I. Cimrák, M. Gusenbauer, and I. Jančigová. An ESPResSo implementation of elastic objects immersed in a fluid. Computer Physics Communications, 185(3):900 – 907, 2014.

[CimrakGS12]

I. Cimrák, M. Gusenbauer, and T. Schrefl. Modelling and simulation of processes in microfluidic devices for biomedical applications. Computers & Mathematics with Applications, 64(3):278–288, 2012.

[CF10]

Lindsay M Crowl and Aaron L Fogelson. Computational model of whole blood exhibiting lateral platelet motion induced by red blood cells. Int. J. Numer. Meth. Biomed. Engng., 26(3-4):471–487, 2010.

[dGMM+16]

Joost de Graaf, Henri Menke, Arnold J.T.M. Mathijssen, Marc Fabritius, Christian Holm, and Tyler N. Shendruk. Lattice-boltzmann hydrodynamics of anisotropic active matter. J. Chem. Phys., 144:134106, 2016. doi:10.1063/1.4944962.

[Des00]

M. Deserno. Counterion condensation for rigid linear polyelectrolytes. PhD thesis, Universität Mainz, 2000.

[DH98a]

M. Deserno and C. Holm. How to mesh up Ewald sums. i. J. Chem. Phys., 109:7678, 1998.

[DH98b]

M. Deserno and C. Holm. How to mesh up Ewald sums. ii. J. Chem. Phys., 109:7694, 1998.

[DHL00]

M. Deserno, C. Holm, and H. J. Limbach. Molecular Dynamics on Parallel Computers, chapter How to mesh up Ewald sums. World Scientific, Singapore, 2000.

[DE86]

M Doi and S F Edwards. The theory of polymer dynamics. Oxford Science Publications, 1986.

[DHCA07]

M.M. Dupin, I. Halliday, C.M. Care, and L. Alboul. Modeling the flow of dense suspensions of deformable particles in three dimensions. Phys Rev E Stat Nonlin Soft Matter Phys., 75:066707, 2007.

[DunwegL08]

Burkhard Dünweg and Anthony J.C. Ladd. Lattice Boltzmann Simulations of Soft Matter Systems. In Lattice Boltzmann Simulations of Soft Matter Systems, Advances in Polymer Science, pages 1–78. Springer Berlin Heidelberg, 2008. URL: http://dx.doi.org/10.1007/12_2008_4, doi:10.1007/12_2008_4.

[EPB+95]

Ulrich Essmann, Lalith Perera, Max L Berkowitz, Tom Darden, Hsing Lee, and Lee G Pedersen. A smooth particle mesh ewald method. The Journal of chemical physics, 103(19):8577–8593, 1995.

[Ewa21]

P.P. Ewald. Die berechnung optischer und elektrostatischer gitterpotentiale. Ann. Phys., 64:253–287, 1921.

[FS02]

Daan Frenkel and Berend Smit. Understanding Molecular Simulation. Academic Press, San Diego, second edition, 2002.

[GK86]

Gary S. Grest and Kurt Kremer. Molecular dynamics simulation for polymers in the presence of a heat bath. Phys. Rev. A, 33(5):3628–31, 1986.

[HTBL+08]

C Heath Turner, John K Brennan, Martin Lisal, William R Smith, J Karl Johnson, and Keith E Gubbins. Simulation of chemical reaction equilibria by the reaction ensemble monte carlo method: a review. Molecular Simulation, 34(2):119–146, 2008.

[HHHS10]

Owen A. Hickey, Christian Holm, James L. Harden, and Gary W. Slater. Implicit Method for Simulating Electrohydrodynamics of Polyelectrolytes. Phys. Rev. Lett., SEP 29 2010. doi:{10.1103/PhysRevLett.105.148301}.

[HE88]

R. W. Hockney and J. W. Eastwood. Computer Simulation Using Particles. IOP, 1988.

[HDS96]

W. Humphrey, A. Dalke, and K. Schulten. VMD: visual molecular dynamics. J. Mol. Graphics, 14:33–38, 1996.

[KSH11]

Stefan Kesselheim, Marcello Sega, and Christian Holm. Applying to dna translocation: effect of dielectric boundaries. Computer Physics Communications, 182(1):33 – 35, 2011. <ce:title>Computer Physics Communications Special Edition for Conference on Computational Physics Kaohsiung, Taiwan, Dec 15-19, 2009</ce:title>. URL: http://www.sciencedirect.com/science/article/pii/S001046551000305X, doi:10.1016/j.cpc.2010.08.014.

[KP92]

Jiri Kolafa and John W. Perram. Cutoff errors in the ewald summation formulae for point charge systems. Molecular Simulation, 9(5):351–368, 1992.

[Kruger11]

Timm Krüger. Computer simulation study of collective phenomena in dense suspensions of red blood cells under shear. PhD thesis, Universität Bochum, 2011.

[LHS17a]

Jonas Landsgesell, Christian Holm, and Jens Smiatek. Simulation of weak polyelectrolytes: a comparison between the constant ph and the reaction ensemble method. The European Physical Journal Special Topics, 2017. doi:10.1140/epjst/e2016-60324-3.

[LHS17b]

Jonas Landsgesell, Christian Holm, and Jens Smiatek. Wang-landau reaction ensemble method: simulation of weak polyelectrolytes and general acid-base reactions. Journal of Chemical Theory and Computation, 13(2):852–862, 2017. doi:10.1021/acs.jctc.6b00791.

[MF01]

D Magatti and F Ferri. Fast multi-tau real-time software correlator for dynamic light scattering. Applied Optics, 40(24):4011–4021, AUG 20 2001. doi:{10.1364/AO.40.004011}.

[Man05]

Bernward A. Mann. The Swelling Behaviour of Polyelectrolyte Networks. PhD thesis, Johannes Gutenberg-University, Mainz, Germany, December 2005.

[Pes03]

Charles S Peskin. The immersed boundary method. Acta Numerica, 11:479–517, 2003.

[PLD+13]

A.Yu. Polyakov, T.V. Lyutyy, S. Denisov, V.V. Reva, and P. Hänggi. Large-scale ferrofluid simulations on graphics processing units. Computer Physics Communications, 184:1483–1489, 2013.

[RSVL10]

Jorge Ramirez, Sathish K. Sukumaran, Bart Vorselaars, and Alexei E. Likhtman. Efficient on the fly calculation of time correlation functions in computer simulations. J. Chem. Phys., 133(15):154103, OCT 21 2010. doi:{10.1063/1.3491098}.

[RR92]

Christopher E Reed and Wayne F Reed. Monte carlo study of titration of linear polyelectrolytes. J. Chem. Phys., 96(2):1609–1620, 1992.

[RA12]

D. Roehm and A. Arnold. Lattice boltzmann simulations on GPUs with ESPResSo. Eur. Phys. J. ST, 210:73–88, 2012.

[RC03]

Michael Rubinstein and Ralph H. Colby. Polymer Physics. Oxford University Press, Oxford, UK, 2003.

[SchatzelDS88]

K. Schätzel, M. Drewel, and S Stimac. Photon-correlation measurements at large lag times - improving statistical accuracy. Journal of Modern Optics, 35(4):711–718, APR 1988. doi:{10.1080/09500348814550731}.

[Smi81]

E. R. Smith. Electrostatic energy in ionic crystals. Proc. R. Soc. Lond. A, 375:475–505, 1981.

[ST94]

WR Smith and B Triska. The reaction ensemble method for the computer simulation of chemical and phase equilibria. i. theory and basic examples. The Journal of chemical physics, 100(4):3019–3027, 1994.

[SDunwegK01]

T. Soddemann, B. Dünweg, and K. Kremer. A generic computer model for amphiphilic systems. Eur. Phys. J. E, 6:409, 2001.

[Str99]

R. Strebel. Pieces of software for the Coulombic $m$ body problem. PhD thesis, ETH Zürich, 1999. URL: http://e-collection.ethbib.ethz.ch/show?type=diss\&nr=13504.

[Suc01]

S. Succi. The lattice Boltzmann equation for fluid dynamics and beyond. Oxford University Press, USA, 2001.

[TPM09]

A. P. Thompson, S. J. Plimpton, and W. Mattson. General formulation of pressure and stress tensor for arbitrary many-body interaction potentials under periodic boundary conditions. Journal of Chemical Physics, 131:154107, 2009.

[TSuzenS+10]

C. Tyagi, M. Süzen, M. Sega, M. Barbosa, S. Kantorovich, and C. Holm. An iterative, fast, linear-scaling method for computing induced charges on arbitrary dielectric boundaries. J. Chem. Phys., 132:154112, 2010. doi:10.1063/1.3376011.

[TAH07]

S. Tyagi, A. Arnold, and C. Holm. ICMMM2D: an accurate method to include planar dielectric interfaces via image charge summation. J. Chem. Phys., 127:154723, 2007.

[TAH08]

Sandeep Tyagi, Axel Arnold, and Christian Holm. Electrostatic layer correction with image charges: a linear scaling method to treat slab 2d + h systems with dielectric interfaces. J. Chem. Phys., 129(20):204102, 2008.

[WP02]

Alexander J. Wagner and Ignacio Pagonabarraga. Lees–edwards boundary conditions for lattice boltzmann. Journal of statistical physics, 107:521–537, 2002. doi:10.1023/A:1014595628808.

[WL01]

Fugao Wang and David P Landau. Efficient, multiple-range random walk algorithm to calculate the density of states. Physical review letters, 86(10):2050, 2001.