documentation for tail (python+c++) and for profiling

doc/reference/c++/contents.rst

@@ -18,3 +18,4 @@ C++
    det_manip/contents
    parameters/parameters
    utilities/contents
+   using_the_lib/profiling

doc/reference/c++/gf/tail.rst

@@ -5,3 +5,68 @@
 High frequency tail
 ===========================
 
+Definition 
+----------------------
+
+The tail of a Green's function is defined as the behavior of the Green's
+function :math:`G` at large Matsubara frequencies, namely
+
+.. math::  \mathbf{G}(i\omega_n) \stackrel {=}{\infty} \mathbf{a}_{-1}\cdot i\omega_n + \mathbf{a}_{0} +\mathbf{a}_{1}\cdot \frac{1}{ i\omega_n} +\mathbf{a}_{2}\cdot \frac{1}{ (i\omega_n)^2} +\dots  
+
+Generically, the tail is parametrized by matrix-valued coefficients
+:math:`\mathbf{a}_{i}` (of size :math:`N_1\times N_2`\ )
+
+.. math:: t = \sum_{i=o_{min}}^{o_{max}} \mathbf{a}_i (i\omega_n)^{-i}
+
+Implementation
+--------------
+
+In TRIQS, the tail is implemented as an object ``tail``. Here is a simple example of use: 
+
+
+.. compileblock:: 
+
+  #include <Python.h>
+  #include <iostream>
+  #include <triqs/gfs/local/tail.hpp>
+  int main(){
+   int N1=1, N2=1;
+   triqs::gfs::local::tail t(N1,N2);
+   t.mask_view() = 5;//only coeffs from -1 to 5 are meaningful
+   std::cout << t(0) << std::endl;
+   t(2) = .5;
+   std::cout << t << std::endl;
+  }
+
+API
+****
+
+
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| Member                          | Description                                                                            | Type                     |
++=================================+========================================================================================+==========================+
+| data()                          | 3-dim array of the coefficients: ``data(i,n,m)`` :math:`=(\mathbf{a}_{i+o_{min}})_{nm}` | data_view_type           |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| mask_view()                     | 2-dim (:math:`N_1 \times N_2`) array of the maximum non-zero indices                   | mask_view_type           |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| order_min()                     | minimum order                                                                          | long                     |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| order_max()                     | maximum order                                                                          | long                     |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| size()                          | first dim of data()                                                                    | size_t                   |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| shape()                         | shape of data()                                                                        | shape_type               |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| smallest_nonzeros()             | order of the smallest_nonzero coefficient                                              | long                     |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| is_decreasing_at_infinity()     | true if the tail is decreasing at infinity                                             | bool                     |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| operator() (int n)              | matrix_valued coefficient :math:`(\mathbf{a}_i)_{nm}`                                  | mv_type                  |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| get_or_zero (int n)             | matrix_valued coefficient :math:`(\mathbf{a}_i)_{nm}`                                  | const_mv_type            |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+| evaluate(dcomplex const &omega) | value of the tail at frequency omega                                                   | arrays::matrix<dcomplex> |
++---------------------------------+----------------------------------------------------------------------------------------+--------------------------+
+    
+   
+The tail is DefaultConstructible, H5Serializable and BoostSerializable.

doc/reference/c++/using_the_lib/profiling.rst

@@ -0,0 +1,35 @@
+Profiling
+##########
+
+One can easily profile c++ and Python code using `Google perftools <http://code.google.com/p/gperftools/>`_. In Ubuntu: ::
+
+  libgoogle-perftools-dev
+  google-perftools
+
+One must link the executable with the profiling library with the flag ``-lprofiler``.
+
+C++
+-------
+
+
+First run the C++ executable (here ``simple_tests``) after setting the environment variable ``CPUPROFILE``: ::
+
+   CPUPROFILE=profile_test.prof ./simple_tests
+
+Then, analyze the results (stored in `profile_test.prof`) with  ``google-pprof``: ::
+
+   google-pprof --text ./simple_tests profile_test.prof | less 
+
+See the documentation of `Google perftools <http://code.google.com/p/gperftools/>`_ for more information.
+
+Python
+--------
+One needs to install the python package `yep <https://pypi.python.org/pypi/yep>`_ (e.g ``easy_install yep``)
+
+First, run your script (``my_test.py``): ::
+
+   pytriqs -myep -v  my_test.py
+
+Then, analyze the results (stored in `my_test.py.prof`) with ``google-pprof``: ::
+
+   google-pprof --text my_test.py my_test.py.prof | less 

doc/reference/python/green/green.rst

@@ -35,4 +35,4 @@ and then proceed with the general Green's function and its block structure.
   block
   transforms
   full
-
+  tail

doc/reference/python/green/tail.rst

@@ -0,0 +1,117 @@
+High-Frequency Tail (``TailGf``)
+=========================================
+
+Definition
+----------------------
+
+The tail of a Green's function is defined as the behavior of the Green's
+function :math:`G` at large Matsubara frequencies, namely
+
+.. math::  \mathbf{G}(i\omega_n) \stackrel {=}{\infty} \mathbf{a}_{-1}\cdot i\omega_n + \mathbf{a}_{0} +\mathbf{a}_{1}\cdot \frac{1}{ i\omega_n} +\mathbf{a}_{2}\cdot \frac{1}{ (i\omega_n)^2} +\dots  
+
+Generically, the tail is parametrized by matrix-valued coefficients
+:math:`\mathbf{a}_{i}` (of size :math:`N_1\times N_2`\ )
+
+.. math:: t = \sum_{i=o_{min}}^{o_{max}} \mathbf{a}_i (i\omega_n)^{-i}
+
+Implementation
+--------------
+
+In TRIQS, the tail is contained in an Python object ``TailGf`` with the
+following members:
+
+-  ``data`` is a numpy array representing :math:`\mathbf{a}_{i}` :
+   ``data[i,m,n]`` :math:`= (\mathbf{a}_i)_{m,n}`\ .
+-  ``mask`` is the :math:`N_1\times N_2` numpy array of the maximal
+   index :math:`i_{nm}` of the known coefficients (``order_max`` may be
+   larger than ``mask``, but all coefficients of indices greater than
+   ``mask`` are irrelevant)
+-  ``N1`` and ``N2`` give the size of each tail coefficient
+   :math:`\mathbf{a}_{i}` : :math:`N_1\times N_2`
+-  ``size`` is the number of coefficients of the tail.
+-  ``__getitem__``and ``__setitem__`` operators: access and set the ith
+   coefficient :math:`\mathbf{a}_{i}` with the bracket operator
+-  ``__call__`` operator: evaluate the tail at a given frequency
+
+Example
+-------
+
+Basic ``TailGf`` object
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. runblock:: python
+
+    from pytriqs.gf.local import *
+    
+    t = TailGf(shape=(1,1))
+    print "t = ",t
+    print "t.data.shape = ",t.data.shape
+    print "t.order_min = ",t.order_min
+    print "t.order_max = ",t.order_max
+    print "t.mask = ",t.mask
+    print "t[1] = ",t[1]
+    t[1]=[1]
+    print "t = ",t
+    t[-1]=.25
+    print "t = ",t
+    print "t(100) = ",t(100)
+
+
+As a member of a Green's function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basic access
+^^^^^^^^^^^^
+
+
+.. runblock:: python
+
+    from pytriqs.gf.local import *
+    
+    # Create the Matsubara-frequency Green's function and initialize it
+    g = GfImFreq(indices = [1], beta = 50, n_points = 1000, name = "imp")
+    g <<= inverse( iOmega_n + 0.5 )
+    
+    print "g.tail = ", g.tail
+    print "g.tail[2] = ",g.tail[2]
+
+Fitting tails: ``fit_tail``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Green's functions have a method ``fit_tail`` allowing to fit the data
+contained in the Green's function. ``fit_tail`` is called in the
+following way:
+
+``fit_tail(fixed_coeff, order_max, fit_start, fit_stop)`` where
+
+-  ``fixed_coeff`` is the :math:`n\times N_1 \times N_2` numpy array of
+   know coefficients
+   (``fixed_coeff[i,n,m]``:math:`\equiv (\mathbf{a}_{-1+i})_{nm}`\ )
+-  ``order_max`` is the maximal index of the coefficients to be
+   determined
+-  ``fit_start`` and ``fit_stop`` are the frequencies between which to
+   fit the data
+
+In the following example, the Green's function ``g`` defined above is
+fitted between :math:`\omega_n=10` and :math:`\omega_n = 20` with fixed
+coefficients :math:`(\mathbf{a}_{-1})_{00} = 0`\ ,
+:math:`(\mathbf{a}_{0})_{00} = 0` and :math:`(\mathbf{a}_{1})_{00} = 1`
+
+.. runblock:: python
+
+    from pytriqs.gf.local import *
+    g = GfImFreq(indices = [1], beta = 50, n_points = 1000, name = "imp")
+    g <<= inverse( iOmega_n + 0.5 )
+    g.tail.zero()
+    fixed_coeff=numpy.zeros([1,1,3],float)
+    fixed_coeff[0,0,0]=0.
+    fixed_coeff[0,0,1]=0.
+    fixed_coeff[0,0,2]=1.
+    order_max = 4
+    fit_start = 10.
+    fit_stop = 20.
+    g.fit_tail(fixed_coeff, order_max, fit_start, fit_stop)
+    print "g.tail = ", g.tail
+
+