src/gromacs/analysisdata/abstractdata.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012, 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::AbstractAnalysisData.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \ingroup module_analysisdata
  41  */
  42 #include "gromacs/analysisdata/abstractdata.h"
  43
  44 #include <vector>
  45
  46 #include "gromacs/analysisdata/datamodule.h"
  47 #include "gromacs/utility/exceptions.h"
  48 #include "gromacs/utility/gmxassert.h"
  49 #include "gromacs/utility/uniqueptr.h"
  50
  51 #include "dataframe.h"
  52 #include "dataproxy.h"
  53
  54 namespace gmx
  55 {
  56
  57 /********************************************************************
  58  * AbstractAnalysisData::Impl
  59  */
  60
  61 /*! \internal \brief
  62  * Private implementation class for AbstractAnalysisData.
  63  *
  64  * \ingroup module_analysisdata
  65  */
  66 class AbstractAnalysisData::Impl
  67 {
  68     public:
  69         //! Shorthand for list of modules added to the data.
  70         typedef std::vector<AnalysisDataModulePointer> ModuleList;
  71
  72         Impl();
  73
  74         /*! \brief
  75          * Present data already added to the data object to a module.
  76          *
  77          * \param[in] data   Data object to read data from.
  78          * \param[in] module Module to present the data to.
  79          * \throws    APIError if \p module is not compatible with the data
  80          *      object.
  81          * \throws    APIError if all data is not available through
  82          *      getDataFrame().
  83          * \throws    unspecified Any exception thrown by \p module in its data
  84          *      notification methods.
  85          *
  86          * Uses getDataFrame() in \p data to access all data in the object, and
  87          * calls the notification functions in \p module as if the module had
  88          * been registered to the data object when the data was added.
  89          */
  90         void presentData(AbstractAnalysisData        *data,
  91                          AnalysisDataModuleInterface *module);
  92
  93         //! List of modules added to the data.
  94         ModuleList              modules_;
  95         //! true if all modules support missing data.
  96         bool                    bAllowMissing_;
  97         //! Whether notifyDataStart() has been called.
  98         mutable bool            bDataStart_;
  99         //! Whether new data is being added.
 100         mutable bool            bInData_;
 101         //! Whether data for a frame is being added.
 102         mutable bool            bInFrame_;
 103         //! Index of the currently active frame.
 104         mutable int             currIndex_;
 105         /*! \brief
 106          * Total number of frames in the data.
 107          *
 108          * The counter is incremented in notifyFrameFinish().
 109          */
 110         int                     nframes_;
 111 };
 112
 113 AbstractAnalysisData::Impl::Impl()
 114     : bAllowMissing_(true), bDataStart_(false), bInData_(false), bInFrame_(false),
 115       currIndex_(-1), nframes_(0)
 116 {
 117 }
 118
 119 void
 120 AbstractAnalysisData::Impl::presentData(AbstractAnalysisData        *data,
 121                                         AnalysisDataModuleInterface *module)
 122 {
 123     module->dataStarted(data);
 124     bool bCheckMissing = bAllowMissing_
 125         && !(module->flags() & AnalysisDataModuleInterface::efAllowMissing);
 126     for (int i = 0; i < data->frameCount(); ++i)
 127     {
 128         AnalysisDataFrameRef frame = data->getDataFrame(i);
 129         GMX_RELEASE_ASSERT(frame.isValid(), "Invalid data frame returned");
 130         // TODO: Check all frames before doing anything for slightly better
 131         // exception behavior.
 132         if (bCheckMissing && !frame.allPresent())
 133         {
 134             GMX_THROW(APIError("Missing data not supported by a module"));
 135         }
 136         module->frameStarted(frame.header());
 137         module->pointsAdded(frame.points());
 138         module->frameFinished(frame.header());
 139     }
 140     if (!bInData_)
 141     {
 142         module->dataFinished();
 143     }
 144 }
 145
 146
 147 /********************************************************************
 148  * AbstractAnalysisData
 149  */
 150 /*! \cond libapi */
 151 AbstractAnalysisData::AbstractAnalysisData()
 152     : impl_(new Impl()), columnCount_(0), bMultiPoint_(false)
 153 {
 154 }
 155 //! \endcond
 156
 157 AbstractAnalysisData::~AbstractAnalysisData()
 158 {
 159 }
 160
 161
 162 int
 163 AbstractAnalysisData::frameCount() const
 164 {
 165     return impl_->nframes_;
 166 }
 167
 168
 169 AnalysisDataFrameRef
 170 AbstractAnalysisData::tryGetDataFrame(int index) const
 171 {
 172     if (index < 0 || index >= frameCount())
 173     {
 174         return AnalysisDataFrameRef();
 175     }
 176     return tryGetDataFrameInternal(index);
 177 }
 178
 179
 180 AnalysisDataFrameRef
 181 AbstractAnalysisData::getDataFrame(int index) const
 182 {
 183     AnalysisDataFrameRef frame = tryGetDataFrame(index);
 184     if (!frame.isValid())
 185     {
 186         GMX_THROW(APIError("Invalid frame accessed"));
 187     }
 188     return frame;
 189 }
 190
 191
 192 bool
 193 AbstractAnalysisData::requestStorage(int nframes)
 194 {
 195     GMX_RELEASE_ASSERT(nframes >= -1, "Invalid number of frames requested");
 196     if (nframes == 0)
 197     {
 198         return true;
 199     }
 200     return requestStorageInternal(nframes);
 201 }
 202
 203
 204 void
 205 AbstractAnalysisData::addModule(AnalysisDataModulePointer module)
 206 {
 207     if ((columnCount() > 1 && !(module->flags() & AnalysisDataModuleInterface::efAllowMulticolumn))
 208         || (isMultipoint() && !(module->flags() & AnalysisDataModuleInterface::efAllowMultipoint))
 209         || (!isMultipoint() && (module->flags() & AnalysisDataModuleInterface::efOnlyMultipoint)))
 210     {
 211         GMX_THROW(APIError("Data module not compatible with data object properties"));
 212     }
 213
 214     if (impl_->bDataStart_)
 215     {
 216         GMX_RELEASE_ASSERT(!impl_->bInFrame_,
 217                            "Cannot add data modules in mid-frame");
 218         impl_->presentData(this, module.get());
 219     }
 220     if (!(module->flags() & AnalysisDataModuleInterface::efAllowMissing))
 221     {
 222         impl_->bAllowMissing_ = false;
 223     }
 224     impl_->modules_.push_back(module);
 225 }
 226
 227
 228 void
 229 AbstractAnalysisData::addColumnModule(int col, int span,
 230                                       AnalysisDataModulePointer module)
 231 {
 232     GMX_RELEASE_ASSERT(col >= 0 && span >= 1 && col + span <= columnCount_,
 233                        "Invalid columns specified for a column module");
 234     if (impl_->bDataStart_)
 235     {
 236         GMX_THROW(NotImplementedError("Cannot add column modules after data"));
 237     }
 238
 239     boost::shared_ptr<AnalysisDataProxy> proxy(
 240             new AnalysisDataProxy(col, span, this));
 241     proxy->addModule(module);
 242     addModule(proxy);
 243 }
 244
 245
 246 void
 247 AbstractAnalysisData::applyModule(AnalysisDataModuleInterface *module)
 248 {
 249     if ((columnCount() > 1 && !(module->flags() & AnalysisDataModuleInterface::efAllowMulticolumn))
 250         || (isMultipoint() && !(module->flags() & AnalysisDataModuleInterface::efAllowMultipoint))
 251         || (!isMultipoint() && (module->flags() & AnalysisDataModuleInterface::efOnlyMultipoint)))
 252     {
 253         GMX_THROW(APIError("Data module not compatible with data object properties"));
 254     }
 255     GMX_RELEASE_ASSERT(impl_->bDataStart_ && !impl_->bInData_,
 256                        "Data module can only be applied to ready data");
 257
 258     impl_->presentData(this, module);
 259 }
 260
 261 /*! \cond libapi */
 262 void
 263 AbstractAnalysisData::setColumnCount(int columnCount)
 264 {
 265     GMX_RELEASE_ASSERT(columnCount > 0, "Invalid data column count");
 266     GMX_RELEASE_ASSERT(columnCount_ == 0 || impl_->modules_.empty(),
 267                        "Data column count cannot be changed after modules are added");
 268     GMX_RELEASE_ASSERT(!impl_->bDataStart_,
 269                        "Data column count cannot be changed after data has been added");
 270     columnCount_ = columnCount;
 271 }
 272
 273
 274 void
 275 AbstractAnalysisData::setMultipoint(bool multipoint)
 276 {
 277     GMX_RELEASE_ASSERT(impl_->modules_.empty(),
 278                        "Data type cannot be changed after modules are added");
 279     GMX_RELEASE_ASSERT(!impl_->bDataStart_,
 280                        "Data type cannot be changed after data has been added");
 281     bMultiPoint_ = multipoint;
 282 }
 283
 284
 285 /*! \internal
 286  * This method is not const because the dataStarted() methods of the attached
 287  * modules can request storage of the data.
 288  */
 289 void
 290 AbstractAnalysisData::notifyDataStart()
 291 {
 292     GMX_RELEASE_ASSERT(!impl_->bDataStart_,
 293                        "notifyDataStart() called more than once");
 294     GMX_RELEASE_ASSERT(columnCount_ > 0, "Data column count is not set");
 295     impl_->bDataStart_ = impl_->bInData_ = true;
 296
 297     Impl::ModuleList::const_iterator i;
 298     for (i = impl_->modules_.begin(); i != impl_->modules_.end(); ++i)
 299     {
 300         if (columnCount_ > 1 && !((*i)->flags() & AnalysisDataModuleInterface::efAllowMulticolumn))
 301         {
 302             GMX_THROW(APIError("Data module not compatible with data object properties"));
 303         }
 304         (*i)->dataStarted(this);
 305     }
 306 }
 307
 308
 309 void
 310 AbstractAnalysisData::notifyFrameStart(const AnalysisDataFrameHeader &header) const
 311 {
 312     GMX_ASSERT(impl_->bInData_, "notifyDataStart() not called");
 313     GMX_ASSERT(!impl_->bInFrame_,
 314                "notifyFrameStart() called while inside a frame");
 315     GMX_ASSERT(header.index() == impl_->nframes_,
 316                "Out of order frames");
 317     impl_->bInFrame_  = true;
 318     impl_->currIndex_ = header.index();
 319
 320     Impl::ModuleList::const_iterator i;
 321     for (i = impl_->modules_.begin(); i != impl_->modules_.end(); ++i)
 322     {
 323         (*i)->frameStarted(header);
 324     }
 325 }
 326
 327
 328 void
 329 AbstractAnalysisData::notifyPointsAdd(const AnalysisDataPointSetRef &points) const
 330 {
 331     GMX_ASSERT(impl_->bInData_, "notifyDataStart() not called");
 332     GMX_ASSERT(impl_->bInFrame_, "notifyFrameStart() not called");
 333     GMX_ASSERT(points.lastColumn() < columnCount(), "Invalid columns");
 334     GMX_ASSERT(points.frameIndex() == impl_->currIndex_,
 335                "Points do not correspond to current frame");
 336     if (!impl_->bAllowMissing_ && !points.allPresent())
 337     {
 338         GMX_THROW(APIError("Missing data not supported by a module"));
 339     }
 340
 341     Impl::ModuleList::const_iterator i;
 342     for (i = impl_->modules_.begin(); i != impl_->modules_.end(); ++i)
 343     {
 344         (*i)->pointsAdded(points);
 345     }
 346 }
 347
 348
 349 void
 350 AbstractAnalysisData::notifyFrameFinish(const AnalysisDataFrameHeader &header)
 351 {
 352     GMX_ASSERT(impl_->bInData_, "notifyDataStart() not called");
 353     GMX_ASSERT(impl_->bInFrame_, "notifyFrameStart() not called");
 354     GMX_ASSERT(header.index() == impl_->currIndex_,
 355                "Header does not correspond to current frame");
 356     impl_->bInFrame_  = false;
 357     impl_->currIndex_ = -1;
 358
 359     // Increment the counter before notifications to allow frame access from
 360     // modules.
 361     ++impl_->nframes_;
 362
 363     Impl::ModuleList::const_iterator i;
 364     for (i = impl_->modules_.begin(); i != impl_->modules_.end(); ++i)
 365     {
 366         (*i)->frameFinished(header);
 367     }
 368 }
 369
 370
 371 void
 372 AbstractAnalysisData::notifyDataFinish() const
 373 {
 374     GMX_RELEASE_ASSERT(impl_->bInData_, "notifyDataStart() not called");
 375     GMX_RELEASE_ASSERT(!impl_->bInFrame_,
 376                        "notifyDataFinish() called while inside a frame");
 377     impl_->bInData_ = false;
 378
 379     Impl::ModuleList::const_iterator i;
 380     for (i = impl_->modules_.begin(); i != impl_->modules_.end(); ++i)
 381     {
 382         (*i)->dataFinished();
 383     }
 384 }
 385 //! \endcond
 386
 387 } // namespace gmx