libhoomd/analyzers/MSDAnalyzer.h

   1 /*
   2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
   4 the University of Michigan All rights reserved.
   5
   6 HOOMD-blue may contain modifications ("Contributions") provided, and to which
   7 copyright is held, by various Contributors who have granted The Regents of the
   8 University of Michigan the right to modify and/or distribute such Contributions.
   9
  10 You may redistribute, use, and create derivate works of HOOMD-blue, in source
  11 and binary forms, provided you abide by the following conditions:
  12
  13 * Redistributions of source code must retain the above copyright notice, this
  14 list of conditions, and the following disclaimer both in the code and
  15 prominently in any materials provided with the distribution.
  16
  17 * Redistributions in binary form must reproduce the above copyright notice, this
  18 list of conditions, and the following disclaimer in the documentation and/or
  19 other materials provided with the distribution.
  20
  21 * All publications and presentations based on HOOMD-blue, including any reports
  22 or published results obtained, in whole or in part, with HOOMD-blue, will
  23 acknowledge its use according to the terms posted at the time of submission on:
  24 http://codeblue.umich.edu/hoomd-blue/citations.html
  25
  26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 http://codeblue.umich.edu/hoomd-blue/
  28
  29 * Apart from the above required attributions, neither the name of the copyright
  30 holder nor the names of HOOMD-blue's contributors may be used to endorse or
  31 promote products derived from this software without specific prior written
  32 permission.
  33
  34 Disclaimer
  35
  36 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  37 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  38 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  39 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  40
  41 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  42 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  46 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  47 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 */
  49
  50 // Maintainer: joaander
  51
  52 /*! \file MSDAnalyzer.h
  53     \brief Declares the MSDAnalyzer class
  54 */
  55
  56 #ifndef __MSD_ANALYZER_H__
  57 #define __MSD_ANALYZER_H__
  58
  59 #ifdef NVCC
  60 #error This header cannot be compiled by nvcc
  61 #endif
  62
  63 #include <string>
  64 #include <fstream>
  65 #include <boost/shared_ptr.hpp>
  66 #include "Analyzer.h"
  67 #include "ParticleGroup.h"
  68
  69 //! Prints a log of the mean-squared displacement calculated over particles in the simulation
  70 /*! On construction, MSDAnalyzer opens the given file name for writing. The file will optionally be overwritten
  71     or appended to. If the file is appended to, the added columns are assumed to be provided in the same order
  72     as with the initial generation of the file. It also records the initial positions of all particles in the
  73     simulation. Each time analyze() is called, the mean-squared displacement is calculated and written out to the file.
  74
  75     The mean squared displacement (MSD) is calculated as:
  76     \f[ \langle |\vec{r} - \vec{r}_0|^2 \rangle \f]
  77
  78     Multiple MSD columns may be desired in a single simulation run. Rather than requiring the user to specify
  79     many analyze.msd commands each with a separate file, a single class instance is designed to be capable of outputting
  80     many columns. The particles over which the MSD is calculated for each column are specified with a ParticleGroup.
  81
  82     To allow for the continuation of msd data when a job is restarted from a file, MSDAnalyzer can assign the reference
  83     state r_0 from a given xml file.
  84
  85     \ingroup analyzers
  86 */
  87 class MSDAnalyzer : public Analyzer
  88     {
  89     public:
  90         //! Construct the msd analyzer
  91         MSDAnalyzer(boost::shared_ptr<SystemDefinition> sysdef,
  92                     std::string fname,
  93                     const std::string& header_prefix="",
  94                     bool overwrite=false);
  95
  96         //! Destructor
  97         ~MSDAnalyzer();
  98
  99         //! Write out the data for the current timestep
 100         void analyze(unsigned int timestep);
 101
 102         //! Sets the delimiter to use between fields
 103         void setDelimiter(const std::string& delimiter);
 104
 105         //! Adds a column to the analysis
 106         void addColumn(boost::shared_ptr<ParticleGroup> group, const std::string& name);
 107
 108         //! Sets r0 from an xml file
 109         void setR0(const std::string& xml_fname);
 110
 111     private:
 112         //! The delimiter to put between columns in the file
 113         std::string m_delimiter;
 114         //! The prefix written at the beginning of the header line
 115         std::string m_header_prefix;
 116         //! Flag indicating this file is being appended to
 117         bool m_appending;
 118
 119         bool m_columns_changed; //!< Set to true if the list of columns have changed
 120         std::ofstream m_file;   //!< The file we write out to
 121
 122         std::vector<Scalar> m_initial_x;    //!< initial value of the x-component listed by tag
 123         std::vector<Scalar> m_initial_y;    //!< initial value of the y-component listed by tag
 124         std::vector<Scalar> m_initial_z;    //!< initial value of the z-component listed by tag
 125
 126         //! struct for storing the particle group and name assocated with a column in the output
 127         struct column
 128             {
 129             //! default constructor
 130             column() {}
 131             //! constructs a column
 132             column(boost::shared_ptr<ParticleGroup const> group, const std::string& name) :
 133                     m_group(group), m_name(name) {}
 134
 135             boost::shared_ptr<ParticleGroup const> m_group; //!< A shared pointer to the group definition
 136             std::string m_name;                             //!< The name to print across the file header
 137             };
 138
 139         std::vector<column> m_columns;  //!< List of groups to output
 140
 141         //! Helper function to write out the header
 142         void writeHeader();
 143         //! Helper function to calculate the MSD of a single group
 144         Scalar calcMSD(boost::shared_ptr<ParticleGroup const> group, const SnapshotParticleData& snapshot);
 145         //! Helper function to write one row of output
 146         void writeRow(unsigned int timestep, const SnapshotParticleData& snapshot);
 147     };
 148
 149 //! Exports the MSDAnalyzer class to python
 150 void export_MSDAnalyzer();
 151
 152 #endif