From 1b5aceb2a598f822dc1ac57cceaebc5c9cfce022 Mon Sep 17 00:00:00 2001 From: Olivier Parcollet Date: Wed, 18 Sep 2013 15:13:23 +0200 Subject: [PATCH] gf: Work on documentation --- doc/installation/requirements.rst | 25 +-- .../c++/arrays/containers/compound_ops.rst | 2 + .../c++/arrays/containers/rebind.rst | 11 +- .../c++/arrays/containers/view_assign.rst | 34 ++-- .../arrays/containers/view_constructors.rst | 36 ++-- doc/reference/c++/arrays/containers/views.rst | 39 ++-- doc/reference/c++/conventions.rst | 9 +- doc/reference/c++/gf/concepts.rst | 4 +- doc/reference/c++/gf/contents.rst | 2 + doc/reference/c++/gf/gf_and_view.rst | 176 +++++++++++++----- doc/reference/c++/gf/gf_assign.rst | 39 ++++ doc/reference/c++/gf/gf_block.rst | 142 +++++++++++++- doc/reference/c++/gf/gf_call.rst | 63 +++++++ doc/reference/c++/gf/gf_constructors.rst | 54 ++++++ doc/reference/c++/gf/gf_data.rst | 49 +++++ doc/reference/c++/gf/gf_imfreq.rst | 48 ++--- doc/reference/c++/gf/gf_imfreq_s.rst | 47 ++--- doc/reference/c++/gf/gf_imtime.rst | 48 ++--- doc/reference/c++/gf/gf_part_eval_curry.rst | 97 ++++++++++ doc/reference/c++/gf/gf_prod.rst | 36 ---- doc/reference/c++/gf/gf_product.rst | 89 +++++++++ doc/reference/c++/gf/gf_refreq.rst | 38 ++-- doc/reference/c++/gf/gf_retime.rst | 34 ++-- doc/reference/c++/gf/gf_subscript.rst | 63 +++++++ doc/reference/c++/gf/implementation_notes.rst | 69 ------- doc/reference/c++/gf/intro.rst | 27 +-- 26 files changed, 907 insertions(+), 374 deletions(-) create mode 100644 doc/reference/c++/gf/gf_assign.rst create mode 100644 doc/reference/c++/gf/gf_call.rst create mode 100644 doc/reference/c++/gf/gf_constructors.rst create mode 100644 doc/reference/c++/gf/gf_data.rst create mode 100644 doc/reference/c++/gf/gf_part_eval_curry.rst delete mode 100644 doc/reference/c++/gf/gf_prod.rst create mode 100644 doc/reference/c++/gf/gf_product.rst create mode 100644 doc/reference/c++/gf/gf_subscript.rst diff --git a/doc/installation/requirements.rst b/doc/installation/requirements.rst index 55a19fbd..d2eddcea 100644 --- a/doc/installation/requirements.rst +++ b/doc/installation/requirements.rst @@ -16,28 +16,23 @@ C++ compilers TRIQS is written in C++, i.e. in the **C++11** standard as defined by the ISO standardization committee. A recent compiler is therefore mandatory. -There are 3 categories of C++ compilers: -* Standard compliant C++ compilers +* Standard compliant C++ compilers (recommended and supported). - * :ref:`clang 3.3` and higher + * :ref:`clang 3.2` and higher (in particular the default clang on OS X 10.8). * g++ 4.8.1 and higher - These compilers are recommended and supported. - - -* Obsolete compilers - - * g++ 4.6.3 to 4.8.0 - - TRIQS can be built with these compilers but because they lack full C++11 support, - TRIQS may be slower (some optimisations are disabled in the library). - These compilers may not be supported in later releases. + * The intel icc 14.0 is close to be C++11 compliant, but presents currently too many bugs to be supported + at present. It compiles 99% of TRIQS, but we do not have the ressources to write and + maintains all necessary workarounds. + + Besides, for *our codes*, icc does not provide a significant speed gain (unlike MKL), + so we do not recommend it for TRIQS. * C++98 compilers - * g++ before 4.6 - * Intel icc 12.0 and below + * g++ before 4.8.1 + * Intel icc 13.0 and below Compilers implementing the previous version of the C++ standard (C++98) do not work and will *not* be supported. diff --git a/doc/reference/c++/arrays/containers/compound_ops.rst b/doc/reference/c++/arrays/containers/compound_ops.rst index 6fe49d29..a254265f 100644 --- a/doc/reference/c++/arrays/containers/compound_ops.rst +++ b/doc/reference/c++/arrays/containers/compound_ops.rst @@ -14,3 +14,5 @@ Compound assignment operators (+=, -=, * =, /=) The containers and the view have compound operators. +*NB* : These operators make no sense for const views, and result in a compile error. + diff --git a/doc/reference/c++/arrays/containers/rebind.rst b/doc/reference/c++/arrays/containers/rebind.rst index 4ee9be50..aeb81e66 100644 --- a/doc/reference/c++/arrays/containers/rebind.rst +++ b/doc/reference/c++/arrays/containers/rebind.rst @@ -5,13 +5,20 @@ rebind ================================== -* **Synopsis**: +* **Synopsis** for X_view (X=array, matrix, vector): .. cpp:function:: void rebind(array_view const & a) +* **Synopsis** for X_const_view (X=array, matrix, vector): + + .. cpp:function:: void rebind(array_view const & a) + .. cpp:function:: void rebind(array_const_view const & a) + +* **Effect** : + Rebinds the view - After this method, the view points to the same as a. + After this method, the view points to the same as *a*. Following the :ref:`memory management rules `, if nothing else views the data originally pointed to by the view, this data is destroyed. diff --git a/doc/reference/c++/arrays/containers/view_assign.rst b/doc/reference/c++/arrays/containers/view_assign.rst index 15189f37..b0833f52 100644 --- a/doc/reference/c++/arrays/containers/view_assign.rst +++ b/doc/reference/c++/arrays/containers/view_assign.rst @@ -7,8 +7,9 @@ Assignment to views **Synopsis** : - template - array_view & operator=(RHS const & X); + template array_view & operator=(RHS const & X); + +*NB: The assignment operator is deleted for const_views.* The `view classes` have a quite general assignment operator. We will illustrate it on the `array_view` class, it is the same for `matrix` and `vector`. @@ -21,31 +22,30 @@ We will illustrate it on the `array_view` class, it is the same for `matrix` and e.g. : array, array_view, matrix, matrix_view, but also formal expression (See , e.g. A+B), or any custom object of your choice. - `Effect` : all the elements viewed by the view are replaced - by the evaluation of RHS. + *Effect* : + Every elements viewed by the view are replaced by the evaluation of RHS. - .. warning:: - - The shape of the view and of RHS must match exactly or behaviour is undefined. + *Precondition* + + The shape of the view and of RHS must match exactly or behaviour is undefined. - If the debug macro, :ref:`TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` is defined, - this condition is checked at runtime. + If the debug macro, :ref:`TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` is defined, + this condition is checked at runtime. - .. note:: - - We could lower this condition, since we don't need a domain here, just the evaluation - on the indices... + NB : We could lower this condition, since we don't need a domain here, just the evaluation on the indices... * A scalar. - `Effect` : all elements viewed by the view are set to this scalar. + *Effect* : + Every elements viewed by the view are set to this scalar, except for the matrix_view, + where the matrix is set to the identity. -NB : no move assign operator +NB : no move assignment operator --------------------------------------- -Note that **there is no move assign operators for views**. -If RHS is an rvalue reference, the regular operator = is called, that +Note that **there is no move assignment operators for views**. +If RHS is an rvalue reference, the regular operator= (view const &) is called, that makes a copy of the data of RHS into the elements viewed by the view. This behaviour is consistent with the fact that views are *not* regular types. diff --git a/doc/reference/c++/arrays/containers/view_constructors.rst b/doc/reference/c++/arrays/containers/view_constructors.rst index 90a051b1..6b1f73bc 100644 --- a/doc/reference/c++/arrays/containers/view_constructors.rst +++ b/doc/reference/c++/arrays/containers/view_constructors.rst @@ -14,15 +14,6 @@ Constructors of array_view Views have `view semantics`, i.e. they **never** make a copy of the data. -====================================================================== ===================================================================================================== -Constructors of array_view Comments -====================================================================== ===================================================================================================== -array_view(const array_view &) Copy construction (makes a shallow copy) -array_view(const T & X) T is any type such that X.indexmap() and X.storage() can be used to construct a view. - REF to concept here .... -====================================================================== ===================================================================================================== - - +-----------------------------------+---------------------------------------------------------------------------------------+ | Constructors of array_view | Comments | +===================================+=======================================================================================+ @@ -39,7 +30,28 @@ array_view(const T & X) T is any +-----------------------------------+---------------------------------------------------------------------------------------+ -Constructors of matrix_view, vector_view ------------------------------------------------- +Constructors of array_const_view +--------------------------------------- -Similar to array_view ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| Constructors of array_const_view | Comments | ++========================================================================+=======================================================================================+ +| array_const_view(array_const_view const &) | Create a new view, viewing the same data. Does **not** copy data. (copy constructor) | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| array_const_view(array_view const &) | Create a new view, viewing the same data. Does **not** copy data | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| array_const_view(const T & X) | T is any type such that X.indexmap() and X.storage() can be used to construct a view. | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| array_const_view(array_const_view &&) | Move construction (trivial here, a copy constructor is very quick anyway). | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| explicit array_const_view(PyObject * X) | Construct an array_view from the Python object X. Type and rank must match exactly, | +| | or an exception if thrown | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| | .. note:: X is a borrowed reference, array does not affect its counting reference. | ++------------------------------------------------------------------------+---------------------------------------------------------------------------------------+ + + +Constructors of matrix_view, vector_view, matrix_const_view, vector_const_view +------------------------------------------------------------------------------- + +Similar to array_view, array_const_view diff --git a/doc/reference/c++/arrays/containers/views.rst b/doc/reference/c++/arrays/containers/views.rst index 4d4a70c6..2f84b424 100644 --- a/doc/reference/c++/arrays/containers/views.rst +++ b/doc/reference/c++/arrays/containers/views.rst @@ -13,19 +13,27 @@ Views template class matrix_view; template class vector_view; + template class array_const_view; + template class matrix_const_view; + template class vector_const_view; + + where triqs::ull_t is the type defined by : .. code-block:: c typedef unsigned long long ull_t; -* The view type of X (= array, matrix, vector) is called X_view, with the same template parameters as the regular type. +* The view types of X (= array, matrix, vector) are called X_view, and X_const_view, with the same template parameters as the regular type. * A `view` is give access to a restricted portion of the array, matrix or vector, i.e. a `partial view` of the data. The view can also be `complete` (i.e. show all the container). * The views model the :ref:`MutableCuboidArray`, :ref:`MutableMatrix`, :ref:`MutableVector`, like the corresponding regular type. +* The const views are similar to view, except that theirs contents can not be modified. + They model the :ref:`ImmutableCuboidArray`, :ref:`ImmutableMatrix`, :ref:`ImmutableVector`, like the corresponding *const* regular type. + * Views have `view semantics`, i.e. their behave like a reference to the data, they are not regular type. In particular, they never make copy of the data. See :ref:`view_vs_regular` for a detailed discussion of the difference between a regular type and its corresponding view. @@ -33,6 +41,8 @@ where triqs::ull_t is the type defined by : * Views are largely interoperable : it is easy and quick to take a matrix_view of an array, or vice versa. Cf constructors belows. +* Const views can be constructed from a view, but the reverse is not true (Cf constructors). + * **Memory Management** Views offers a strong guarantee of the existence of the data, like a std::shared_ptr. @@ -70,15 +80,17 @@ NB: Rank is only present for array, since matrix have rank 2 and vector rank 1. Member types -------------------------------------- -+--------------+----------------------------------------------------------+ -| Member type | Definitions | -+==============+==========================================================+ -| value_type | ValueType | -+--------------+----------------------------------------------------------+ -| view_type | The corresponding view type, i.e. the view itself | -+--------------+----------------------------------------------------------+ -| regular_type | The corresponding regular type | -+--------------+----------------------------------------------------------+ ++-----------------+-----------------------------------+ +| Member type | Definitions | ++=================+===================================+ +| value_type | ValueType | ++-----------------+-----------------------------------+ +| view_type | The corresponding view type | ++-----------------+-----------------------------------+ +| const_view_type | The corresponding const view type | ++-----------------+-----------------------------------+ +| regular_type | The corresponding regular type | ++-----------------+-----------------------------------+ Member constexpr -------------------------------------- @@ -92,7 +104,7 @@ Member constexpr +--------+------+-------------------------------+ Member functions ---------------------- +------------------ +-------------------------------------------+------------------------------------------+ | Member function | Meaning | @@ -101,12 +113,12 @@ Member functions +-------------------------------------------+------------------------------------------+ | (destructor) | | +-------------------------------------------+------------------------------------------+ +| :ref:`operator ()` | element of access/views/lazy expressions | ++-------------------------------------------+------------------------------------------+ | :ref:`operator =` | assigns values to the container | +-------------------------------------------+------------------------------------------+ | :ref:`operator +=,-=,*=,/=` | compound assignment operators | +-------------------------------------------+------------------------------------------+ -| :ref:`operator ()` | element of access/views/lazy expressions | -+-------------------------------------------+------------------------------------------+ | begin/cbegin | returns iterator to the beginning | +-------------------------------------------+------------------------------------------+ | end/cend | returns iterator to the end | @@ -133,7 +145,6 @@ Member functions Non-member functions ------------------------ - +---------------------------------+-------------------------------------------+ | Member function | Meaning | +=================================+===========================================+ diff --git a/doc/reference/c++/conventions.rst b/doc/reference/c++/conventions.rst index 64c3fc01..655608ff 100644 --- a/doc/reference/c++/conventions.rst +++ b/doc/reference/c++/conventions.rst @@ -18,14 +18,15 @@ Efficient techniques which were considered before as complex and reserved to pro are now becoming simple to implement, like e.g. expression templates. The implementation of most of the TRIQS library (e.g. clef, arrays) would be either impossible or at least -much more complex and time consuming (with a lot of abstruse boost-like construction) +much more complex and time consuming (with a lot of abstruse boost-like constructions) in previous versions of C++. -Besides, this evolution is not finished. +Besides, this evolution is not finished (in fact it seems to accelerate !). The new coming standard, C++14, expected to be adopted and implemented very soon, -will still make it a lot better. In particular, the concept support (template constraints) +will still make it a lot better. In particular, the concept support (template constraints TS) will hopefully solve the most problematic issue with metaprogramming techniques, i.e. the lack of concept -check at compile time, resulting in long and obscur error messages from the compiler when *using* the library. +check at compile time, resulting in long and obscur error messages from the compiler when *using* the library, +which can leave the non-C++-expert user quite clueless... Hence, TRIQS will move to C++14 as soon as compilers are available. Notation diff --git a/doc/reference/c++/gf/concepts.rst b/doc/reference/c++/gf/concepts.rst index ba30703c..bf68da5b 100644 --- a/doc/reference/c++/gf/concepts.rst +++ b/doc/reference/c++/gf/concepts.rst @@ -99,7 +99,7 @@ Mesh It does not really need to be a mesh : e.g. if the function is represented on a polynomial basis, it is the parameters of this representation (max number of coordinates, e.g.) -* **Refines** : RegularType, HasConstIterator BoostSerializable, H5-serializable. +* **Refines** : RegularType, HasConstIterator BoostSerializable, H5-serializable, Printable. * **Definition** : @@ -165,7 +165,7 @@ MeshPoint | void reset() | Reset the mesh point to the first point | +------------------------------------------------+-----------------------------------------------------------------------------+ | cast_t | == mesh_t::domain_t::point_t | -| operator cast_t() const | *implicit* cast to the corresponding domain point | +| operator cast_t() const | *implicit* cast to the corresponding domain point | +------------------------------------------------+-----------------------------------------------------------------------------+ For one dimensional mesh, we also require that the MeshPoint implement the basic arithmetic operations diff --git a/doc/reference/c++/gf/contents.rst b/doc/reference/c++/gf/contents.rst index a58e2466..7378c68b 100644 --- a/doc/reference/c++/gf/contents.rst +++ b/doc/reference/c++/gf/contents.rst @@ -15,6 +15,8 @@ various Green functions. intro gf_and_view + gf_part_eval_curry + slicing concepts meshes tail diff --git a/doc/reference/c++/gf/gf_and_view.rst b/doc/reference/c++/gf/gf_and_view.rst index a01aaf6a..079fd1b6 100644 --- a/doc/reference/c++/gf/gf_and_view.rst +++ b/doc/reference/c++/gf/gf_and_view.rst @@ -5,30 +5,37 @@ gf and gf_view ================= -gf is the Green function container, with its view gf_view, defined as :: - - template class gf; // regular type - template class gf_view; // view type +**Synopsis**: -In this section, we describe all common properties of gf. -In practice, one works with one of the specialization described below (:ref:`gf_special`), -with their specific aspects (domains, interpolation methods, ....). - +.. code-block:: c + + template class gf; + template class gf_view; + template class gf_const_view; + +Hereafter, we describe the containers, the views. +Properties specific to each :ref:`specializations` are described in a specific page, linked in the table below. Template parameters ---------------------------- -* **Variable** determines the domain of the Green function -* **Target** determines the value of the Green function -* **Opt** is currently not used [default to void]. It may be used to differentiate different Green functions - with the same Variable, Target but different behaviour (e.g. interpolation, ...). ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ +| Template parameter | Accepted type | Access in the class | Meaning | ++=========================================+===============================+===============================+======================================+ +| Variable | Cf table below | variable_t | The domain of definition of the | +| | | | Green function | ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ +| Target | Cf Table below | target_t | The target space of the function | ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ +| Opt | void | option_t | Currently unused | ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ -They can have the following values : +The *Variable* template parameter can take the following values : +--------------------------+--------------------------------------------+ | Variable | Meaning | +==========================+============================================+ -| gf_imfreq | Imaginary Matsubara frequency | +| imfreq | Imaginary Matsubara frequency | +--------------------------+--------------------------------------------+ | imtime | Imaginary Matsubara time | +--------------------------+--------------------------------------------+ @@ -43,14 +50,16 @@ They can have the following values : | cartesian_product | Cartesian product of gf ... functions. | +--------------------------+--------------------------------------------+ -and - +The *Target* template parameter can take the following values : + +-------------------------+-----------------------------------------------------+ | Target | Meaning | +=========================+=====================================================+ +| scalar_valued | The function is scalar valued (double, complex...). | ++-------------------------+-----------------------------------------------------+ | matrix_valued [default] | The function is matrix valued. | +-------------------------+-----------------------------------------------------+ -| scalar_valued | The function is scalar valued (double, complex...). | +| tensor_valued | The function is tensor valued with rank | +-------------------------+-----------------------------------------------------+ .. _gf_special: @@ -58,19 +67,21 @@ and Specializations ------------------- -+-----------------+------------------+--------------------+----------------------------+ -| Variable\Target | matrix_valued | scalar_valued | G (another Green function) | -+=================+==================+====================+============================+ -| imfreq | :doc:`gf_imfreq` | :doc:`gf_imfreq_s` | | -+-----------------+------------------+--------------------+----------------------------+ -| imtime | :doc:`gf_imtime` | :doc:`gf_imtime_s` | | -+-----------------+------------------+--------------------+----------------------------+ -| refreq | :doc:`gf_refreq` | :doc:`gf_refreq_s` | | -+-----------------+------------------+--------------------+----------------------------+ -| retime | :doc:`gf_retime` | :doc:`gf_retime_s` | | -+-----------------+------------------+--------------------+----------------------------+ -| block_index | | | :doc:`block_gf` | -+-----------------+------------------+--------------------+----------------------------+ ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| Variable/Target | matrix_valued | scalar_valued | gf_valued | ++=========================+===============================+===============================+===========================+ +| imfreq | :doc:`gf_imfreq` | :doc:`gf_imfreq_s` | | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| imtime | :doc:`gf_imtime` | :doc:`gf_imtime_s` | | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| refreq | :doc:`gf_refreq` | :doc:`gf_refreq_s` | | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| retime | :doc:`gf_retime` | :doc:`gf_retime_s` | | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| block_index | | | :doc:`block_gf` | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ +| cartesian_product | :doc:`gf_product` | :doc:`gf_product` | | ++-------------------------+-------------------------------+-------------------------------+---------------------------+ .. toctree:: :hidden: @@ -82,32 +93,103 @@ Specializations gf_imtime gf_retime gf_block - gf_prod - -Construction/factories -------------------------------- - -gf/gf_view have very basic constructors : -default, copy, move, and one constructor from the data used by the functions (reserved for advanced users). - -Various specializations however provides several factories, adapted to each case, of the form :: - - auto g= make_gf ( ....) ; - -This is the recommended way to construct `gf` objects. -Cf examples in various specializations. + gf_product -Member types ------------------ - +Member types +-------------------------------------- ++----------------+-------------------------------------------------------------+ +| Member type | Definitions | ++================+=============================================================+ +| view_type | The corresponding view type | ++----------------+-------------------------------------------------------------+ +| regular_type | The corresponding regular type i.e. the container itself | ++----------------+-------------------------------------------------------------+ +| mesh_t | The mesh | ++----------------+-------------------------------------------------------------+ +| target_shape_t | Type storing the information to construct the target space, | +| | Depends on the specialisation (a shape for matrix_valued | +| | gf, empty for a scalar valued, ... Cf Specialisations) | ++----------------+-------------------------------------------------------------+ +| data_t | Type of the data array | ++----------------+-------------------------------------------------------------+ +| singularity_t | Type of the singularity (tail, nothing...) | ++----------------+-------------------------------------------------------------+ +| symmetry_t | Symmetry (unused at this stage). | ++----------------+-------------------------------------------------------------+ Member functions --------------------- ++-------------------------------------------+------------------------------------------+ +| Member function | Meaning | ++===========================================+==========================================+ +| :ref:`(constructor)` | | ++-------------------------------------------+------------------------------------------+ +| (destructor) | | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator ()` | Evaluation on a point of the domain | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator []` | Access to the value on the mesh | ++-------------------------------------------+------------------------------------------+ +| :ref:`mesh` | Access to the mesh | ++-------------------------------------------+------------------------------------------+ +| :ref:`singularity` | Access to the singularity | ++-------------------------------------------+------------------------------------------+ +| :ref:`symmetry` | Access to the symmetry | ++-------------------------------------------+------------------------------------------+ +| :ref:`data` | Direct view of the data [Advanced] | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator =` | Assigns values to the container | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator +=,-=,*=,/=` | compound assignment operators | ++-------------------------------------------+------------------------------------------+ + + +.. toctree:: + + :hidden: + + gf_constructors + gf_data + gf_assign + gf_call + gf_subcript + compound_ops + call + resize + STL Non-member functions ------------------------ ++---------------------------------+-------------------------------------------+ +| Member function | Meaning | ++=================================+===========================================+ +| :ref:`swap` | Swap of 2 containers | ++---------------------------------+-------------------------------------------+ +| :ref:`operator\<\<` | Writing to stream | ++---------------------------------+-------------------------------------------+ + + +.. toctree:: + :hidden: + + stream + swap + +Interaction with CLEF expressions +------------------------------------- + +The gf containers and their view classes can be :doc:`used with the CLEF Library `. + +.. toctree:: + :hidden: + + clef + + + + diff --git a/doc/reference/c++/gf/gf_assign.rst b/doc/reference/c++/gf/gf_assign.rst new file mode 100644 index 00000000..77038d91 --- /dev/null +++ b/doc/reference/c++/gf/gf_assign.rst @@ -0,0 +1,39 @@ + +.. highlight:: c + +.. _gf_reg_assign: + +Assignment +========================= + + +**Synopsis** :: + + + gf & operator=(gf const & X); (1) + + template gf & operator=(RHS const & X); (2) + +The container have a quite general assignment operator. + +* (1) just make a copy of X into *\*this*. + +* (2) **RHS** can be anything that models the :ref:`???` concept + + +.. warning:: + + In both cases, if needed, the container is resized. + + Hence **assignment invalidates all pointers and views to it**. + + +Move assign operator +--------------------------- + +**Synopsis** :: + + gf & operator=(gf && X); + +Standard move assign operator. +Move the data of X as data of `*this`. diff --git a/doc/reference/c++/gf/gf_block.rst b/doc/reference/c++/gf/gf_block.rst index fe9b56db..bd9d5f13 100644 --- a/doc/reference/c++/gf/gf_block.rst +++ b/doc/reference/c++/gf/gf_block.rst @@ -2,35 +2,165 @@ .. _gf_block: -gf or block_gf +block_gf (alias of gf) =================================================== This is a specialisation of :ref:`gf_and_view` for block functions. - -Domain & mesh ----------------- +A block Green function is nothing but Green function on a discrete domain representing the +block indices, and whose value is a Green function itself. +For convenience, for following aliases are provided :: + + template using block_gf = gf >; + template using block_gf_view = gf_view >; + template using block_gf_const_view = gf_const_view>; + +Constructors +-------------- + +The constructors of the gf. + +target_shape_t = {} -Singularity -------------- Factories ------------- +Also several factories are provided for these block Green functions. + +Factories for the regular type +..................................... + +The factories for the regular type *gf* are :: + + // From a number and a gf to be copied + template + block_gf + make_block_gf(int n, gf const & g); + + // From a vector of gf (moving directly) + template + block_gf + make_block_gf(std::vector> &&V); + + // From a vector of gf or views (a gf must be contructible from GF2) + template + block_gf + make_block_gf(std::vector const &V); + + // From a init list of GF with the correct type + template + block_gf + make_block_gf(std::initializer_list> const &V); + + // From vector and a gf to be copied + template + block_gf + make_block_gf(std::vector const &block_names, + gf const &g); + + // From vector, vector + template + block_gf + make_block_gf(std::vector const &block_names, + std::vector> V); + + // From vector, init_list + template + block_gf + make_block_gf(std::vector const &block_names, + std::initializer_list> const &V); + + +Factories for the view type +..................................... + +The factories for the view type *gf_view*, *gf_const_view* are :: + + // Build a view of the gf. + // 1- All Green functions must have the same type + // 2- [Expert only] This is a simplified version of the code. + // In the real code, the reference is of stripped from G in the type deduction. + template + gf_view + make_block_gf_view(G && ... g); + + // Make a view from a vector of gf + template + gf_view + make_block_gf_view_from_vector (std::vector V); + + +Domain & mesh +---------------- + +The domain is a discrete domain ... + +Singularity +------------- + +None. Interpolation method --------------------- +None. + Data storage --------------- +Not exposed to user. HDF5 storage convention --------------------------- +TO BE WRITTEN. + +Iterators +----------- + +TO BE COMPLETED. + +Block gf have a natural iterator, e.g. :: + + // if a BG is block function + for (auto & g : BG) .... + Examples --------- +.. compileblock:: + #include + using namespace triqs::gfs; using triqs::clef::placeholder; + int main() { + double beta =1; + + // Make a block gf of 3 gf, which are empty (default constructed). + auto Bg0 = block_gf (3); + + // make a few gf ... + auto g1 = gf ({beta, Fermion}, {2,2}); + + // ... and construct some block function out of them. + auto Bg1 = make_block_gf (3, g1); + auto Bg2 = make_block_gf ({g1,g1,g1}); + auto Bg3 = make_block_gf ({"a","b","c"}, {g1,g1,g1}); + + // do something on all blocks + for (auto const &g : Bg1) { + std::cout<< g.mesh() << std::endl; + } + + // multiply them by 1,2,3 ... + auto i = 1; + for (auto & g : Bg1) g = g * i++; + + // a little save in an hdf5 file ? + H5::H5File file("test_block_gf.h5", H5F_ACC_TRUNC ); + h5_write(file, "B3", Bg3); + } + + diff --git a/doc/reference/c++/gf/gf_call.rst b/doc/reference/c++/gf/gf_call.rst new file mode 100644 index 00000000..b2ce3115 --- /dev/null +++ b/doc/reference/c++/gf/gf_call.rst @@ -0,0 +1,63 @@ +.. highlight:: c + +.. _gf_call: + +Operator() +================================== + +**Synopsis** :: + + value_type const & operator()(mesh_t::domain_t::point_t) const (1) + + view_type operator()() const (2) + + ClefExpression operator()(ClefExpression) const (3) + + +The operator () is in charge of evaluating the Green function on its domain, +by any means (e.g. interpolation) that the specialization define. + +For example, g(t) for a Green function in time would return some interpolation of +the value of g between the closest mesh point. +Hence, this operator is only const : it would make no sense to modify g(t). +(to modify the Green function, cf operator []). + +However, the Clef automatic assignment method (cf...) *is* written +with the () operator, in order have a better syntax for multivariable function. +It would be more logical to use [], but a strange, old and extremely inconvenient limitation of C++ +forbids to overload [] for multiple variables... + + +NB : This is valid for both the container (e.g. gf), and the view (e.g. gf_view). + + +.. _gf_element_access: + +(1) Evaluation +--------------------------------- + +Evaluation at one point of the domain. + +NB : Specialization may provide other overloads. + +.. _gf_making_view: + +(2) Building a view +--------------------------------- + + +The special case (2) (no argument) returns a complete view of the object +(equivalent to view_type(* this)). + + +.. _gf_lazy: + +(3) Interaction with clef expressions +------------------------------------------------- + +* gf and gf_view can be used with the triqs::clef library + + + + + diff --git a/doc/reference/c++/gf/gf_constructors.rst b/doc/reference/c++/gf/gf_constructors.rst new file mode 100644 index 00000000..760cf1b6 --- /dev/null +++ b/doc/reference/c++/gf/gf_constructors.rst @@ -0,0 +1,54 @@ +.. highlight:: c + +.. _gf_constr: + +Constructors +==================== + +Constructors of gf +--------------------------- + + ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| Constructors | Comments | ++================================+===================================================================================================================+ +| gf() | Empty gf | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(gf const &) | Copy construction | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(gf &&) | Move construction | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(gf_view & g) | Make a clone of the view. | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(gf_const_view & g) | Make a clone of the const view. | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(mesh_t m, target_shape_t s) | Constructs a gf with mesh m and a target shape s. s depends on the specialization: it is the information needed | +| | to construct the gf, aside from the mesh itself : typically the size of the matrix for a matrix_valued gf. | +| | target_shape_t is described in the specialization section. section XXX). The function is initialized to 0 | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ +| gf(mesh_t m, data_t dat, | *[Advanced]* Construct a gf from its elements (a mesh, a data array, a singularity, a symmetry, and an evaluator. | +| singularity_view_t const & si, | Normally should be reserved for lib purposes...(remove from the doc ?). | +| symmetry_t const & s, | | +| evaluator_t const & eval) | | ++--------------------------------+-------------------------------------------------------------------------------------------------------------------+ + + + +Examples +------------ + +There are more examples for each specializations in the corresponding pages. + + +.. compileblock:: + + #include + using namespace triqs::gfs; + int main(){ + auto beta = 10; + gf gf { {beta, Fermion}, {1,1}}; + } + + + + diff --git a/doc/reference/c++/gf/gf_data.rst b/doc/reference/c++/gf/gf_data.rst new file mode 100644 index 00000000..fb7896b5 --- /dev/null +++ b/doc/reference/c++/gf/gf_data.rst @@ -0,0 +1,49 @@ +.. highlight:: c + +.. _gf_data: + +Data access +==================== + +mesh +------------ + +* **Synopsis**: + + .. cpp:function:: mesh_t const & () const + + + Access to the mesh of the green function. + +data +------------ + +* **Synopsis**: + + .. cpp:function:: data_t const & () const + .. cpp:function:: data_t & () + + + Access to the data array where the value of the gf is stored on the mesh points. + +singularity +------------ + +* **Synopsis**: + + .. cpp:function:: singularity_t const & () const + .. cpp:function:: singularity & () + + + Access to the singularity type + +symmetry +------------ + +* **Synopsis**: + + .. cpp:function:: symmetry_t const & () const + + Access to the symmetry type. Can not be modifed after construction. *(why ?)*. + + diff --git a/doc/reference/c++/gf/gf_imfreq.rst b/doc/reference/c++/gf/gf_imfreq.rst index b22ff37a..2fc32a06 100644 --- a/doc/reference/c++/gf/gf_imfreq.rst +++ b/doc/reference/c++/gf/gf_imfreq.rst @@ -5,27 +5,18 @@ gf ========================================================== + This is a specialisation of :ref:`gf_and_view` for imaginary Matsubara frequencies. Domain & mesh ---------------- - Singularity ------------- :ref:`gf_tail`. -Factories -------------- - - -The factories are :: - - make_gf(gf_mesh m, matrix_shape_t shape, local::tail_view t = local::tail(shape) ) - make_gf(double beta, statistic_enum S, matrix_shape_t shape, size_t Nmax = 1025, local::tail_view t = local::tail(shape) ) - Interpolation method --------------------- @@ -51,30 +42,25 @@ Examples .. compileblock:: - #include - using namespace triqs::gfs; - int main() { - double beta=1; // inverse temperature - size_t n_freq=5; // we will have 5 points including iw=0 and iw=beta - - auto GF = make_gf(beta, Fermion, make_shape(1,1), n_freq); - }; - - -An alternative declaration with an explicit construction of the underlying mesh: - -.. compileblock:: - - - #include - using namespace triqs::gfs; + #include + using namespace triqs::gfs; using triqs::clef::placeholder; int main(){ double beta=10; int Nfreq =100; - - auto GF = make_gf(gf_mesh{beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1)); - // or even simpler - auto GF2 = make_gf({beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1)); + + // First give information to build the mesh, second to build the target + auto GF1 = gf { {beta,Fermion,Nfreq}, {1,1} }; + // or a more verbose/explicit form ... + auto GF2 = gf { gf_mesh{beta,Fermion,Nfreq}, make_shape(1,1) }; + + // Filling the gf with something... + placeholder<0> wn_; + GF1(wn_) << 1/ (wn_ + 2); + + // evaluation at n=3 + std::cout << GF1(3) << " == "<< 1/ ( 1_j * std::acos(-1) / beta * (2*3+1) + 2) << std::endl; + // the high frequency expansion was automatically computed. + std::cout << GF1.singularity() << std::endl; } diff --git a/doc/reference/c++/gf/gf_imfreq_s.rst b/doc/reference/c++/gf/gf_imfreq_s.rst index 0710c380..81650bc2 100644 --- a/doc/reference/c++/gf/gf_imfreq_s.rst +++ b/doc/reference/c++/gf/gf_imfreq_s.rst @@ -16,15 +16,6 @@ Singularity :ref:`gf_tail`. -Factories -------------- - - -The factories are :: - - make_gf(mesh m, local::tail_view t = local::tail({1,1}) ) - make_gf(double beta, statistic_enum S, size_t Nmax = 1025, local::tail_view t = local::tail({1,1}) ) - Interpolation method --------------------- @@ -50,30 +41,26 @@ Examples .. compileblock:: - #include - using namespace triqs::gfs; - int main() { - double beta=1; // inverse temperature - size_t n_freq=5; // we will have 5 points including iw=0 and iw=beta - - auto GF = make_gf(beta, Fermion, n_freq); - }; - - -An alternative declaration with an explicit construction of the underlying mesh: - -.. compileblock:: - - - #include - using namespace triqs::gfs; + #include + using namespace triqs::gfs; using triqs::clef::placeholder; int main(){ double beta=10; int Nfreq =100; - - auto GF = make_gf(gf_mesh{beta,Fermion,Nfreq}); - // auto GF2 = make_gf({beta,Fermion,Nfreq}); + + // First give information to build the mesh, second to build the target + auto GF1 = gf { {beta,Fermion,Nfreq} }; + // or a more verbose/explicit form ... + auto GF2 = gf { gf_mesh{beta,Fermion,Nfreq} }; + + // Filling the gf with something... + placeholder<0> wn_; + GF1(wn_) << 1/ (wn_ + 2); + + // evaluation at n=3 + std::cout << GF1(3) << " == "<< 1/ ( 1_j * std::acos(-1) / beta * (2*3+1) + 2) << std::endl; + // the high frequency expansion was automatically computed. + std::cout << GF1.singularity() << std::endl; } - + diff --git a/doc/reference/c++/gf/gf_imtime.rst b/doc/reference/c++/gf/gf_imtime.rst index 17b51a01..ed92edab 100644 --- a/doc/reference/c++/gf/gf_imtime.rst +++ b/doc/reference/c++/gf/gf_imtime.rst @@ -10,48 +10,52 @@ This is a specialisation of :ref:`gf_and_view` for imaginary Matsubara time. Domain & mesh ---------------- - Singularity ------------- -Factories -------------- - -Code :: - - - make_gf(MeshType && m, tqa::mini_vector shape, local::tail_view const & t) - make_gf(double beta, statistic_enum S, tqa::mini_vector shape, size_t Nmax=1025, mesh_kind mk= half_bins) - make_gf(double beta, statistic_enum S, tqa::mini_vector shape, size_t Nmax, mesh_kind mk, local::tail_view const & t) - - Interpolation method --------------------- +None. + Data storage --------------- +* `data_t` : 3d array (C ordered) of complex. + +* g.data()(i, range(), range()) is the value of g for the i-th point of the mesh. + HDF5 storage convention --------------------------- +h5 tag : `ImTime` Examples --------- -.. compileblock:: +.. compileblock:: - #include - using namespace triqs::gfs; + #include + using namespace triqs::gfs; using triqs::clef::placeholder; + int main(){ + double beta=10, a = 1; + int n_times=5; + + // First give information to build the mesh, second to build the target + auto GF1 = gf { {beta,Fermion,n_times}, {1,1} }; + // or a more verbose/explicit form ... + auto GF2 = gf { gf_mesh{beta,Fermion,n_times}, make_shape(1,1) }; + + // Filling the gf with something... + placeholder<0> tau_; + //GF1(tau_) << exp ( - a * tau_) / (1 + exp(- beta * a)); + + // evaluation at n=3 + std::cout << make_matrix(GF1(3)) << " == "<< exp ( - a * 3) / (1 + exp(- beta * a)) << std::endl; + } - int main() { - double beta=1; //inverse temperature - triqs::gfs::statistic_enum stat=triqs::gfs::Fermion; - size_t n_times=5; - auto shape = triqs::arrays::make_shape(1,1); - auto GF=make_gf(beta, stat, shape, n_times); - }; diff --git a/doc/reference/c++/gf/gf_part_eval_curry.rst b/doc/reference/c++/gf/gf_part_eval_curry.rst new file mode 100644 index 00000000..74a2c1c1 --- /dev/null +++ b/doc/reference/c++/gf/gf_part_eval_curry.rst @@ -0,0 +1,97 @@ +.. highlight:: c + +.. _gf_eval_curry: + +Partial evaluation and Currying +================================ + +.. warning:: + + This part of the library is still in alpha, in development. + +Multivariable Green function are be both partially evalued, and "curried". + +Partial evaluation +-------------------------- + +**Purpose** : + + Having a function (x,y) -> f(x,y), fix x = x0 in order to obtain a function of y only. + +**Synopsis** :: + + template + gf_view< sliced_domain_t> ,Target, Opt, IsConst> + partial_eval(gf_impl< cartesian_product, Target,Opt,B,IsConst> const & g, IT index) { + +Probably an example would help here ... : + +.. compileblock:: + + #include + using namespace triqs::gfs; using triqs::clef::placeholder; + int main(){ + double beta =1, tmin=0, tmax=1.0; + int n_re_time=100, n_im_time=100; + + using g_t_tau_s = gf, scalar_valued>; + + // a scalar valued function + auto g= g_t_tau_s { { {tmin, tmax, n_re_time}, {beta, Fermion, n_im_time}} }; + + // evaluation of the second variable to 3 : 3 is the **index** of the point ! + auto g_sliced = partial_eval<1>(g(), 3); + // g_sliced is now a gf_view/gf_const_view seeing the value at the index 3 + + std::cout<< g_sliced<< std::endl; + } + + +Currying +------------- + +**Purpose** : + + Having a function (x,y) -> f(x,y), rewrite it as x-> y-> f(x,y) + +**Synopsis** :: + + template + gf_view, pos...>>, + lambda_valued, Target, Opt,IsConst>, pos...>>, Opt, IsConst> + curry(gf_view, Target, Opt, IsConst> g); + + +.. compileblock:: + + #include + using namespace triqs::gfs; using triqs::clef::placeholder; + int main(){ + double beta =1, wmin=0, wmax=1.0; + int n_re_freq=100, n_im_freq=100; + + using g_w_wn_s = gf, scalar_valued>; + + // a scalar valued function + auto g= g_w_wn_s{ { {wmin, wmax, n_re_freq}, {beta, Fermion, n_im_freq}} }; + + // put expression in it + triqs::clef::placeholder<0> w_; + triqs::clef::placeholder<1> wn_; + g (w_,wn_)<<1/(wn_-1)/( w_ + 3_j ); + + // Currying by selecting the first variable, i.e. t -> tau -> g(t,tau) + auto g1 = curry<0>(g); + + // Currying by selecting the second variable, i.e. tau -> t -> g(t,tau) + auto g2 = curry<1>(g); + + //std::cout << g << g1[1]<< g2 [2] << std::endl; + std::cout<< g1[1][2] << g2 [2][1] << g [{1,2}] << std::endl; + } + + + + + + diff --git a/doc/reference/c++/gf/gf_prod.rst b/doc/reference/c++/gf/gf_prod.rst deleted file mode 100644 index f3e02030..00000000 --- a/doc/reference/c++/gf/gf_prod.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. highlight:: c - -.. _gf_prod: - -gf, T> -=================================================== - -This is a specialisation of :ref:`gf_and_view` for many variables Green functions. - -Domain & mesh ----------------- - - -Singularity -------------- - -Factories -------------- - - -Interpolation method ---------------------- - -Data storage ---------------- - - -HDF5 storage convention ---------------------------- - - - -Examples ---------- - - diff --git a/doc/reference/c++/gf/gf_product.rst b/doc/reference/c++/gf/gf_product.rst new file mode 100644 index 00000000..e7a6b204 --- /dev/null +++ b/doc/reference/c++/gf/gf_product.rst @@ -0,0 +1,89 @@ +.. highlight:: c + +.. _gf_product: + +Green functions on cartesian product domains +=================================================== + +.. warning:: + + This part of the library is still in alpha, in development. + +Domain & mesh +---------------- + +The domain is a cartesian product of domains. + +The mesh is a cartesian product of the corresponding meshes. + + +Singularity +------------- + +None. + +Interpolation method +--------------------- + +A multidimensional linear interpolation is automatically +built from the linear interpolation of the domains. + +Data storage +--------------- + +Like single variables gf, the first index of the array is a flattening +of the indices of the composite mesh. + + +HDF5 storage convention +--------------------------- + +For convenience, in hdf5 files, the arrays has higher dimension, +so that the first indices are *not* flatten. EXPLAIN. + + +Examples +--------- +.. compileblock:: + + #include + using namespace triqs::gfs; using triqs::clef::placeholder; + int main(){ + double beta =1, tmin=0, tmax=1.0; + int n_re_time=100, n_im_time=100; + + using g_t_tau_s = gf, scalar_valued>; + using g_t_tau_m = gf, matrix_valued>; + using g_t_tau_t = gf, tensor_valued<3>>; + + // a scalar valued function + auto m1 = gf_mesh{tmin, tmax, n_re_time}; + auto m2 = gf_mesh{beta, Fermion, n_im_time}; + auto g= g_t_tau_s { {m1,m2} }; + + // a more compact notation + auto g2= g_t_tau_s { { {tmin, tmax, n_re_time}, {beta, Fermion, n_im_time}} }; + + // a matrix_valued_version + auto gm= g_t_tau_m { { {tmin, tmax, n_re_time}, {beta, Fermion, n_im_time}} , {2,2} }; + + // a tensor_valued_version + auto gt= g_t_tau_t { { {tmin, tmax, n_re_time}, {beta, Fermion, n_im_time}} , {2,2,2} }; + + // a little save in an hdf5 file ? + H5::H5File file("test_product_gf.h5", H5F_ACC_TRUNC ); + h5_write(file, "g", g); + } + + +See also : + +.. toctree:: + + :maxdepth: 1 + + gf_part_eval_curry + + + + diff --git a/doc/reference/c++/gf/gf_refreq.rst b/doc/reference/c++/gf/gf_refreq.rst index 0fc9e71d..afc28d5e 100644 --- a/doc/reference/c++/gf/gf_refreq.rst +++ b/doc/reference/c++/gf/gf_refreq.rst @@ -14,47 +14,37 @@ Domain & mesh Singularity ------------- -Factories -------------- - -code :: - - make_gf(MeshType && m, tqa::mini_vector shape, local::tail_view const & t) - make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector shape) - make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector shape, mesh_kind mk) - - - - Interpolation method --------------------- +Linear interpolation on the mesh. + Data storage --------------- +* `data_t` : 3d array (C ordered) of complex. + +* g.data()(i, range(), range()) is the value of g for the i-th point of the mesh. HDF5 storage convention --------------------------- - +h5 tag : `ReFreq` Examples --------- - .. compileblock:: - #include + #include using namespace triqs::gfs; - + int main() { - double tmin=0; - double tmax=10; - //we will have 5 points - size_t n_times=5; - //we want a Green function whose values are complex numbers - auto shape = triqs::arrays::make_shape(1,1); - // the type of GF is triqs::gfs::gf - auto GF=make_gf(tmin, tmax, n_times, shape); + double wmin=0, wmax=10; // Frequencies interval + auto n_freq=100; // Number of points + + // We want a 2x2 matrix valued function on this mesh... + auto g = gf { {wmin, wmax, n_freq}, {2,2} }; }; + diff --git a/doc/reference/c++/gf/gf_retime.rst b/doc/reference/c++/gf/gf_retime.rst index 8fcedfcd..57a0900b 100644 --- a/doc/reference/c++/gf/gf_retime.rst +++ b/doc/reference/c++/gf/gf_retime.rst @@ -14,44 +14,36 @@ Domain & mesh Singularity ------------- -Factories -------------- - -Code :: - - make_gf(double tmin, double tmax, size_t n_points, tqa::mini_vector shape) - - make_gf(double tmin, double tmax, size_t n_points, tqa::mini_vector shape, mesh_kind mk) - - - Interpolation method --------------------- +Linear interpolation on the mesh. + Data storage --------------- +* `data_t` : 3d array (C ordered) of complex. + +* g.data()(i, range(), range()) is the value of g for the i-th point of the mesh. HDF5 storage convention --------------------------- - +h5 tag : `ReTime` Examples --------- .. compileblock:: - #include + #include using namespace triqs::gfs; - + 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(wmin, wmax, n_freq, shape); + double tmin=0, tmax=10; // the time interval + auto n_times=100; // we will have 100 points + + //we want a 2x2 matrix-valued Green function + auto g=gf{ {tmin, tmax, n_times} , {2,2} }; }; - diff --git a/doc/reference/c++/gf/gf_subscript.rst b/doc/reference/c++/gf/gf_subscript.rst new file mode 100644 index 00000000..39d3daf7 --- /dev/null +++ b/doc/reference/c++/gf/gf_subscript.rst @@ -0,0 +1,63 @@ +.. highlight:: c + +.. _gf_subscript: + +Operator [] +================================== + +**Synopsis** :: + + value_type const & operator[](mesh_t::index_t const &) const (1a) + value_type & operator[](mesh_t::index_t const &) (1b) + + value_type const & operator[](closest_mesh_pt_t const &) const (2a) + value_type & operator[](closest_mesh_pt_t const &) (2b) + + ClefExpression operator[](ClefExpression expr) const (3) + + +The operator [] is in charge of accessing the data of the Green function +on the mesh. This is therefore a way to modify the Green function. + + +NB : This is valid for both the container (e.g. gf), and the view (e.g. gf_view). + + +.. _gf_subscript_index: + +(1) Use the linear index of the mesh +----------------------------------------- + + +.. _gf_subscript_closest: +.. + +(2) Find the closest mesh point from a domain point +--------------------------------------------------------- + +* May or may not be provided by the specialisation. Cf specialization. + +* This is normally used with the helper function:: + + closest_mesh_point_t closest_mesh_point(Anything x) + + closest_mesh_point_t is just a little "vehicle" that can contain anything (by copy or ref ???), + and carry it through the []. + +* Usage :: + + g [ closest_mesh_point(x) ] += y; + + +.. _gf_subscript_lazy: + +(3) Interaction with clef expressions +------------------------------------------------- + +Like (), [] can be called with a ClefExpression. + + + + + + diff --git a/doc/reference/c++/gf/implementation_notes.rst b/doc/reference/c++/gf/implementation_notes.rst index b686d496..aeba6efc 100644 --- a/doc/reference/c++/gf/implementation_notes.rst +++ b/doc/reference/c++/gf/implementation_notes.rst @@ -3,73 +3,4 @@ Implementation notes =========================== -This part describes how to create a new green function.... - -.. _Concept_HasConstIterator: - -Mesh -------------------------------------------------- - -* **Purpose** : An object which has a const_iterator and corresponding functions. - -* **Refines** : - -* **Definition** : - -+--------------------------------------------------------------+-------------------------------------------------------------------------------+ -| Elements | Comment | -+==============================================================+===============================================================================+ -| mesh_pt_generator const_iterator | A generator of all the mesh points. | -+--------------------------------------------------------------+-------------------------------------------------------------------------------+ -| const_iterator begin()/end() const | Standard access to iterator on the mesh | -| const_iterator cbegin()/cend() const | Standard access to iterator on the mesh | -+--------------------------------------------------------------+-------------------------------------------------------------------------------+ - - - -Doxygen documentation -------------------------------------------------- - - -The :doxy:`full C++ documentation` is available here. - -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| Elements | Comment | -+====================================================================================+===============================================================================+ -| struct tag {}; | A tag for the gf | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| mesh_t | Mesh for the gf, modeling Mesh concept | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| storage_t | The type of the storage of the data (array, vector, etc....) | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| singularity_t | Type of object storing the singularities of the gf. It is used e.g. in the | -| | Fourier transformation, density computation, etc... For a simple g(omega), | -| | g(t), it is typically a high frequency tail. For a more complex function | -| | g(nu,nu'), it can be different. | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| symmetry_t | Type of the object storing the symmetry property of the Green function. It is | -| | *nothing* by default. This type must be a value (DefaultConstructible, | -| | CopyConstructible, Assignable) | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| target_indices_t | Type of the indices of the gf, typically array | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| static const int arity | Number of variable authorized in calling the gf (just for compile time check | -| | and nice error message, it is not really necessary) | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| struct evaluator { auto operator()( mesh_t const &, DATA_t const &, S_t const &, | All the permitted const call of the gf ! (DATA_t defined below) with the | -| Args&&... args) .... as many overload as necessary } | parenthesis operator The gf<...> function create such a struct, so it can | -| | hold some data ... | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| static std::string h5_name() | Name for hdf5 naming (attribute of the tree in which the gf is stored). | -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ - -* **Values vs Views** - target_t, singularity_t, indices_t are expected to be *values*. - The corresponding views, i.e., target_view_t, singularity_view_t, indices_view_t will be deduced from the value type, and - replaced by the value_type if no view is available. - -* S_t is singularity_t or its corresponding view type (if it exists). - - - diff --git a/doc/reference/c++/gf/intro.rst b/doc/reference/c++/gf/intro.rst index 147c8900..f3db05af 100644 --- a/doc/reference/c++/gf/intro.rst +++ b/doc/reference/c++/gf/intro.rst @@ -5,15 +5,13 @@ Introduction ================= -The TRIQS library provides a generic container `gf` and its view `gf_view`, to store and manipulate -various Green functions. - -Several specific green functions are implemented : +The `gf` container and its views `gf_view` and `gf_const_view` allows to store and manipulate +various Green functions, on various meshes, e.g. : +* Matsubara frequency(ies), +* Matsubara time(s), * real time(s), * real frequency(ies), -* Matsubara time(s), -* Matsubara frequency(ies), * Legendre representation. * Block of other green functions. * Cartesian product of green functions. @@ -21,23 +19,8 @@ Several specific green functions are implemented : Various free functions are also provided to handle transformations between various representation of a Green function, such as Fourier transforms. -More generally, the variable is a point of a ``domain`` - -The value of the Green function on a point of the domain can be a scalar, a matrix or whatever you want (this type is called type ``target_t``). - -You can group several green functions into *blocks* (for example, one block per orbital, or per wave vector...). - -Fourier transforms are implemented for these Green functions: - - real time <-> real frequency - - Matsubara time <-> Matsubara frequency - - This section is organized as follows : -* the concepts related to Green functions, their domain, their representation on a grid. -* the container `gf` and its view `gf_view`, which represent various Green functions. - +TO BE WRITTEN