src/gromacs/trajectoryanalysis/analysismodule.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014, 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 classes in analysismodule.h.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \ingroup module_trajectoryanalysis
  41  */
  42 #include "gmxpre.h"
  43
  44 #include "gromacs/trajectoryanalysis/analysismodule.h"
  45
  46 #include <utility>
  47
  48 #include "gromacs/analysisdata/analysisdata.h"
  49 #include "gromacs/selection/selection.h"
  50 #include "gromacs/utility/exceptions.h"
  51 #include "gromacs/utility/gmxassert.h"
  52
  53 namespace gmx
  54 {
  55
  56 /********************************************************************
  57  * TrajectoryAnalysisModule::Impl
  58  */
  59
  60 /*! \internal \brief
  61  * Private implementation class for TrajectoryAnalysisModule.
  62  *
  63  * \ingroup module_trajectoryanalysis
  64  */
  65 class TrajectoryAnalysisModule::Impl
  66 {
  67     public:
  68         //! Container that associates a data set with its name.
  69         typedef std::map<std::string, AbstractAnalysisData *> DatasetContainer;
  70         //! Container that associates a AnalysisData object with its name.
  71         typedef std::map<std::string, AnalysisData *> AnalysisDatasetContainer;
  72
  73         //! Initializes analysis module data with given name and description.
  74         Impl(const char *name, const char *description)
  75             : name_(name), description_(description)
  76         {
  77         }
  78
  79         //! Name of the module.
  80         std::string                     name_;
  81         //! Description of the module.
  82         std::string                     description_;
  83         //! List of registered data set names.
  84         std::vector<std::string>        datasetNames_;
  85         /*! \brief
  86          * Keeps all registered data sets.
  87          *
  88          * This container also includes datasets from \a analysisDatasets_.
  89          */
  90         DatasetContainer                datasets_;
  91         //! Keeps registered AnalysisData objects.
  92         AnalysisDatasetContainer        analysisDatasets_;
  93 };
  94
  95 /********************************************************************
  96  * TrajectoryAnalysisModuleData::Impl
  97  */
  98
  99 /*! \internal \brief
 100  * Private implementation class for TrajectoryAnalysisModuleData.
 101  *
 102  * \ingroup module_trajectoryanalysis
 103  */
 104 class TrajectoryAnalysisModuleData::Impl
 105 {
 106     public:
 107         //! Container that associates a data handle to its AnalysisData object.
 108         typedef std::map<const AnalysisData *, AnalysisDataHandle>
 109             HandleContainer;
 110
 111         //! \copydoc TrajectoryAnalysisModuleData::TrajectoryAnalysisModuleData()
 112         Impl(TrajectoryAnalysisModule          *module,
 113              const AnalysisDataParallelOptions &opt,
 114              const SelectionCollection         &selections);
 115
 116         //! Checks whether the given AnalysisData has been initialized.
 117         bool isInitialized(const AnalysisData &data) const;
 118
 119         //! Keeps a data handle for each AnalysisData object.
 120         HandleContainer            handles_;
 121         //! Stores thread-local selections.
 122         const SelectionCollection &selections_;
 123 };
 124
 125 TrajectoryAnalysisModuleData::Impl::Impl(
 126         TrajectoryAnalysisModule          *module,
 127         const AnalysisDataParallelOptions &opt,
 128         const SelectionCollection         &selections)
 129     : selections_(selections)
 130 {
 131     TrajectoryAnalysisModule::Impl::AnalysisDatasetContainer::const_iterator i;
 132     for (i = module->impl_->analysisDatasets_.begin();
 133          i != module->impl_->analysisDatasets_.end(); ++i)
 134     {
 135         AnalysisDataHandle handle;
 136         if (isInitialized(*i->second))
 137         {
 138             handle = i->second->startData(opt);
 139         }
 140         handles_.insert(std::make_pair(i->second, handle));
 141     }
 142 }
 143
 144 bool TrajectoryAnalysisModuleData::Impl::isInitialized(
 145         const AnalysisData &data) const
 146 {
 147     for (int i = 0; i < data.dataSetCount(); ++i)
 148     {
 149         if (data.columnCount(i) > 0)
 150         {
 151             // If not all of the column counts are set, startData() in the
 152             // constructor asserts, so that does not need to be checked here.
 153             return true;
 154         }
 155     }
 156     return false;
 157 }
 158
 159
 160 /********************************************************************
 161  * TrajectoryAnalysisModuleData
 162  */
 163
 164 TrajectoryAnalysisModuleData::TrajectoryAnalysisModuleData(
 165         TrajectoryAnalysisModule          *module,
 166         const AnalysisDataParallelOptions &opt,
 167         const SelectionCollection         &selections)
 168     : impl_(new Impl(module, opt, selections))
 169 {
 170 }
 171
 172
 173 TrajectoryAnalysisModuleData::~TrajectoryAnalysisModuleData()
 174 {
 175 }
 176
 177
 178 void TrajectoryAnalysisModuleData::finishDataHandles()
 179 {
 180     // FIXME: Call finishData() for all handles even if one throws
 181     Impl::HandleContainer::iterator i;
 182     for (i = impl_->handles_.begin(); i != impl_->handles_.end(); ++i)
 183     {
 184         if (i->second.isValid())
 185         {
 186             i->second.finishData();
 187         }
 188     }
 189     impl_->handles_.clear();
 190 }
 191
 192
 193 AnalysisDataHandle
 194 TrajectoryAnalysisModuleData::dataHandle(const AnalysisData &data)
 195 {
 196     Impl::HandleContainer::const_iterator i = impl_->handles_.find(&data);
 197     GMX_RELEASE_ASSERT(i != impl_->handles_.end(),
 198                        "Data handle requested on unknown dataset");
 199     return i->second;
 200 }
 201
 202
 203 Selection TrajectoryAnalysisModuleData::parallelSelection(const Selection &selection)
 204 {
 205     // TODO: Implement properly.
 206     return selection;
 207 }
 208
 209
 210 SelectionList
 211 TrajectoryAnalysisModuleData::parallelSelections(const SelectionList &selections)
 212 {
 213     // TODO: Consider an implementation that does not allocate memory every time.
 214     SelectionList                 newSelections;
 215     newSelections.reserve(selections.size());
 216     SelectionList::const_iterator i = selections.begin();
 217     for (; i != selections.end(); ++i)
 218     {
 219         newSelections.push_back(parallelSelection(*i));
 220     }
 221     return newSelections;
 222 }
 223
 224
 225 /********************************************************************
 226  * TrajectoryAnalysisModuleDataBasic
 227  */
 228
 229 namespace
 230 {
 231
 232 /*! \brief
 233  * Basic thread-local trajectory analysis data storage class.
 234  *
 235  * Most simple tools should only require data handles and selections to be
 236  * thread-local, so this class implements just that.
 237  *
 238  * \ingroup module_trajectoryanalysis
 239  */
 240 class TrajectoryAnalysisModuleDataBasic : public TrajectoryAnalysisModuleData
 241 {
 242     public:
 243         /*! \brief
 244          * Initializes thread-local storage for data handles and selections.
 245          *
 246          * \param[in] module     Analysis module to use for data objects.
 247          * \param[in] opt        Data parallelization options.
 248          * \param[in] selections Thread-local selection collection.
 249          */
 250         TrajectoryAnalysisModuleDataBasic(TrajectoryAnalysisModule          *module,
 251                                           const AnalysisDataParallelOptions &opt,
 252                                           const SelectionCollection         &selections);
 253
 254         virtual void finish();
 255 };
 256
 257 TrajectoryAnalysisModuleDataBasic::TrajectoryAnalysisModuleDataBasic(
 258         TrajectoryAnalysisModule          *module,
 259         const AnalysisDataParallelOptions &opt,
 260         const SelectionCollection         &selections)
 261     : TrajectoryAnalysisModuleData(module, opt, selections)
 262 {
 263 }
 264
 265
 266 void
 267 TrajectoryAnalysisModuleDataBasic::finish()
 268 {
 269     finishDataHandles();
 270 }
 271
 272 }   // namespace
 273
 274
 275 /********************************************************************
 276  * TrajectoryAnalysisModule
 277  */
 278
 279 TrajectoryAnalysisModule::TrajectoryAnalysisModule(const char *name,
 280                                                    const char *description)
 281     : impl_(new Impl(name, description))
 282 {
 283 }
 284
 285
 286 TrajectoryAnalysisModule::~TrajectoryAnalysisModule()
 287 {
 288 }
 289
 290
 291 void TrajectoryAnalysisModule::optionsFinished(
 292         Options                    * /*options*/,
 293         TrajectoryAnalysisSettings * /*settings*/)
 294 {
 295 }
 296
 297
 298 void TrajectoryAnalysisModule::initAfterFirstFrame(
 299         const TrajectoryAnalysisSettings & /*settings*/,
 300         const t_trxframe                 & /*fr*/)
 301 {
 302 }
 303
 304
 305 TrajectoryAnalysisModuleDataPointer
 306 TrajectoryAnalysisModule::startFrames(const AnalysisDataParallelOptions &opt,
 307                                       const SelectionCollection         &selections)
 308 {
 309     return TrajectoryAnalysisModuleDataPointer(
 310             new TrajectoryAnalysisModuleDataBasic(this, opt, selections));
 311 }
 312
 313
 314 void TrajectoryAnalysisModule::finishFrames(TrajectoryAnalysisModuleData * /*pdata*/)
 315 {
 316 }
 317
 318
 319 const char *TrajectoryAnalysisModule::name() const
 320 {
 321     return impl_->name_.c_str();
 322 }
 323
 324
 325 const char *TrajectoryAnalysisModule::description() const
 326 {
 327     return impl_->description_.c_str();
 328 }
 329
 330
 331 int TrajectoryAnalysisModule::datasetCount() const
 332 {
 333     return impl_->datasetNames_.size();
 334 }
 335
 336
 337 const std::vector<std::string> &TrajectoryAnalysisModule::datasetNames() const
 338 {
 339     return impl_->datasetNames_;
 340 }
 341
 342
 343 AbstractAnalysisData &TrajectoryAnalysisModule::datasetFromIndex(int index) const
 344 {
 345     if (index < 0 || index >= datasetCount())
 346     {
 347         GMX_THROW(APIError("Out of range data set index"));
 348     }
 349     Impl::DatasetContainer::const_iterator item
 350         = impl_->datasets_.find(impl_->datasetNames_[index]);
 351     GMX_RELEASE_ASSERT(item != impl_->datasets_.end(),
 352                        "Inconsistent data set names");
 353     return *item->second;
 354 }
 355
 356
 357 AbstractAnalysisData &TrajectoryAnalysisModule::datasetFromName(const char *name) const
 358 {
 359     Impl::DatasetContainer::const_iterator item = impl_->datasets_.find(name);
 360     if (item == impl_->datasets_.end())
 361     {
 362         GMX_THROW(APIError("Unknown data set name"));
 363     }
 364     return *item->second;
 365 }
 366
 367
 368 void TrajectoryAnalysisModule::registerBasicDataset(AbstractAnalysisData *data,
 369                                                     const char           *name)
 370 {
 371     GMX_RELEASE_ASSERT(data != NULL, "Attempting to register NULL data");
 372     // TODO: Strong exception safety should be possible to implement.
 373     GMX_RELEASE_ASSERT(impl_->datasets_.find(name) == impl_->datasets_.end(),
 374                        "Duplicate data set name registered");
 375     impl_->datasets_[name] = data;
 376     impl_->datasetNames_.push_back(name);
 377 }
 378
 379
 380 void TrajectoryAnalysisModule::registerAnalysisDataset(AnalysisData *data,
 381                                                        const char   *name)
 382 {
 383     // TODO: Strong exception safety should be possible to implement.
 384     registerBasicDataset(data, name);
 385     impl_->analysisDatasets_[name] = data;
 386 }
 387
 388 } // namespace gmx