Branch data Line data Source code
1 : : // *****************************************************************************
2 : : /*!
3 : : \file src/Statistics/Statistics.hpp
4 : : \copyright 2012-2015 J. Bakosi,
5 : : 2016-2018 Los Alamos National Security, LLC.,
6 : : 2019-2021 Triad National Security, LLC.
7 : : All rights reserved. See the LICENSE file for details.
8 : : \brief Statistics class declaration
9 : : \details This file implements a statistics class that can be used to
10 : : estimate statistics from an ensemble. Supported at this time are ordinary
11 : : and central statistical moments of arbitrary-length products and arbitrary
12 : : number of 1D, 2D, and 3D probability density functions (PDF) with sample
13 : : spaces of ordinary and/or central sample space variables.
14 : :
15 : : _Definitions and nomenclature:_
16 : :
17 : : - Upper-case letters denote a full random variable, e.g., X
18 : :
19 : : - Lower-case letters denote a fluctuation about the mean, i.e.,
20 : : x = X - \<X\>
21 : :
22 : : - Letters can be augmented by a field ID, i.e., X2 is the full variable of
23 : : the second component of the vector X, while x1 = X1 - \<X1\> is the
24 : : fluctuation about the mean of the first component of vector X.
25 : :
26 : : - If the field ID is unspecified, it defaults to the first field, i.e.,
27 : : X = X1, x = x1, etc.
28 : :
29 : : - Statistical moments of arbitrary-length products can be computed.
30 : :
31 : : Examples:
32 : : - \<X\> - mean,
33 : : - \<xx\> - variance,
34 : : - \<xxx\> - third central moment,
35 : : - \<xy\> - covariance of X and Y,
36 : : - \<x1y2\> - covariance of the first component of vector X and the second
37 : : component of vector Y
38 : :
39 : : - In general, arbitrary-length products can be estimated that make up a
40 : : statistical moment, using any number and combinations of upper and
41 : : lower-case letters and their field IDs \< [A-Za-z][1-9] ... \>.
42 : :
43 : : - A statistical moment is ordinary if and only if all of its terms are
44 : : ordinary. A central moment has at least one term that is central, i.e., a
45 : : fluctuation about its mean.
46 : :
47 : : - Examples of ordinary moments: \<X\>, \<XX\>, \<XYZ\>, etc.
48 : : - Examples of central moments: \<x1x2\>, \<Xy\>, \<XYz\>, etc.
49 : :
50 : : - Estimation of the PDFs can be done using either ordinary or central sample
51 : : space variables.
52 : :
53 : : Examples:
54 : : - p(X) denotes the univariate PDF of the full variable X,
55 : : - f(x1,x2) denotes the bivariate joint PDF of the fluctuations of the
56 : : variables x1 and x2 about their respective means,
57 : : - g(X,y,Z2) denotes the trivariate joint PDF of variables X,
58 : : y = Y - \<Y\>, and Z2.
59 : :
60 : : \see @ref statistics_output
61 : : */
62 : : // *****************************************************************************
63 : : #ifndef Statistics_h
64 : : #define Statistics_h
65 : :
66 : : #include <vector>
67 : : #include <cstddef>
68 : :
69 : : #include "Types.hpp"
70 : : #include "StatCtr.hpp"
71 : : #include "Particles.hpp"
72 : : #include "SystemComponents.hpp"
73 : : #include "UniPDF.hpp"
74 : : #include "BiPDF.hpp"
75 : : #include "TriPDF.hpp"
76 : :
77 : : namespace tk {
78 : :
79 : : //! Statistics estimator
80 : : class Statistics {
81 : :
82 : : public:
83 : : //! Constructor
84 : : explicit Statistics( const tk::Particles& particles,
85 : : const ctr::OffsetMap& offset,
86 : : const std::vector< ctr::Product >& stat,
87 : : const std::vector< ctr::Probability >& pdf,
88 : : const std::vector< std::vector< tk::real > >& binsize );
89 : :
90 : : //! Accumulate (i.e., only do the sum for) ordinary moments
91 : : void accumulateOrd();
92 : :
93 : : //! Accumulate (i.e., only do the sum for) central moments
94 : : void accumulateCen( const std::vector< tk::real >& om );
95 : :
96 : : //! Accumulate (i.e., only do the sum for) ordinary PDFs
97 : : void accumulateOrdPDF();
98 : :
99 : : //! Accumulate (i.e., only do the sum for) central PDFs
100 : : void accumulateCenPDF( const std::vector< tk::real >& om );
101 : :
102 : : //! Ordinary moments accessor
103 : 5509065 : const std::vector< tk::real >& ord() const noexcept { return m_ordinary; }
104 : :
105 : : //! Central moments accessor
106 : 5509065 : const std::vector< tk::real >& ctr() const noexcept { return m_central; }
107 : :
108 : : //! Ordinary univariate PDFs accessor
109 : 5509065 : const std::vector< tk::UniPDF >& oupdf() const noexcept { return m_ordupdf; }
110 : :
111 : : //! Ordinary bivariate PDFs accessor
112 : 5509065 : const std::vector< tk::BiPDF >& obpdf() const noexcept { return m_ordbpdf; }
113 : :
114 : : //! Ordinary trivariate PDFs accessor
115 : 5509065 : const std::vector< tk::TriPDF >& otpdf() const noexcept { return m_ordtpdf; }
116 : :
117 : : //! Central univariate PDFs accessor
118 : 5509065 : const std::vector< tk::UniPDF >& cupdf() const noexcept { return m_cenupdf; }
119 : :
120 : : //! Central bivariate PDFs accessor
121 : 5509065 : const std::vector< tk::BiPDF >& cbpdf() const noexcept { return m_cenbpdf; }
122 : :
123 : : //! Central trivariate PDFs accessor
124 : 5509065 : const std::vector< tk::TriPDF >& ctpdf() const noexcept { return m_centpdf; }
125 : :
126 : : private:
127 : : /** @name Setup functions, called from the constructor */
128 : : ///@{
129 : : //! Setup ordinary moments
130 : : void setupOrdinary( const ctr::OffsetMap& offset,
131 : : const std::vector< ctr::Product >& stat );
132 : :
133 : : //! Setup central moments
134 : : void setupCentral( const ctr::OffsetMap& offset,
135 : : const std::vector< ctr::Product >& stat );
136 : :
137 : : //! Setup PDFs
138 : : void setupPDF( const ctr::OffsetMap& offset,
139 : : const std::vector< ctr::Probability >& pdf,
140 : : const std::vector< std::vector< tk::real > >& binsize );
141 : : ///@}
142 : :
143 : : //! Return mean for fluctuation
144 : : std::size_t mean(const tk::ctr::Term& term) const;
145 : :
146 : : //! Particle properties
147 : : const tk::Particles& m_particles;
148 : :
149 : : /** @name Data for statistical moment estimation */
150 : : ///@{
151 : : //! Instantaneous variable pointers for computing ordinary moments
152 : : std::vector< std::vector< const tk::real* > > m_instOrd;
153 : : //! Ordinary moments
154 : : std::vector< tk::real > m_ordinary;
155 : : //! Ordinary moment Terms, used to find means for fluctuations
156 : : std::vector< tk::ctr::Term > m_ordTerm;
157 : : //! Number of ordinary moments
158 : : std::size_t m_nord;
159 : :
160 : : //! Instantaneous variable pointers for computing central moments
161 : : std::vector< std::vector< const tk::real* > > m_instCen;
162 : : //! Central moments
163 : : std::vector< tk::real > m_central;
164 : : //! Ordinary moments about which to compute central moments
165 : : std::vector< std::vector< const tk::real* > > m_ctr;
166 : : //! Number of central moments
167 : : std::size_t m_ncen;
168 : : ///@}
169 : :
170 : : /** @name Data for univariate probability density function estimation */
171 : : ///@{
172 : : //! Instantaneous variable pointers for computing ordinary univariate PDFs
173 : : std::vector< std::vector< const tk::real* > > m_instOrdUniPDF;
174 : : //! Ordinary univariate PDFs
175 : : std::vector< tk::UniPDF > m_ordupdf;
176 : :
177 : : //! Instantaneous variable pointers for computing central univariate PDFs
178 : : std::vector< std::vector< const tk::real* > > m_instCenUniPDF;
179 : : //! Central univariate PDFs
180 : : std::vector< tk::UniPDF > m_cenupdf;
181 : : //! Ordinary moments about which to compute central univariate PDFs
182 : : std::vector< std::vector< const tk::real* > > m_ctrUniPDF;
183 : : ///@}
184 : :
185 : : /** @name Data for bivariate probability density function estimation */
186 : : ///@{
187 : : //! Instantaneous variable pointers for computing ordinary bivariate PDFs
188 : : std::vector< std::vector< const tk::real* > > m_instOrdBiPDF;
189 : : //! Ordinary bivariate PDFs
190 : : std::vector< tk::BiPDF > m_ordbpdf;
191 : :
192 : : //! Instantaneous variable pointers for computing central bivariate PDFs
193 : : std::vector< std::vector< const tk::real* > > m_instCenBiPDF;
194 : : //! Central bivariate PDFs
195 : : std::vector< tk::BiPDF > m_cenbpdf;
196 : : //! Ordinary moments about which to compute central bivariate PDFs
197 : : std::vector< std::vector< const tk::real* > > m_ctrBiPDF;
198 : : ///@}
199 : :
200 : : /** @name Data for trivariate probability density function estimation */
201 : : ///@{
202 : : //! Instantaneous variable pointers for computing ordinary trivariate PDFs
203 : : std::vector< std::vector< const tk::real* > > m_instOrdTriPDF;
204 : : //! Ordinary trivariate PDFs
205 : : std::vector< tk::TriPDF > m_ordtpdf;
206 : :
207 : : //! Instantaneous variable pointers for computing central trivariate PDFs
208 : : std::vector< std::vector< const tk::real* > > m_instCenTriPDF;
209 : : //! Central trivariate PDFs
210 : : std::vector< tk::TriPDF > m_centpdf;
211 : : //! Ordinary moments about which to compute central trivariate PDFs
212 : : std::vector< std::vector< const tk::real* > > m_ctrTriPDF;
213 : : ///@}
214 : : };
215 : :
216 : : } // tk::
217 : :
218 : : #endif // Statistics_h
219 : :
|
