/*
+ * This file is part of the GROMACS molecular simulation package.
*
- * This source code is part of
+ * Copyright (c) 2010,2011,2012,2013,2014, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
*
- * G R O M A C S
+ * GROMACS is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
*
- * GROningen MAchine for Chemical Simulations
+ * GROMACS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
*
- * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
- * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
- * Copyright (c) 2001-2009, The GROMACS development team,
- * check out http://www.gromacs.org for more information.
-
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with GROMACS; if not, see
+ * http://www.gnu.org/licenses, or write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
- * If you want to redistribute modifications, please consider that
- * scientific software is very special. Version control is crucial -
- * bugs must be traceable. We will be happy to consider code for
- * inclusion in the official distribution, but derived work must not
- * be called official GROMACS. Details are found in the README & COPYING
- * files - if they are missing, get the official version at www.gromacs.org.
+ * If you want to redistribute modifications to GROMACS, please
+ * consider that scientific software is very special. Version
+ * control is crucial - bugs must be traceable. We will be happy to
+ * consider code for inclusion in the official distribution, but
+ * derived work must not be called official GROMACS. Details are found
+ * in the README & COPYING files - if they are missing, get the
+ * official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
- * the papers on the package - you can find them in the top README file.
- *
- * For more info, check our website at http://www.gromacs.org
+ * the research papers on the package. Check out http://www.gromacs.org.
*/
/*! \file
* \brief
* Declares gmx::AnalysisData and gmx::AnalysisDataHandle.
*
- * \author Teemu Murtola <teemu.murtola@cbr.su.se>
+ * \author Teemu Murtola <teemu.murtola@gmail.com>
* \inpublicapi
* \ingroup module_analysisdata
*/
#ifndef GMX_ANALYSISDATA_ANALYSISDATA_H
#define GMX_ANALYSISDATA_ANALYSISDATA_H
-#include "abstractdata.h"
+#include "gromacs/analysisdata/abstractdata.h"
+#include "gromacs/utility/real.h"
namespace gmx
{
*
* This is the main class used to implement parallelizable data processing in
* analysis tools. It is used by first creating an object and setting its
- * properties using setColumnCount() and setMultipoint(), and attaching
- * necessary modules using addModule() etc. Then one or more
+ * properties using setDataSetCount(), setColumnCount() and setMultipoint(),
+ * and attaching necessary modules using addModule() etc. Then one or more
* AnalysisDataHandle objects can be created using startData(). Each data
* handle can then be independently used to provide data frames (each frame
* must be provided by a single handle, but different frames can be freely
* expect them.
*
* \todo
- * Currently, multiple handles with multipoint data are not implemented.
- *
- * \todo
* Parallel implementation is not complete.
*
* \if internal
virtual ~AnalysisData();
/*! \brief
- * Sets the number of columns in the data.
+ * Sets the number of data sets.
*
- * \param[in] ncol Number of columns in the data (must be > 0).
+ * \param[in] dataSetCount Number of data sets (must be > 0).
+ * \throws std::bad_alloc if out of memory.
+ * \throws APIError if modules have been added that are not
+ * compatible with the new data set count.
*
- * Must be called before startData(), and can be called multiple times
- * before modules are added.
* Must not be called after startData() has been called.
+ * If not called, a single data set is assumed.
+ * If called multiple times, the last call takes effect.
+ */
+ void setDataSetCount(int dataSetCount);
+ /*! \brief
+ * Sets the number of columns in a data set.
*
- * Does not currently throw, but this may change for the case that
- * modules have already been added.
+ * \param[in] dataSet Zero-based data set index.
+ * \param[in] columnCount Number of columns in the data (must be > 0).
+ * \throws APIError if modules have been added that are not
+ * compatible with the new column count.
+ *
+ * Must be called before startData() for each data set.
+ * Must not be called after startData() has been called.
+ * If called multiple times for a data set, the last call takes effect.
*/
- void setColumnCount(int ncol);
+ void setColumnCount(int dataSet, int columnCount);
/*! \brief
* Sets whether the data contains multiple points per column per frame.
*
* \param[in] bMultipoint Whether the data will allow multiple points
* per column within a single frame.
+ * \throws APIError if modules have been added that are not
+ * compatible with the new setting.
*
* If this method is not called, the data is not multipoint.
*
- * Must not be called after modules have been added or startData() has
- * been called.
- *
- * Does not currently throw, but this may change for the case that
- * modules have already been added.
+ * Must not be called after startData() has been called.
*
* \see isMultipoint()
*/
void setMultipoint(bool bMultipoint);
+ virtual int frameCount() const;
+
/*! \brief
* Create a handle for adding data.
*
* called.
*
* For simple (non-multipoint) data, within a frame values can be set using
- * setPoint() and setPoints(). Setting the same column multiple times
- * overrides previously set values. When the frame is finished, attached
- * modules are notified.
+ * selectDataSet(), setPoint() and setPoints(). Setting the same column in the
+ * same data set multiple times overrides previously set values.
+ * When the frame is finished, attached modules are notified.
*
* Multipoint data works otherwise similarly, but requires finishPointSet() to
* be called for each set of points for which the modules need to be notified.
* Each point set starts empty (after startFrame() or finishPointSet()), and
- * values can be set using setPoint()/setPoints(). finishPointSet() must also
- * be called for the last point set just before finishFrame().
+ * values can be set using setPoint()/setPoints().
+ * A single point set can contain values only for a single data set, which must
+ * be selected with selectDataSet() before setting any values.
+ * finishPointSet() must also be called for the last point set just before
+ * finishFrame().
*
* This class works like a pointer type: copying and assignment is lightweight,
* and all copies work interchangeably, accessing the same internal handle.
*/
AnalysisDataHandle();
+ //! Returns whether this data handle is valid.
+ bool isValid() const { return impl_ != NULL; }
+
/*! \brief
* Start data for a new frame.
*
* is not finished).
*/
void startFrame(int index, real x, real dx = 0.0);
+ /*! \brief
+ * Selects a data set for subsequent setPoint()/setPoints() calls.
+ *
+ * \param[in] index Zero-based data set index.
+ *
+ * After startFrame(), the first data set is always selected.
+ * The set value is remembered until the end of the current frame, also
+ * across finishPointSet() calls.
+ *
+ * Does not throw.
+ */
+ void selectDataSet(int index);
/*! \brief
* Set a value for a single column for the current frame.
*
/*! \brief
* Creates a new data handle associated with \p data.
*
- * \param data Data to associate the handle with.
+ * \param impl Data to associate the handle with.
*
* The constructor is private because data handles should only be
* constructed through AnalysisData::startData().
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff