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