Skip to content

Commit

Permalink
Minor changes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@pkreissl
pkreissl committed Aug 29, 2016
1 parent 137871f commit 0512c96
Showing 1 changed file with 63 additions and 39 deletions.
102 changes: 63 additions & 39 deletions doc/tutorials/python/01-lennard_jones/01-lennard_jones.tex
View file
Expand Up @@ -121,13 +121,14 @@ \section{Introduction}

In this tutorial, you will learn, how to use the \es{} package for your
research. We will cover the basics of \es, i.e., how to set up and modify a
physical system, how to run a simulation, and how to load, save and analyze the
data.
physical system, how to run a simulation, and how to load, save and analyze
the produced simulation data.

The more advanced features and algorithms available in the \es{} package are
More advanced features and algorithms available in the \es{} package are
described in additional tutorials.

\section{Background}

Today's research on Soft Condensed Matter has brought the needs for having a
flexible, extensible, reliable, and efficient (parallel) molecular simulation
package. For this reason \es{} (Extensible Simulation Package for Research on
Expand All @@ -139,7 +140,8 @@ \section{Background}
for example. \es{} has been nominated for the Heinz-Billing-Preis for
Scientific Computing in 2003 \cite{arnold2003ees}.

\subsection{Lennard-Jones Potential}
\subsection{The Lennard-Jones Potential}

A pair of neutral atoms or molecules is subject to two distinct forces in the limit
of large separation and small separation: an attractive force at long ranges (van der
Waals force, or dispersion force) and a repulsive force at short ranges (the result
Expand All @@ -161,18 +163,18 @@ \subsection{Lennard-Jones Potential}
of the L-J formula is more convenient due to the ease and efficiency of computing
$r^{12}$ as the square of $r^6$.

\subsection{Units}
Novice users must understand that Espresso has no fixed unit system. The unit
system is set by the user. Conventionally, reduced units are employed, in other
words LJ units.
\footnote{If we have charges there is additionally a concept of Bjerrum length, consult Espresso original paper for more details.}
\subsection{Units}

Novice users must understand that Espresso has no fixed unit system. The unit
system is set by the user. Conventionally, reduced units are employed, in other
words LJ units.
\footnote{If we have charges there is additionally a concept of Bjerrum length, consult Espresso original paper for more details.}

\section{First Steps}\label{sec:espresso}

What is \es{}? It is not a coffee, indeed. It is an extensible, efficient
Molecular Dynamics package specially powerful on simulating charged systems.
In depth information about the package can be found in the relevant sources
\cite{esp_url,arnold2003ees,limbach2006ees,arnold13a}.
What is \es{}? It is not a coffee, indeed. It is an extensible, efficient
Molecular Dynamics package specially powerful on simulating charged systems.
In depth information about the package can be found in the relevant sources\cite{esp_url,arnold2003ees,limbach2006ees,arnold13a}.

\es consists of two components.
The simulation engine is written in C and C++ for the sake
Expand All @@ -186,31 +188,40 @@ \section{First Steps}\label{sec:espresso}
data, storing the data about particles, communication between
different processors or cells of the cell-system.

The scripting interface (Python) is used to setup the system (particles, boundary conditions, interactions, \dots), control the simulation, run analysis, and store and load results.
The user has at hand the full reliability and functionality of the scripting language. For instance, it is possible to use the SciPy package for analysis and PyPlot for plotting.
The scripting interface (Python) is used to setup the system (particles, boundary conditions,
interactions, \dots), control the simulation, run analysis, and store and load results.
The user has at hand the full reliability and functionality of the scripting language.
For instance, it is possible to use the SciPy package for analysis and PyPlot for plotting.
With a certain overhead in efficiency, it can also be
used to reject/accept new configurations in combined MD/MC schemes. In
principle, any parameter which is accessible from the scripting level can be
changed at any moment of runtime. In this way methods like
changed at any moment of runtime. In this way methods like
thermodynamic integration become readily accessible.

\emph{Note: This tutorial assumes that you already have a working \es{}
installation on your system. If this is not the case, please consult the first chapters of the user's guide for installation instructions.}
installation on your system. If this is not the case, please consult the first
chapters of the user's guide for installation instructions.}

\vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth}
\begin{task}

Using the pypresso script in the build directory, python simulation scripts can be run conveniently:

\vspace{0,2cm}
\noindent\texttt{./pypresso simulation.py}

\vspace{1cm}\framebox{
\begin{minipage}{0.95\textwidth}
\begin{task}
You can check the features, that are compiled in the \es{} core by
issueing \texttt{print(code\_info.features())} after having imported the
\texttt{code\_info} Module:
\end{task}
\end{minipage}}\vspace{1cm}
\end{minipage}
}\vspace{1cm}

\begin{lstlisting}
from espressomd import code_info
print(code_info.features())
\end{lstlisting}


from espressomd import code_info
print(code_info.features())
\end{lstlisting}


\section{Overview over a Simulation Script}
Expand All @@ -224,6 +235,7 @@ \section{Overview over a Simulation Script}
\item Integration loop (propagate the system in time and record measurements)
\end{itemize}
In the following sections, it will be shown, how these steps can be taken. Once the basics are covered, we apply them to the simulation of the Lennard-Jones liquid.
Note, that only the core elements of the Lennared-Jones simulation script will be covered in this document. The full script can be found in the under \verb+scripts/lj_tutorial.py+ in the Lennard-Jones tutorial directory.


\subsection{System Setup}
Expand All @@ -248,23 +260,23 @@ \subsection{Chosing the thermodynamic ensemble, thermostat}
Simulations can be carried out in different thermodynamic ensembles such as NVE (particle
Number, Velocity, Energy) or NVT (particle Number, Velocity, Temperature)
as well as NPT-isotropic (particle Number, Pressure, Temperature).
The ensemble is maintained by a thermostat.
In this tutorial, the NVE-ensemble will be maintained by means of the Langevin thermostat.
The ensemble is maintained by a thermostat. In this tutorial we use the Langevin thermostat.

In \es{}, the thermostat is set as follows:
{\small\vspace{0,2cm}
\begin{lstlisting}
system.thermostat.turn_off()
system.thermostat.set_langevin(kT=1.0, gamma=0.5)
\end{lstlisting}}\vspace{0,2cm}
\noindent This results in an NVE ensemble.
\noindent Use a Langevin thermostat (NVT ensemble) with temperature set to 1.0 and damping coefficient to 0.5. Alternatively, the thermostat can be turned off using
{\small\vspace{0,2cm}
\begin{lstlisting}
system.thermostat.set_langevin(kT=1.0, gamma=0.5)
system.thermostat.turn_off()
\end{lstlisting}}\vspace{0,2cm}
\noindent Use a Langevin thermostat (NVT ensemble) with temperature set to 1.0 and damping coefficient to 0.5.
\noindent This results in an NVE ensemble.


\subsection{Placing and Accessing Particles}

Particles in the simulation can be accessed via the \texttt{part}-property of the System class. Individual particles are referred to by an integer id, e.g., \texttt{system.part[0]}. It is also possible to use common python iterators and slicing operations to access several particles at once.
\begin{lstlisting}
# access position of single particle
Expand All @@ -278,7 +290,7 @@ \subsection{Placing and Accessing Particles}
#Obtain all particle positions
cur_pos = system.part[:].pos
\end{lstlisting}
Particles can be grouped into several types, so that, e.g., a binary fluid can be simulated. Particle types are identified by integer ids, which are set via the particles' \texttt{type} attribute. If no type is specified, 0 is implied.
Particles can be grouped into several types, so that, e.g., a binary fluid can be simulated. Particle types are identified by integer ids, which are set via the particles' \texttt{type} attribute.

Particles are added to the simulation as follows
\begin{lstlisting}
Expand Down Expand Up @@ -309,7 +321,9 @@ \subsection{Setting up Non-Bonded Interactions}
\end{lstlisting}
}\vspace{0,2cm}


\subsection{Warmup}

In many cases, including this tutorial, particles are initially placed randomly in the simulation box. It is therefore possible that particles overlap, resulting in a huge repulsive force between them. In this case, integrating the equations of motion would not be numerically stable. Hence, it is necessary to remove this overlap.
This is done by limiting the maximum force between two particles, integrating the equations of motion, and increasing the force limit step by step.
This is done as follows
Expand All @@ -331,13 +345,16 @@ \subsection{Warmup}
\end{lstlisting}
In this code fragment, you can also see, how the analysis routines can be used to obtain information about the simulation system, and how to integrate the equation of motion.


\section{Putting It All Together: Lennard-Jones Liquid Simulation}

After we have briefly explained the use of \es{}, we now come to the
Lennard-Jones Liquid Simulation. Before we explain the script step by step, run the
\texttt{lj\_tutorial.py} with \texttt{pypresso} to get all generated files.


\subsection{Initialization}

First, we include necessary modules with \lstinline|import|.
{\small\vspace{0,2cm}
\begin{lstlisting}
Expand Down Expand Up @@ -419,7 +436,9 @@ \subsubsection{System Setup}
system.thermostat.set_langevin(kT=temperature, gamma=1.0)
\end{lstlisting}


\subsection{Particles}

\begin{lstlisting}
# Particle setup
#############################################################
Expand Down Expand Up @@ -463,7 +482,9 @@ \subsection{Particles}
\end{center}
\end{figure}


\subsection{Warmup}

After we have set the necessary environment we must warmup our system before we run the simulation. We set particles at random positions, so some particles can overlap. In this situation \es will crash with an error:
particle out of range. To remove the overlap between particles, we cap forces by setting the Lennard-Jones force constant below a certain distance.
This is done using the \lstinline|set_force_cap| command. We do the procedure \verb"warm_n_times" times
Expand Down Expand Up @@ -515,10 +536,10 @@ \subsection{Warmup}
\end{lstlisting}}\vspace{0,2cm}

\subsection{Integrating the Equations of Motion, Taking Measurements}
\noindent After we have set the necessary environment and warmed up our system, we can now start with the actual
simulation. To analyze our data after the simulation has completed, we open some files to write the data to.
\noindent At this point, we have set the necessary environment and warmed up our system. As a last
step before starting the actual simulation, we now open the files which we want to output data to
during the simulation. Then the simulation is started.

{\small\vspace{0,2cm}
\begin{lstlisting}
print("\nSampling\n")
system.time_step = time_step
Expand Down Expand Up @@ -553,13 +574,11 @@ \subsection{Integrating the Equations of Motion, Taking Measurements}
en_fp.write("%i\t%1.5e\t%1.5e\t%1.5e\t%1.5e\t%1.5e\n" % (i, pressure['total'], energies['total'], energies['ideal'], energies['total'] - energies['ideal'], kinetic_temperature))
\end{lstlisting}}\vspace{0,2cm}


In the energy.dat file we print out the values for pressure, kinetic
and potential energies, temperature obtained with the analysis submodule
\lstinline|system.analysis.energy()|. See the code in the snippet above, which
contains the main sampling loop of the script.


\noindent \texttt{kinetic temperature} here refers to the measured temperature
obtained from kinetic energy and the number of degrees of freedom in the system. It
should fluctuate around the preset temperature of the thermostat.
Expand Down Expand Up @@ -590,7 +609,7 @@ \subsection{Simple Error Estimation on Time Series Data}
\emph{uncorrelated} samples:
\begin{align}
\sigma &= \langle x^2 - \langle x\rangle^2 \rangle \\
SE &= \sqrt{\frac{sigma}{N}}
SE &= \sqrt{\frac{\sigma}{N}}
\label{eq:variance}
\end{align}

Expand All @@ -612,10 +631,11 @@ \subsection{Simple Error Estimation on Time Series Data}
en_fp.write("#mean_energy energy_error mean_pressure pressure_error\n#%1.5e %1.5e %1.5e %1.5e" % \
\end{lstlisting}


\newpage


\subsection{Online Analysis of Correlations}

\label{subsection:online_analysis}
% TODO
% Once the correlator found its way into the python interface this section has to be
Expand All @@ -624,7 +644,9 @@ \subsection{Online Analysis of Correlations}
This section will be updated once the correlator functionality is available in the
python interface.


\subsection{Other Useful Scripts}

\label{subsection:other_useful_scripts}
The radial distribution function (rdf) describes the distribution of particles around
the center of a fixed particle, as a function of the particle-particle distance. This of course assumes
Expand Down Expand Up @@ -673,7 +695,9 @@ \subsection{Other Useful Scripts}
\end{center}
\end{figure}


\section{Binary Lennard-Jones Liquid}

In \es{} it is possible to simulate particles of various sizes, meaning different
values of the Lennard-Jones paramter $\sigma$. For this purpose there are different mixing
rules that define how particles of different size and different ``affinity'', Lennard-Jones $\epsilon$ interact. The most commonly used mixing rules are the
Expand Down

0 comments on commit 0512c96

Please sign in to comment.