Merge branch 'master' of github.com:espressomd/espresso into bootstrap

doc/tutorials/01-lennard_jones/01-lennard_jones.tex

@@ -121,7 +121,7 @@ \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 analyse the 
+physical system, how to run a simulation, and how to load, save and analyze the 
 data.
 
 The more advanced features and algorithms available in the \es{} package will 
@@ -160,14 +160,14 @@ \section{Tutorial Outline}
 After a brief introduction to \es{} in Section \ref{sec:espresso}, we provide 
 you with a short tutorial to the Tcl programming language which is used to 
 control simulations using \es{} in Section \ref{sec:tcl}. In Section \ref{sec:ljliquid}, we will 
-introduce you to the problem system studied in this tutorial and familiarise you with the necessary 
+introduce you to the problem system studied in this tutorial and familiarize you with the necessary 
 background knowledge. Please note, however, that it is beyond the scope of this 
 tutorial to give a complete overview of the the area. We give a few 
 references that can give you more detailed information regarding MD.
 
-%In Section \ref{sec:vmd}, we demonstrate how to visualise simulation data with 
+%In Section \ref{sec:vmd}, we demonstrate how to visualize simulation data with 
 %\emph{VMD\footnote{\texttt{http://www.ks.uiuc.edu/Research/vmd/}}} and how to 
-%analyse it with the aid of the functions provided by \es{}. At the end of this tutorial,
+%analyze it with the aid of the functions provided by \es{}. At the end of this tutorial,
 %you will be able to compare your results to the ones obtained in the original 
 %investigations on the presented topic.
 
@@ -190,16 +190,16 @@ \section{First steps}\label{sec:espresso}
   scripts by using Tcl scripting language\footnote{In short, a \emph{scripting language
   } allows the user to write instructions that are carried out by an interpreter
   without prior compiling. This enables the user to use \es{} for vastly
-  different applications without the need of different specialised executable files.}.
+  different applications without the need of different specialized executable files.}.
   In a given \es{} script, some commands
   are interpreted by the scripting language (Tcl), while others by the core
   \es{} program written in C. However, all \es{} commands and directives in the
   script are
-  transparent to the user, regardless of ifs implementation either on the C- or Tcl-level.
+  transparent to the user, regardless of its implementation either on the C- or Tcl-level.
 
 \emph{Note: This tutorial assumes that you already have a working \es{}
 installation on your system. If this is not the case, please go to
-\texttt{http://www.espresso.mpg.de/} for information on how to obtain and
+\texttt{http://espressomd.org/} for information on how to obtain and
 install \es{}.}
 
 \vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth} 
@@ -236,7 +236,7 @@ \section{First steps}\label{sec:espresso}
 \end{task}
 \end{minipage}}\vspace{1cm}
 
-On the screenshot you can see several incompiled features, i.e.~the fake multiprocessing interface, the fast fourier transformation, the Lennard Jones and electrostatic potential. All features can be found explained in the \es{} User Guide.
+On the screenshot you can see several compiled in features, i.e.~the fake multiprocessing interface, the fast Fourier transform, the Lennard-Jones and electrostatic potential. All features can be found explained in the \es{} User Guide.
 
 %%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%
@@ -249,7 +249,7 @@ \section{First steps}\label{sec:espresso}
    Aside from writing any valid Tcl code, the user can write any valid \es{}
    command on the \es{} CLI. Here we will review the 
    basic Tcl tutorial \cite{tcl_tut_url} in Espresso CLI. Now type 
-   \texttt{Espresso}. Once in the CLI, you can familiarise yourself with the 
+   \texttt{Espresso}. Once in the CLI, you can familiarize yourself with the 
    basics of TCL. 
 
     \subsection{Assignments and evaluation}
@@ -390,7 +390,7 @@ \subsection{Comparisons and looping}
 }
 
 \noindent One can access all the elements by using \lstinline|foreach| looping 
-consruct as well
+construct as well
 
 {\small\vspace{0,2cm}
 \begin{lstlisting}[numbers=none]
@@ -579,7 +579,7 @@ \subsection{Lennard-Jones Potential}
 
 \subsection{Assigning Particle Properties}\label{sec:partprop}
 The power of the \es{} package lies in the flexible manipulation of particle
-data. Particles can be manipulated by the \lstinline|part| command which recognises the unique particle 
+data. Particles can be manipulated by the \lstinline|part| command which recognizes the unique particle 
    id. Each particle must be a member of a group which is called \emph{type}. 
 Interactions among those types can be defined through \emph{type} number 
    with \lstinline|inter| command.
@@ -648,7 +648,7 @@ \subsection{Generating Data: Lennard-Jones Liquid Simulation }
   % tutorial should explain all steps and contain important results and graphs.}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-We include necessary functions with  \lstinline|source lj_functions.tcl| by using the external lj\_functions.tcl file and print out the incompiled features of \es
+We include necessary functions with  \lstinline|source lj_functions.tcl| by using the external lj\_functions.tcl file and print out the in compiled features of \es
 {\small\vspace{0,2cm}
 \begin{lstlisting}{bsp_code}
 source lj_functions.tcl
@@ -865,7 +865,7 @@ \subsubsection{System Setup}
   puts "sampling "
 setmd time_step $tstep
 
-# files to save simulation datas
+# files to save simulation data
 set en [open "data/energy.dat" "w"]
 set blockfile [open "data/sim_info.dat" "w"]
 
@@ -1063,7 +1063,7 @@ \subsection{Simple Error Analysis on Time Series Data with \texttt{uwerr}}
   Here to obtain, for example, the error for the total energy we submit as a first argument for 
   \lstinline|uwerr| the array of all measured values of total energy   \verb"$atotal", and then the total
   number of samples   \verb"$sampling_iterations". 1 as the third argument means that we ran only
-  one full measument (complete simulation). In general, the mean value could be also obtained
+  one full measurement (complete simulation). In general, the mean value could be also obtained
   from several simulations, providing  \verb"$atotal" then as a matrix, not as an array, the total
   number of samples for every simulation should be the same and the third argument for \lstinline|uwerr|
   would be the number of simulations. \lstinline|uwerr| returns a string, the first value of which is 
@@ -1099,7 +1099,7 @@ \subsection{Simple Error Analysis on Time Series Data with \texttt{uwerr}}
 %\vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth} 
 %     \begin{task}
 
-%      Inspect what \texttt{analyse energy} command returns. Make the similar 
+%      Inspect what \texttt{analyze energy} command returns. Make the similar 
 %      error analysis for kinetic  temperature, kinetic energy and potential 
 %      energy, in the main script.
 %     \end{task}
@@ -1110,17 +1110,105 @@ \subsection{Simple Error Analysis on Time Series Data with \texttt{uwerr}}
 \vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth} 
      \begin{task}
 
-     Inspect what \texttt{analyse pressure total} command returns. Make a 
+     Inspect what \texttt{analyze pressure total} command returns. Make a 
      similar error analysis for total pressure.
      \end{task}
 
 \end{minipage}}\vspace{1cm}
 
-\noindent {\bf Hint:} \texttt{analyse pressure} (without \texttt{total}) returns the pressure and
+\noindent {\bf Hint:} \texttt{analyze pressure} (without \texttt{total}) returns the pressure and
 corresponding contributions to it.
 \newpage
+
+\subsection{Online analysis of correlations}
+\label{subsection:online_analysis}
+\es{} can do online analysis of observables and correlations. This means that part of the analysis
+is run on the fly during the simulation without first writing the configuration data to disk and re-reading it later on for analysis.
+ To illustrate this the script calculates the mean square displacement of the particles online. 
+The mean square displacement (MSD) is the average squared distance that a particle traveled during a given time.
+It is defined by
+
+$$
+\text{MSD}(t) = \langle \Delta r(t) ^{2} \rangle = \frac {1} {N} \sum_{i=0}^{N} | r_{i}(t)-r_{i}(0) | ^{2}
+$$
+
+See section \ref{subsection:other_useful_scripts} for an offline version of the MSD calculation. The basic idea is to have a set of observables
+that can be evaluated and correlated as needed. In the script the correlation for the mean square displacement of the particle is setup by
+
+{\small\vspace{0,2cm}
+\begin{lstlisting}[numbers=none]
+# Setup observable for the positions
+set obs_pos [observable new particle_positions all]
+# Setup msd as position correlation
+set msd [correlation new obs1 $obs_pos corr_operation square_distance_componentwise dt $tstep tau_max [expr 50.*$tstep]]
+\end{lstlisting}\vspace{0,2cm}
+} 
+
+First a new observable is created via the \texttt{observable new} command, which is then used to create a new correlation. Here we use the predefined observable \texttt{particle\_positions}. There is a large set of predefined obsevables which are listed in the users guide. Observables can also defined as TCL functions provided by the user, please refer to the documentation.
+
+The \texttt{correlation} command can create arbitraty time-correlations between observables. In this case
+we want to calculate the position auto correlation. Autocorrelations are created by only passing one observable to the command. The most important other parameters are the \texttt{corr\_operation}, which is the operation performed by bevor averaging, here the observable is squared componentwise. For a list of predefined operations please have a look at the documentation. The maximum timespan for which the correlation function should be sampled is set by \texttt{tau\_max}.
+
+Observables can either be updated automatically in regular intervals or explicitly by the user. In the script we update explicitly by calling
+
+{\small\vspace{0,2cm}
+\begin{lstlisting}[numbers=none]
+correlation $msd update
+\end{lstlisting}\vspace{0,2cm}
+} 
+
+Finally after the sampling phase we have to write the calculated MSD to the disk.
+Since we calculated the correlation separately for every component of every particle we first
+average over all the components to improve statistics.
+
+{\small\vspace{0,2cm}
+\begin{lstlisting}[numbers=none]
+# Get calculated MSD from correlator
+set msd_data [correlation $msd print]
+# Open file to write MSD to
+set msd_file [open "data/msd_correlator.dat" "w"]
+
+# Loop over all the times
+foreach msd_sample $msd_data {
+    # Holds the average over all the components of all the particles
+    set average 0.0
+    # Current time
+    set tau [lindex $msd_sample 0]
+    # Loop over all the components of all the particles for this time
+    for { set i 0 }  { $i < [expr 3*$n_part] } { incr i } {
+        # and sum them up
+	set average [expr $average + [lindex $msd_sample [expr $i + 2]]]
+    }
+    # Normalize
+    set average [expr $average/(3*$n_part)]
+    # Write to file
+    puts $msd_file "$tau $average"
+}
+
+close $msd_file
+\end{lstlisting}\vspace{0,2cm}
+} 
+
+
+\es{} employs an algorithm called \emph{multiple $\tau$ correlator} to calculate the correlation function
+that makes it efficient to calculate correlations for very long times (cf. \cite{frenkel02b}), possibly over the run of the complete
+simulation. The correlator is a very powerful tool that is very flexible and can do many types of calculations.
+An in-depth discussion of its features would be a tutorial in its own right and is beyond the scope of this
+one, but it might be worthwhile to read up on it and see if it can solve your problem before you implement
+something yourself. The predefined observables and correlation functions are implemented in the \es{} core and
+are typically several orders of magnitude faster than analysis that is implemented on the TCL level.
+
+\vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth} 
+     \begin{task}  
+      Inspect the code for the MSD calculation and plot the MSD from \texttt{data/msd\_correlator.dat}. 
+      Try different parameters  for the \texttt{correlator} command, such as the sample length and the number of points. 
+      What do you observe if you make the maximal tau bigger? Can you find out how to calculate the velocity autocorrelation instead?
+     \end{task}
+\end{minipage}}\vspace{1cm}
+
 \subsection{Other Useful Scripts}
-The radial distribution function (RDF) describes the distibution of particles around
+\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
 that the particle distribution is isotropic around the particles.
 
@@ -1178,7 +1266,8 @@ \subsection{Other Useful Scripts}
 
 \newpage
 
-The mean square displacement (MSD) is the average squared distance that a particle travelled during a given time.
+We can also calculate the mean square displacement (MSD) from the offline data (see section \ref{subsection:online_analysis} for an online version of the calculation).
+The mean square displacement (MSD) is the average squared distance that a particle traveled during a given time.
 
 \vspace{1cm}\framebox{\begin{minipage}{0.95\textwidth} 
      \begin{task}  
@@ -1201,14 +1290,14 @@ \subsection{Other Useful Scripts}
 \end{figure}
 
 \noindent On short time scales a particle does not collide with others
-(ballistic regime) so the distance travelled should be proportional to
+(ballistic regime) so the distance traveled should be proportional to
 the time and therefore the MSD should increase quadratically. On
 bigger time scales, a particle performs sort of a random walk due to
 many interactions with other particles. This regime is called
 diffusive; in this regime the MSD increases linearly with time. The coefficient of
 proportionality is the diffusion coefficient: $D=\frac{1}{2 d t} \langle
 \Delta r(t) \rangle^2$, where d is the dimensionality of the problem and $t$ the
-travelling time.
+traveling time.
 
 If \texttt{msd.dat} is plotted in log-log scale, then ballistic and diffusive regimes will be visible even better
 (better sampling won't harm).

doc/tutorials/01-lennard_jones/refs.bib

@@ -41,7 +41,7 @@ @ARTICLE{wolff
 }
 
 @MISC{esp_url,
-  title = {http://www.espresso.mpg.de/}
+  title = {http://espressomd.org/}
 }
 
 @MISC{tcl_tut_url,

doc/tutorials/01-lennard_jones/scripts/lj_tutorial.tcl

@@ -175,6 +175,12 @@ for { set i 0 } { $i < $equilibration_iterations } { incr i } {
    puts -nonewline "eq run $i at time=[setmd time] \r"
    # puts "temp = [expr [lindex $energies 1 1]/(1.5*[setmd n_part])]"
 }
+
+# Setup observable for the positions
+set obs_pos [observable new particle_positions all]
+# Setup msd as postition correlation
+set msd [correlation new obs1 $obs_pos corr_operation square_distance_componentwise dt $tstep tau_max [expr 50.*$tstep] tau_lin 16]
+
   puts "sampling "
 setmd time_step $tstep
 set nrep 0
@@ -205,6 +211,9 @@ for {set i 0} { $i < $sampling_iterations } { incr i} {
      lappend apotential $potential
      lappend atemperature $temperature
      lappend atotal $total
+
+     correlation $msd update
+
      puts -nonewline "integration step   $i / $sampling_iterations \r"
      # puts -nonewline "total = [expr $total/$n_part] kinetic= [expr $kinetic/$n_part] potential= [expr $potential/$n_part]  temperature = $temperature\n"
 }
@@ -230,4 +239,30 @@ close $en
   set value [lindex $error 0]
   set verror [lindex $error 1]
   puts "     Pressure : $value  $verror"
+  puts "-- Writing MSD to file"
+
+# Get calculated MSD from correlator
+set msd_data [correlation $msd print]
+# Open file to write MSD to
+set msd_file [open "data/msd_correlator.dat" "w"]
+
+# Loop over all the times
+foreach msd_sample $msd_data {
+    # Holds the average over all the components of all the particles
+    set average 0.0
+    # Current time
+    set tau [lindex $msd_sample 0]
+    # Loop over all the components of all the particles for this time
+    for { set i 0 }  { $i < [expr 3*$n_part] } { incr i } {
+        # and sum them up
+	set average [expr $average + [lindex $msd_sample [expr $i + 2]]]
+    }
+    # Normalize
+    set average [expr $average/(3*$n_part)]
+    # Write to file
+    puts $msd_file "$tau $average"
+}
+
+close $msd_file
+
 exit

doc/tutorials/01-lennard_jones/solutions/lj_tutorial.tcl

@@ -1,4 +1,4 @@
-# Copyright (C) 2010,2011,2012,2013,2014 The ESPResSo project
+# Copyright (C) 2010,2011,2012,2013,2014,2015 The ESPResSo project
 #  
 # This file is part of ESPResSo.
 #  
@@ -46,7 +46,7 @@ puts " "
 
 
 
-cellsystem domain_decomposition  -no_verlet_list
+#cellsystem domain_decomposition  -no_verlet_list
 #############################################################
 #  Parameters                                               #
 #############################################################
@@ -172,6 +172,12 @@ for { set i 0 } { $i < $equilibration_iterations } { incr i } {
    puts -nonewline "eq run $i at time=[setmd time] \r"
    # puts "temp = [expr [lindex $energies 1 1]/(1.5*[setmd n_part])]"
 }
+
+# Setup observable for the positions
+set obs_pos [observable new particle_positions all]
+# Setup msd as postition correlation
+set msd [correlation new obs1 $obs_pos corr_operation square_distance_componentwise dt $tstep tau_max [expr 50.*$tstep] tau_lin 16]
+
   puts "sampling "
 setmd time_step $tstep
 set nrep 0
@@ -201,6 +207,9 @@ for {set i 0} { $i < $sampling_iterations } { incr i} {
      lappend apotential $potential
      lappend atemperature $temperature
      lappend atotal $total
+
+     correlation $msd update
+
      puts -nonewline "integration step   $i / $sampling_iterations \r"
      # puts -nonewline "total = [expr $total/$n_part] kinetic= [expr $kinetic/$n_part] potential= [expr $potential/$n_part]  temperature = $temperature\n"
 }
@@ -226,4 +235,30 @@ close $en
   set value [lindex $error 0]
   set verror [lindex $error 1]
   puts "     Pressure : $value  $verror"
+  puts "-- Writing MSD to file"
+
+# Get calculated MSD from correlator
+set msd_data [correlation $msd print]
+# Open file to write MSD to
+set msd_file [open "data/msd_correlator.dat" "w"]
+
+# Loop over all the times
+foreach msd_sample $msd_data {
+    # Holds the average over all the components of all the particles
+    set average 0.0
+    # Current time
+    set tau [lindex $msd_sample 0]
+    # Loop over all the components of all the particles for this time
+    for { set i 0 }  { $i < [expr 3*$n_part] } { incr i } {
+        # and sum them up
+	set average [expr $average + [lindex $msd_sample [expr $i + 2]]]
+    }
+    # Normalize
+    set average [expr $average/(3*$n_part)]
+    # Write to file
+    puts $msd_file "$tau $average"
+}
+
+close $msd_file
+
 exit