3
0
mirror of https://github.com/triqs/dft_tools synced 2024-12-25 05:43:40 +01:00
dft_tools/doc/reference/python/green/full.rst
Michel Ferrero f7fad85fca Iteration over the doc
This is an iteration over the doc mainly thank to Priyanka.
I fixed another couple of details on the way.
2013-12-31 14:22:00 +01:00

234 lines
8.1 KiB
ReStructuredText

.. index::
single: Green's functions; full Green's function
module: gf.local
.. _fullgreen:
The complete Green's function (BlockGf)
=======================================
As mentioned in the introduction, due to the symmetry, a local Green's function usually
has a block structure.
We refer to this object as the `full` or `complete` Green's function, in contrast to
the blocks it is made of.
Most properties of this object can be remembered by the simple sentence:
`A full Green's function is an ordered dictionary {name -> block}, or equivalently a list of tuples (name, block).`
The blocks can be any of the matrix-valued Green's functions described :ref:`above<blockgreen>`.
The role of this object is to gather them, and simplify the code writing
by factorizing some simple operations.
A little example
--------------------
To start with an example, imagine that the problem
that we consider could involve 5 d-bands of a solid that, for symmetry reasons,
are separated into 2 eg and 3 t2g bands. We therefore first construct the 2
corresponding block Green's functions (in Matsubara frequencies for example)
and group these blocks into a full Green's function `G` with::
from pytriqs.gf.local import *
g1 = GfImFreq(indices = ['eg1','eg2'], beta = 50, n_points = 1000, name = "egBlock")
g2 = GfImFreq(indices = ['t2g1','t2g2','t2g3'], beta = 50, n_points = 1000, name = "t2gBlock")
G = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = False)
where:
* `name_list` is the ordered list of the names of the blocks.
* `block_list` is the corresponding list of block Green's function.
* `make_copies` lets you specify if the blocks of the full Green's function are **copies** of the blocks given in
`block_list` or if they are **views** of these blocks, see :ref:`below<fullgreencopypolicy>`
These names will be used when we try to access a particular block, for example ::
>>> G
Green's Function composed of 2 blocks at inverse temperature Beta = 50.0:
GfImFreq eg : Beta = 50.000; IndicesL = ['eg1', 'eg2'], IndicesR = ['eg1', 'eg2']
GfImFreq t2g : Beta = 50.000; IndicesL = ['t2g1', 't2g2', 't2g3'], IndicesR = ['t2g1', 't2g2', 't2g3']
>>> G['eg']
GfImFreq eg : Beta = 50.000; IndicesL = ['eg1', 'eg2'], IndicesR = ['eg1', 'eg2']
Reference
----------------
.. autoclass:: pytriqs.gf.local.BlockGf
:members: copy, copy_from
Operations
---------------
The full Green's functions support various simple operations, that are simply done block by block.
.. note::
All these operations compute the array of data, but also, if present in the object, the high frequency expansion tail automatically.
* compound operators, `+=`, `-=`, `*=`, `\=` : RHS can be a Green's function of the same type or an expression
* arithmetic operations : `+`, `-`, `*`, `/`, e.g. ::
G = G1 + 2*G2
* inversion, e.g. ::
inv = inverse(g)
g2 = inverse(inverse(g) - sigma) # this is a Dyson equation
Block access
----------------
Blocks can be accessed like in a `dict` :
These names will be used when we try to access a particular block, for example ::
G['eg']
The generic way to access a Green's function element :math:`G^a_{i j}` is therefore ::
G[a][i,j]
Iterator
--------------------
One can iterate on the blocks ::
for name, g in G:
do_something()
In the example above ::
>>> for name, g in G:
... print name, g
eg GfImFreq eg : Beta = 50.000; IndicesL = ['eg1', 'eg2'], IndicesR = ['eg1', 'eg2']
t2g GfImFreq t2g : Beta = 50.000; IndicesL = ['t2g1', 't2g2', 't2g3'], IndicesR = ['t2g1', 't2g2', 't2g3']
As a result ::
BlockGf( name_block_generator= G, make_copies=False)
generates a new Green's function `G`, viewing the same blocks.
More interestingly ::
BlockGf( name_block_generator= [ (index,g) for (index,g) in G if Test(index), make_copies=False)]
makes a partial view of some of the blocks selected by the `Test` condition.
.. warning::
The order in which the blocks appear is guaranteed to be the same as in the constructor.
This is why the Green's function is similar to an **ordered** dictionary, not a simple dict.
.. _fullgreencopypolicy:
View or copies?
---------------------
The Green's function is to be thought like a dict, hence accessing the
block returns references. When constructing the Green's function BlockGf,
the parameter `make_copies` determines if a copy of the blocks must be made
before putting them in the Green's function.
.. note::
This is the standard behaviour in python for a list of a dict.
Example:
* If you define a Green's function with::
G = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = False)
.. note::
`make_copies` is optional; its default value is False. We keep it here for clarity.
The ``make_copies = False`` implies that the blocks of ``G`` are *references* ``g1`` and ``g2``.
So, if you modify ``g1``, say by putting it to zero with ``g1.zero()``, then the
first block of G will also be put to zero. Similarly, imagine you define two
Green's functions like this::
G1 = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = False)
G2 = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = False)
Then, G1 and G2 are exactly the same object, because they both have blocks
which are views of ``g1`` and ``g2``.
* Instead, if you write::
G = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = True)
The ``Copy = True`` ensures that the blocks of G are new copies of ``g1``
and ``g2``. If you then modify ``g1`` it will not have any effect on G.
Clearly if you define::
G1 = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = True)
G2 = BlockGf(name_list = ('eg','t2g'), block_list = (g1,g2), make_copies = True)
Here ``G1`` and ``G2`` are different objects, both having made copies
of ``g1`` and ``g2`` for their blocks.
An equivalent definition would be ::
G1 = BlockGf(name_list = ('eg','t2g'), block_list = (g1.copy(),g2.copy()))
G2 = BlockGf(name_list = ('eg','t2g'), block_list = (g1.copy(),g2.copy()))
shelve / pickle
---------------------
Green's functions are `picklable`, i.e. they support the standard python serialization techniques.
* It can be used with the `shelve <http://docs.python.org/library/shelve.html>`_ and `pickle <http://docs.python.org/library/pickle.html>`_ module::
import shelve
s = shelve.open('myfile','w')
s['G'] = G # G is stored in the file.
* It can be sent/broadcasted/reduced over mpi ::
from pytriqs.utility import mpi
mpi.send (G, destination)
.. warning::
Shelve is not a portable format, it may change from python version to another (and it does).
For portability, we recommend using the HDF5 interface for storing data on disks.
HDF5
--------
BlockGf are hdf-compatible with the following HDF5 data scheme
The BlockGf(TRIQS_HDF5_data_scheme = "BlockGf") is decomposed in the following objects :
========================= =========================== ===========================================================================
Name Type Meaning
========================= =========================== ===========================================================================
__BlockIndicesList string The python repr of the list of blocks, e.g. ('up', 'down')
__Name string Name of the Green's function block
__Note string Note
For each block name type of the block The Block Green's function
========================= =========================== ===========================================================================
Example::
/Gtau Group
/Gtau/__BlockIndicesList Dataset {SCALAR}
/Gtau/__Name Dataset {SCALAR}
/Gtau/__Note Dataset {SCALAR}
/Gtau/down Group
/Gtau/down/Data Dataset {1, 1, 1000}
/Gtau/down/ ...
...
/Gtau/up Group
/Gtau/up/Data Dataset {1, 1, 1000}
/Gtau/up/ ...