src/gromacs/trajectoryanalysis/modules/distance.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013, by the GROMACS development team, led by
   5  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   6  * others, as listed in the AUTHORS file in the top-level source
   7  * directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \internal \file
  36  * \brief
  37  * Implements gmx::analysismodules::Distance.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \ingroup module_trajectoryanalysis
  41  */
  42 #include "distance.h"
  43
  44 #include "gromacs/legacyheaders/pbc.h"
  45 #include "gromacs/legacyheaders/vec.h"
  46
  47 #include "gromacs/analysisdata/analysisdata.h"
  48 #include "gromacs/analysisdata/modules/plot.h"
  49 #include "gromacs/options/basicoptions.h"
  50 #include "gromacs/options/filenameoption.h"
  51 #include "gromacs/options/options.h"
  52 #include "gromacs/selection/selection.h"
  53 #include "gromacs/selection/selectionoption.h"
  54 #include "gromacs/trajectoryanalysis/analysissettings.h"
  55 #include "gromacs/utility/exceptions.h"
  56 #include "gromacs/utility/stringutil.h"
  57
  58 namespace gmx
  59 {
  60
  61 namespace analysismodules
  62 {
  63
  64 const char Distance::name[]             = "distance";
  65 const char Distance::shortDescription[] =
  66     "Calculate distances between pairs of positions";
  67
  68 Distance::Distance()
  69     : TrajectoryAnalysisModule(name, shortDescription),
  70       meanLength_(0.1), lengthDev_(1.0), binWidth_(0.001)
  71 {
  72     summaryStatsModule_.reset(new AnalysisDataAverageModule());
  73     summaryStatsModule_->setAverageDataSets(true);
  74     distances_.addModule(summaryStatsModule_);
  75     allStatsModule_.reset(new AnalysisDataAverageModule());
  76     distances_.addModule(allStatsModule_);
  77     averageModule_.reset(new AnalysisDataFrameAverageModule());
  78     distances_.addModule(averageModule_);
  79     histogramModule_.reset(new AnalysisDataSimpleHistogramModule());
  80     distances_.addModule(histogramModule_);
  81
  82     registerAnalysisDataset(&distances_, "dist");
  83     registerAnalysisDataset(&xyz_, "xyz");
  84     registerBasicDataset(summaryStatsModule_.get(), "stats");
  85     registerBasicDataset(allStatsModule_.get(), "allstats");
  86     registerBasicDataset(averageModule_.get(), "average");
  87     registerBasicDataset(&histogramModule_->averager(), "histogram");
  88 }
  89
  90
  91 Distance::~Distance()
  92 {
  93 }
  94
  95
  96 void
  97 Distance::initOptions(Options *options, TrajectoryAnalysisSettings * /*settings*/)
  98 {
  99     static const char *const desc[] = {
 100         "[TT]gmx distance[tt] calculates distances between pairs of positions",
 101         "as a function of time. Each selection specifies an independent set",
 102         "of distances to calculate. Each selection should consist of pairs",
 103         "of positions, and the distances are computed between positions 1-2,",
 104         "3-4, etc.[PAR]",
 105         "[TT]-oav[tt] writes the average distance as a function of time for",
 106         "each selection.",
 107         "[TT]-oall[tt] writes all the individual distances.",
 108         "[TT]-oxyz[tt] does the same, but the x, y, and z components of the",
 109         "distance are written instead of the norm.",
 110         "[TT]-oh[tt] writes a histogram of the distances for each selection.",
 111         "The location of the histogram is set with [TT]-len[tt] and",
 112         "[TT]-tol[tt]. Bin width is set with [TT]-binw[tt].",
 113         "[TT]-oallstat[tt] writes out the average and standard deviation for",
 114         "each individual distance, calculated over the frames."
 115     };
 116
 117     options->setDescription(concatenateStrings(desc));
 118
 119     options->addOption(FileNameOption("oav").filetype(eftPlot).outputFile()
 120                            .store(&fnAverage_).defaultBasename("distave")
 121                            .description("Average distances as function of time"));
 122     options->addOption(FileNameOption("oall").filetype(eftPlot).outputFile()
 123                            .store(&fnAll_).defaultBasename("dist")
 124                            .description("All distances as function of time"));
 125     options->addOption(FileNameOption("oxyz").filetype(eftPlot).outputFile()
 126                            .store(&fnXYZ_).defaultBasename("distxyz")
 127                            .description("Distance components as function of time"));
 128     options->addOption(FileNameOption("oh").filetype(eftPlot).outputFile()
 129                            .store(&fnHistogram_).defaultBasename("disthist")
 130                            .description("Histogram of the distances"));
 131     options->addOption(FileNameOption("oallstat").filetype(eftPlot).outputFile()
 132                            .store(&fnAllStats_).defaultBasename("diststat")
 133                            .description("Statistics for individual distances"));
 134     options->addOption(SelectionOption("select").storeVector(&sel_)
 135                            .required().dynamicMask().multiValue()
 136                            .description("Position pairs to calculate distances for"));
 137     // TODO: Extend the histogramming implementation to allow automatic
 138     // extension of the histograms to cover the data, removing the need for
 139     // the first two options.
 140     options->addOption(DoubleOption("len").store(&meanLength_)
 141                            .description("Mean distance for histogramming"));
 142     options->addOption(DoubleOption("tol").store(&lengthDev_)
 143                            .description("Width of full distribution as fraction of [TT]-len[tt]"));
 144     options->addOption(DoubleOption("binw").store(&binWidth_)
 145                            .description("Bin width for histogramming"));
 146 }
 147
 148
 149 namespace
 150 {
 151
 152 /*! \brief
 153  * Checks that selections conform to the expectations of the tool.
 154  */
 155 void checkSelections(const SelectionList &sel)
 156 {
 157     for (size_t g = 0; g < sel.size(); ++g)
 158     {
 159         if (sel[g].posCount() % 2 != 0)
 160         {
 161             std::string message = formatString(
 162                         "Selection '%s' does not evaluate into an even number of positions "
 163                         "(there are %d positions)",
 164                         sel[g].name(), sel[g].posCount());
 165             GMX_THROW(InconsistentInputError(message));
 166         }
 167         if (sel[g].isDynamic())
 168         {
 169             for (int i = 0; i < sel[g].posCount(); i += 2)
 170             {
 171                 if (sel[g].position(i).selected() != sel[g].position(i+1).selected())
 172                 {
 173                     std::string message =
 174                         formatString("Dynamic selection %d does not select "
 175                                      "a consistent set of pairs over the frames",
 176                                      static_cast<int>(g + 1));
 177                     GMX_THROW(InconsistentInputError(message));
 178                 }
 179             }
 180         }
 181     }
 182 }
 183
 184 }       // namespace
 185
 186
 187 void
 188 Distance::initAnalysis(const TrajectoryAnalysisSettings &settings,
 189                        const TopologyInformation         & /*top*/)
 190 {
 191     checkSelections(sel_);
 192
 193     distances_.setDataSetCount(sel_.size());
 194     xyz_.setDataSetCount(sel_.size());
 195     for (size_t i = 0; i < sel_.size(); ++i)
 196     {
 197         const int distCount = sel_[i].posCount() / 2;
 198         distances_.setColumnCount(i, distCount);
 199         xyz_.setColumnCount(i, distCount * 3);
 200     }
 201     const double histogramMin = (1.0 - lengthDev_) * meanLength_;
 202     const double histogramMax = (1.0 + lengthDev_) * meanLength_;
 203     histogramModule_->init(histogramFromRange(histogramMin, histogramMax)
 204                                .binWidth(binWidth_).includeAll());
 205
 206     if (!fnAverage_.empty())
 207     {
 208         AnalysisDataPlotModulePointer plotm(
 209                 new AnalysisDataPlotModule(settings.plotSettings()));
 210         plotm->setFileName(fnAverage_);
 211         plotm->setTitle("Average distance");
 212         plotm->setXAxisIsTime();
 213         plotm->setYLabel("Distance (nm)");
 214         for (size_t g = 0; g < sel_.size(); ++g)
 215         {
 216             plotm->appendLegend(sel_[g].name());
 217         }
 218         averageModule_->addModule(plotm);
 219     }
 220
 221     if (!fnAll_.empty())
 222     {
 223         AnalysisDataPlotModulePointer plotm(
 224                 new AnalysisDataPlotModule(settings.plotSettings()));
 225         plotm->setFileName(fnAll_);
 226         plotm->setTitle("Distance");
 227         plotm->setXAxisIsTime();
 228         plotm->setYLabel("Distance (nm)");
 229         // TODO: Add legends? (there can be a massive amount of columns)
 230         distances_.addModule(plotm);
 231     }
 232
 233     if (!fnXYZ_.empty())
 234     {
 235         AnalysisDataPlotModulePointer plotm(
 236                 new AnalysisDataPlotModule(settings.plotSettings()));
 237         plotm->setFileName(fnAll_);
 238         plotm->setTitle("Distance");
 239         plotm->setXAxisIsTime();
 240         plotm->setYLabel("Distance (nm)");
 241         // TODO: Add legends? (there can be a massive amount of columns)
 242         xyz_.addModule(plotm);
 243     }
 244
 245     if (!fnHistogram_.empty())
 246     {
 247         AnalysisDataPlotModulePointer plotm(
 248                 new AnalysisDataPlotModule(settings.plotSettings()));
 249         plotm->setFileName(fnHistogram_);
 250         plotm->setTitle("Distance histogram");
 251         plotm->setXLabel("Distance (nm)");
 252         plotm->setYLabel("Probability");
 253         for (size_t g = 0; g < sel_.size(); ++g)
 254         {
 255             plotm->appendLegend(sel_[g].name());
 256         }
 257         histogramModule_->averager().addModule(plotm);
 258     }
 259
 260     if (!fnAllStats_.empty())
 261     {
 262         AnalysisDataPlotModulePointer plotm(
 263                 new AnalysisDataPlotModule(settings.plotSettings()));
 264         plotm->setFileName(fnAllStats_);
 265         plotm->setErrorsAsSeparateColumn(true);
 266         plotm->setTitle("Statistics for individual distances");
 267         plotm->setXLabel("Distance index");
 268         plotm->setYLabel("Average/standard deviation (nm)");
 269         for (size_t g = 0; g < sel_.size(); ++g)
 270         {
 271             plotm->appendLegend(std::string(sel_[g].name()) + " avg");
 272             plotm->appendLegend(std::string(sel_[g].name()) + " std.dev.");
 273         }
 274         // TODO: Consider whether this output format is the best possible.
 275         allStatsModule_->addModule(plotm);
 276     }
 277 }
 278
 279
 280 void
 281 Distance::analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
 282                        TrajectoryAnalysisModuleData *pdata)
 283 {
 284     AnalysisDataHandle   distHandle = pdata->dataHandle(distances_);
 285     AnalysisDataHandle   xyzHandle  = pdata->dataHandle(xyz_);
 286     const SelectionList &sel        = pdata->parallelSelections(sel_);
 287
 288     checkSelections(sel);
 289
 290     distHandle.startFrame(frnr, fr.time);
 291     xyzHandle.startFrame(frnr, fr.time);
 292     for (size_t g = 0; g < sel.size(); ++g)
 293     {
 294         distHandle.selectDataSet(g);
 295         xyzHandle.selectDataSet(g);
 296         for (int i = 0, n = 0; i < sel[g].posCount(); i += 2, ++n)
 297         {
 298             const SelectionPosition &p1 = sel[g].position(i);
 299             const SelectionPosition &p2 = sel[g].position(i+1);
 300             rvec                     dx;
 301             if (pbc != NULL)
 302             {
 303                 pbc_dx(pbc, p2.x(), p1.x(), dx);
 304             }
 305             else
 306             {
 307                 rvec_sub(p2.x(), p1.x(), dx);
 308             }
 309             real dist     = norm(dx);
 310             bool bPresent = p1.selected() && p2.selected();
 311             distHandle.setPoint(n, dist, bPresent);
 312             xyzHandle.setPoints(n*3, 3, dx);
 313         }
 314     }
 315     distHandle.finishFrame();
 316     xyzHandle.finishFrame();
 317 }
 318
 319
 320 void
 321 Distance::finishAnalysis(int /*nframes*/)
 322 {
 323     AbstractAverageHistogram &averageHistogram = histogramModule_->averager();
 324     averageHistogram.normalizeProbability();
 325     averageHistogram.done();
 326 }
 327
 328
 329 void
 330 Distance::writeOutput()
 331 {
 332     SelectionList::const_iterator sel;
 333     int                           index;
 334     for (sel = sel_.begin(), index = 0; sel != sel_.end(); ++sel, ++index)
 335     {
 336         printf("%s:\n", sel->name());
 337         printf("  Number of samples:  %d\n",
 338                summaryStatsModule_->sampleCount(index, 0));
 339         printf("  Average distance:   %-6.3f nm\n",
 340                summaryStatsModule_->average(index, 0));
 341         printf("  Standard deviation: %-6.3f nm\n",
 342                summaryStatsModule_->standardDeviation(index, 0));
 343     }
 344 }
 345
 346 } // namespace analysismodules
 347
 348 } // namespace gmx