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  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source 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 <string>
  45
  46 #include "gromacs/legacyheaders/pbc.h"
  47 #include "gromacs/legacyheaders/vec.h"
  48
  49 #include "gromacs/analysisdata/analysisdata.h"
  50 #include "gromacs/analysisdata/modules/average.h"
  51 #include "gromacs/analysisdata/modules/histogram.h"
  52 #include "gromacs/analysisdata/modules/plot.h"
  53 #include "gromacs/options/basicoptions.h"
  54 #include "gromacs/options/filenameoption.h"
  55 #include "gromacs/options/options.h"
  56 #include "gromacs/selection/selection.h"
  57 #include "gromacs/selection/selectionoption.h"
  58 #include "gromacs/trajectoryanalysis/analysissettings.h"
  59 #include "gromacs/utility/exceptions.h"
  60 #include "gromacs/utility/stringutil.h"
  61
  62 namespace gmx
  63 {
  64
  65 namespace analysismodules
  66 {
  67
  68 namespace
  69 {
  70
  71 class Distance : public TrajectoryAnalysisModule
  72 {
  73     public:
  74         Distance();
  75
  76         virtual void initOptions(Options                    *options,
  77                                  TrajectoryAnalysisSettings *settings);
  78         virtual void initAnalysis(const TrajectoryAnalysisSettings &settings,
  79                                   const TopologyInformation        &top);
  80
  81         virtual void analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
  82                                   TrajectoryAnalysisModuleData *pdata);
  83
  84         virtual void finishAnalysis(int nframes);
  85         virtual void writeOutput();
  86
  87     private:
  88         SelectionList                            sel_;
  89         std::string                              fnAverage_;
  90         std::string                              fnAll_;
  91         std::string                              fnXYZ_;
  92         std::string                              fnHistogram_;
  93         std::string                              fnAllStats_;
  94         double                                   meanLength_;
  95         double                                   lengthDev_;
  96         double                                   binWidth_;
  97
  98         AnalysisData                             distances_;
  99         AnalysisData                             xyz_;
 100         AnalysisDataAverageModulePointer         summaryStatsModule_;
 101         AnalysisDataAverageModulePointer         allStatsModule_;
 102         AnalysisDataFrameAverageModulePointer    averageModule_;
 103         AnalysisDataSimpleHistogramModulePointer histogramModule_;
 104
 105         // Copy and assign disallowed by base.
 106 };
 107
 108 Distance::Distance()
 109     : TrajectoryAnalysisModule(DistanceInfo::name, DistanceInfo::shortDescription),
 110       meanLength_(0.1), lengthDev_(1.0), binWidth_(0.001)
 111 {
 112     summaryStatsModule_.reset(new AnalysisDataAverageModule());
 113     summaryStatsModule_->setAverageDataSets(true);
 114     distances_.addModule(summaryStatsModule_);
 115     allStatsModule_.reset(new AnalysisDataAverageModule());
 116     distances_.addModule(allStatsModule_);
 117     averageModule_.reset(new AnalysisDataFrameAverageModule());
 118     distances_.addModule(averageModule_);
 119     histogramModule_.reset(new AnalysisDataSimpleHistogramModule());
 120     distances_.addModule(histogramModule_);
 121
 122     registerAnalysisDataset(&distances_, "dist");
 123     registerAnalysisDataset(&xyz_, "xyz");
 124     registerBasicDataset(summaryStatsModule_.get(), "stats");
 125     registerBasicDataset(allStatsModule_.get(), "allstats");
 126     registerBasicDataset(averageModule_.get(), "average");
 127     registerBasicDataset(&histogramModule_->averager(), "histogram");
 128 }
 129
 130
 131 void
 132 Distance::initOptions(Options *options, TrajectoryAnalysisSettings * /*settings*/)
 133 {
 134     static const char *const desc[] = {
 135         "[THISMODULE] calculates distances between pairs of positions",
 136         "as a function of time. Each selection specifies an independent set",
 137         "of distances to calculate. Each selection should consist of pairs",
 138         "of positions, and the distances are computed between positions 1-2,",
 139         "3-4, etc.[PAR]",
 140         "[TT]-oav[tt] writes the average distance as a function of time for",
 141         "each selection.",
 142         "[TT]-oall[tt] writes all the individual distances.",
 143         "[TT]-oxyz[tt] does the same, but the x, y, and z components of the",
 144         "distance are written instead of the norm.",
 145         "[TT]-oh[tt] writes a histogram of the distances for each selection.",
 146         "The location of the histogram is set with [TT]-len[tt] and",
 147         "[TT]-tol[tt]. Bin width is set with [TT]-binw[tt].",
 148         "[TT]-oallstat[tt] writes out the average and standard deviation for",
 149         "each individual distance, calculated over the frames."
 150     };
 151
 152     options->setDescription(concatenateStrings(desc));
 153
 154     options->addOption(FileNameOption("oav").filetype(eftPlot).outputFile()
 155                            .store(&fnAverage_).defaultBasename("distave")
 156                            .description("Average distances as function of time"));
 157     options->addOption(FileNameOption("oall").filetype(eftPlot).outputFile()
 158                            .store(&fnAll_).defaultBasename("dist")
 159                            .description("All distances as function of time"));
 160     options->addOption(FileNameOption("oxyz").filetype(eftPlot).outputFile()
 161                            .store(&fnXYZ_).defaultBasename("distxyz")
 162                            .description("Distance components as function of time"));
 163     options->addOption(FileNameOption("oh").filetype(eftPlot).outputFile()
 164                            .store(&fnHistogram_).defaultBasename("disthist")
 165                            .description("Histogram of the distances"));
 166     options->addOption(FileNameOption("oallstat").filetype(eftPlot).outputFile()
 167                            .store(&fnAllStats_).defaultBasename("diststat")
 168                            .description("Statistics for individual distances"));
 169     options->addOption(SelectionOption("select").storeVector(&sel_)
 170                            .required().dynamicMask().multiValue()
 171                            .description("Position pairs to calculate distances for"));
 172     // TODO: Extend the histogramming implementation to allow automatic
 173     // extension of the histograms to cover the data, removing the need for
 174     // the first two options.
 175     options->addOption(DoubleOption("len").store(&meanLength_)
 176                            .description("Mean distance for histogramming"));
 177     options->addOption(DoubleOption("tol").store(&lengthDev_)
 178                            .description("Width of full distribution as fraction of [TT]-len[tt]"));
 179     options->addOption(DoubleOption("binw").store(&binWidth_)
 180                            .description("Bin width for histogramming"));
 181 }
 182
 183
 184 /*! \brief
 185  * Checks that selections conform to the expectations of the tool.
 186  */
 187 void checkSelections(const SelectionList &sel)
 188 {
 189     for (size_t g = 0; g < sel.size(); ++g)
 190     {
 191         if (sel[g].posCount() % 2 != 0)
 192         {
 193             std::string message = formatString(
 194                         "Selection '%s' does not evaluate into an even number of positions "
 195                         "(there are %d positions)",
 196                         sel[g].name(), sel[g].posCount());
 197             GMX_THROW(InconsistentInputError(message));
 198         }
 199         if (sel[g].isDynamic())
 200         {
 201             for (int i = 0; i < sel[g].posCount(); i += 2)
 202             {
 203                 if (sel[g].position(i).selected() != sel[g].position(i+1).selected())
 204                 {
 205                     std::string message =
 206                         formatString("Dynamic selection %d does not select "
 207                                      "a consistent set of pairs over the frames",
 208                                      static_cast<int>(g + 1));
 209                     GMX_THROW(InconsistentInputError(message));
 210                 }
 211             }
 212         }
 213     }
 214 }
 215
 216
 217 void
 218 Distance::initAnalysis(const TrajectoryAnalysisSettings &settings,
 219                        const TopologyInformation         & /*top*/)
 220 {
 221     checkSelections(sel_);
 222
 223     distances_.setDataSetCount(sel_.size());
 224     xyz_.setDataSetCount(sel_.size());
 225     for (size_t i = 0; i < sel_.size(); ++i)
 226     {
 227         const int distCount = sel_[i].posCount() / 2;
 228         distances_.setColumnCount(i, distCount);
 229         xyz_.setColumnCount(i, distCount * 3);
 230     }
 231     const double histogramMin = (1.0 - lengthDev_) * meanLength_;
 232     const double histogramMax = (1.0 + lengthDev_) * meanLength_;
 233     histogramModule_->init(histogramFromRange(histogramMin, histogramMax)
 234                                .binWidth(binWidth_).includeAll());
 235
 236     if (!fnAverage_.empty())
 237     {
 238         AnalysisDataPlotModulePointer plotm(
 239                 new AnalysisDataPlotModule(settings.plotSettings()));
 240         plotm->setFileName(fnAverage_);
 241         plotm->setTitle("Average distance");
 242         plotm->setXAxisIsTime();
 243         plotm->setYLabel("Distance (nm)");
 244         for (size_t g = 0; g < sel_.size(); ++g)
 245         {
 246             plotm->appendLegend(sel_[g].name());
 247         }
 248         averageModule_->addModule(plotm);
 249     }
 250
 251     if (!fnAll_.empty())
 252     {
 253         AnalysisDataPlotModulePointer plotm(
 254                 new AnalysisDataPlotModule(settings.plotSettings()));
 255         plotm->setFileName(fnAll_);
 256         plotm->setTitle("Distance");
 257         plotm->setXAxisIsTime();
 258         plotm->setYLabel("Distance (nm)");
 259         // TODO: Add legends? (there can be a massive amount of columns)
 260         distances_.addModule(plotm);
 261     }
 262
 263     if (!fnXYZ_.empty())
 264     {
 265         AnalysisDataPlotModulePointer plotm(
 266                 new AnalysisDataPlotModule(settings.plotSettings()));
 267         plotm->setFileName(fnAll_);
 268         plotm->setTitle("Distance");
 269         plotm->setXAxisIsTime();
 270         plotm->setYLabel("Distance (nm)");
 271         // TODO: Add legends? (there can be a massive amount of columns)
 272         xyz_.addModule(plotm);
 273     }
 274
 275     if (!fnHistogram_.empty())
 276     {
 277         AnalysisDataPlotModulePointer plotm(
 278                 new AnalysisDataPlotModule(settings.plotSettings()));
 279         plotm->setFileName(fnHistogram_);
 280         plotm->setTitle("Distance histogram");
 281         plotm->setXLabel("Distance (nm)");
 282         plotm->setYLabel("Probability");
 283         for (size_t g = 0; g < sel_.size(); ++g)
 284         {
 285             plotm->appendLegend(sel_[g].name());
 286         }
 287         histogramModule_->averager().addModule(plotm);
 288     }
 289
 290     if (!fnAllStats_.empty())
 291     {
 292         AnalysisDataPlotModulePointer plotm(
 293                 new AnalysisDataPlotModule(settings.plotSettings()));
 294         plotm->setFileName(fnAllStats_);
 295         plotm->setErrorsAsSeparateColumn(true);
 296         plotm->setTitle("Statistics for individual distances");
 297         plotm->setXLabel("Distance index");
 298         plotm->setYLabel("Average/standard deviation (nm)");
 299         for (size_t g = 0; g < sel_.size(); ++g)
 300         {
 301             plotm->appendLegend(std::string(sel_[g].name()) + " avg");
 302             plotm->appendLegend(std::string(sel_[g].name()) + " std.dev.");
 303         }
 304         // TODO: Consider whether this output format is the best possible.
 305         allStatsModule_->addModule(plotm);
 306     }
 307 }
 308
 309
 310 void
 311 Distance::analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
 312                        TrajectoryAnalysisModuleData *pdata)
 313 {
 314     AnalysisDataHandle   distHandle = pdata->dataHandle(distances_);
 315     AnalysisDataHandle   xyzHandle  = pdata->dataHandle(xyz_);
 316     const SelectionList &sel        = pdata->parallelSelections(sel_);
 317
 318     checkSelections(sel);
 319
 320     distHandle.startFrame(frnr, fr.time);
 321     xyzHandle.startFrame(frnr, fr.time);
 322     for (size_t g = 0; g < sel.size(); ++g)
 323     {
 324         distHandle.selectDataSet(g);
 325         xyzHandle.selectDataSet(g);
 326         for (int i = 0, n = 0; i < sel[g].posCount(); i += 2, ++n)
 327         {
 328             const SelectionPosition &p1 = sel[g].position(i);
 329             const SelectionPosition &p2 = sel[g].position(i+1);
 330             rvec                     dx;
 331             if (pbc != NULL)
 332             {
 333                 pbc_dx(pbc, p2.x(), p1.x(), dx);
 334             }
 335             else
 336             {
 337                 rvec_sub(p2.x(), p1.x(), dx);
 338             }
 339             real dist     = norm(dx);
 340             bool bPresent = p1.selected() && p2.selected();
 341             distHandle.setPoint(n, dist, bPresent);
 342             xyzHandle.setPoints(n*3, 3, dx);
 343         }
 344     }
 345     distHandle.finishFrame();
 346     xyzHandle.finishFrame();
 347 }
 348
 349
 350 void
 351 Distance::finishAnalysis(int /*nframes*/)
 352 {
 353     AbstractAverageHistogram &averageHistogram = histogramModule_->averager();
 354     averageHistogram.normalizeProbability();
 355     averageHistogram.done();
 356 }
 357
 358
 359 void
 360 Distance::writeOutput()
 361 {
 362     SelectionList::const_iterator sel;
 363     int                           index;
 364     for (sel = sel_.begin(), index = 0; sel != sel_.end(); ++sel, ++index)
 365     {
 366         printf("%s:\n", sel->name());
 367         printf("  Number of samples:  %d\n",
 368                summaryStatsModule_->sampleCount(index, 0));
 369         printf("  Average distance:   %-6.3f nm\n",
 370                summaryStatsModule_->average(index, 0));
 371         printf("  Standard deviation: %-6.3f nm\n",
 372                summaryStatsModule_->standardDeviation(index, 0));
 373     }
 374 }
 375
 376 }       // namespace
 377
 378 const char DistanceInfo::name[]             = "distance";
 379 const char DistanceInfo::shortDescription[] =
 380     "Calculate distances between pairs of positions";
 381
 382 TrajectoryAnalysisModulePointer DistanceInfo::create()
 383 {
 384     return TrajectoryAnalysisModulePointer(new Distance);
 385 }
 386
 387 } // namespace analysismodules
 388
 389 } // namespace gmx