src/gromacs/trajectoryanalysis/modules/distance.cpp

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