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                 :    4495789 :     const std::vector< tk::real >& ord() const noexcept { return m_ordinary; }
     104                 :            : 
     105                 :            :     //! Central moments accessor
     106                 :    4495789 :     const std::vector< tk::real >& ctr() const noexcept { return m_central; }
     107                 :            : 
     108                 :            :     //! Ordinary univariate PDFs accessor
     109                 :    4495789 :     const std::vector< tk::UniPDF >& oupdf() const noexcept { return m_ordupdf; }
     110                 :            : 
     111                 :            :     //! Ordinary bivariate PDFs accessor
     112                 :    4495789 :     const std::vector< tk::BiPDF >& obpdf() const noexcept { return m_ordbpdf; }
     113                 :            : 
     114                 :            :     //! Ordinary trivariate PDFs accessor
     115                 :    4495789 :     const std::vector< tk::TriPDF >& otpdf() const noexcept { return m_ordtpdf; }
     116                 :            : 
     117                 :            :     //! Central univariate PDFs accessor
     118                 :    4495789 :     const std::vector< tk::UniPDF >& cupdf() const noexcept { return m_cenupdf; }
     119                 :            : 
     120                 :            :     //! Central bivariate PDFs accessor
     121                 :    4495789 :     const std::vector< tk::BiPDF >& cbpdf() const noexcept { return m_cenbpdf; }
     122                 :            : 
     123                 :            :     //! Central trivariate PDFs accessor
     124                 :    4495789 :     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                 :            :