From 14067abb342d09161655736102b1c3eba55f1f80 Mon Sep 17 00:00:00 2001 From: tayral Date: Thu, 13 Feb 2014 17:37:42 +0000 Subject: [PATCH] Statistical tools documentation. --- doc/reference/c++/contents.rst | 1 + .../c++/statistics/autocorrelation_time.rst | 10 ++ doc/reference/c++/statistics/binning.rst | 26 +++++ doc/reference/c++/statistics/contents.rst | 99 +++++++++++++++++++ doc/reference/c++/statistics/ising2d.rst | 11 +++ doc/reference/c++/statistics/jackknife.rst | 33 +++++++ doc/reference/c++/statistics/src | 1 + triqs/statistics.hpp | 1 + 8 files changed, 182 insertions(+) create mode 100644 doc/reference/c++/statistics/autocorrelation_time.rst create mode 100644 doc/reference/c++/statistics/binning.rst create mode 100644 doc/reference/c++/statistics/contents.rst create mode 100644 doc/reference/c++/statistics/ising2d.rst create mode 100644 doc/reference/c++/statistics/jackknife.rst create mode 120000 doc/reference/c++/statistics/src diff --git a/doc/reference/c++/contents.rst b/doc/reference/c++/contents.rst index 9b6e3c62..71d782fb 100644 --- a/doc/reference/c++/contents.rst +++ b/doc/reference/c++/contents.rst @@ -17,5 +17,6 @@ C++ mctools/intro det_manip/contents parameters/parameters + statistics/contents utilities/contents using_the_lib/profiling diff --git a/doc/reference/c++/statistics/autocorrelation_time.rst b/doc/reference/c++/statistics/autocorrelation_time.rst new file mode 100644 index 00000000..2f40146b --- /dev/null +++ b/doc/reference/c++/statistics/autocorrelation_time.rst @@ -0,0 +1,10 @@ +Autocorrelation time +===================== + +Synopsis +--------- + + + +Example +-------- diff --git a/doc/reference/c++/statistics/binning.rst b/doc/reference/c++/statistics/binning.rst new file mode 100644 index 00000000..016f954f --- /dev/null +++ b/doc/reference/c++/statistics/binning.rst @@ -0,0 +1,26 @@ +Binning +========== + +Synopsis +---------- + +`make_binned_series(T series, int bin_size)` + - series: object with **TimeSeries** concept + - bin_size: size of the bin + + returns the binned time series. + +Example +-------- + +.. compileblock:: + + #include + using namespace triqs::statistics; + int main(){ + observable A; + A<<1.;A<<1.5;A<<.2;A<<1.1; + auto A_b = make_binned_series(A,2); + std::cout << A_b << std::endl; + return 0; + } diff --git a/doc/reference/c++/statistics/contents.rst b/doc/reference/c++/statistics/contents.rst new file mode 100644 index 00000000..338db340 --- /dev/null +++ b/doc/reference/c++/statistics/contents.rst @@ -0,0 +1,99 @@ +Tools for statistical analysis: binning and jackknife +====================================================== + +Introduction +------------- +Given the statistical samples :math:`\lbrace x_i\rbrace _{i=0\dots N-1}` and :math:`\lbrace y_i\rbrace _{i=0\dots N-1}` of random variables :math:`X` and :math:`Y`, one often wants to compute the estimate of the following observables: + +:math:`\langle X \rangle`, :math:`\langle X\rangle/\langle Y \rangle`, :math:`\langle X \rangle^2`, or in general :math:`f(\langle X \rangle , \langle Y \rangle, \dots)` + +as well as the estimate of the errors: + +:math:`\Delta\langle X \rangle`, :math:`\Delta\langle X\rangle /\langle Y \rangle`, :math:`\Delta\langle X\rangle ^2` or :math:`\Delta f(\langle X \rangle , \langle Y \rangle, \dots)` + +The estimate of the expectation values is the empirical average : + +:math:`\langle X \rangle \approx \frac{1}{N} \sum_{i=0}^{N-1} x_i` + +If the samples are independent from each other and :math:`f` is a linear function of its variables (e.g :math:`f=Id`): + +:math:`(\Delta \langle X \rangle)^2 \approx \frac{\frac{N-1}{N} \sigma^2({x})}{N}` + +where :math:`\sigma^2({x})` is the empirical variance of the sample. + + +In the general case, however, + + - the samples are correlated (with a characteristic correlation time): one needs to :doc:`bin ` the series to obtain a reliable estimate of the error bar + - :math:`f` is non-linear in its arguments: one needs to :doc:`jackknife ` the series + + +This library allows one to reliably compute the estimates of :math:`f(\langle X \rangle , \langle Y \rangle, \dots)` and its error bar :math:`\Delta f(\langle X \rangle , \langle Y \rangle, \dots)` in the general case. + +Synopsis +--------- +`average_and_error` takes an object with the **Observable** concept (see below) and returns a struct with two members `val` and `error`: + - `val` is the estimate of the expectation value of the random variable for a given sample of it + - `error` is the estimate of the error on this expectation value for the given sample + +Concepts +--------- + +TimeSeries +~~~~~~~~~~~ +An object has the concept of a TimeSeries if it has the following member functions: + ++-------------+-------------------+ +| Return type | Name | ++=============+===================+ +| value_type | operator[](int i) | ++-------------+-------------------+ +| int | size() | ++-------------+-------------------+ + +and the following member type: + ++-------------+------------------------------------------+ +| Name | Property | ++=============+==========================================+ +| value_type | belong to an algebra (has +,- operators) | ++-------------+------------------------------------------+ + +Observable +~~~~~~~~~~~ + +An object has the concept of an observable if it is a TimeSeries and has, additionally, the following member function: + ++-------------+-----------------+ +| Return type | Name | ++=============+=================+ +| observable& | operator<<(T x) | ++-------------+-----------------+ + +where `T` belongs to an algebra. + +Example +-------- + +.. compileblock:: + + #include + #include + using namespace triqs::statistics; + int main(){ + observable X; + X<<1.0; + X<<-1.0; + X<<.5; + X<<.0; + std::cout << average_and_error(X) << std::endl; + std::cout << average_and_error(X*X) << std::endl; + return 0; + } + + +.. toctree:: + binning + jackknife + autocorrelation_time + ising2d diff --git a/doc/reference/c++/statistics/ising2d.rst b/doc/reference/c++/statistics/ising2d.rst new file mode 100644 index 00000000..4d57dc9c --- /dev/null +++ b/doc/reference/c++/statistics/ising2d.rst @@ -0,0 +1,11 @@ +.. highlight:: c + +Full example: Monte-Carlo simulation of the 2D Ising model +=========================================================== + + +.. literalinclude:: src/ising2d.cpp + +The output is + +.. literalinclude:: src/ising2d.output diff --git a/doc/reference/c++/statistics/jackknife.rst b/doc/reference/c++/statistics/jackknife.rst new file mode 100644 index 00000000..3d099c6d --- /dev/null +++ b/doc/reference/c++/statistics/jackknife.rst @@ -0,0 +1,33 @@ +.. highlight:: c + +Jackknife +============ + +Synopsis +--------- + + +`make_jackknife(T series)` + - series: object with **TimeSeries** concept + + returns the jackknifed time series. + + + + + +Example +--------- + +.. compileblock:: + + #include + using namespace triqs::statistics; + int main(){ + observable A; + A<<1.;A<<1.5;A<<.2;A<<1.1; + auto A_j = make_jackknife(A); + std::cout << A_j << std::endl; + return 0; + } + diff --git a/doc/reference/c++/statistics/src b/doc/reference/c++/statistics/src new file mode 120000 index 00000000..2ed39df4 --- /dev/null +++ b/doc/reference/c++/statistics/src @@ -0,0 +1 @@ +../../../../test/triqs/statistics \ No newline at end of file diff --git a/triqs/statistics.hpp b/triqs/statistics.hpp index 27ec0eee..05a97708 100644 --- a/triqs/statistics.hpp +++ b/triqs/statistics.hpp @@ -19,5 +19,6 @@ * ******************************************************************************/ #pragma once +#include "./clef.hpp" #include "./statistics/statistics.hpp"