[doc] First draft of the blockstructure documentation

doc/documentation.rst

@@ -40,9 +40,9 @@ Advanced Topics
 .. toctree::
    :maxdepth: 2
 
+   guide/blockstructure
    guide/BasisRotation
    guide/soc
-   guide/removeorbitals
 
 Postprocessing
 --------------

doc/guide/BasisRotation.rst

@@ -1,7 +1,7 @@
 .. _basisrotation:
 
-Numerical Treatment of the Sign-Problem: Basis Rotations
+Automatic basis rotations in DFT+DMFT
-=======
+=====================================
 
 When performing calculations with off-diagonal terms in the hybridisation function or in the local Hamiltonian, one is
 often limited by the fermionic sign-problem slowing down the QMC calculations significantly. This can occur for instance if the crystal shows locally rotated or distorted cages, or when spin-orbit coupling is included. The examples for this are included in the :ref:`tutorials` of this documentation.
@@ -16,9 +16,10 @@ The transformation matrix can be stored in the :class:`BlockStructure` and the
 transformation is automatically performed when using :class:`SumkDFT`'s :meth:`extract_G_loc`
 and :meth:`put_Sigma` (see below).
 
+[UPDATE EVERYTHING FROM HERE ON:]
 
-Finding the Transformation Matrix
+Finding the transformation matrix
------------------
+---------------------------------
 
 The :class:`TransBasis` class offers a simple method to calculate the transformation
 matrices to a basis where either the local Hamiltonian or the density matrix
@@ -33,7 +34,7 @@ is diagonal::
 
 
 Transforming Green's functions manually
------------------
+---------------------------------------
 
 One can transform Green's functions manually using the :meth:`convert_gf` method::
 
@@ -43,7 +44,7 @@ One can transform Green's functions manually using the :meth:`convert_gf` method
 
 
 Automatic transformation during the DMFT loop
------------------
+---------------------------------------------
 
 During a DMFT loop one is often switching back and forth between the unrotated basis (Sumk-Space) and the rotated basis that is used by the QMC Solver. However, this need not be done manually each time. Instead, 
 once the block_structure.transformation property is set as shown above, this is

doc/guide/blockstructure.rst

@@ -0,0 +1,35 @@
+.. _blockstructure:
+
+Manipulating the Greens functions block structure
+=================================================
+
+The DFTTools package includes the general :class:`BlockStructure <dft.block_structure.BlockStructure>` class for manipulating the blocks of Greens functions. In the following, we will introduce its basic and most commonly used functionalities that might show up in an actual DFT+DMFT calculation, and will illustrate them on a very basic fictitious problem.
+
+SumK and Solver structure
+-------------------------
+
+The main idea is to have two structures for the Greens functions available. The first one is used in the procedures of the :class:`SumkDFT <dft.sumk_dft.SumkDFT>` to calculate Dysons equations, lattice Greens functions, and so on. The second structure is the one which is used for the solution of the Anderson impurity problem. As a matter of fact, these two structure need not necessarily be the same.
+
+[TODO] Describe the mapping. Discuss why small blocks are important for the QMC solver. Do the example.
+
+Picking orbitals
+----------------
+
+In some cases it might happen that for the projection to localised orbitals a full d or f-shells has to be used. However, for the Anderson impurity problem, just a subset of the orbitals are needed. This is the case, e.g., when the projection leads to completely empty or full orbitals that you don't want to include in the AIM. 
+
+For the example we are dealing with it means that .... [CONTINUE]
+
+Basis rotations
+---------------
+
+In cases where the Greens function or the local Hamiltonian shows off diagonal entries in the chosen basis, it is often beneficial to rotate to a different basis. This is of particular interest when using a QMC solver, since off-diagonal contributions lead to a famous fermionic sign problem. The :class:`BlockStructure <dft.block_structure.BlockStructure>` class includes methods to perform such basis rotations.
+
+[TODO] Show it on the example
+
+Dismissing off-diagonals
+------------------------
+
+As said above, off diagonal contributions lead to some troubles. However,
+When you are exactly sure that you know what you are doing, there is functionality to take only the diagonal parts into account in the block structure. Be careful, there is no automatic check whether this approximation is justified or not!
+
+[TODO] Show the example  

doc/guide/removeorbitals.rst

@@ -1,6 +0,0 @@
-.. _removeorbitals:
-
-Reducing the number of orbitals for the Solver
-==============================================
-
-To be done...

doc/guide/soc.rst

@@ -36,6 +36,6 @@ We strongly suggest using the :py:meth:`.dos_wannier_basis` functionality of the
 Note that, with SOC, there are usually off-diagonal elements of the spectral function, which can also be imaginary.
 The imaginary part can be found in the third column of the files ``DOS_wann_...``.
 
-After the projection, one can proceed with the DMFT calculation. However, two things need to be noted here. First, since the spin is not a good quantum number any more, there are off-diagonal elements in the hybridisation function and the local Hamiltonian coupling the two spin directions. This will eventually lead to a fermonic sign problem when QMC is used as a impurity solver. Second, although the :math:`e_{g}` subshell needs to be included in the projection, it can in many cases be neglected in the solution of the Anderson impurity model, after a transformation to a rotated local basis is done. This basis diagonalising the local Hamiltonian in the presence of SOC, is often called the numerical j-Basis. How rotations are performed is described in :ref:`basisrotation`, and the cutting of the orbitals in :ref:`removeorbitals`.
+After the projection, one can proceed with the DMFT calculation. However, two things need to be noted here. First, since the spin is not a good quantum number any more, there are off-diagonal elements in the hybridisation function and the local Hamiltonian coupling the two spin directions. This will eventually lead to a fermonic sign problem when QMC is used as a impurity solver. Second, although the :math:`e_{g}` subshell needs to be included in the projection, it can in many cases be neglected in the solution of the Anderson impurity model, after a transformation to a rotated local basis is done. This basis, diagonalising the local Hamiltonian in the presence of SOC, is often called the numerical j-basis. How rotations are performed is described in :ref:`basisrotation`, and the cutting of the orbitals in :ref:`blockstructure`.
 
 A DMFT calculation including SOC for Sr2MgOsO6 is included in the :ref:`tutorials`.