analysis.rst half done and some other minor changes

doc/guide/analysis.rst

@@ -3,75 +3,33 @@
 Tools for analysis
 ==================
 
-.. warning::
-  TO BE UPDATED!
-
 This section explains how to use some tools of the package in order to analyse the data.
 
+There are two practical tools for which a self energy on the real axis is not needed, namely:
+
+  * :meth:`dos_wannier_basis` for the density of states of the Wannier orbitals and
+  * :meth:`partial_charges` for the partial charges according to the Wien2k definition.
+
+However, a real frequency self energy has to be provided by the user to use the methods:
+
+  * :meth:`dos_parproj_basis` for the momentum-integrated spectral function including self energy effects and
+  * :meth:`spaghettis` for the momentum-resolved spectral function (i.e. ARPES)
+
 .. warning::
-  The package does NOT provide an explicit method to do an **analytic continuation** of the
+  This package does NOT provide an explicit method to do an **analytic continuation** of the
-  self energies and Green functions from Matsubara frequencies to the real frequancy axis! 
+  self energies and Green functions from Matsubara frequencies to the real frequency axis! 
-  There are methods included e.g. in the :program:`ALPS` package, which can be used for these purposes. But
+  There are methods included e.g. in the :program:`ALPS` package, which can be used for these purposes. 
-  be careful: All these methods have to be used very carefully!
+  Keep in mind that all these methods have to be used very carefully!
 
-The tools for analysis can be found in an extension of the :class:`SumkDFT` class and are
+Most conveniently, you have your self energy already stored as a real frequency :class:`BlockGf` object 
-loaded by importing the module :class:`SumkDFTTools`::
+in a hdf5 file, which can be easily loaded::
 
-  from pytriqs.applications.dft.sumk_dft_tools import *
+  ar = HDFArchive(filename+'.h5','r')
-
+  SigmaReFreq = ar['SigmaReFreq']
-There are two practical tools for which you do not need a self energy on the real axis, namely the:
-
-  * density of states of the Wannier orbitals,
-  * partial charges according to the Wien2k definition.
-
-The self energy on the real frequency axis is necessary in computing the:
-
-  * momentum-integrated spectral function including self-energy effects,
-  * momentum-resolved spectral function (i.e. ARPES).
-
-The initialisation of the class is equivalent to that of the :class:`SumkDFT` 
-class::
-
-  SK = SumkDFTTools(hdf_file = filename)
-
-Note that all routines available in :class:`SumkDFT` are also available here. 
-
-Routines without real-frequency self energy
--------------------------------------------
-
-For plotting the 
-density of states of the Wannier orbitals, you simply type::
-
-  SK.check_input_dos(om_min, om_max, n_om)
-
-which produces plots between the real frequencies `om_min` and `om_max`, using a mesh of `n_om` points. There
-is an optional parameter `broadening` which defines an additional Lorentzian broadening, and has the default value of
-`0.01` by default.
-
-Since we can calculate the partial charges directly from the Matsubara Green's functions, we also do not need a
-real-frequency self energy for this purpose. The calculation is done by::
-
-  ar = HDFArchive(SK.hdf_file)
-  SK.put_Sigma([ ar['SigmaImFreq'] ])
   del ar
-  dm = SK.partial_charges()
 
-which calculates the partial charges using the data stored in the hdf5 file, namely the self energy, double counting, and
+.. note::
-chemical potential. Here we assumed that the final self energy is stored as `SigmaImFreq` in the archive. 
+    What happens if one has a self energy only in text files...?
-On return, `dm` is a list, where the list items correspond to the density matrices of all shells
-defined in the list `SK.shells`. This list is constructed by the Wien2k converter routines and stored automatically
-in the hdf5 archive. For the detailed structure of `dm`, see the reference manual.
-
-
-Routines with real-frequency self energy
-----------------------------------------
-
-In order to plot data including correlation effects on the real axis, one has to provide the real frequency self energy. 
-Most conveniently, it is stored as a real frequency :class:`BlockGf` object in the hdf5 file::
-
-  ar = HDFArchive(filename+'.h5','a')
-  ar['SigmaReFreq'] = SigmaReFreq
-  del ar
 
 You may also store it in text files. If all blocks of your self energy are of dimension 1x1, you store them in `fname_(block)0.dat` files. Here `(block)` is a block name (`up`, `down`, or combined `ud`). In the case when you have matrix blocks, you store them in `(i)_(j).dat` files, where `(i)` and `(j)` are the orbital indices, in the `fname_(block)` directory.
 
@@ -88,6 +46,57 @@ where:
   
 The chemical potential as well as the double counting correction were already read in the initialisation process.
 
+Initialisation
+--------------
+
+All tools described below are collected in an extension of the :class:`SumkDFT` class and are
+loaded by importing the module :class:`SumkDFTTools`::
+
+  from pytriqs.applications.dft.sumk_dft_tools import *
+
+The initialisation of the class is equivalent to that of the :class:`SumkDFT` 
+class::
+
+  SK = SumkDFTTools(hdf_file = filename + '.h5')
+
+Note that all routines available in :class:`SumkDFT` are also available here. 
+
+If required, the real frequency self energy is set with::
+  
+    SK.put_Sigma(Sigma_imp = [ SigmaReFreq ])
+
+Density of states of the Wannier orbitals
+-----------------------------------------
+
+For plotting the 
+density of states of the Wannier orbitals, you simply type::
+
+  SK.check_input_dos(om_min, om_max, n_om)
+
+which produces plots between the real frequencies `om_min` and `om_max`, using a mesh of `n_om` points. There
+is an optional parameter `broadening` which defines an additional Lorentzian broadening, and has the default value of
+`0.01` by default.
+
+Partial charges
+---------------
+
+Since we can calculate the partial charges directly from the Matsubara Green's functions, we also do not need a
+real-frequency self energy for this purpose. The calculation is done by::
+
+  ar = HDFArchive(SK.hdf_file)
+  SK.put_Sigma([ ar['SigmaImFreq'] ])
+  del ar
+  dm = SK.partial_charges()
+
+which calculates the partial charges using the data stored in the hdf5 file, namely the self energy, double counting, and
+chemical potential. Here we assumed that the final self energy is stored as `SigmaImFreq` in the archive. 
+On return, `dm` is a list, where the list items correspond to the density matrices of all shells
+defined in the list `SK.shells`. This list is constructed by the Wien2k converter routines and stored automatically
+in the hdf5 archive. For the detailed structure of `dm`, see the reference manual.
+
+Correlated spectral function (with self energy)
+-----------------------------------------------
+
 With this self energy, we can now execute::
 
   SK.dos_partial(broadening=broadening)
@@ -103,6 +112,9 @@ The output is printed into the files
   * `DOScorr(sp)_proj(i)_(m)_(n).dat`: As above, but printed as orbitally-resolved matrix in indices 
     `(m)` and `(n)`. For `d` orbitals, it gives the DOS seperately for, e.g., :math:`d_{xy}`, :math:`d_{x^2-y^2}`, and so on.
 
+Momentum resolved spectral function (with self energy)
+------------------------------------------------------
+
 Another quantity of interest is the momentum-resolved spectral function, which can directly be compared to ARPES
 experiments. We assume here that we already converted the output of the :program:`dmftproj` program with the 
 converter routines (see :ref:`interfacetowien`). The spectral function is calculated by::

doc/guide/conversion.rst

@@ -133,6 +133,10 @@ After this step, all the necessary information for the DMFT loop is
 stored in the hdf5 archive, where the string variable
 `Converter.hdf_filename` gives the file name of the archive.
 
+At this point you should use the method :meth:`dos_wannier_basis` 
+contained in the module :class:`SumkDFTTools` to check the density of 
+states of the Wannier orbitals (see :ref:`analysis`). 
+
 You have now everything for performing a DMFT calculation, and you can
 proceed with :ref:`singleshot`.
 

doc/guide/dftdmft_singleshot.rst

@@ -18,7 +18,7 @@ Before doing the calculation, we have to intialize all the objects that we will
 to get the local quantities used in DMFT. It is initialized by::
 
   from pytriqs.applications.dft.sumk_dft import *
-  SK = SumkDFT(hdf_file = filename)
+  SK = SumkDFT(hdf_file = filename + '.h5')
 
 
 Setting up the impurity solver

doc/guide/transport.rst

@@ -36,9 +36,13 @@ Prerequisites
 First perform a standard :ref:`DFT+DMFT calculation <dftdmft_selfcons>` for your desired material and obtain the real-frequency self energy by doing an
 analytic continuation.
 
-.. note::
+.. warning::
-   It is crucial to perform the analytic continuation in such a way that the obtained real-frequency self energy is accurate around the Fermi energy as only its
+  This package does NOT provide an explicit method to do an **analytic continuation** of
-   low energy structure influences the final results!
+  self energies and Green functions from Matsubara frequencies to the real frequency axis! 
+  There are methods included e.g. in the :program:`ALPS` package, which can be used for these purposes.
+  Keep in mind that all these methods have to be used very carefully. Especially for optics calculations
+  it is crucial to perform the analytic continuation in such a way that the obtained real frequency self energy 
+  is accurate around the Fermi energy as low energy features strongly influence the final results!
 
 Besides the self energy the Wien2k files read by the transport converter (:meth:`convert_transport_input <pytriqs.applications.dft.converters.wien2k_converter.Wien2kConverter.convert_transport_input>`) are:
    * :file:`.struct`: The lattice constants specified in the struct file are used to calculate the unit cell volume.