Work on doc

- remove empty parts, start to clean the tour.
- added export of _template and _static to reuse in appli doc.
- clean tutorial part. rm cookbook.

doc/CMakeLists.txt

@@ -106,12 +106,15 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ COMPONENT documentation DEST
  PATTERN "*.py"
  PATTERN "*.txt"
  PATTERN "*.bib"
+ PATTERN "*.inv"
  PATTERN ".svn" EXCLUDE 
  PATTERN "CVS" EXCLUDE
  )
 
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/themes/agogo DESTINATION share/triqs/themes)
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/themes/triqs DESTINATION share/triqs/themes)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/_static DESTINATION share/triqs/export)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/_templates DESTINATION share/triqs/export)
 
 # PDF documentation
 if (Build_PDF_Documentation)

doc/_templates/sideb.html

@@ -6,9 +6,11 @@
 <img style="width: 80px; margin: 10px 0 0 5px" src='_static/logo_erc.jpg' alt="ERC"/> 
 </p>
 
+<!--
 <h3><a href="applications.html">TRIQS applications</a></h3>
 
 <p>
 Some applications are supported by the TRIQS collaboration, 
 <a class="reference external" href="{{ pathto("applications") }}">check them out!</a>
 </p>
+-->

doc/_templates/sideb_appli.html

@@ -0,0 +1,9 @@
+<p>
+<a href="http://ipht.cea.fr"> <img style="width: 80px; margin: 10px 5px 0 0" src='_static/logo_cea.png' alt="CEA"/> </a>
+<a href="http://www.cpht.polytechnique.fr"> <img style="width: 80px; margin: 10px 5px 0 5px" src='_static/logo_x.png' alt="Ecole Polytechnique"/> </a>
+<br>
+<a href="http://www.cnrs.fr"> <img style="width: 80px; margin: 10px 0 0 5px" src='_static/logo_cnrs.png' alt="CNRS"/> </a>
+<img style="width: 80px; margin: 10px 0 0 5px" src='_static/logo_erc.jpg' alt="ERC"/> 
+</p>
+
+

doc/documentation.rst

@@ -9,24 +9,19 @@ A quick tour
 .. toctree::
    :maxdepth: 1
 
-   overview
+   tutorials/python/introduction
-   tutorials/contents
+   tutorials/c++/contents
 
-C++ libraries
+Reference manual 
--------------
+-----------------
+
+This is the reference manual for the Python and the C++ libraries.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
-
-   reference/c++/contents
-
-Python modules
---------------
-
-.. toctree::
-   :maxdepth: 1
 
    reference/python/contents
+   reference/c++/contents
 
 Version compatibility
 ---------------------

doc/index.rst

@@ -11,31 +11,33 @@ Welcome
    have changed too. So go look at our :ref:`changelog page <changelog>`
    to find out how to upgrade to 1.0.
 
-TRIQS is a scientific project providing a set of C++ and Python libraries to develop new tools
+TRIQS (**T**\oolbox for **R**\esearch on **I**\nteracting **Q**\uantum **S**\ystems)
+is a scientific project providing a set of C++ and Python libraries to develop new tools
 for the study of interacting quantum systems. 
 
 The goal of this toolkit is to provide condensed matter physicists with 
-high quality, high level, efficient and simple to use libraries in C++ and Python,
+high level, efficient and simple to use libraries in C++ and Python,
-and to promote the use of modern programming techniques and practices in our field.
+and to promote the use of modern programming techniques in our field.
 
 TRIQS is free software (GPL).
 
 TRIQS applications
 -----------------------
 
-Several :ref:`full-fledged applications <applications>` have been written using
+Based on the TRIQS toolkit, several :ref:`full-fledged applications <applications>`
-TRIQS and are also maintained by the TRIQS collaboration. They allow for example to
+are also maintained by the TRIQS collaboration. They allow for example to
 solve a generic quantum impurity model or to run a complete LDA+DMFT
 calculation.
 
-Since 2005, the TRIQS library and applications have allowed to address
+Elaborated in a collaboration between IPhT Saclay and Ecole Polytechnique since 2005, 
-questions as diverse as:
+the TRIQS library and applications have allowed to address questions as diverse as:
 
 * Momentum-selective aspects on cuprate superconductors (with various cluster DMFT)
 * Degree of correlation in iron-based superconductors (within an LDA+DMFT approach)
 * Fermionic Mott transition and exploration of Sarma phase in cold-atoms
 
-C++ & Python 
+ 
+Python & C++
 -----------------------------
 
 The libraries exist at two

doc/install.rst

@@ -7,7 +7,11 @@
 Installation 
 ============
 
-This page describes the installation of TRIQS itself. The installation of the applications based on TRIQS
+TRIQS and its applications are provided *à la carte*: 
+after you have installed the TRIQS toolkit, you will be able to easily install 
+various TRIQS-based applications: impurity solvers, realistic DMFT tools, ...
+
+This page describes the installation of the TRIQS toolkit itself. The installation of the applications
 is described in their respective documentation.
 
 Prerequisite
@@ -41,7 +45,7 @@ Installation steps
      $ cmake -DCMAKE_INSTALL_PREFIX=path_to_install_directory ../src
 
    If you omit ``CMAKE_INSTALL_PREFIX``, the default
-   ``path_to_install_directory`` is a subdirectory ``INSTALL_DIR`` in your build
+   ``path_to_install_directory`` is the subdirectory *INSTALL_DIR* in your build
    directory. More configuration options are described in the
    :ref:`cmake options <install_options>`.
 

doc/installation/osx_lion.rst

@@ -1,7 +1,8 @@
-.. index:: install_on_osx_lion
+.. index:: install_osx_lion
+
+.. highlight:: bash
 
 .. _install_on_osx_lion:
-.. highlight:: bash
 
 Installing required libraries on Mac OS X
 =========================================

doc/reference/c++/arrays/cookbook/contents.rst

@@ -1,12 +0,0 @@
-Arrays cookbook : learn through simple examples... 
-**********************************************************************************
-
-.. highlight:: c
-
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   basic
-   intermediate 
-    

doc/reference/c++/arrays/cookbook/intermediate.rst

@@ -1,6 +0,0 @@
-
-Intermediate 
-===============
-
-.. highlight:: c
-

doc/reference/c++/contents.rst

@@ -1,5 +1,5 @@
 
-C++ libraries
+C++
 =============
 
 .. toctree::

doc/reference/c++/gf/cookbook/contents.rst

@@ -1,11 +0,0 @@
-.. _greenfunctions:
-
-Green's function cookbook
-==========================
-
-
-.. toctree::
-   :maxdepth: 2
-
-   real
-   imaginary

doc/reference/c++/gf/cookbook/imaginary.rst

@@ -1,2 +0,0 @@
-Learn more in the full referencen, see :ref:`greenfunctions`
-

doc/reference/c++/gf/cookbook/real.rst

@@ -1,20 +0,0 @@
-
-Create a real frequency Green function 
---------------------------------------
-.. compileblock:: 
-
-    #include <triqs/arrays.hpp>
-    #include <triqs/gfs/refreq.hpp>
-    
-    using triqs::gfs::make_gf;
-    using triqs::gfs::refreq;
-
-    int main() {
-      double wmin=0;
-      double wmax=10;
-      size_t n_freq=5;
-      //we want a Green function whose values are 2*2 matrices of complex numbers
-      auto shape = triqs::arrays::make_shape(2,2);
-      auto GF=make_gf<refreq>(wmin, wmax, n_freq, shape);
-    };
-

doc/reference/c++/utilities/exceptions.rst

@@ -4,53 +4,54 @@
 .. _util_exceptions:
 
 Exceptions
-=============================
+=============
 
 
 TRIQS defines special exceptions, with the following characteristics :
 
-* they derives from std::exceptions and have the interface
+* they derives from std::exceptions 
 * their .what() contains : 
 
   * the file and line where the exception occurred
   * an additionnal error message (see example below). The error behaves like a std::stringstream, 
     one can accumulate any message
   * a complete stack strace of the C++ code at the exception point, with demangling of the function name (on gcc and clang).
-  * the boost python interface catches these exceptions and report all the information , for debugging.
-    So instead of having "Unknown exception in C++", you have a complete trace of the problem that occurred.
 
 .. warning::
   
    For uniformity, it is highly recommended to use these macros when developing for TRIQS.
 
-Example of use ::
+Example : 
 
+.. compileblock::
+
+    // automatically included in e.g. arrays, gfs, any triqs library...
     #include <triqs/utility/exceptions.hpp> 
     
-  ...
+    int main() { 
-  if (!condition) TRIQS_RUNTIME_ERROR <<" The value of a = "<<a<<" is not in the expected range" << R;
+     if (2!=3) TRIQS_RUNTIME_ERROR <<" The condition is false because "<< 2 << "!=" << 3;
-  ...
+    }
 
-List of available exceptions : 
+The exception can of course be caught :
 
-* TRIQS_RUNTIME_ERROR. 
+.. compileblock::
-
-  This macro is simply ::
-
-   #define TRIQS_RUNTIME_ERROR  throw triqs::runtime_error()<<" Triqs runtime error at "<<__FILE__<< " : "<<__LINE__<<"\n\n Trace is :\n\n"<<triqs::utility::stack_trace()<<"\n"
-
-  So it can be catched with the `triqs::runtime_error` type, e.g. ::
 
+    // automatically included in e.g. arrays, gfs, any triqs library...
     #include <triqs/utility/exceptions.hpp>
+    #include <iostream> 
     
+    void f() { 
      try { 
-      ...
+      if (2!=3) TRIQS_RUNTIME_ERROR <<" The condition is false because "<< 2 << "!=" << 3;
-      if (!condition) TRIQS_RUNTIME_ERROR <<" The value of a = "<<a<<" is not in the expected range" << R;
-      ...
      }
      catch (triqs::runtime_error const & e) { 
       std::cout << "caught error "<< e.what()<<std::endl;
      }
+    } 
+    
+    int main() { 
+     f();
+    }
 
 
 

doc/reference/python/contents.rst

@@ -1,5 +1,5 @@
 
-Python libraries
+Python
 ================
 
 .. toctree::

doc/tutorials/c++/array_tutorial.rst

@@ -1,9 +1,10 @@
-Basic 
+Using arrays
-============
+===============
 
 .. highlight:: c
 
 
+
 Declaring and printing an array
 -------------------------------
 .. compileblock:: 
@@ -37,19 +38,6 @@ Simple operations
     }
 
 
-Simple functions
--------------------
-.. compileblock:: 
-
-    #include <triqs/arrays.hpp>
-    using triqs::arrays::array;
-    int main(){
-      array<double,1> A(10),B(10);
-      A()=2;B()=3;
-      ///.....
-    }
-
-
 HDF5 Archiving
 -------------------
 Archiving an array into an HDF5 file is easy:
@@ -185,35 +173,3 @@ Map and fold
     }
 
 
-Bound checking
----------------
-By default, there is no bound checking:
-
-.. compileblock::
-
-    #include <triqs/arrays.hpp>
-    using triqs::arrays::array;
-    int main(){
-        array<double,2> A(2,2); A() = 3;   
-        std::cout << A(0,3) << std::endl;            
-    }
-
-But one can add bound-checking by adding a preprocessor command:
-
-.. compileblock::
-
-    #define TRIQS_ARRAYS_ENFORCE_BOUNDCHECK
-    #include <triqs/arrays.hpp>
-    using triqs::arrays::array;
-    int main(){
-        try { 
-          array<double,2> A(2,2); A() = 3;   
-          std::cout << A(0,3) << std::endl;            
-        }
-        //catch (triqs::arrays::key_error & e) { std::cout<< e.what()<< std::endl;}
-        catch (std::exception & e) { std::cout<< e.what()<< std::endl;} // or like this : triqs::arrays::key_error derives from std::exception
-    }
-
-
-
-  

doc/tutorials/c++/contents.rst

@@ -1,8 +1,14 @@
 C++ libraries
 =================================
 
+.. warning::
+
+  TO BE WRITTEN
+
 .. toctree::
    :maxdepth: 1  
 
-   ../../reference/c++/arrays/cookbook/contents
+
-   ../../reference/c++/gf/cookbook/contents
+
+..
+   array_tutorial

doc/tutorials/python/aim.py

@@ -0,0 +1,42 @@
+from pytriqs.gf.local import *
+from pytriqs.operators import *
+from pytriqs.applications.impurity_solvers.cthyb_matrix import Solver
+
+D, V, U = 1.0, 0.2, 4.0
+e_f, Beta = -U/2.0, 50
+
+# The impurity solver
+S = Solver(Beta = Beta,                             # inverse temperature
+           GFstruct = [ ('up',[1]), ('down',[1]) ], # Structure of the Green's function 
+           H_Local = U * N('up',1) * N('down',1),   # Local Hamiltonian 
+           Quantum_Numbers = {                      # Quantum Numbers 
+               'Nup' : N('up',1),                   # (operators commuting with H_Local) 
+               'Ndown' : N('down',1) },          
+           N_Cycles  = 500000,                      # Number of QMC cycles
+           Length_Cycle = 200,                      # Length of one cycle 
+           N_Warmup_Cycles = 10000,                 # Warmup cycles
+           N_Legendre_Coeffs = 50,                  # Number of Legendre coefficients
+           Random_Generator_Name = 'mt19937',       # Name of the random number generator
+           Use_Segment_Picture = True,              # Use the segment picture
+           Measured_Operators = {                   # Operators to be averaged
+             'Nimp' : N('up',1)+N('down',1) },
+           Global_Moves = [                         # Global move in the QMC
+               (0.05, lambda (a,alpha,dag) : ( {'up':'down','down':'up'}[a],alpha,dag ) ) ], 
+           )
+
+# Initialize the non-interacting Green's function S.G0
+for spin, g0 in S.G0 :
+    g0 <<= inverse( iOmega_n - e_f - V**2 * Wilson(D) ) 
+
+# Run the solver. The result will be in S.G
+S.Solve()
+
+# Save the results in an hdf5 file (only on the master node)
+from pytriqs.archive import HDFArchive
+import pytriqs.utility.mpi as mpi
+
+if mpi.is_master_node():
+  Results = HDFArchive("solution.h5",'w')
+  Results["G"] = S.G
+  Results["Gl"] = S.G_Legendre
+  Results["Nimp"] = S.Measured_Operators_Results['Nimp']

doc/tutorials/python/aim_plot.py

@@ -0,0 +1,6 @@
+from pytriqs.gf.local import *
+from pytriqs.archive import *
+from pytriqs.plot.mpl_interface import oplot
+
+A = HDFArchive("solution.h5")
+oplot(A['G']['up'], '-o', x_window = (0,10))

doc/tutorials/python/introduction.rst

@@ -1,33 +1,11 @@
 .. index:: introduction
 .. role:: red
 
-Python modules
+Python 
 ==================================
 
-TRIQS (**T**\oolbox for **R**\esearch on **I**\nteracting **Q**\uantum **S**\ystems)
+This introduction is a little tour of some aspects of TRIQS and some of its applications, 
-is a free software scientific project 
+at the Python level. The goal is not to explain here in details but to quickly show some of TRIQS's current capabilities.
-that aims at providing tools for the theoretical study of strongly correlated quantum systems.
-It is based on some of the codes originally developed and used at IPhT Saclay and Ecole Polytechnique since 2005
-(see :ref:`credits <collaboration>`).
-It is implemented as a `Python <http://www.python.org>`_  library, with Python, C++ and Fortran codes and contains : 
-
-* Various basic objects e.g. : 
-
-  * Local Green's functions of various kinds.
-  * Bravais lattices, tight-binding hoppings, local density of states, superlattices (for cluster methods)
-  * Some simple *k*-sums over the Brillouin zone.
-
-* Optional extension modules :
-
-  * Quantum impurity solvers :
-
-     * :ref:`Continuous-time hybridization Quantum Monte Carlo  <ctqmc_hyb>`.
-     * :ref:`Hubbard I <hubbardI>`.
-
-  * :ref:`Wien2TRIQS <Wien2k>` : an interface to the Wien2k electronic structure code for performing LDA+DMFT computations.
-
-The rest of the introduction is a little demo of examples used elsewhere in the documentation.
-The goal is not to explain them here in details but to quickly show some of TRIQS's current capabilities.
 
 .. toctree::
    :maxdepth: 1

doc/tutorials/python/reading.rst

@@ -1,5 +1,5 @@
 
-Recommended reading and references 
+Learning Python : recommended reading and references 
 ----------------------------------------------------------
 
 * A good set of lectures is the `Scipy lecture notes <http://scipy-lectures.github.com/>`_.   

doc/tutorials/python/single_site_bethe.py

@@ -0,0 +1,48 @@
+from pytriqs.gf.local import *
+from pytriqs.archive import *
+import pytriqs.utility.mpi as mpi
+
+# Set up a few parameters
+Half_Bandwidth = 1.0    
+U = 2.5
+Chemical_Potential = U/2.0
+Beta = 100
+N_loops = 5
+
+# Construct a CTQMC solver
+from pytriqs.applications.impurity_solvers.operators import *                          # imports the class manipulating C, C_dagger and N = C_dagger C
+from pytriqs.applications.impurity_solvers.cthyb_matrix import Solver        # imports the solver class
+S = Solver(Beta = Beta,                                                       # inverse temperature
+           GFstruct = [ ('up',[1]), ('down',[1]) ],                           # Structure of the Green function 
+           H_Local = U * N('up',1) * N('down',1),                             # Local Hamiltonian 
+           Quantum_Numbers = { 'Nup' : N('up',1), 'Ndown' : N('down',1) },    # Quantum Numbers (operators commuting with H_Local)
+           N_Cycles = 5000,                                                   # Number of QMC cycles
+           Length_Cycle = 200,                                                # Length of a cycle
+           N_Warmup_Cycles = 1000,                                            # How many warmup cycles
+           N_Legendre_Coeffs = 30,                                            # Use 30 Legendre coefficients to represent G(tau)
+           Random_Generator_Name = "mt19937",                                 # Use the Mersenne Twister 19937 random generator
+           Use_Segment_Picture = True)                                        # Here we can use the segment picture
+
+# Initalize the Green's function to a semi circular
+S.G <<= SemiCircular(Half_Bandwidth)
+
+# Now do the DMFT loop 
+for IterationNumber in range(N_loops):
+
+    # Compute S.G0 with the self-consistency condition while imposing paramagnetism 
+    g = 0.5 * ( S.G['up'] + S.G['down'] )
+    for name, g0block in S.G0:
+        g0block <<= inverse( iOmega_n + Chemical_Potential - (Half_Bandwidth/2.0)**2  * g )
+    
+    # Run the solver
+    S.Solve()
+
+    # Some intermediate saves
+    if mpi.is_master_node():
+      R = HDFArchive("single_site_bethe.h5")
+      R["G-%s"%IterationNumber] = S.G
+      del R
+
+    # Here we would usually write some convergence test
+    # if Converged : break  
+

doc/tutorials/python/tour1.rst

@@ -21,6 +21,6 @@ Finally, the obtained bath and impurity densities of states are plotted using th
    :include-source:
    :scale: 70
 
-You will find more information on the local Green's function implementation in TRIQS in :ref:`the corresponding chapter of the manual  <green>`
+You will find more information on the local Green's function implementation in TRIQS in :doc:`the corresponding chapter of the manual  <../../reference/python/green/green>`
 
 

doc/tutorials/python/tour2.rst

@@ -9,12 +9,12 @@ neighbour hopping using the ``BravaisLattice`` class of TRIQS, compute its
 density of states (DOS) and then plot it by using again the ``oplot`` function.
 
 
-.. literalinclude:: ../lattice/ex1.py
+.. literalinclude:: ../../reference/python/lattice/ex1.py
    :lines: 1-34
 
-.. image:: ../lattice/ex1.png
+.. image:: ../../reference/python/lattice/ex1.png
    :width: 700
    :align: center
 
-More information on the lattice tools implemeted in TRIQS can be :ref:`found here <lattice>`
+More information on the lattice tools implemeted in TRIQS can be :doc:`found here <../../reference/python/lattice/lattice>`
 

doc/tutorials/python/tour3.rst

@@ -3,6 +3,8 @@
 Tour 3: Solving a quantum impurity model with QMC 
 ----------------------------------------------------------
 
+`[Requires TRIQS and the application cthyb_matrix]`
+
 Free electrons are nice, but the `I` in TRIQS means `interacting`.
 So let us solve a simple one-band Anderson impurity model
 
@@ -25,14 +27,14 @@ We solve this model using the hybridization expansion Continuous Time Quantum Mo
 proposed by `P. Werner et al. <http://link.aps.org/doi/10.1103/PhysRevLett.97.076405>`_
 
 To this end we first initialize the ``Solver`` class of the TRIQS CT-Hyb implementaion 
-``pytriqs.applications.impurity_solvers.ctqmc_hyb``.
+``pytriqs.applications.impurity_solvers.cthyb_matrix``.
 Then, after having constructed the non-interacting Green's function :math:`G^{-1}_{0,\sigma}`, 
-we launch the CT-Hyb calculations by calling the ``Solve`` method of the ``Solver`` class. 
+we launch the impurity solver calculations by calling the ``Solve`` method.
 Finally, the resulting interacting Green's function as well as average impurity occupancy 
 is stored in the :ref:`HDF5 format<hdf5_base>`.
 
 
-.. literalinclude:: ../solvers/aim.py
+.. literalinclude:: ./aim.py
 
 The result can be then read from the ``HDF5`` file and plotted using the ``oplot`` function:
 
@@ -43,5 +45,5 @@ The result can be then read from the ``HDF5`` file and plotted using the ``oplot
    :align: center
 
 
-We go through this example in more details in the tutorial :ref:`Anderson impurity model <aim>`
+We go through this example in more details in the documentation of the cthyb_matrix application.
 

doc/tutorials/python/tour4.rst

@@ -2,6 +2,9 @@
 Tour 4: Dynamical Mean Field Theory on a Bethe lattice
 ------------------------------------------------------
 
+  `Requires TRIQS and the application cthyb_matrix`
+  
+
 In the case of Bethe lattice the dynamical mean-field theory (DMFT) self-consistency condition takes a particularly simple form
 
 .. math::
@@ -15,7 +18,7 @@ the previous single-impurity example to the case of a bath with semi-circular de
 Here is a complete program doing this plain vanilla DMFT  on a half-filled one-band Bethe lattice:
 
 
-.. literalinclude:: ../solvers/dmft/single_site_bethe.py
+.. literalinclude:: ./single_site_bethe.py
 
 
 A general introduction to DMFT calculations with TRIQS can be found :ref:`here <dmftloop>`