2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2013,2014,2015,2019,2021, 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.
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.
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.
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.
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.
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.
37 * Declares gmx::AnalysisDataFrameAverager.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
40 * \ingroup module_analysisdata
42 #ifndef GMX_ANALYSISDATA_MODULES_FRAMEAVERAGER_H
43 #define GMX_ANALYSISDATA_MODULES_FRAMEAVERAGER_H
47 #include "gromacs/utility/basedefinitions.h"
48 #include "gromacs/utility/gmxassert.h"
49 #include "gromacs/utility/real.h"
54 class AnalysisDataPointSetRef;
58 * Helper class for modules that average values over frames.
60 * This class implements common functionality for analysis data modules that
61 * need to average a set of values over frames. Currently, it is designed for
62 * computing averages for each input column independently, but should be
63 * relatively easy to make more general if required.
65 * This class takes care of accumulating the values and computing their
66 * variance. It allows different number of samples for each input column.
67 * Accumulation is always in double precision and uses a formula that is
68 * relatively stable numerically. For now, does nothing fancy,
69 * but provides ground for other implementation (e.g., related to
70 * parallelization) that would benefit all such modules.
72 * Methods in this class do not throw unless otherwise indicated.
74 * \ingroup module_analysisdata
76 class AnalysisDataFrameAverager
79 AnalysisDataFrameAverager() : bFinished_(false) {}
82 * Returns the number of columns in this averager.
84 int columnCount() const { return values_.size(); }
87 * Sets the number of columns in the input data.
89 * \throws std::bad_alloc if out of memory.
91 * Typically called from IAnalysisDataModule::dataStarted().
93 * Must be called exactly once, before setting calling any other method
96 void setColumnCount(int columnCount);
98 * Adds a single value to the average for a given column.
100 * \param[in] index Index of the column to add the value to.
101 * \param[in] value Value to add to the sample.
103 void addValue(int index, real value);
105 * Accumulates data from a given point set into the average.
107 * Typically called from IAnalysisDataModule::pointsAdded().
109 * Each call accumulates the values for those columns that are present
110 * in the point set. Can be called multiple times for a frame, and
111 * does not need to be called for every frame.
113 void addPoints(const AnalysisDataPointSetRef& points);
115 * Finalizes the calculation of the averages and variances.
117 * Does any computation that is not done during the accumulation in
118 * addPoints(). Currently, does nothing, but provided as a placeholder
119 * for more complex implementation.
121 * Typically called from IAnalysisDataModule::dataFinished().
126 * Returns the computed average for a given column.
128 * If called before finish(), the results are undefined.
130 real average(int index) const
132 GMX_ASSERT(index >= 0 && index < columnCount(), "Invalid column index");
133 GMX_ASSERT(bFinished_, "Values available only after finished() has been called");
134 return values_[index].average;
137 * Returns the computed (sample) variance for a given column.
139 * If called before finish(), the results are undefined.
141 real variance(int index) const
143 GMX_ASSERT(index >= 0 && index < columnCount(), "Invalid column index");
144 GMX_ASSERT(bFinished_, "Values available only after finished() has been called");
145 const AverageItem& item = values_[index];
146 return item.samples > 1 ? item.squaredSum / (item.samples - 1) : 0.0;
149 * Returns the number of samples for a given column.
151 * If called before finish(), the results are undefined.
153 int sampleCount(int index) const
155 GMX_ASSERT(index >= 0 && index <= ssize(values_), "Invalid column index");
156 GMX_ASSERT(bFinished_, "Values available only after finished() has been called");
157 return values_[index].samples;
163 AverageItem() : average(0.0), squaredSum(0.0), samples(0) {}
165 //! Average of the values so far.
167 //! Sum of squared deviations from the average for values so far.
169 //! Number of values so far.
173 std::vector<AverageItem> values_;