From 0f524b26fc7211c085c1705d36c2adce02d202fc Mon Sep 17 00:00:00 2001 From: Olivier Parcollet Date: Thu, 22 Aug 2013 16:55:51 +0200 Subject: [PATCH] work on doc --- doc/contents.rst | 2 +- doc/reference/c++/arrays/Design/contents.rst | 11 - doc/reference/c++/arrays/Interop_Python.rst | 18 + doc/reference/c++/arrays/Iterators.rst | 2 - doc/reference/c++/arrays/algebras.rst | 4 +- doc/reference/c++/arrays/all.rst | 360 ------------------ doc/reference/c++/arrays/arrays.rst | 139 ------- doc/reference/c++/arrays/assignment.rst | 51 +-- doc/reference/c++/arrays/basic_classes.rst | 103 ----- doc/reference/c++/arrays/basic_interop.rst | 21 - doc/reference/c++/arrays/call.rst | 25 -- doc/reference/c++/arrays/class_diff.rst | 33 -- doc/reference/c++/arrays/compound_ops.rst | 21 - doc/reference/c++/arrays/concepts.rst | 203 ++++++++++ .../c++/arrays/{ => containers}/STL.rst | 0 doc/reference/c++/arrays/containers/call.rst | 137 +++++++ .../c++/arrays/containers/range_ell.rst | 76 ++++ .../reg_assign.rst} | 60 +-- .../reg_constructors.rst} | 57 +-- .../c++/arrays/containers/regular.rst | 146 +++++++ .../c++/arrays/containers/resize.rst | 71 ++++ .../{move_swap.rst => containers/swap.rst} | 27 +- doc/reference/c++/arrays/containers/views.rst | 105 +++++ doc/reference/c++/arrays/contents.rst | 34 +- doc/reference/c++/arrays/contents.rst.1 | 20 - doc/reference/c++/arrays/cookbook/basic.rst | 3 +- doc/reference/c++/arrays/element_acces.rst | 27 -- doc/reference/c++/arrays/expr_arith.rst | 104 ----- doc/reference/c++/arrays/expr_custom.rst | 59 --- doc/reference/c++/arrays/expr_predef.rst | 22 -- doc/reference/c++/arrays/expression.rst | 48 --- doc/reference/c++/arrays/fold.rst | 57 --- doc/reference/c++/arrays/foreach.rst | 2 +- doc/reference/c++/arrays/h5_proxy.rst | 4 + .../implementation_notes/assignment.rst | 12 + .../centralconcept.rst | 0 .../concepts.rst | 2 + .../arrays/implementation_notes/contents.rst | 27 ++ .../cuboid_formula.rst | 0 .../expresssion_template.rst | 16 + .../implementation_notes/functional.rst | 8 + .../c++/arrays/implementation_notes/hdf5.rst | 10 + .../arrays/implementation_notes/indexmaps.rst | 21 + .../c++/arrays/implementation_notes/isp.rst | 13 + .../arrays/implementation_notes/linalg.rst | 16 + .../arrays/implementation_notes/python.rst | 11 + .../implementation_notes/reinterpretation.rst | 14 + .../slicing.rst | 0 .../arrays/implementation_notes/storage.rst | 20 + .../strategy.rst | 0 .../implementation_notes/userclasses.rst | 12 + doc/reference/c++/arrays/introduction.rst | 7 +- doc/reference/c++/arrays/map.rst | 12 +- doc/reference/c++/arrays/mapped_fnt.rst | 28 +- doc/reference/c++/arrays/matrix.rst | 101 ----- .../c++/arrays/memory_management.rst | 40 -- doc/reference/c++/arrays/multithreading.rst | 12 + doc/reference/c++/arrays/options.rst | 79 ---- doc/reference/c++/arrays/python_tools.rst | 18 - doc/reference/c++/arrays/shape.rst | 66 ++-- doc/reference/c++/arrays/slicing.rst | 22 +- doc/reference/c++/arrays/vector.rst | 98 ----- doc/reference/c++/arrays/view_or_not_view.rst | 55 ++- doc/reference/c++/arrays/views.rst | 66 ---- doc/reference/c++/contents.rst | 9 +- doc/reference/c++/gf/concepts.rst | 245 +++--------- doc/reference/c++/gf/contents.rst | 38 +- doc/reference/c++/gf/cookbook/imaginary.rst | 59 --- doc/reference/c++/gf/cookbook/real.rst | 27 +- doc/reference/c++/gf/gf_and_view.rst | 88 +++++ doc/reference/c++/gf/gf_block.rst | 36 ++ doc/reference/c++/gf/gf_imfreq.rst | 80 ++++ doc/reference/c++/gf/gf_imtime.rst | 57 +++ doc/reference/c++/gf/gf_misc.rst | 16 + doc/reference/c++/gf/gf_prod.rst | 36 ++ doc/reference/c++/gf/gf_refreq.rst | 60 +++ doc/reference/c++/gf/gf_retime.rst | 57 +++ doc/reference/c++/gf/implementation_notes.rst | 75 ++++ doc/reference/c++/gf/intro.rst | 43 +++ doc/reference/c++/gf/meshes.rst | 16 +- doc/reference/c++/gf/plan.rst | 46 +++ doc/reference/c++/gf/tail.rst | 7 + doc/reference/c++/gf/the_four_basic_GFs.rst | 46 --- doc/reference/c++/utilities/contents.rst | 14 + .../c++/utilities/python_include_mess.rst | 28 ++ doc/reference/c++/utilities/tupletools.rst | 77 ++++ doc/reference/python/contents.rst | 2 +- test/triqs/arrays/diagonal_matrix.cpp | 5 + 88 files changed, 1970 insertions(+), 2035 deletions(-) delete mode 100644 doc/reference/c++/arrays/Design/contents.rst delete mode 100644 doc/reference/c++/arrays/Iterators.rst delete mode 100644 doc/reference/c++/arrays/all.rst delete mode 100644 doc/reference/c++/arrays/arrays.rst delete mode 100644 doc/reference/c++/arrays/basic_classes.rst delete mode 100644 doc/reference/c++/arrays/basic_interop.rst delete mode 100644 doc/reference/c++/arrays/call.rst delete mode 100644 doc/reference/c++/arrays/class_diff.rst delete mode 100644 doc/reference/c++/arrays/compound_ops.rst create mode 100644 doc/reference/c++/arrays/concepts.rst rename doc/reference/c++/arrays/{ => containers}/STL.rst (100%) create mode 100644 doc/reference/c++/arrays/containers/call.rst create mode 100644 doc/reference/c++/arrays/containers/range_ell.rst rename doc/reference/c++/arrays/{compound_assignment.rst => containers/reg_assign.rst} (61%) rename doc/reference/c++/arrays/{construct.rst => containers/reg_constructors.rst} (77%) create mode 100644 doc/reference/c++/arrays/containers/regular.rst create mode 100644 doc/reference/c++/arrays/containers/resize.rst rename doc/reference/c++/arrays/{move_swap.rst => containers/swap.rst} (74%) create mode 100644 doc/reference/c++/arrays/containers/views.rst delete mode 100644 doc/reference/c++/arrays/contents.rst.1 delete mode 100644 doc/reference/c++/arrays/element_acces.rst delete mode 100644 doc/reference/c++/arrays/expr_arith.rst delete mode 100644 doc/reference/c++/arrays/expr_custom.rst delete mode 100644 doc/reference/c++/arrays/expr_predef.rst delete mode 100644 doc/reference/c++/arrays/expression.rst delete mode 100644 doc/reference/c++/arrays/fold.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/assignment.rst rename doc/reference/c++/arrays/{Design => implementation_notes}/centralconcept.rst (100%) rename doc/reference/c++/arrays/{Design => implementation_notes}/concepts.rst (99%) create mode 100644 doc/reference/c++/arrays/implementation_notes/contents.rst rename doc/reference/c++/arrays/{Design => implementation_notes}/cuboid_formula.rst (100%) create mode 100644 doc/reference/c++/arrays/implementation_notes/expresssion_template.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/functional.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/hdf5.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/indexmaps.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/isp.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/linalg.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/python.rst create mode 100644 doc/reference/c++/arrays/implementation_notes/reinterpretation.rst rename doc/reference/c++/arrays/{Design => implementation_notes}/slicing.rst (100%) create mode 100644 doc/reference/c++/arrays/implementation_notes/storage.rst rename doc/reference/c++/arrays/{Design => implementation_notes}/strategy.rst (100%) create mode 100644 doc/reference/c++/arrays/implementation_notes/userclasses.rst delete mode 100644 doc/reference/c++/arrays/matrix.rst delete mode 100644 doc/reference/c++/arrays/memory_management.rst create mode 100644 doc/reference/c++/arrays/multithreading.rst delete mode 100644 doc/reference/c++/arrays/options.rst delete mode 100644 doc/reference/c++/arrays/python_tools.rst delete mode 100644 doc/reference/c++/arrays/vector.rst delete mode 100644 doc/reference/c++/arrays/views.rst create mode 100644 doc/reference/c++/gf/gf_and_view.rst create mode 100644 doc/reference/c++/gf/gf_block.rst create mode 100644 doc/reference/c++/gf/gf_imfreq.rst create mode 100644 doc/reference/c++/gf/gf_imtime.rst create mode 100644 doc/reference/c++/gf/gf_misc.rst create mode 100644 doc/reference/c++/gf/gf_prod.rst create mode 100644 doc/reference/c++/gf/gf_refreq.rst create mode 100644 doc/reference/c++/gf/gf_retime.rst create mode 100644 doc/reference/c++/gf/implementation_notes.rst create mode 100644 doc/reference/c++/gf/intro.rst create mode 100644 doc/reference/c++/gf/plan.rst create mode 100644 doc/reference/c++/gf/tail.rst delete mode 100644 doc/reference/c++/gf/the_four_basic_GFs.rst create mode 100644 doc/reference/c++/utilities/contents.rst create mode 100644 doc/reference/c++/utilities/python_include_mess.rst create mode 100644 doc/reference/c++/utilities/tupletools.rst diff --git a/doc/contents.rst b/doc/contents.rst index 6061fcdb..f562b797 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -4,7 +4,7 @@ Table of contents ================= .. toctree:: - :maxdepth: 3 + :maxdepth: 2 overview installation/install diff --git a/doc/reference/c++/arrays/Design/contents.rst b/doc/reference/c++/arrays/Design/contents.rst deleted file mode 100644 index de4e0d73..00000000 --- a/doc/reference/c++/arrays/Design/contents.rst +++ /dev/null @@ -1,11 +0,0 @@ -Concepts, implementation, design ... -*************************************** - -.. highlight:: c - -.. toctree:: - :maxdepth: 1 - :numbered: - - concepts - diff --git a/doc/reference/c++/arrays/Interop_Python.rst b/doc/reference/c++/arrays/Interop_Python.rst index 857ef0fe..b8a37893 100644 --- a/doc/reference/c++/arrays/Interop_Python.rst +++ b/doc/reference/c++/arrays/Interop_Python.rst @@ -76,3 +76,21 @@ Put here the array_cython example _testarray.f(a) +Memory management +----------------- + +TO BE WRITTEN + +The reference counting system is *compatible* with the Python reference counting (but distinct), +if you compile with python support of course. + +As long as you write pure C++ code, you are basically using a shared_ptr to your data block. +No python is involved. + +But, if you return your view into a numpy array in python, ownership of your data +is automatically transfered to the python interpreter:: + +The interpreter then take the responsability of destroying the data when needed (meaning here, long after f has returned, +when the python object returned will be cleaned). + + diff --git a/doc/reference/c++/arrays/Iterators.rst b/doc/reference/c++/arrays/Iterators.rst deleted file mode 100644 index 8ad8b176..00000000 --- a/doc/reference/c++/arrays/Iterators.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. highlight:: c - diff --git a/doc/reference/c++/arrays/algebras.rst b/doc/reference/c++/arrays/algebras.rst index 3f653cfd..c25e834c 100644 --- a/doc/reference/c++/arrays/algebras.rst +++ b/doc/reference/c++/arrays/algebras.rst @@ -6,7 +6,7 @@ Operations : array and matrix/vector algebras Operations ------------ -Arrays and matrices can be combined in formal algebraic expressions, which models the :ref:`HasImmutableArrayInterface` concept. +Arrays and matrices can be combined in formal algebraic expressions, which models the :ref:`ImmutableCuboidArray` concept. This algebraic expressions can therefore be used as RHS of assignment (SEE) or in array/matrix contructors. For example ; @@ -71,7 +71,7 @@ Indeed, the operations are implemented with the `expression templates` technique The principle is that the result of A+B is **NOT** an array, but a more complex type which stores the expression using the naturally recursive structure of templates. -Expressions models :ref:`HasImmutableArrayInterface` concept. +Expressions models :ref:`ImmutableCuboidArray` concept. They behave like an immutable array : they have a domain, they can be evaluated. Hence they can used *anywhere* an object modeling this concept is accepted, e.g. : diff --git a/doc/reference/c++/arrays/all.rst b/doc/reference/c++/arrays/all.rst deleted file mode 100644 index b10dd6f4..00000000 --- a/doc/reference/c++/arrays/all.rst +++ /dev/null @@ -1,360 +0,0 @@ -.. highlight:: c - -array and array_view -============================ - -array and array_view are the class for standard d-dimensional cuboid array -and the corresponding view. - -Template parameters ----------------------------- - -* The class has four template parameters (same for array_view). - - .. code-block:: c - - array - - - ============================ ========================== ======================================= - Template parameter Access in the class Meaning - ============================ ========================== ======================================= - ValueType value_type The type of the element of the array - Rank rank The rank of the array *[int]* - IndexOrderTag indexmap_type The ordering in memory : can be Tag::C, Tag::Fortran or a permutation - StorageTag storage_type The storage : Tag::shared_block or Tag::numpy - ============================ ========================== ======================================= - - -* Various IndexOrderTag are possible : - - ================= ==================================================================================================== - IndexOrderTag Meaning - ================= ==================================================================================================== - Tag::C C-style order *[default]* - Tag::Fortran Fortran-style order - P - P is a permutation - - Determined by a permutation P at compile time. Explain here the permutation, the convention. - ================= ==================================================================================================== - - -* Two possible storages : - - ================== ============================================================================ - StorageTag Meaning - ================== ============================================================================ - Tag::shared_block a (shared_ptr on a) C++ block *[default]* - Tag::numpy stored in a numpy array, in which case the array is also a numpy array - and read numpy, be returned as numpy, sliced into a numpy, etc... - ================== ============================================================================ - - -.. _array_constructors: - -Constructors ------------------ - -Intentionally, array and array_view have only a few constructors : - -========================================== =========================================================================================== -Constructors of array Comments -========================================== =========================================================================================== -array() - empty array of size 0 -array(size_t, ...., size_t) - from the dimensions -array(cuboid_domain const &) - a new array with the corresponding cuboid -array(const array &) - copy construction -array(const T & X) - Type T models the :ref:`HasImmutableArrayInterface` concept. - - X must have the appropriate domain (checked at compile time). - - Enabled iif has_immutable_array_interface::value == true. - - Constructs a new array of domain X.domain() and fills it with evaluation of X. -========================================== =========================================================================================== - -====================================================================== ======================================================================================= -Constructors of array_view Comments -====================================================================== ======================================================================================= -array_view(indexmap_type const & I, S_type const &) from a couple of indexmap I and storage of type S_type -array_view(const T & X) T is any type such that X.indexmap() and X.storage(). Models ISP ... -====================================================================== ======================================================================================= - -array_view are typically constructed by slicing (Cf below). - -* Examples :: - - array A(10,2); - array Af (2,2); - - //Higher dim, custom order : - array > A0 (2,3,4); - array > A1 (2,3,4); - array > A2 (2,3,4); - array A3 (2,3,4); - array A4 (2,3,4); - - -Access to data, domain, simple evaluation, ... --------------------------------------------------------- - -array, array_view, matrix, matrix_view, vector, vector_view model HasImmutableArrayInterface. - - -Assignment & Copy --------------------- - -Every classes comes in two flavors: C and C_view (with C = array, matrix, vector, etc...). -These two flavors differ in the way they handle their data in construction, copy construction, assignement. -Basically, C owns its data, while C_view if only a view. - -array, matrix, vector -^^^^^^^^^^^^^^^^^^^^^^^^ - -They own their data. In many aspects, they are similar to like std::vector. - -* The data are contiguous in memory. -* Constructors and copy constructors all create a new memory block. If needed, they - make a *true* copy of the data. -* The assignment operator may create a new Storage if size do not match. -* As a result, /pointers to the data/ and reference to the storage are invalid after assignment. -* They can be resized, again invalidating all references. - -array_view, matrix_view, vector_view -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These classes do not own their data, but only present a view of them. - -* The data may not be contiguous in memory (e.g. if the view is the result of a slice). -* Constructors only make another view of the data. -* They *never* copy data, so they are quite quick. - In particular, copy constructor makes shallow copy (i.e. return another view). -* The assignement operator just copy data into the view. Behaviour is undefined if the - size of the view is too small (define the macro ARRAY_CHECK for dynamical debugging checks). -* Pointers to data taken from the views are still valid after assignement. -* Views can be not be resized. - -.. warning:: **Memory management** - - Views carry a reference to the memory block they view, - which guarantees that memory will not be - dellocated before the destruction of the view. - Indeed, the Storage types implement incorporated a reference counting mechanism, - either using boost::shared_ptr for the C++ arrays, or using the python references - for the numpy storage. - The memory block will be dellocated when its array and all array_view - pointing to it or to a portion of it will be destroyed, and only at that moment. - -Examples:: - - array *A = new array (Matrix(2,3)); // create an array A - array_view B(*A); // making a view - delete A; // A is gone... - cout< array & operator=(const RHS & X); - - * RHS models HasImmutableArrayInterface. - * array is first resized to have a domain X.domain(), and then filled - with the evaluation of X (e.g. a copy if X is an array, computing the value if X is an expression). - - -array_view, matrix_view, vector_view -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -//.. cpp:function:: - template array_view & operator=(const RHS & X); - - * RHS models HasImmutableArrayInterface [ or less ? : RHS can be evaluated in the domain_type::value_type, no domain needed.]. - * Dimension of the view must match or behaviour is undefined. - -Iterators and interaction with STL containers and algorithms ----------------------------------------------------------------- - -STL compliant iterators, hence STL algorithms work... - -Examples:: - - array A (2,3); - - // first print the index generator - for (array::indexmap_type::domain_type::generator it = A.indexmap().domain().begin(); !it.at_end(); ++it) - cout<<" "<<*it<::iterator it = A.begin(); !it.at_end(); ++it) - { *it =it.indices().get<0>() + 10 *it.indices().get<1>() ; } - - int u=0; - for (array::iterator it = A.begin(); !it.at_end(); ++it,++u) { *it =u; } - - array A (2,3); - std::vector > VV; VV.push_back(A); - map > MAP; MAP["1"] = A; - - // Trying to put a vector in an array - std::vector V (10); - array B(V.size()), C(V.size()); - for (unsigned int i =0; i<10; ++i) V[i] = 10+i; - - std::copy(V.begin(),V.end(),B.begin()); - std::copy(B.begin(),B.end(),V.begin()); - cout<<" Number of elements <25 : "<< std::count_if(B.begin(), B.end(),te)< A (2,3); - array_view SL( A(range(0,2),0)); - array_view SL2( A(1,range(0,2))); - - -It is the standard way to produce a view. - -NB : - -* we use here the python convention: range(0,3) is 0:3, i.e. 0,1,2 NOT 0,1,2,3. -* Todo : in fact we should wrap the range to python::slice for interoperability with python. - -Serialization -------------------------------------------------- - -* Boost.serialization -* Boost.mpi - -Examples:: - - array A (2,2), B(2,2),C(2,2); - boost::mpi::reduce (world, A,C, std::plus >(),0); - - -* HDF5 (ALPS), eg. - -Examples:: - - array A (2,3),B,vc; - array Af,Bf,vf; - - alps::hdf5::oarchive ar1("data.h5"); - ar1 << alps::make_pvp("Tableau", A); - ar1 << alps::make_pvp("Tableau2", Af); - ar1 << alps::make_pvp("Tableau_view", A(range(),range(1,3))); - - alps::hdf5::iarchive ar2("data.h5"); - ar2 >> alps::make_pvp("Tableau", B); - ar2 >> alps::make_pvp("Tableau", Bf); - ar2 >> alps::make_pvp("Tableau_view", vc); - ar2 >> alps::make_pvp("TableauC",C); - - -blas/lapack interface -------------------------------------------------- - -* matrix, vector and their views are interfaced with blas/lapack, via boost::numerics::bindings. -* If needed (for a view), a temporary (and silent) copy is made to reorganize the -data before calling blas/lapack (impl: cache class). -Of course, performance is altered, but code is simple... - -Examples:: - - namespace blas = boost::numeric::bindings::blas; - namespace lapack = boost::numeric::bindings::lapack; - - triqs_arrays::vector > V(5),V2(5); - triqs_arrays::vector V3(2); - triqs_arrays::matrix M1(2,2), M2(2,2), M3(2,2); - - blas::axpy(2.0,V,V2); - blas::gemm(1.0,M1, M2, 1.0, M3); - blas::ger(1.0,V3,V3,M2); - - // invert - triqs_arrays::vector ipiv(2); - lapack::getrf(M1, ipiv); - lapack::getri(M1, ipiv); - -Transparent use of python arrays -------------------------------------------------- - -* If the storage is Tag::numpy, the memory block is allocated/viewed through the numpy interface. -* One can mix arrays with any storage in expression (they have the same concepts). -* boost python converters are enable for those arrays into numpy and their views [impl :broken for views]. - - -Expression -------------------------------------------------- - -Simple expressions are made using boost.proto. -Examples :: - - array A (2,2), B(2,2),C; - C= A + 2*B; - array D( A+ 2*B); - - // or even in C++0x : - auto e = A + 2*B; // expression, purely formal - array D(e); // really makes the computation - cout<< e < A (2,2), B(2,2),C(2,2); - C= A + 2*B; - C= std::plus >()(A,B); - C = A + Transpose(B); // Transpose(X) returns a lazy object that models HasImmutableArrayInterface. - C = A + Transpose(B + B); // X can also be an expression... - C = Transpose(B); // - array F( 0.5 * A); // Type promotion is automatic - - // non square - array R(2,3),Rt(3,2); - cout<<" R = "<< array(Transpose(R)) < {1,2,3,4}; + auto d = immutable_diagonal_matrix_view{a}; + std::cout << "domain = " << d.domain()<< std::endl; + std::cout << "d = "<< d << std::endl; + std::cout << "2*d = "<< matrix(2*d) << std::endl; + std::cout << "d*d = "<< matrix(d*d) << std::endl; + } + + +* Discussion + + * Of course, this solution is not perfect. Several algorithms could be optimised if we know that a matrix is diagonal. + E.g. multiplying a diagonal matrix by a full matrix. Currently, it creates a full matrix from the diagonal one, and + call gemm. This is clearly not optimal. + + However, this is not the point. + + This class *just works* out of the box, and takes only a few minutes to write. + One can of course then work more and specialize e.g. the operator * to optimize the multiplication, + or any other algorithm, `if and when this is necesssary`. That is an implementation detail, + that be done later, or by someone else in the team, without stopping the work. + + * One can generalize for a Mutable diagonal matrix. Left as an exercise... + + + + diff --git a/doc/reference/c++/arrays/STL.rst b/doc/reference/c++/arrays/containers/STL.rst similarity index 100% rename from doc/reference/c++/arrays/STL.rst rename to doc/reference/c++/arrays/containers/STL.rst diff --git a/doc/reference/c++/arrays/containers/call.rst b/doc/reference/c++/arrays/containers/call.rst new file mode 100644 index 00000000..e27e46c2 --- /dev/null +++ b/doc/reference/c++/arrays/containers/call.rst @@ -0,0 +1,137 @@ +.. highlight:: c + +.. _arr_reg_call: + +Operator() +================================== + +**Synopsis** :: + + value_type const & operator()(size_t ...) const (1a) + value_type & operator()(size_t ...) (1b) + + view_type operator()() const (2a) + view_type operator()( size_t | range | ellipsis ) const (2b) + + `clef expression` operator()( `at least a lazy argument` ) const (3) + +.. _arr_element_access: + +(1) Element access +--------------------------------- + +Following the concept :ref:`ImmutableCuboidArray`, the form (1) is an access to the elements. + +It must be called with exactly `rank` size_t (or it is a compile time error). + +Example +^^^^^^^^^ + +.. compileblock:: + + #include + using namespace triqs::arrays; + int main(){ + array A(2,3); + A() = 0; // assign 0 to A + A(0,0) = 5; + A(1,1) = 2 * A(0,0); + std::cout <<"A = "<< A << std::endl; + } + + +Another :: + + A(1, range(0,2) ) // 1d slice + A(1, range()) // 1d slice taking all the second dim + + A(range(0,10,2), range(0,10,2)) // a 2d slice viewing every each elements with even coordinates. + + array_view SL = A(0,range(0,3)); // naming the view. No data copied here ! + array_view SL ( A(0,range(0,3))); // same thing ! + + + +.. _arr_making_view: + +(2) Building a view +--------------------------------- + + +When the arguments contains at least one :ref:`range` or one :ref:`ellipsis`, and no placeholder (see 3)), +the return type is a (partial) view of the container. + +The special case (2a) (no argument) returns a complete view of the object +(equivalent to view_type(* this)). + +The return type of the () operator is : + + * Partial views of array or array_view return a array_view. + * Partial views of vector or vector_view return a vector_view. + * 2d partial views of matrix or matrix_view return a matrix_view. + * BUT : (1d) partial view of matrix or matrix_view return a vector_view. + + +Example +^^^^^^^^^^^^ + +.. compileblock:: + + #include + using namespace triqs::arrays; + int main(){ + array A(4,4); + for(int i=0; i<4; ++i) for(int j=0; j<4; ++j) A(i,j) = i+ 10*j; + array_view V = A(range(0,2), range(0,2)); + std::cout <<"V = "<< V << std::endl; + V = -V; + std::cout <<"A = "<< A << std::endl; + } + + + +.. highlight:: c + +.. _arr_lazy: + +(3) Interaction with clef expressions +------------------------------------------------- + + +* The containers and their views can be used with the triqs::clef library : + +* Using the clef library offers a quick and efficient way to fill an array with multiple advantages : + + * It is simpler and more readeable than a series of for loops. + * It is usually more optimal since the for loops are automatically written in the TraversalOrder of the + array. + +* NB : the expression can be (and are) inlined by the compilers... + +* **Example** : + +.. compileblock:: + + #include + using triqs::arrays::array; using triqs::clef::placeholder; + + int main(){ + placeholder<0> i_; placeholder<1> j_; + array A(2,2), B(2,2); + + A(i_,j_) << i_ + 2*j_ ; + B(i_,j_) << A(j_,i_)/2; + + std::cout << "A = "< class array_view; + template class matrix_view; + template class vector_view; + +where triqs::ull_t is the type defined by : + +.. code-block:: c + + typedef unsigned long long ull_t; + +The view classes have the same template parameters to the regular type. + + +* A `view` is defined as a view of a restricted portion of the array, matrix or vector. + +* The view type of X (= array, matrix, vector) is called X_view, with the same template parameters as the regular type. + +* A partial view models the :ref:`MutableCuboidArray`, :ref:`MutableMatrix`, :ref:`MutableVector`, like the corresponding regular type. + +* Basically X_view should be understood as a reference to the data of the viewed object, + dressed to model the "`MutableX`" concept. + +* A view class behaves like the value class when called, put in expression, ... + but differs from it by its behaviour under copy and assignment. + It has a reference semantics : like a pointer or a reference, it does not make a deep copy of the data + when copied. See :ref:`view_vs_regular` for a detailed discussion of the difference between array and array_view. + + + +====================================================================== ===================================================================================================== +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 .... +====================================================================== ===================================================================================================== + + +Memory management +------------------------ + +View classes contains a reference counting system to the memory block they view +(like a std::shared_ptr, but more sophisticated to properly interface to Python numpy). + +This guarantees that memory will not be dellocated before the destruction of the view. + +The memory block will be dellocated when its array and all array_view +pointing to it or to a portion of it will be destroyed, and only at that moment. + +Example:: + + array *p = new array (2,3); // create an array p + array_view B = *p; // making a view + delete p; // p is gone... + B(0,0) = 314; cout<) + the reference counting is again incremented, and the memory guarantee holds. + +* Explicit construction of weak views is intentionally not documented here. + It is designed to be (almost) an implementation detail. + +* The () operator returns a weak view `on a modern C++11 compiler`, + allowing therefore for better performance on such compiler, in some loops. + (in particular, `rvalue reference for *this` must be implemented). + +* It is however necessary for the advanced user to know about this implementation detail, + because in some convolved cases, the memory guarantee may not hold. + Example : + + + + diff --git a/doc/reference/c++/arrays/contents.rst b/doc/reference/c++/arrays/contents.rst index 784e2470..7fad9f58 100644 --- a/doc/reference/c++/arrays/contents.rst +++ b/doc/reference/c++/arrays/contents.rst @@ -1,4 +1,4 @@ -Array library +Multidimensional arrays ******************************************* .. highlight:: c @@ -7,30 +7,26 @@ Array library :maxdepth: 1 :numbered: - cookbook - introduction.rst - view_or_not_view - basic_classes - construct - views - move_swap + introduction + concepts + containers/regular + containers/views shape - element_acces - slicing + view_or_not_view lazy - call - debug - assignment - algebras - blas_lapack + foreach + map mapped_fnt + algebras + move_swap + blas_lapack H5 Interop_Python IO - foreach STL - map group_indices + debug + multithreading FAQ - Design/contents.rst - + implementation_notes/contents + diff --git a/doc/reference/c++/arrays/contents.rst.1 b/doc/reference/c++/arrays/contents.rst.1 deleted file mode 100644 index 591e0901..00000000 --- a/doc/reference/c++/arrays/contents.rst.1 +++ /dev/null @@ -1,20 +0,0 @@ -Array library -**************** - -.. warning:: - This library is still beta. Beware of bugs ! - - -The documentation of the array library is divided into three parts. - -.. highlight:: c - - -.. toctree:: - :maxdepth: 1 - - introduction.rst - CookBook/contents.rst - UserManual/contents.rst - Design/contents.rst - diff --git a/doc/reference/c++/arrays/cookbook/basic.rst b/doc/reference/c++/arrays/cookbook/basic.rst index 002b2d00..a2136aab 100644 --- a/doc/reference/c++/arrays/cookbook/basic.rst +++ b/doc/reference/c++/arrays/cookbook/basic.rst @@ -141,8 +141,7 @@ Linear algebra .. compileblock:: #include - #include - #include + #include using triqs::arrays::array; using triqs::arrays::matrix; using triqs::clef::placeholder; int main(){ diff --git a/doc/reference/c++/arrays/element_acces.rst b/doc/reference/c++/arrays/element_acces.rst deleted file mode 100644 index b8e49394..00000000 --- a/doc/reference/c++/arrays/element_acces.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. highlight:: c - -.. _ElementAccess: - -Element access -================================== - -The elements of the arrays can be naturally accessed using the ( ) operator. - - If A is an array and i,j,k, its indices - - A(i,j,k) is the element (i,j,k) of the array. - -.. compileblock:: - - #include - namespace tqa=triqs::arrays; - int main(){ - tqa::array A(2,3); - A() = 0; // assign 0 to a complete view of A. - A(0,0) = 5; - A(1,1) = 2* A(0,0); - std::cout <<"A = "<< A << std::endl; - } - - - diff --git a/doc/reference/c++/arrays/expr_arith.rst b/doc/reference/c++/arrays/expr_arith.rst deleted file mode 100644 index 87e824e5..00000000 --- a/doc/reference/c++/arrays/expr_arith.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. highlight:: c - -.. _arith_expression: - -Arithmetic Expressions -------------------------------------------------- - -* **Definition** : - - By `expression`, we mean here an object, typically representing a mathematical expression, - which models the :ref:`HasImmutableArrayInterface` concept. - -* **Use** : - - Expression can be used : - - as RHS (Right Hand Side) of various operators (=, +=, -=, ...) - - at any place where an `expression` is expected. - -* **How to make expression ?** - - Expressions can be build easily in various ways : - - - Using arithmetic operators, e.g. A + 2*B - Examples :: - - array A (2,2), B(2,2),C; - C= A + 2*B; - array D( A+ 2*B); - array F( 0.5 * A); // Type promotion is automatic - - // or even in C++0x : - auto e = A + 2*B; // expression, purely formal - array D(e); // really makes the computation - cout<< e < M1(2,2), M2(2,2), M3; - M3 = matmul(M1,M2); - - will do the following : - - matmul returns a lazy object modelling the :ref:`Expression` concept. - - a result this is compiled as some `matmul_with_lapack(M1,M2,M3)` : **there is NO intermediate copy**. - - - mat_vec_mul - - - Building custom expressions. The transpose example... - - Describe the concept, what to implement, etc.... - - - Transpose:: - - array A (2,2), B(2,2),C(2,2); - C= A + 2*B; - C = A + Transpose(B); // Transpose(X) returns a lazy object that models HasImmutableArrayInterface. - C = A + Transpose(B + B); // X can also be an expression... - C = Transpose(B); // - - // non square - array R(2,3),Rt(3,2); - cout<<" R = "<< array(Transpose(R)) < iterator | A generator of all the mesh points. | +--------------------------------------------------------------+-------------------------------------------------------------------------------+ -| iterator begin()/end() const | Standard access to iterator on the mesh | -+--------------------------------------------------------------+-------------------------------------------------------------------------------+ -| friend bool operator == (mesh_t const& M1, mesh_t const &M2) | Comparison between meshes | +| const_iterator begin()/end() const | Standard access to iterator on the mesh | +| const_iterator cbegin()/cend() const | Standard access to iterator on the mesh | +--------------------------------------------------------------+-------------------------------------------------------------------------------+ +.. _Concept_MeshPoint: -* **Examples** : Some domains and the corresponding possible meshes. - -+-----------------------------------------------------+--------------------------------------------------------+ -| Domain Type | What does the corresponding mesh type contain ? | -+=====================================================+========================================================+ -| Matsubara frequencies | Nmax, the max number of Matsubara Freq. | -+-----------------------------------------------------+--------------------------------------------------------+ -| Matsubara time | The time slicing is on a mesh, or the Legendre mesh is | -| | we store the function with Legendre representation. | -+-----------------------------------------------------+--------------------------------------------------------+ -| Real frequencies | Parameters of the mesh in frequency | -+-----------------------------------------------------+--------------------------------------------------------+ -| Real time | | -+-----------------------------------------------------+--------------------------------------------------------+ -| Brillouin zone | parameters of the mesh over the BZ, symmetry ? | -+-----------------------------------------------------+--------------------------------------------------------+ - - -MeshPoint concept +MeshPoint ------------------------------------------------- * **Purpose** : Abstraction of a point on a mesh. A little more than a ref to the mesh and a index. @@ -168,148 +164,33 @@ MeshPoint concept +------------------------------------------------+-----------------------------------------------------------------------------+ | void reset() | Reset the mesh point to the first point | +------------------------------------------------+-----------------------------------------------------------------------------+ -| cast_t | type of the corresponding domain point | -| operator cast_t() const | cast to the corresponding domain point | -+------------------------------------------------+-----------------------------------------------------------------------------+ -| Implements the basic operations on the domain | Only for non composite mesh | -| by using the cast operation | | +| cast_t | == mesh_t::domain_t::point_t | +| operator cast_t() const | *implicit* cast to the corresponding domain point | +------------------------------------------------+-----------------------------------------------------------------------------+ -The MeshPoint mechanism ---------------------------- +For one dimensional mesh, we also require that the MeshPoint implement the basic arithmetic operations +using the cast. -A MeshPoint is just a storage of a reference to the mesh and the index of the point in a custom structure. -The interest of having such a structure is that : +* **Discussion** : -* The gf function has a operator()(mesh_t::mesh_point_t) (see below) which is a direct access to the data on the grid. - Hence if MP is a such a MeshPoint, g(MP) is equivalent to something like g.data_on_grid_at_index( MP.index) +A MeshPoint is just an index of a point on the mesh, and containers like gf can easily be overloaded for this type +to have a direct access to the grid (Cf [] operator of gf). -* MP however can be casted to a point in the domain and therefore it *is* a domain_t::point_t as well. +However, since the MeshPoint can be implicitely casted into the domain point, simple +expression like :: - As a result, g(MP) = 1/(MP + 2) makes senses iif it makes senses in the domain. + g[p] = 1/ (p +2) -* Moreover, because of the iterator on the mesh, one can write :: +make sense and fill the corresponding point wiht the evaluation of 1/ (p+2) in the domain. + +As a result, because iterating on a mesh result in a series of object modelling MeshPoint, +one can write naturally :: // example of g, a Green function in Matsubara frequencies w for (auto w : g.mesh()) - g(w) = 1/(w + 2) + g[w] = 1/(w + 2) // This runs overs the mesh, and fills the function with 1/(w+2) // In this expression, w is casted to the domain_t::point_t, here a complex // which allows to evaluate the function -FunctionOnMesh concept ------------------------------ - -* **Purpose** : A function from a domain to a target space, represented in a mesh. - This function can only be evaluated on the mesh points. - -* **Refines** : BoostSerializable, H5-serializable. - -* **Definition** : - -+--------------------------------------------------+------------------------------------------------------------------------+ -| Elements | Comment | -+==================================================+========================================================================+ -| mesh_t | Type of the mesh representing the domain. | -+--------------------------------------------------+------------------------------------------------------------------------+ -| mesh_t const & mesh() const | Returns the mesh. | -+--------------------------------------------------+------------------------------------------------------------------------+ -| auto operator ( grid_pt const &) const | Calling on a grid_pt gives direct access to the value on a grid point. | -| auto & operator ( grid_pt const &) | Const and non const version. | -+--------------------------------------------------+------------------------------------------------------------------------+ - -* **NB** : the result type of the () operator is deduced. Not needed in the concept. - - -descriptors -====================================== - -A descriptor is a structure that contains everything specific to the Green function -(number of variables, domain of definition, interpolation techniques, etc...). - - -Descriptor concept ---------------------------- - -* **Purpose** : - -* **Refines** : - -* **NB** : Pure static, does NOT contains any data. - -* **Definition** : - -+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ -| 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). - - -The gf/gf_view class -==================== - -The gf/gf_view classes are generic Green function, templated on Descriptor. - -They handle : - -* view/non view aspect, copy, etc... -* hdf5 interface -* clef interface -* the MeshPoint mechanism as explained above. -* perfect forwarding of all other const call of operator() to Descriptor. - -Constructors are limited to a minimal number : - -* empty one for gf (value semantics). -* copy construction, from gf and gf_view of the same descriptor. -* construction from the data of the GF. - -The other custom construction are delegated to make_gf functions:: - - gf make_gf (Descriptor, my_favorite arguments). - -We use here the simplest dispatch using the fact that Descriptor is an empty struct, -so we can dispath the make_gf. Example of use :: - - auto G = make_gf (matsubara_freq(), beta, Fermion, make_shape(2,2)); - - - -Doxygen documentation -====================== - -The :doxy:`full C++ documentation` is available here. - diff --git a/doc/reference/c++/gf/contents.rst b/doc/reference/c++/gf/contents.rst index 3b4d9aae..b278da72 100644 --- a/doc/reference/c++/gf/contents.rst +++ b/doc/reference/c++/gf/contents.rst @@ -1,40 +1,20 @@ .. _greenfunctions: -The Green function class -======================== +Green functions +================= -The TRIQS library has a class called ``gf`` which allows you to use easily a whole set of Green functions. - -You can use as variable(s) - -* real time(s), - -* real frequency(ies), - -* Matsubara time(s), - -* Matsubara frequency(ies), - -* or other variables that you can define. - -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 +The TRIQS library provides a generic container `gf` and its view `gf_view`, to store and manipulate +various Green functions. .. toctree:: :maxdepth: 2 + intro + gf_and_view concepts meshes - the_four_basic_GFs + tail fourier - cookbook/contents + gf_misc + implementation_notes diff --git a/doc/reference/c++/gf/cookbook/imaginary.rst b/doc/reference/c++/gf/cookbook/imaginary.rst index 5e16b453..b728899b 100644 --- a/doc/reference/c++/gf/cookbook/imaginary.rst +++ b/doc/reference/c++/gf/cookbook/imaginary.rst @@ -1,61 +1,2 @@ - -Create a Matsubara frequency Green function -------------------------------------------- - -The particularity here is that the statistics influences the position of the Matsubara frequencies. - -.. compileblock:: - - #include - #include - - using triqs::gf::make_gf; - using triqs::gf::imfreq; - - int main() { - double beta=1; //inverse temperature - triqs::gf::statistic_enum stat=triqs::gf::Fermion; - //we will have 5 points including iw=0 and iw=beta - size_t n_freq=5; - auto shape = triqs::arrays::make_shape(1,1); - auto GF=make_gf(beta, stat, shape, n_freq); - }; - - -An alternative declaration with an explicit construction of the underlying mesh: - -.. compileblock:: - - - #include - using namespace triqs::gf; - int main(){ - double beta=10; - int Nfreq =100; - auto fermionic_imfreq_mesh = make_gf_mesh(beta,triqs::gf::Fermion,Nfreq); - auto GF = make_gf(fermionic_imfreq_mesh, triqs::arrays::make_shape(1,1), local::tail(1,1)); - } - - Learn more in the full referencen, see :ref:`greenfunctions` -Create a Matsubara time Green function --------------------------------------- -.. compileblock:: - - #include - #include - using triqs::gf::make_gf; - using triqs::gf::imtime; - - int main() { - double beta=1; //inverse temperature - triqs::gf::statistic_enum stat=triqs::gf::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/cookbook/real.rst b/doc/reference/c++/gf/cookbook/real.rst index a2763da2..953c3aa5 100644 --- a/doc/reference/c++/gf/cookbook/real.rst +++ b/doc/reference/c++/gf/cookbook/real.rst @@ -1,34 +1,13 @@ -Create a real time Green function ---------------------------------- - -.. compileblock:: - - #include - #include - - using triqs::gf::make_gf; - using triqs::gf::retime; - - 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::gf::gf - auto GF=make_gf(tmin, tmax, n_times, shape); - }; Create a real frequency Green function -------------------------------------- .. compileblock:: #include - #include + #include - using triqs::gf::make_gf; - using triqs::gf::refreq; + using triqs::gfs::make_gf; + using triqs::gfs::refreq; int main() { double wmin=0; diff --git a/doc/reference/c++/gf/gf_and_view.rst b/doc/reference/c++/gf/gf_and_view.rst new file mode 100644 index 00000000..dcccccb4 --- /dev/null +++ b/doc/reference/c++/gf/gf_and_view.rst @@ -0,0 +1,88 @@ +.. highlight:: c + +.. _gf_and_view: + +gf and gf_view +================= + +gf is the Green function container, with its view gf_view, defined as :: + + template class gf; // the regular type + template class gf_view; // the view type + +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, ....). + + +Template parameters +---------------------------- + +* Variable determines the domain of the Green function. It can be : + + ============================ ==================================================================== + Variable tag Meaning + ============================ ==================================================================== + :ref:`imfreq` Imaginary Matsubara frequency + imtime Imaginary Matsubara time + refreq Real frequency + retime Real time + legendre Legendre polynomial representation + block_index Block Green function + cartesian_product Cartesian product of gf ... functions. + ============================ ==================================================================== + +* Target determines the value of the Green function + + ============================ ==================================================================== + Target tag Meaning + ============================ ==================================================================== + matrix_valued [default] The function is matrix valued. + scalar_valued The function is scalar valued (double, complex...). + ============================ ==================================================================== + +* Opt is currently not used [default to void]. + +.. _gf_special: + +Specializations +------------------- + + +.. toctree:: + :maxdepth: 1 + + gf_imfreq + gf_refreq + 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. + + +Member types +----------------- + + + +Member functions +--------------------- + + +Non-member functions +------------------------ + + diff --git a/doc/reference/c++/gf/gf_block.rst b/doc/reference/c++/gf/gf_block.rst new file mode 100644 index 00000000..fe9b56db --- /dev/null +++ b/doc/reference/c++/gf/gf_block.rst @@ -0,0 +1,36 @@ +.. highlight:: c + +.. _gf_block: + +gf or block_gf +=================================================== + +This is a specialisation of :ref:`gf_and_view` for block functions. + + +Domain & mesh +---------------- + + +Singularity +------------- + +Factories +------------- + + +Interpolation method +--------------------- + +Data storage +--------------- + + +HDF5 storage convention +--------------------------- + + + +Examples +--------- + diff --git a/doc/reference/c++/gf/gf_imfreq.rst b/doc/reference/c++/gf/gf_imfreq.rst new file mode 100644 index 00000000..d47d5ac4 --- /dev/null +++ b/doc/reference/c++/gf/gf_imfreq.rst @@ -0,0 +1,80 @@ +.. highlight:: c + +.. _gf_imfreq: + +gf & 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(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 +--------------------- + +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 : `ImFreq` + + +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; + int main(){ + double beta=10; + int Nfreq =100; + + auto GF = make_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)); + } + + + diff --git a/doc/reference/c++/gf/gf_imtime.rst b/doc/reference/c++/gf/gf_imtime.rst new file mode 100644 index 00000000..17b51a01 --- /dev/null +++ b/doc/reference/c++/gf/gf_imtime.rst @@ -0,0 +1,57 @@ +.. highlight:: c + +.. _gf_imtime: + +gf +=================================================== + +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 +--------------------- + +Data storage +--------------- + + +HDF5 storage convention +--------------------------- + + + +Examples +--------- + +.. compileblock:: + + #include + using namespace triqs::gfs; + + 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_misc.rst b/doc/reference/c++/gf/gf_misc.rst new file mode 100644 index 00000000..9d93471e --- /dev/null +++ b/doc/reference/c++/gf/gf_misc.rst @@ -0,0 +1,16 @@ +.. highlight:: c + +.. _gf_misc: + +Misc +========================================================== + +.. _def_statistic_enum: + +Statistic +---------------- + +The enum statistic_enum encode the statistic :: + + enum statistic_enum {Boson,Fermion}; + diff --git a/doc/reference/c++/gf/gf_prod.rst b/doc/reference/c++/gf/gf_prod.rst new file mode 100644 index 00000000..f3e02030 --- /dev/null +++ b/doc/reference/c++/gf/gf_prod.rst @@ -0,0 +1,36 @@ +.. 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_refreq.rst b/doc/reference/c++/gf/gf_refreq.rst new file mode 100644 index 00000000..0fc9e71d --- /dev/null +++ b/doc/reference/c++/gf/gf_refreq.rst @@ -0,0 +1,60 @@ +.. highlight:: c + +.. _gf_refreq: + +gf +=================================================== + +This is a specialisation of :ref:`gf_and_view` for imaginary Matsubara frequencies. + +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 +--------------------- + +Data storage +--------------- + + +HDF5 storage convention +--------------------------- + + + +Examples +--------- + + +.. compileblock:: + + #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); + }; + diff --git a/doc/reference/c++/gf/gf_retime.rst b/doc/reference/c++/gf/gf_retime.rst new file mode 100644 index 00000000..8fcedfcd --- /dev/null +++ b/doc/reference/c++/gf/gf_retime.rst @@ -0,0 +1,57 @@ +.. highlight:: c + +.. _gf_retime: + +gf +=================================================== + +This is a specialisation of :ref:`gf_and_view` for imaginary Matsubara frequencies. + +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 +--------------------- + +Data storage +--------------- + + +HDF5 storage convention +--------------------------- + + + +Examples +--------- + +.. compileblock:: + + #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); + }; + + diff --git a/doc/reference/c++/gf/implementation_notes.rst b/doc/reference/c++/gf/implementation_notes.rst new file mode 100644 index 00000000..b686d496 --- /dev/null +++ b/doc/reference/c++/gf/implementation_notes.rst @@ -0,0 +1,75 @@ + + +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 new file mode 100644 index 00000000..147c8900 --- /dev/null +++ b/doc/reference/c++/gf/intro.rst @@ -0,0 +1,43 @@ +.. highlight:: c + +.. _intro: + +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 : + +* real time(s), +* real frequency(ies), +* Matsubara time(s), +* Matsubara frequency(ies), +* Legendre representation. +* Block of other green functions. +* Cartesian product of green functions. + +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. + + + diff --git a/doc/reference/c++/gf/meshes.rst b/doc/reference/c++/gf/meshes.rst index 05256a9d..418150ec 100644 --- a/doc/reference/c++/gf/meshes.rst +++ b/doc/reference/c++/gf/meshes.rst @@ -30,8 +30,8 @@ How to access to a mesh point with its index .. compileblock:: - #include - using namespace triqs::gf; + #include + using namespace triqs::gfs; int main() { @@ -59,8 +59,8 @@ In this case, we look for the closest mesh point, but can need the distance of t .. compileblock:: - #include - using namespace triqs::gf; + #include + using namespace triqs::gfs; int main() { double wmin = 0.0; @@ -132,8 +132,8 @@ How to access to the closest mesh point .. compileblock:: - #include - using namespace triqs::gf; + #include + using namespace triqs::gfs; int main() { double tmax = 1.0; @@ -152,8 +152,8 @@ How to access to a mesh point with its index .. compileblock:: - #include - using namespace triqs::gf; + #include + using namespace triqs::gfs; int main() { double tmax = 1.0; diff --git a/doc/reference/c++/gf/plan.rst b/doc/reference/c++/gf/plan.rst new file mode 100644 index 00000000..17237dc9 --- /dev/null +++ b/doc/reference/c++/gf/plan.rst @@ -0,0 +1,46 @@ + +General ideas : + +Various gf : Variable, Target, Opt +Notion of domain, and meshes. Precise concept in appendix. + +- domains +- meshes +- scalar_valued and matrix_valued target. + +- 1 page per gf ? + - imfreq, etc... + in each page : + - include + - synopsis + - example + - are they wrapped to python ? -> a cython example ? + - singularity : documentation of local tail + + - block : iterators. a bit more specific. + + - product gf. + +- Common operations for all gf. + +- creating using a factory. Very few constructors. +- regular vs view. rebind, assignment delegation +- evaluation +- grid access. The mesh point mechanism +- arithmetic +- lazy +- hdf5 +- mpi +- slice. +- partial_evaluation and curry. + examples. + +- Operations on the gf + + * Fourier transformation. + notion of lazy +- implementation guide. + The various traits and their concept. + + + diff --git a/doc/reference/c++/gf/tail.rst b/doc/reference/c++/gf/tail.rst new file mode 100644 index 00000000..2888402f --- /dev/null +++ b/doc/reference/c++/gf/tail.rst @@ -0,0 +1,7 @@ +.. highlight:: c + +.. _gf_tail: + +High frequency tail +=========================== + diff --git a/doc/reference/c++/gf/the_four_basic_GFs.rst b/doc/reference/c++/gf/the_four_basic_GFs.rst deleted file mode 100644 index 6e4b1161..00000000 --- a/doc/reference/c++/gf/the_four_basic_GFs.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: c - - -The four reference Green functions -################################## - -Real time ----------- - -``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)`` - - -Real frequency ---------------- - -``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)`` - - -Matsubara time ---------------- - -``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)`` - - -Matsubara frequency --------------------- - -``make_gf(MeshType && m, tqa::mini_vector shape, local::tail_view const & t)`` - -``make_gf(double beta, statistic_enum S, tqa::mini_vector shape)`` - -``make_gf(double beta, statistic_enum S, tqa::mini_vector shape, size_t Nmax)`` - -``make_gf(double beta, statistic_enum S, tqa::mini_vector shape, size_t Nmax, local::tail_view const & t)`` - - diff --git a/doc/reference/c++/utilities/contents.rst b/doc/reference/c++/utilities/contents.rst new file mode 100644 index 00000000..37cc0a62 --- /dev/null +++ b/doc/reference/c++/utilities/contents.rst @@ -0,0 +1,14 @@ +Utilities +******************************************* + +.. highlight:: c + +.. toctree:: + :maxdepth: 1 + :numbered: + + factory + tupletools + mini_vector + python_include_mess + diff --git a/doc/reference/c++/utilities/python_include_mess.rst b/doc/reference/c++/utilities/python_include_mess.rst new file mode 100644 index 00000000..42617c45 --- /dev/null +++ b/doc/reference/c++/utilities/python_include_mess.rst @@ -0,0 +1,28 @@ +Python include warnings +=============================== + +Very often compile warnings of Python can be seen, something like :: + + /usr/local/install/python-2.7.5/include/python2.7/pyconfig.h:1173:0: warning: "_POSIX_C_SOURCE" redefined [enabled by default] + #define _POSIX_C_SOURCE 200112L + ^ + In file included from /usr/local/install/gcc-4.8.1/include/c++/4.8.1/x86_64-unknown-linux-gnu/bits/os_defines.h:39:0, + ...... + /usr/include/features.h:162:0: note: this is the location of the previous definition + # define _POSIX_C_SOURCE 200809L + ... + #define _XOPEN_SOURCE 600 + + +It is due to the fact that Python.h must be included +before some other headers (cf python documentation). + +Solutions : + +#. include first some triqs library, like arrays.hpp, gfs.hpp, etc... + +#. include first + that conditionally includes python if python is to be supported. + (used by all triqs libs, hence the first point). + + diff --git a/doc/reference/c++/utilities/tupletools.rst b/doc/reference/c++/utilities/tupletools.rst new file mode 100644 index 00000000..9a6a45a7 --- /dev/null +++ b/doc/reference/c++/utilities/tupletools.rst @@ -0,0 +1,77 @@ +.. highlight:: c + +.. _util_tuple: + +Tuple compile time tools +============================= + +Very useful for lib developers, they fill a missing gap in the std library. +They implement various standard functional operations, at compile time, +on tuple... + +.. note:: + + Simple measures have shown that these routines are **as fast as native code** (tested on gcc, clang, icc), + due to inlining. They can therefore be used in critical parts of codes. + +apply +----------------------------------------------- + +*Purpose* : `apply a function on a tuple of arguments` + + Given a function object `f`, and its arguments stored in a tuple `t`, and we want to apply `f` on `t`. + + Python equivalent : `f(*t)` + +*Synopsis* :: + + template auto apply (Function && f, Tuple const & t); + +*Solution* : + +.. compileblock:: + + #include + #include + int main() { + + auto fun= [](int i, double x, double y, int k) {return 6*k + i - 1.3*x + 2*y;}; + auto t = std::make_tuple(1,2.3,4.3,8); + + auto res = triqs::tuple::apply(fun,t); + std::cout << " f(t) =" << res << std::endl ; + } + +for_each +------------------------------------------------------------------------- + +*Purpose* : `apply a function for each element of a tuple (in order)` + + + Given a function object `f`, we want to apply it to all elements of a tuple `t`. + + Python equivalent : `for x in t : f(x)` + +*Synopsis* :: + + template void for_each(Tuple const & t, Function && f); + +*Solution* : + +.. compileblock:: + + #include + #include + + struct print_t { template void operator()(T x) { std::cout << x << " "; } }; + + int main() { + auto t = std::make_tuple(1,2.3,4.3,8, "hello"); + triqs::tuple::for_each(t, print_t()); + + // C++14 solution : with generic lambda, there is no need to define a print_t ... + // triqs::tuple::for_each(t, [](auto x) { std::cout<( 2* d) << std::endl; std::cout << matrix( d * d) << std::endl; + + int sum =0; + foreach (d, [&sum, &d](int i, int j) { sum += d(i,j);}); + std::cout << "sum = "<< sum << std::endl; + return 0; }