LCPQ/dft_tools
3
0
Fork 0
mirror of https://github.com/triqs/dft_tools synced 2024-12-26 06:14:14 +01:00
Code Issues Releases Wiki Activity

work on doc

Browse Source
This commit is contained in:
Olivier Parcollet 2013-08-22 16:55:51 +02:00
parent 165b44a081
commit 0f524b26fc
88 changed files with 1970 additions and 2035 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/contents.rst
View File

@ -4,7 +4,7 @@ Table of contents
================= =================
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 2
overview overview
installation/install installation/install

11
doc/reference/c++/arrays/Design/contents.rst
View File

@ -1,11 +0,0 @@
Concepts, implementation, design ...
***************************************
.. highlight:: c
.. toctree::
:maxdepth: 1
:numbered:
concepts

18
doc/reference/c++/arrays/Interop_Python.rst
View File

@ -76,3 +76,21 @@ Put here the array_cython example
_testarray.f(a) _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).

2
doc/reference/c++/arrays/Iterators.rst
View File

@ -1,2 +0,0 @@
.. highlight:: c

4
doc/reference/c++/arrays/algebras.rst
View File

@ -6,7 +6,7 @@ Operations : array and matrix/vector algebras
Operations 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. This algebraic expressions can therefore be used as RHS of assignment (SEE) or in array/matrix contructors.
For example ; 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 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. 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. 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. : Hence they can used *anywhere* an object modeling this concept is accepted, e.g. :

360
doc/reference/c++/arrays/all.rst
View File

@ -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<ValueType, // The type of the element of the array
Rank, // int : the rank of the array
IndexOrderTag=Tag::C, // The ordering in memory : can be Tag::C, Tag::Fortran or a permutation
StorageTag=Tag::shared_block // The storage : Tag::shared_block or Tag::numpy
>
============================ ========================== =======================================
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<rank> 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<T>::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<int,2> A(10,2);
array<int,2,Tag::Fortran> Af (2,2);
//Higher dim, custom order :
array<long, 3, Permutations::permutation<2,1,0> > A0 (2,3,4);
array<long, 3, Permutations::permutation<0,1,2> > A1 (2,3,4);
array<long, 3, Permutations::permutation<1,0,2> > A2 (2,3,4);
array<long, 3 > A3 (2,3,4);
array<long, 3, Tag::Fortran > 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<int,Matrix> *A = new array<int,Matrix> (Matrix(2,3)); // create an array A
array_view<int, Matrix> B(*A); // making a view
delete A; // A is gone...
cout<<B<<endl; // ok, but B (and the data) is still alive
Operator =
------------
array, matrix, vector
^^^^^^^^^^^^^^^^^^^^^^^^
//.. cpp:member::
template<typename RHS> 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<typename RHS> 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<long,2> A (2,3);
// first print the index generator
for (array<long,2>::indexmap_type::domain_type::generator it = A.indexmap().domain().begin(); !it.at_end(); ++it)
cout<<" "<<*it<<endl;
//A(i,j) = i + 10*j
for (array<long,2>::iterator it = A.begin(); !it.at_end(); ++it)
{ *it =it.indices().get<0>() + 10 *it.indices().get<1>() ; }
int u=0;
for (array<long,2>::iterator it = A.begin(); !it.at_end(); ++it,++u) { *it =u; }
array<long,2> A (2,3);
std::vector<array<long,2> > VV; VV.push_back(A);
map<string, array<long,2> > MAP; MAP["1"] = A;
// Trying to put a vector in an array
std::vector<int> V (10);
array<int,1 > 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)<<endl;
cout<<" max(B) "<< *std::max_element(B.begin(),B.end())<<endl;
std::replace_if (B.begin(), B.end(), te, 0);
std::swap(B,C);
Slicing (or partial view)
-------------------------------------------------
Slicing or partial view consists in presenting a view of a sub-part of the array, e.g.
Examples::
array<long,2> A (2,3);
array_view<long,1> SL( A(range(0,2),0));
array_view<long,1> 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<long,2> A (2,2), B(2,2),C(2,2);
boost::mpi::reduce (world, A,C, std::plus<array<long,2> >(),0);
* HDF5 (ALPS), eg.
Examples::
array<long,2> A (2,3),B,vc;
array<long,2,Tag::Fortran> 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<std::complex<double> > V(5),V2(5);
triqs_arrays::vector <double> V3(2);
triqs_arrays::matrix<double,'F' > 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 <int> 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<long,2> A (2,2), B(2,2),C;
C= A + 2*B;
array<long,2> D( A+ 2*B);
// or even in C++0x :
auto e = A + 2*B; // expression, purely formal
array<long,2> D(e); // really makes the computation
cout<< e <<endl ; // prints the expression
cout<< e(1,2) <<endl ; // evaluates just at a point
cout<< e.domain() <<endl ; // just computes the domain
array<long,2> A (2,2), B(2,2),C(2,2);
C= A + 2*B;
C= std::plus<array<long,2> >()(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<double,2> F( 0.5 * A); // Type promotion is automatic
// non square
array<long,2> R(2,3),Rt(3,2);
cout<<" R = "<< array<long,2>(Transpose(R)) <<endl;
// mapping any function
C = map_expr(&sqr,A);
cout<<" C = "<< map_expr(&sqr,A,"SQR")<<" = "<<C<<endl;
// matmul as expression Oi are 'C' or 'F'
matrix<double,O1> M1(2,2); matrix<double,O2> M2(2,2); matrix<double,O3> M3;
// The central instruction : note that matmul returns a lazy object
// that has ImmutableArray interface, and defines a specialized version assignment
// As a result this is equivalent to some matmul_with_lapack(M1,M2,M3) : there is NO intermediate copy.
M3 = matmul(M1,M2);
See expression.hpp.
At the moment, only +,-, * and / by scalar are implemented.
An expression models HasImmutableArrayInterface, i.e. :
* It has a domain (computed from the expression)
* It can be evaluated.
It is then easy to mix them with other objects,
that model the same concept. See e.g. expr2.cpp (map_expr) for examples.
* *Multiplication* :
not decided, since it is not the same for array or matrices.
Two choices :
* Do not add \* for array, matrices (use matmul e.g.) and allow mixing array, matrix
e.g. add an array<int,2> and a matrix <int>
* Add the \*, but then do different expression for array and matrix/vector,
then one can not mix them.
In that case, it is however trivial to say e.g. M + matrix_view<int>(A) if A is an array.

139
doc/reference/c++/arrays/arrays.rst
View File

@ -1,139 +0,0 @@
.. highlight:: c
array and array_view : declaration & construction
====================================================================================================================
array and array_view :
* are the standard d-dimensional cuboid array and the corresponding view.
* allow **custom memory ordering** at compile time.
* model the :ref:`HasImmutableArrayInterface` concept.
Template parameters
----------------------------
* The classes have three template parameters.
.. code-block:: c
template <typename ValueType, int Rank, typename Opt= Option::Default > class array_view;
template <typename ValueType, int Rank, typename Opt= Option::Default > class array;
============================ ================================== ========================== ====================================================================
Template parameter Accepted type Access in the class Meaning
============================ ================================== ========================== ====================================================================
ValueType normally a scalar, but any default value_type The type of the element of the array
constructible type (?).
Rank int rank The rank of the array
Opt Option::options< ...> opt_type Compile time options, see below.
============================ ================================== ========================== ====================================================================
Options template parameters are described :ref:`here <option_template>`.
.. _array_constructors:
Constructors of array
---------------------------
========================================== ===========================================================================================
Constructors of array Comments
========================================== ===========================================================================================
array() - Empty array of size 0
array(const array &) - Copy constructor
array(array &&) - Move constructor
array(size_t, ...., size_t) - From the dimensions [number of parameters checked at compile time].
Does **NOT** initialize the array elements to 0 ! (see compile time option)
Use my_array() =0 to do it explicitely.
array(cuboid_domain<rank> const &) - New array with the corresponding domain
array(PyObject * X) - Construct a new array from the Python object X.
NB : X is a borrowed reference, array does affect its counting reference.
- it takes a **copy** of the data of X (or of numpy(X)) into C++.
- X is first transformed into a numpy by the python numpy lib itself
(as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type
(e.g. you construct an array<double,2> from a numpy of int....), and
copied into the array.
array(const T & X) - Type T models the :ref:`HasImmutableArrayInterface` concept.
- X must have the appropriate domain (checked at compile time).
- Constructs a new array of domain X.domain() and fills it with evaluation of X.
========================================== ===========================================================================================
.. warning::
The constructor from the dimensions does **NOT** initialize the matrix to 0
(because it may not be optimal).
If needed, do it explicitely by (a if the array) `a()=0`;
- LAYOUT
Examples
------------
.. compileblock::
#include <triqs/arrays.hpp>
using triqs::arrays::array; using triqs::arrays::matrix;
using triqs::arrays::vector; using triqs::arrays::permutation;
int main(){
// A 3d array of long, C ordering, no option
array<long, 3> A3(1,2,3);
// A 2d array of double, C ordering, with explicit Bound Checking
array<double, 2> B(1,2);
// a matrix of long
matrix<long> M(2,2);
// a vector of double
vector<double> V(10);
// arrays with custom TraversalOrder
// C-style
array<long, 3, 0, permutation(2,1,0)> A0(2,3,4);
array<long, 3, 0> A0b; // same type but empty
// Fortran-style
array<long, 3, TRAVERSAL_ORDER_FORTRAN> A4 (2,3,4);
array<long, 3, 0, permutation(0,1,2)> A1b(); //same type but empty
// custom : (i,j,k) : index j is fastest, then k, then i
array<long, 3, 0, permutation(1,0,2)> A2(2,3,4);
}
Constructors of array_views
----------------------------------------------
Automatic construction
^^^^^^^^^^^^^^^^^^^^^^^^^^^
array_view are normally automatically constructed by making (partial) views, ref:`Slicing`, e.g. ::
array<int,2> A(2,2);
A(range(),2) ; // --> this makes a view...
A() ; // --> this makes a view over the full array
Explicit construction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To explicitly make a view of an array, use make_view or the ()::
array<int,2> A(2,2);
make_view(A); //-> a view...
make_view(A) = 13 ; // to assign e.g.
A() = 13; // same thing...
====================================================================== =====================================================================================================
Constructors of array_view Comments
====================================================================== =====================================================================================================
array_view(const array_view &) - Copy construction (shallow copy)
array_view(const T & X) - `[Advanced]` T is any type such that X.indexmap() and X.storage() can be used to construct a view.
array_view(indexmap_type const & I, S_type const &) - `[Advanced]` From a couple of indexmap I and storage of type S_type.
====================================================================== =====================================================================================================

37
doc/reference/c++/arrays/assignment.rst
View File

@ -13,7 +13,7 @@ We will illustrate it on the `array` class, it is the same for `matrix` and `vec
* **What can be RHS ?** * **What can be RHS ?**
RHS can be ... anything that models the HasImmutableArrayInterface concept ! RHS can be ... anything that models the :ref:`ImmutableCuboidArray` concept !
e.g. : array, array_view, matrix, matrix_view, e.g. : array, array_view, matrix, matrix_view,
but also formal expression (See , e.g. A+B), or any custom object of your choice. but also formal expression (See , e.g. A+B), or any custom object of your choice.
@ -23,7 +23,7 @@ We will illustrate it on the `array` class, it is the same for `matrix` and `vec
================= ======================================================================= ====================================================================================== ================= ======================================================================= ======================================================================================
Topic value class : array, matrix, vector view: array_view, matrix_view, vector_view Topic value class : array, matrix, vector view: array_view, matrix_view, vector_view
================= ======================================================================= ====================================================================================== ================= ======================================================================= ======================================================================================
RHS ... - RHS models the concept `HasImmutableArrayInterface`. - RHS models HasImmutableArrayInterface RHS ... - RHS models the concept :ref:`ImmutableCuboidArray`. - RHS models :ref:`ImmutableCuboidArray`
[or less ? : RHS can be evaluated in the domain_type::value_type, no domain needed.]. [or less ? : RHS can be evaluated in the domain_type::value_type, no domain needed.].
Effect - array is resized to have a domain X.domain() - View's domain must match X's domain or behaviour is undefined. Effect - array is resized to have a domain X.domain() - View's domain must match X's domain or behaviour is undefined.
- array is filled with the evaluation of X. - array is filled with the evaluation of X. - array is filled with the evaluation of X. - array is filled with the evaluation of X.
@ -34,33 +34,24 @@ We will illustrate it on the `array` class, it is the same for `matrix` and `vec
- a copy if X is an array. - a copy if X is an array.
- computing the value if X is an expression. - computing the value if X is an expression.
* **Optimisation** `[advanced]` Compound operators (+=, -=, * =, /=)
-------------------------------------------------
In some case, we know that optimisation is possible. * **Syntax**
If the RHS class derives from `Tag::has_special_assign`, then the instruction ::
A = rhs; The syntax is natural ::
will be rewritten by compiler as :: template<typename RHS> array & operator += (const RHS & X);
template<typename RHS> array & operator -= (const RHS & X);
template<typename RHS> array & operator *= (const Scalar & S);
template<typename RHS> array & operator /= (const Scalar & S);
rhs.assign_invoke(A); * **What can be RHS ?**
An example is the matmul class, which stores the ref. to the objects to be multiplied. Same as for = operator.
If A and B are matrices, writing ::
C = matmul(A,B); // (1) * **Behaviour**
is rewritten as :: Similar to for = operator, with obvious changes.
matmul(A,B).assign_invoke(C);
which is then itself rewritten into (without all the messy details) ::
call_lapack( A, B, C); // (2)
The point is that :
* the user code is (1), very simple and readable
* but the compiler compiles (2), which eliminates temporaries...

103
doc/reference/c++/arrays/basic_classes.rst
View File

@ -1,103 +0,0 @@
Basic classes : array, matrix and vector and their views
=================================================================
* The library provides several interoperable forms of arrays :
* array : general (rectangular) `N`-dimensionnal array; models :ref:`HasImmutableArrayInterface` concept.
* matrix : models the :ref:`MutableMatrix` concept.
* vector : models the :ref:`MutableVector` concept.
and the corresponding view classes : array_view, matrix_view, vector_view.
* All these classes contains basically two things :
* a *storage*, i.e. a (shared) pointer to the data in memory.
* an *indexmap*, i.e. an object that encode the index systems and can map it to the memory.
* They differ by their behaviour :
* array, matrix, vector are *values* with value semantics, while the X_view classes
are views, with reference semantics, see below.
* array form an array algebra, where operation are done element-wise, while matrix and vector
for the usual algebra and vector space of linear algebra.
* These classes are largely interoperable, as explained below : it is easy and quick to take a
matrix_view of an array, or vice versa.
* The classes haves similar template parameters :
.. code-block:: c
typedef unsigned long long ull_t;
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array;
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array_view;
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class matrix;
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class matrix_view;
template <typename ValueType, ull_t OptionsFlags=0> class vector;
template <typename ValueType, ull_t OptionsFlags=0> class vector_view;
where triqs::ull_t is the type defined by :
.. code-block:: c
typedef unsigned long long ull_t;
Template parameters
----------------------------
============================ ================================== ========================== ====================================================================
Template parameter Accepted type Access in the class Meaning
============================ ================================== ========================== ====================================================================
ValueType normally a scalar, but any default value_type The type of the element of the array
constructible type (?).
Rank int rank The rank of the array
OptionsFlags unsigned long long Compile time options, see below.
TraversalOrder unsigned long long Compile time options, see below.
============================ ================================== ========================== ====================================================================
* Rank is only present for array, since matrix have rank 2 and vector rank 1.
* OptionFlags is a series of flags determining various options at compile time.
The possible flags are accessible via a constexpr ull_t in triqs::arrays or a macro :
======================== =======================================
Macro constexpr equivalent
======================== =======================================
BOUND_CHECK triqs::arrays::BoundCheck
TRAVERSAL_ORDER_C triqs::arrays::TraversalOrderC
TRAVERSAL_ORDER_FORTRAN triqs::arrays::TraversalOrderFortran
DEFAULT_INIT triqs::arrays::DefaultInit
======================== =======================================
Defaults can be modified with the macros :
* `TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` : enforce BoundCheck by default (slows down codes ! Use only for debugging purposes).
* `TRIQS_ARRAYS_ENFORCE_INIT_DEFAULT` : init all arrays by default [ NOT IMPLEMENTED]
* TraversalOrder is a coding of the optimal ordering of indices, given by a permutation
evaluated at **compile time**.
The traversal of the arrays (iterators, foreach loop) will be written and optimised for this
order.
The default (0) is understood as regular C-style ordering (slowest index first).
Note that an array can use any index ordering in memory, and that decision is take at run time
(this is necessary for interfacing with python numpy arrays, see below).
The code will be correct for any order, but optimised for the TraversalOrder.
For a few very specials operations (e.g. regrouping of indices), the indices ordering in memory and TraversalOrder
must coincide. This will be explicitely said below. By default, it is not necessary.
The permutation P encodes the position of the index : P[0] is the fastest index, P[rank - 1] the slowest index
(see examples below).
TraversalOrder is not present for vector since there is only one possibility in 1d.
* Examples will be given in the next paragraph, with constructors.

21
doc/reference/c++/arrays/basic_interop.rst
View File

@ -1,21 +0,0 @@
Interoperability
---------------------------------------------------
* These classes are largely similar, and are interoperable.
* One can construct a matrix_view from a array, e.g. (providing the rank of the array is 2, of course...).
* Why several classes then ? The reason is that their algebra (i.e. their behaviour under operations) differ.
For example, a matrix<T> is not really a array<T,2> :
the multiplication for a matrix is the matrix multiplication, while it is element wise for the array.
The expression template implements two different algebras, one for arrays, one for matrices and vectors.
TODO : write the example and code the make_matrix_view function....
Example::
array<double,3> A; matrix<double> M;
auto res = matrix_view<double> ( A(0,range(),range()) ) + M;

25
doc/reference/c++/arrays/call.rst
View File

@ -1,25 +0,0 @@
.. highlight:: c
Operator() : summary
==================================
* To summarize the previous items, here is the list of possible call of array, matrix, vector and their view.
If A is an array, and Args ... the arguments, the return type of the call ::
A( Args ... args)
is summarized in the following table.
=========================================== ========================================================
Arguments Returns
=========================================== ========================================================
None a complete view of the array
One at least Args is clef expression a clef expression
Args is a set of Range, Ellipsis, size_t a view class representing the partial view
=========================================== ========================================================
* Example ::
// write here an example with several variant

33
doc/reference/c++/arrays/class_diff.rst
View File

@ -1,33 +0,0 @@
Why several classes ?
=================================================================
The library provides several interoperable forms of arrays : array, matrix and vector.
.. note:: Why several classes ?
Because their algebra differ, e.g. a matrix<T> is not really a array<T,2> :
the multiplication for a matrix is the matrix multiplication, while it is element wise for the array.
Interoperability
---------------------------------------------------
* These classes are largely similar, and are interoperable.
* One can construct a matrix_view from a array, e.g. (providing the rank of the array is 2, of course...).
* Why several classes then ? The reason is that their algebra (i.e. their behaviour under operations) differ.
For example, a matrix<T> is not really a array<T,2> :
the multiplication for a matrix is the matrix multiplication, while it is element wise for the array.
The expression template implements two different algebras, one for arrays, one for matrices and vectors.
TODO : write the example and code the make_matrix_view function....
Example::
array<double,3> A; matrix<double> M;
auto res = matrix_view<double> ( A(0,range(),range()) ) + M;

21
doc/reference/c++/arrays/compound_ops.rst
View File

@ -1,21 +0,0 @@
.. highlight:: c
Compound operators (+=, -=, *=, /=)
======================================
The `value classes` and the `view classes` behaves similarly.
We will illustrate it on the `array` class, it is the same for `matrix` and `vector`.
* **Syntax**
The syntax is natural ::
template<typename RHS> array & operator += (const RHS & X);
template<typename RHS> array & operator -= (const RHS & X);
template<typename RHS> array & operator *= (const Scalar & S);
template<typename RHS> array & operator /= (const Scalar & S);
* **Behaviour**
- Domain must match.
- X is evaluated and added term by term.

203
doc/reference/c++/arrays/concepts.rst Normal file
View File

@ -0,0 +1,203 @@
Concepts
=============================================================
In this section, we define the basic concepts (in the C++ sense)
related to the multidimentional arrays.
Readers not familiar with the idea of concepts in programming can skip this section,
which is however needed for a more advanced usage of the library.
A multidimentional array is basically a function of some indices, typically integers taken in a specific domain,
returning the element type of the array, e.g. int, double.
Indeed, if a is an two dimensionnal array of int,
it is expected that a(i,j) returns an int or a reference to an int, for i,j integers in some domain.
We distinguish two separate notions, whether this function is `pure` or not,
i.e. whether one can or not modify a(i,j).
* An `Immutable` array is just a pure function on the domain of definition.
a(i,j) returns a int, or a int const &, that can not be modified (hence immutable).
* A `Mutable` array is on the other hand, a piece of memory, addressed by the indices,
which can be modified. a(i,j) can return a int &.
The formal definition is given below
.. note::
The tag (made by derivation) is use to quickly recognize that an object
models a given concept, due to the current lack of concept support in C++.
It is used e.g. to detect to which algebra (Array or Matrix/Vector) the object belongs...
.. _ImmutableCuboidArray:
ImmutableCuboidArray
----------------------------
* **Purpose** :
The most abstract definition of something that behaves like an immutable array.
* it has a domain (hence a rank).
* it can be evaluated on any value of the indices in the domain
* NB : It does not need to be stored in memory. A formal expression, e.g. model this concept.
* **Definition** ([A] denotes something optional).
* The class derives from : TRIQS_CONCEPT_TAG_NAME(ImmutableCuboidArray)
================================================================================================== =============================================================================
Elements Comment
================================================================================================== =============================================================================
domain_type Type of the domain.
domain_type [const &] domain() const Access to the domain.
value_type Type of the element of the array
value_type [const &] operator() (size_t ... i) const Evaluation. Must have exactly rank argument (checked at compiled time).
================================================================================================== =============================================================================
* **Examples** :
* array, array_view, matrix, matrix_view, vector, vector_view.
* array expressions.
.. _MutableCuboidArray:
MutableCuboidArray
-------------------------
* **Purpose** : An array where the data can be modified...
* **Refines** : :ref:`ImmutableCuboidArray`.
* **Definition** ([A] denotes something optional).
* The class derives from : TRIQS_CONCEPT_TAG_NAME(MutableCuboidArray)
================================================================================================== =============================================================================
Elements Comment
================================================================================================== =============================================================================
domain_type Type of the domain.
domain_type [const &] domain() const Access to the domain.
value_type Type of the element of the array
value_type const & operator() (size_t ... i) const Element access: Must have exactly rank argument (checked at compiled time).
value_type & operator() (size_t ... i) Element access: Must have exactly rank argument (checked at compiled time).
================================================================================================== =============================================================================
* **Examples** :
* array, array_view, matrix, matrix_view, vector, vector_view.
.. _ImmutableMatrix:
ImmutableMatrix
-------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that :
* the rank of the domain must be 2
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableMatrix).
.. _ImmutableVector:
ImmutableVector
-------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that :
* the rank of the domain must be 1
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableVector).
.. _MutableMatrix:
MutableMatrix
-------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that :
* the rank of the domain must be 2
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableMatrix).
.. _MutableVector:
MutableVector
-------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that :
* the rank of the domain must be 1
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableVector).
Why concepts ? [Advanced]
-----------------------------
Why is it useful to define those concepts ?
Simply because of lot of the library algorithms only use those concepts, and can be used
for an array, or any custom class that model the concept.
Example :
* Problem: we want to quickly assemble a small class to store a diagonal matrix.
We want this class to operate with other matrices, e.g. be part of expression, be printed,
or whatever.
But we only want to store the diagonal element.
* A simple solution :
.. compileblock ::
#include <triqs/arrays.hpp>
#include <iostream>
namespace triqs { namespace arrays { // better to put it in this namespace for ADL...
template<typename T> class immutable_diagonal_matrix_view : TRIQS_CONCEPT_TAG_NAME(ImmutableMatrix) {
array_view<T,1> data; // the diagonal stored as a 1d array
public:
immutable_diagonal_matrix_view(array_view<T,1> v) : data (v) {} // constructor
// the ImmutableMatrix concept
typedef indexmaps::cuboid::domain_t<2> domain_type;
domain_type domain() const { auto s = data.shape()[0]; return {s,s}; }
typedef T value_type;
T operator()(size_t i, size_t j) const { return (i==j ? data(i) : 0);} // just kronecker...
friend std::ostream & operator<<(std::ostream & out, immutable_diagonal_matrix_view const & d) { return out<<"diagonal_matrix "<<d.data;}
};
}}
/// TESTING
using namespace triqs::arrays;
int main(int argc, char **argv) {
auto a = array<int,1> {1,2,3,4};
auto d = immutable_diagonal_matrix_view<int>{a};
std::cout << "domain = " << d.domain()<< std::endl;
std::cout << "d = "<< d << std::endl;
std::cout << "2*d = "<< matrix<int>(2*d) << std::endl;
std::cout << "d*d = "<< matrix<int>(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...

0
doc/reference/c++/arrays/STL.rst → doc/reference/c++/arrays/containers/STL.rst
View File

137
doc/reference/c++/arrays/containers/call.rst Normal file
View File

@ -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 <triqs/arrays.hpp>
using namespace triqs::arrays;
int main(){
array<double,2> 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<T,1> SL = A(0,range(0,3)); // naming the view. No data copied here !
array_view<T,1> SL ( A(0,range(0,3))); // same thing !
.. _arr_making_view:
(2) Building a view
---------------------------------
When the arguments contains at least one :ref:`range<arr_range>` or one :ref:`ellipsis<arr_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 <triqs/arrays.hpp>
using namespace triqs::arrays;
int main(){
array<double,2> 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<double,2> 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 <triqs/arrays.hpp>
using triqs::arrays::array; using triqs::clef::placeholder;
int main(){
placeholder<0> i_; placeholder<1> j_;
array<double,2> A(2,2), B(2,2);
A(i_,j_) << i_ + 2*j_ ;
B(i_,j_) << A(j_,i_)/2;
std::cout << "A = "<<A << std::endl;
std::cout << "B = "<<B << std::endl;
}
.. note::
The syntax uses a <<, not = since the array is not assigned to an expression
but filled by the evaluation thereof.

76
doc/reference/c++/arrays/containers/range_ell.rst Normal file
View File

@ -0,0 +1,76 @@
.. highlight:: c
.. _arr_range:
range
=========
`range` mimics the Python `range`. Arguments of the constructor can be :
* no argument : it then takes the whole set of indices in the dimension (like `:` in python) ::
A(range(), 0) // take the first column of A
* two arguments to specify a range ::
A(range (0,3), 0) // means A(0,0), A(1,0), A(2,0)
.. warning::
the second element is excluded : range(0,3) is 0,1,2, like in Python.
* three arguments : a range with a step ::
A(range(0,4,2), 0) // means A(0,0), A(2,0)
.. _arr_ellipsis:
ellipsis
===============
* Ellipsis can be provided in place of `range`, as in python. The type `ellipsis` is similar to range
except that it is implicitely repeated to as much as necessary.
* Example:
.. compileblock ::
#include <triqs/arrays.hpp>
using triqs::arrays::array; using triqs::arrays::ellipsis;
int main(){
array<long,4> B(2,3,4,5) ;
B(0,ellipsis(),3) ; // same as B(0, range(),range(), 3 )
B(0,ellipsis(),2,3); // same as B(0, range(), 2, 3 )
B(ellipsis(),2,3) ; // same as B( range(),range(), 2, 3 )
}
* NB : there can be at most one ellipsis per expression (otherwise it would be meaningless).
* Example of usage :
Ellipsis are useful to write generic algorithms. For example, imagine that you want to sum
arrays on their first index :
.. compileblock ::
#include <triqs/arrays.hpp>
using triqs::arrays::array; using triqs::arrays::ellipsis;
// a generic function that sum array, array_view or in fact anything
// with the right concept on its first dimension
template<typename ArrayType>
array<typename ArrayType::value_type, ArrayType::rank-1> sum0 (ArrayType const & A) {
array<typename ArrayType::value_type, ArrayType::rank-1> res = A(0,ellipsis());
for (size_t u =1; u< first_dim(A); ++u) res += A(u,ellipsis());
return res;
}
// test
int main(){
array<double,2> A(5,2); A()=2;
array<double,3> B(5,2,3); B() = 1;
std::cout<< sum0(A) << sum0(B) <<std::endl;
}

60
doc/reference/c++/arrays/compound_assignment.rst → doc/reference/c++/arrays/containers/reg_assign.rst
View File

@ -1,16 +1,12 @@
.. highlight:: c .. highlight:: c
Compound assignment operators : +=, -=, *=, /= .. _arr_reg_assign:
=============================================================
The `value classes` and the `view classes` have a quite general assignment operator (=), Assignment
and corresponding compound operators (+=, -=). =========================
We will illustrate it on the `array` class, it is the same for `matrix` and `vector`.
Assignment operator (=)
-------------------------------------------------
The `value classes` and the `view classes` have a quite general assignment operator. The `value classes` and the `view classes` have a quite general assignment operator.
We will illustrate it on the `array` class, it is the same for `matrix` and `vector`.
* **Syntax** : the syntax is the same in both cases:: * **Syntax** : the syntax is the same in both cases::
@ -19,7 +15,7 @@ The `value classes` and the `view classes` have a quite general assignment opera
* **What can be RHS ?** * **What can be RHS ?**
RHS can be ... anything that models the HasImmutableArrayInterface concept ! RHS can be ... anything that models the :ref:`ImmutableCuboidArray` concept !
e.g. : array, array_view, matrix, matrix_view, e.g. : array, array_view, matrix, matrix_view,
but also formal expression (See , e.g. A+B), or any custom object of your choice. but also formal expression (See , e.g. A+B), or any custom object of your choice.
@ -29,7 +25,7 @@ The `value classes` and the `view classes` have a quite general assignment opera
================= ======================================================================= ====================================================================================== ================= ======================================================================= ======================================================================================
Topic value class : array, matrix, vector view: array_view, matrix_view, vector_view Topic value class : array, matrix, vector view: array_view, matrix_view, vector_view
================= ======================================================================= ====================================================================================== ================= ======================================================================= ======================================================================================
RHS ... - RHS models the concept `HasImmutableArrayInterface`. - RHS models HasImmutableArrayInterface RHS ... - RHS models the concept :ref:`ImmutableCuboidArray`. - RHS models :ref:`ImmutableCuboidArray`
[or less ? : RHS can be evaluated in the domain_type::value_type, no domain needed.]. [or less ? : RHS can be evaluated in the domain_type::value_type, no domain needed.].
Effect - array is resized to have a domain X.domain() - View's domain must match X's domain or behaviour is undefined. Effect - array is resized to have a domain X.domain() - View's domain must match X's domain or behaviour is undefined.
- array is filled with the evaluation of X. - array is filled with the evaluation of X. - array is filled with the evaluation of X. - array is filled with the evaluation of X.
@ -40,41 +36,10 @@ The `value classes` and the `view classes` have a quite general assignment opera
- a copy if X is an array. - a copy if X is an array.
- computing the value if X is an expression. - computing the value if X is an expression.
* **Optimisation** `[advanced]`
In some case, we know that optimisation is possible.
If the RHS class derives from `Tag::has_special_assign`, then the instruction ::
A = rhs;
will be rewritten by compiler as ::
rhs.assign_invoke(A);
An example is the matmul class, which stores the ref. to the objects to be multiplied.
If A and B are matrices, writing ::
C = matmul(A,B); // (1)
is rewritten as ::
matmul(A,B).assign_invoke(C);
which is then itself rewritten into (without all the messy details) ::
call_lapack( A, B, C); // (2)
The point is that :
* the user code is (1), very simple and readable
* but the compiler compiles (2), which eliminates temporaries...
Compound operators (+=, -=, * =, /=) Compound operators (+=, -=, * =, /=)
------------------------------------------------- -------------------------------------------------
* **Syntax**
* **Syntax**
The syntax is natural :: The syntax is natural ::
@ -83,9 +48,12 @@ Compound operators (+=, -=, * =, /=)
template<typename RHS> array & operator *= (const Scalar & S); template<typename RHS> array & operator *= (const Scalar & S);
template<typename RHS> array & operator /= (const Scalar & S); template<typename RHS> array & operator /= (const Scalar & S);
* **Behaviour** * **What can be RHS ?**
Same as for = operator.
* **Behaviour**
Similar to for = operator, with obvious changes.
- Domain must match.
- X is evaluated and added term by term.
To be written : special operators.

57
doc/reference/c++/arrays/construct.rst → doc/reference/c++/arrays/containers/reg_constructors.rst
View File

@ -1,16 +1,19 @@
.. highlight:: c .. highlight:: c
Value classes and their constructors .. _arr_reg_constr:
==============================================================================
Constructors
====================
Constructors of array
---------------------------
* The value classes array, matrix and vector have very similar constructors. * The value classes array, matrix and vector have very similar constructors.
We will therefore describe only for the array, and mention the difference for matrix and vector below. We will therefore describe only for the array, and mention the difference for matrix and vector below.
* As mentioned earlier, they are *values*, * array, matrix, vector are regular types (with value semantics).
so all these constructors make a **copy** of the data, except of course the move constructor. Hence, all these constructors make a **copy** of the data, except of course the move constructor.
Constructors of array
---------------------------
========================================== =========================================================================================== ========================================== ===========================================================================================
Constructors of array Comments Constructors of array Comments
@ -18,66 +21,63 @@ Constructors of array
array() Empty array of size 0 array() Empty array of size 0
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(size_t, ...., size_t) From the lengths of the array dimensions, with Rank arguments (checked at compile time). array(size_t, ...., size_t) From the lengths of the array dimensions, with Rank arguments (checked at compile time).
Does **NOT** initialize the array elements to 0 ! (see compile time option)
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(const array &) Copy construction array(const array &) Copy construction
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(array &&) Move construction array(array &&) Move construction
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(const T & X) Type T models the :ref:`HasImmutableArrayInterface` concept. array(const T & X) Type T models the :ref:`ImmutableCuboidArray` concept.
- X must have the appropriate domain (checked at compile time). - X must have the appropriate domain (checked at compile time).
- Constructs a new array of domain X.domain() and fills it with evaluation of X. - Constructs a new array of domain X.domain() and fills it with evaluation of X.
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(shape_t const &) New array with the corresponding shape (as returned by the function shape. See example array(shape_t const &) New array with the corresponding shape (as returned by the function shape. See example
in section XXX). in section XXX).
------------------------------------------ ------------------------------------------------------------------------------------------- ------------------------------------------ -------------------------------------------------------------------------------------------
array(PyObject * X) Construct a new array from the Python object X. array(PyObject * X) Construct a new array from the Python object X.
NB : X is a borrowed reference, array does affect its counting reference.
- it takes a **copy** of the data of X (or of numpy(X)) into C++. - it takes a **copy** of the data of X (or of numpy(X)) into C++.
- X is first transformed into a numpy by the python numpy lib itself - X is first transformed into a numpy by the python numpy lib itself
(as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type (as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type
(e.g. you construct an array<double,2> from a numpy of int....), and (e.g. you construct an array<double,2> from a numpy of int....), and
copied into the array. copied into the array.
.. note:: X is a borrowed reference, array does not affect its counting reference.
========================================== =========================================================================================== ========================================== ===========================================================================================
.. warning:: .. warning::
The constructor from the dimensions does **NOT** initialize the array to 0 The constructor from the dimensions does **NOT** initialize the array to 0
(because it may not be optimal). (because it may not be optimal).
If needed, do it explicitely by (a if the array) `a()=0`;, see section ?. If needed, do it explicitely by (a if the array) `a()=0`
Constructors of matrix Constructors of matrix
--------------------------- ---------------------------
* matrix have similar constructors * matrix have similar constructors
========================================== =========================================================================================== ========================================== =======================================================================================================
Constructors of matrix Comments Constructors of matrix Comments
========================================== =========================================================================================== ========================================== =======================================================================================================
matrix() empty matrix of size 0 matrix() empty matrix of size 0
matrix(size_t, size_t) from the dimensions. Does NOT initialize the elements of matrix to 0 ! matrix(size_t, size_t) from the dimensions. Does NOT initialize the elements of matrix to 0 !
matrix(const matrix &) copy construction matrix(const matrix &) copy construction
matrix(matrix &&) move construction matrix(matrix &&) move construction
matrix (PyObject * X) Construct a new matrix from the Python object X. matrix (PyObject * X) Construct a new matrix from the Python object X.
matrix(const T & X) Type T models the :ref:`HasImmutableArrayInterface` concept. Same as array. matrix(const T & X) Type T models the :ref:`ImmutableMatrix` or :ref:`ImmutableCuboidArray` (with rank 2). Same as array.
========================================== =========================================================================================== ========================================== =======================================================================================================
Constructors of vector Constructors of vector
--------------------------- ---------------------------
========================================== =========================================================================================== ========================================== =======================================================================================================
Constructors of vector Comments Constructors of vector Comments
========================================== =========================================================================================== ========================================== =======================================================================================================
vector() empty vector of size 0 vector() empty vector of size 0
vector(size_t) from the dimensions. Does NOT initialize the elements of vector to 0 ! vector(size_t) from the dimensions. Does NOT initialize the elements of vector to 0 !
vector(const vector &) copy construction vector(const vector &) copy construction
vector(vector &&) move construction vector(vector &&) move construction
vector (PyObject * X) Construct a new vector from the Python object X. vector (PyObject * X) Construct a new vector from the Python object X.
vector(const T & X) Type T models the :ref:`HasImmutableArrayInterface` concept. Same as array. vector(const T & X) Type T models the :ref:`ImmutableVector` or :ref:`ImmutableCuboidArray` (with rank 1). Same as array.
========================================== =========================================================================================== ========================================== =======================================================================================================
Examples Examples
------------ ------------
@ -115,3 +115,4 @@ Examples
array<long, 3, 0, permutation(1,0,2)> A2(2,3,4); array<long, 3, 0, permutation(1,0,2)> A2(2,3,4);
} }

146
doc/reference/c++/arrays/containers/regular.rst Normal file
View File

@ -0,0 +1,146 @@
.. highlight:: c
array, matrix & vector
===========================================
**Synopsis**:
.. code-block:: c
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array;
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class matrix;
template <typename ValueType, ull_t OptionsFlags=0> class vector;
where triqs::ull_t is the type defined by :
.. code-block:: c
typedef unsigned long long ull_t;
* The library provides three basic containers :
* array : general (rectangular) `N`-dimensionnal array; models :ref:`MutableCuboidArray` concept.
* matrix : models the :ref:`MutableMatrix` concept.
* vector : models the :ref:`MutableVector` concept.
and the corresponding view classes : array_view, matrix_view, vector_view (Cf :ref:`partial_views`).
* The matrix and vector are very similar to an array of dimension 2 and 1 respectivily,
except for their algebra. Array form an array algebra, where operation are done element-wise, while matrix and vector
form the usual algebra and vector space of linear algebra.
* These classes are largely interoperable, as explained below : it is easy and quick to take a
matrix_view of an array, or vice versa.
Template parameters
----------------------------
============================ ============================== ========================== ====================================================================
Template parameter Accepted type Access in the class Meaning
============================ ============================== ========================== ====================================================================
ValueType any regular type (typically a value_type The type of the element of the array
scalar).
Rank int rank The rank of the array
OptionsFlags ull_t Compile time options, see below.
TraversalOrder ull_t Compile time options, see below.
============================ ============================== ========================== ====================================================================
* Rank is only present for array, since matrix have rank 2 and vector rank 1.
* OptionFlags is a series of flags determining various options at compile time.
The possible flags are accessible via a constexpr ull_t in triqs::arrays or a macro :
======================== =======================================
Macro constexpr equivalent
======================== =======================================
BOUND_CHECK triqs::arrays::BoundCheck
TRAVERSAL_ORDER_C triqs::arrays::TraversalOrderC
TRAVERSAL_ORDER_FORTRAN triqs::arrays::TraversalOrderFortran
DEFAULT_INIT triqs::arrays::DefaultInit
======================== =======================================
Defaults can be modified with the macros :
* `TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` : enforce BoundCheck by default (slows down codes ! Use only for debugging purposes).
* TraversalOrder is a coding of the optimal ordering of indices, given by a permutation
evaluated at **compile time**.
The traversal of the arrays (iterators, foreach loop) will be written and optimised for this
order.
The default (0) is understood as regular C-style ordering (slowest index first).
Note that an array can use any index ordering in memory, and that decision is take at run time
(this is necessary for interfacing with python numpy arrays, see below).
The code will be correct for any order, but optimised for the TraversalOrder.
For a few very specials operations (e.g. regrouping of indices), the indices ordering in memory and TraversalOrder
must coincide. This will be explicitely said below. By default, it is not necessary (but can be suboptimal).
The permutation P encodes the position of the index : P[0] is the fastest index, P[rank - 1] the slowest index
(see examples below).
TraversalOrder is not present for vector since there is only one possibility in 1d.
Member types
-----------------
=================== ======================================
Member type Definitions
=================== ======================================
value_type ValueType
view_type The corresponding view type
=================== ======================================
Member functions
---------------------
============================================= ==============================================
Member function Meaning
============================================= ==============================================
:ref:`(constructor)<arr_reg_constr>`
(destructor)
:ref:`operator =<arr_reg_assign>` assigns values to the container
:ref:`operator ()<arr_reg_call>` element of access/views/lazy expressions
begin/cbegin returns iterator to the beginning
end/cend returns iterator to the end
:ref:`resize<arr_resize>` resize the container
============================================= ==============================================
.. toctree::
:hidden:
reg_constructors
reg_assign
call
resize
STL
Non-member functions
------------------------
============================================= ==============================================
Member function Meaning
============================================= ==============================================
:ref:`swap<arr_swap>`
:ref:`deep_swap<arr_deep_swap>`
============================================= ==============================================
.. toctree::
:hidden:
swap

71
doc/reference/c++/arrays/containers/resize.rst Normal file
View File

@ -0,0 +1,71 @@
.. highlight:: c
.. _arr_resize:
resize
==================================
* **Synopsis**:
.. cpp:function:: void resize(size_t, ..., size_t)
Resizes the container.
* **Examples** :
.. compileblock::
#include <triqs/arrays.hpp>
using namespace triqs::arrays;
int main() {
array<double,2> A(2,3);
A.resize (make_shape (5,5));
matrix<double,2> M;
M.resize(3,3);
vector<double> V;
V.resize(10);
}
.. note::
Views can not be resized.
* **Invalidation** :
As for std::vector, resize invalidate all pointers to the data of the container
(they may move in memory, to maintain data contiguity).
Views are invalidated too : more precisely, because of the memory guarantee provided by the views,
the view is still valid (code will not crash), but it does *not* view the container anymore...
Illustration :
.. compileblock::
#include <triqs/arrays.hpp>
using namespace triqs::arrays;
int main() {
array<double,2> A(2,3); A()= 9;
array_view<double,2> V = A();
A.resize (make_shape (5,5)); A()=0;
std::cout<< V<< std::endl;
}
.. _arr_resize_ch:
resize_or_check_if_view
==================================
* **Synopsis**:
.. cpp:function:: void resize_or_check_if_view(ArrayType const & A, shape_t)
* If A is a value : resize A
* If A is a view : check that the shape if the shape_t and throw an exception if not.

27
doc/reference/c++/arrays/move_swap.rst → doc/reference/c++/arrays/containers/swap.rst
View File

@ -1,23 +1,25 @@
.. _Move: swap & deep_swap
Move and swap
================================== ==================================
Move There are two possible interpretation of "swapping two arrays" :
------ either use 3 moves like std::swap, i.e. swapping the pointer to the data in memory,
or making a deep swap, i.e. really swapping all the elements in memeory.
Every classes have proper move constructor and move assignment operators. .. _arr_swap:
Swap swap
-------- --------
* swap and std::swap (equivalent) can be used to swap to array, array_view and so on.
* swap just exchange the (shared) pointer to the data in memory, * swap just exchange the (shared) pointer to the data in memory,
it does not affect the data them self. it does not affect the data them self.
This distinction of importance for views in particular. This distinction of importance for views in particular.
* For the regular type, std::swap and swap are equivalent.
For the views, std::swap is explicitely deleted, since it is incorrect
due to the lack of move constructor for a view.
Use `swap` instead.
* **Example** : * **Example** :
.. compileblock:: .. compileblock::
@ -38,9 +40,16 @@ Swap
std::cout << "V = "<< V << " W = " << W<< " V view "<< VV<< " W view "<< VW<< std::endl; std::cout << "V = "<< V << " W = " << W<< " V view "<< VV<< " W view "<< VW<< std::endl;
} }
.. _arr_deep_swap:
deep_swap deep_swap
-------------- --------------
.. warning::
Currently implemented only for triqs::vector and triqs::vector_view.
* deep_swap swaps the data in memory. * deep_swap swaps the data in memory.
* **Example** (compare with swap) : * **Example** (compare with swap) :

105
doc/reference/c++/arrays/containers/views.rst Normal file
View File

@ -0,0 +1,105 @@
.. highlight:: c
.. _partial_views:
Views
==============================================================
**Synopsis**:
.. code-block:: c
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array_view;
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class matrix_view;
template <typename ValueType, ull_t OptionsFlags=0> 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<int,2> *p = new array<int,2> (2,3); // create an array p
array_view<int,2> B = *p; // making a view
delete p; // p is gone...
B(0,0) = 314; cout<<B<<endl; // B (and the data) is still alive
.. warning::
TRIQS arrays, and in particular views are NOT thread-safe, contrary to std::shared_ptr.
This is a deliberate choice for optimisation.
Weak views [Advanced]
^^^^^^^^^^^^^^^^^^^^^^^^
Unfortunately this can not be the end of the story, at least on current C++11 compilers.
It turns out that, in very performance sensitive loops, increasing this tiny
reference counter can break a lot of optimisations in almost all compilers, including the most
recent ones (gcc 4.8, clang 3.3).
It was therefore decided to introduce `weak views`.
* Weak views are completely similar to "normal" views, except that they do `not` increase the memory
reference counter.
* Normal views are be implicitely constructed from weak view (the reverse is also true),
As soon as you store the weak view into a normal view (e.g. array_view<T,N>)
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 :

32
doc/reference/c++/arrays/contents.rst
View File

@ -1,4 +1,4 @@
Array library Multidimensional arrays
******************************************* *******************************************
.. highlight:: c .. highlight:: c
@ -7,30 +7,26 @@ Array library
:maxdepth: 1 :maxdepth: 1
:numbered: :numbered:
cookbook introduction
introduction.rst concepts
view_or_not_view containers/regular
basic_classes containers/views
construct
views
move_swap
shape shape
element_acces view_or_not_view
slicing
lazy lazy
call foreach
debug map
assignment
algebras
blas_lapack
mapped_fnt mapped_fnt
algebras
move_swap
blas_lapack
H5 H5
Interop_Python Interop_Python
IO IO
foreach
STL STL
map
group_indices group_indices
debug
multithreading
FAQ FAQ
Design/contents.rst implementation_notes/contents

20
doc/reference/c++/arrays/contents.rst.1
View File

@ -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

3
doc/reference/c++/arrays/cookbook/basic.rst
View File

@ -141,8 +141,7 @@ Linear algebra
.. compileblock:: .. compileblock::
#include <triqs/arrays.hpp> #include <triqs/arrays.hpp>
#include <triqs/arrays/linalg/inverse.hpp> #include <triqs/arrays/linalg/det_and_inverse.hpp>
#include <triqs/arrays/linalg/determinant.hpp>
using triqs::arrays::array; using triqs::arrays::matrix; using triqs::clef::placeholder; using triqs::arrays::array; using triqs::arrays::matrix; using triqs::clef::placeholder;
int main(){ int main(){

27
doc/reference/c++/arrays/element_acces.rst
View File

@ -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<T,R> and i,j,k, its indices
A(i,j,k) is the element (i,j,k) of the array.
.. compileblock::
#include <triqs/arrays.hpp>
namespace tqa=triqs::arrays;
int main(){
tqa::array<double,2> 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;
}

104
doc/reference/c++/arrays/expr_arith.rst
View File

@ -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<long,2> A (2,2), B(2,2),C;
C= A + 2*B;
array<long,2> D( A+ 2*B);
array<double,2> F( 0.5 * A); // Type promotion is automatic
// or even in C++0x :
auto e = A + 2*B; // expression, purely formal
array<long,2> D(e); // really makes the computation
cout<< e <<endl ; // prints the expression
cout<< e(1,2) <<endl ; // evaluates just at a point
cout<< e.domain() <<endl ; // just computes the domain
- Using predefined expressions :
- matmul
The code::
matrix<double> 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<long,2> 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<long,2> R(2,3),Rt(3,2);
cout<<" R = "<< array<long,2>(Transpose(R)) <<endl;
// mapping any function
C = map_expr(&sqr,A);
cout<<" C = "<< map_expr(&sqr,A,"SQR")<<" = "<<C<<endl;
// matmul as expression Oi are 'C' or 'F'
matrix<double,O1> M1(2,2); matrix<double,O2> M2(2,2); matrix<double,O3> M3;
// The central instruction : note that matmul returns a lazy object
// that has ImmutableArray interface, and defines a specialized version assignment
// As a result this is equivalent to some matmul_with_lapack(M1,M2,M3) : there is NO intermediate copy.
M3 = matmul(M1,M2);
See expression.hpp.
At the moment, only +,-, * and / by scalar are implemented.
An expression models HasImmutableArrayInterface, i.e. :
* It has a domain (computed from the expression)
* It can be evaluated.
It is then easy to mix them with other objects,
that model the same concept. See e.g. expr2.cpp (map_expr) for examples.
* *Multiplication* :
not decided, since it is not the same for array or matrices.
Two choices :
* Do not add \* for array, matrices (use matmul e.g.) and allow mixing array, matrix
e.g. add an array<int,2> and a matrix <int>
* Add the \*, but then do different expression for array and matrix/vector,
then one can not mix them.
In that case, it is however trivial to say e.g. M + matrix_view<int>(A) if A is an array.

59
doc/reference/c++/arrays/expr_custom.rst
View File

@ -1,59 +0,0 @@
.. highlight:: c
.. _custom_expression:
Custom Expressions
-------------------------------------------------
- Building custom expressions. The transpose example...
Describe the concept, what to implement, etc....
- Transpose::
array<long,2> 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<long,2> R(2,3),Rt(3,2);
cout<<" R = "<< array<long,2>(Transpose(R)) <<endl;
// mapping any function
C = map_expr(&sqr,A);
cout<<" C = "<< map_expr(&sqr,A,"SQR")<<" = "<<C<<endl;
// matmul as expression Oi are 'C' or 'F'
matrix<double,O1> M1(2,2); matrix<double,O2> M2(2,2); matrix<double,O3> M3;
// The central instruction : note that matmul returns a lazy object
// that has ImmutableArray interface, and defines a specialized version assignment
// As a result this is equivalent to some matmul_with_lapack(M1,M2,M3) : there is NO intermediate copy.
M3 = matmul(M1,M2);
See expression.hpp.
At the moment, only +,-, * and / by scalar are implemented.
An expression models HasImmutableArrayInterface, i.e. :
* It has a domain (computed from the expression)
* It can be evaluated.
It is then easy to mix them with other objects,
that model the same concept. See e.g. expr2.cpp (map_expr) for examples.
* *Multiplication* :
not decided, since it is not the same for array or matrices.
Two choices :
* Do not add \* for array, matrices (use matmul e.g.) and allow mixing array, matrix
e.g. add an array<int,2> and a matrix <int>
* Add the \*, but then do different expression for array and matrix/vector,
then one can not mix them.
In that case, it is however trivial to say e.g. M + matrix_view<int>(A) if A is an array.

22
doc/reference/c++/arrays/expr_predef.rst
View File

@ -1,22 +0,0 @@
.. highlight:: c
.. _predef_expression:
Predefined Expressions
-------------------------------------------------
- Using predefined expressions :
- matmul
The code::
matrix<double> 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

48
doc/reference/c++/arrays/expression.rst
View File

@ -1,48 +0,0 @@
.. highlight:: c
to be removed...
-------------------------------------------------
* **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 :ref:`arith_expression`, e.g. A + 2*B
- Using predefined expressions, e.g. for Linear Algebra operations.
For example, in the code::
matrix<double> M1(2,2), M2(2,2), M3;
M3 = matmul(M1,M2);
`matmul` returns an expression, a lazy object modelling the :ref:`Expression` concept.
REF :
- Building :ref:`custom_expression`.
.. toctree::
:maxdepth: 1
expr_arith
expr_predef
expr_custom

57
doc/reference/c++/arrays/fold.rst
View File

@ -1,57 +0,0 @@
.. highlight:: c
Functional construct (II) : map
========================================================
* **Purpose** :
fold implements the folding (or reduction) on the array.
* **Syntax** :
If `f` is a function, or a function object of synopsis (T, R being 2 types) ::
R f ( T, R )
then ::
auto F = fold(f);
is a callable object which can fold any array of value_type T.
So, if
* A is a type which models the :ref:`HasImmutableArrayInterface` concept
(e.g. an array , a matrix, a vector, an expression, ...)
* A::value_type is T
then ::
fold (f) ( A, R init = R() ) = f( f( f( ... f( a(0,1), f(a(0,0), init)))))
Note that :
* The order of traversal is the same as foreach.
* The precise return type of fold is an implementation detail, depending on the precise type of f,
use auto to keep it.
* The function f will be inlined if possible, leading to efficient algorithms.
* fold is implemented using a foreach loop, hence it is efficient.
* **Example** :
Many algorithms can be written in form of map/fold.
The function *sum* which returns the sum of all the elements of the array is implemented approximately like this
(this function already exists in the lib, cf ???) ::
template <class A>
typename A::value_type sum(A const & a) { return fold ( std::plus<typename A::value_type>()) (a); }
Note in this example :
* the simplicity of the code
* the genericity : it is valid for any dimension of array.
* internally, the library will rewrite it as a series of for loop, ordered in the TraversalOrder of the array
and inline the plus operator.

2
doc/reference/c++/arrays/foreach.rst
View File

@ -2,7 +2,7 @@
.. _Foreach: .. _Foreach:
The foreach construct Loops : the foreach constructs
======================================================== ========================================================
foreach and its variants are a compact and efficient way to foreach and its variants are a compact and efficient way to

4
doc/reference/c++/arrays/h5_proxy.rst
View File

@ -3,6 +3,10 @@
h5::array_proxy : a simple proxy to the array in file h5::array_proxy : a simple proxy to the array in file
=========================================================== ===========================================================
.. warning::
NOT operational any more ... : development needed
The principle is that `array_proxy` is a proxy to an array, possibly big, in the h5 file. The principle is that `array_proxy` is a proxy to an array, possibly big, in the h5 file.
It has a domain, and can be assigned from/to an array and sliced. It has a domain, and can be assigned from/to an array and sliced.
This allows to read/write only parts of a large array using the same slicing syntax This allows to read/write only parts of a large array using the same slicing syntax

12
doc/reference/c++/arrays/implementation_notes/assignment.rst Normal file
View File

@ -0,0 +1,12 @@
.. _impl_assign:
operator =
=============================================================
Using delegation.
Various cases...

0
doc/reference/c++/arrays/Design/centralconcept.rst → doc/reference/c++/arrays/implementation_notes/centralconcept.rst
View File

2
doc/reference/c++/arrays/Design/concepts.rst → doc/reference/c++/arrays/implementation_notes/concepts.rst
View File

@ -1,4 +1,6 @@
.. _impl_concepts:
Concepts Concepts
============================================================= =============================================================

27
doc/reference/c++/arrays/implementation_notes/contents.rst Normal file
View File

@ -0,0 +1,27 @@
Implementation notes
***************************************
.. highlight:: c
This section is for the library maintainers.
It describes the various parts and concepts of the library,
in a way suitable for studying/reading/maintening...
.. toctree::
:maxdepth: 1
:numbered:
concepts
storage
indexmaps
isp
userclasses
assignment
expression_template
functional
linalg
hdf5
reinterpretation
python

0
doc/reference/c++/arrays/Design/cuboid_formula.rst → doc/reference/c++/arrays/implementation_notes/cuboid_formula.rst
View File

16
doc/reference/c++/arrays/implementation_notes/expresssion_template.rst Normal file
View File

@ -0,0 +1,16 @@
.. _impl_expr_templ:
Expression template
=============================================================
Principle. Link to lecture ?
array vs matrix/vector algebra.
Use tag to detect.
Use concept

8
doc/reference/c++/arrays/implementation_notes/functional.rst Normal file
View File

@ -0,0 +1,8 @@
.. _impl_func:
Functional aspect : fold, map, mapped functions
=============================================================
map and fold
p

10
doc/reference/c++/arrays/implementation_notes/hdf5.rst Normal file
View File

@ -0,0 +1,10 @@
.. _impl_h5:
Hdf5 interface (also for utility/h5)
=============================================================
Organisation
---------------
Issue with complex numbers
---------------------------

21
doc/reference/c++/arrays/implementation_notes/indexmaps.rst Normal file
View File

@ -0,0 +1,21 @@
.. _impl_indexmaps:
Indexmaps
=============================================================
Concepts
----------
Implementation : cuboid map
----------------------------
* domain with foreach
* map
* permutation at compile time
* slicer

13
doc/reference/c++/arrays/implementation_notes/isp.rst Normal file
View File

@ -0,0 +1,13 @@
.. _impl_isp:
IndexmapStoragePair implementation class
=============================================================
* goal : a generic implementation of the container, view or not.
* lazy description
* rvalue ref !

16
doc/reference/c++/arrays/implementation_notes/linalg.rst Normal file
View File

@ -0,0 +1,16 @@
.. _impl_linalg:
Linear algebra, blas, lapack
=============================================================
Blas/lapack interface
----------------------
?
Linalg
-------
* lazy objects with the concepts.

11
doc/reference/c++/arrays/implementation_notes/python.rst Normal file
View File

@ -0,0 +1,11 @@
.. _impl_python:
Interface to python
=============================================================
Files :
Low level : memory guarantee
High level : 2 functions for going back and forth.

14
doc/reference/c++/arrays/implementation_notes/reinterpretation.rst Normal file
View File

@ -0,0 +1,14 @@
.. _impl_reinterpretation:
Reinterpretation
=============================================================
Basic reinterpretation
-------------------------
Grouping indices
----------------------

0
doc/reference/c++/arrays/Design/slicing.rst → doc/reference/c++/arrays/implementation_notes/slicing.rst
View File

20
doc/reference/c++/arrays/implementation_notes/storage.rst Normal file
View File

@ -0,0 +1,20 @@
.. _impl_storage:
Storage
=============================================================
Concept
------------
The storage concept...
Implementation : shared_block
------------------------------
Quick description of shared_block, Weak flags, clone etc...
And the python mechanism

0
doc/reference/c++/arrays/Design/strategy.rst → doc/reference/c++/arrays/implementation_notes/strategy.rst
View File

12
doc/reference/c++/arrays/implementation_notes/userclasses.rst Normal file
View File

@ -0,0 +1,12 @@
.. _impl_userclasses:
User classes : array, matrix, vector
=============================================================
* view and not
* move semantic pb of views.
* special functions...

7
doc/reference/c++/arrays/introduction.rst
View File

@ -7,16 +7,17 @@ Rational
This library provides a multi-dimensionnal array library This library provides a multi-dimensionnal array library
for numerical computations with the following characteristics/goals : for numerical computations with the following characteristics/goals :
* **Simplicity of use**. * **Simplicity of use** :
Arrays must be as simple to use as in python (numpy) or fortran. Arrays must be as simple to use as in python (numpy) or fortran.
This library is designed to be used by physicists, not only by professionnal programmers, This library is designed to be used by physicists, not by professionnal programmers,
We do *a lot* of array manipulations, and we want to maintain *readable* codes. We do *a lot* of array manipulations, and we want to maintain *readable* codes.
* **Genericity, abstraction and performance** : * **Genericity, abstraction and performance** :
We want to have simple, readeable code, with the same (or better) speed than manually written low level code. We want to have simple, readeable code, with the same (or better) speed than manually written low level code.
Most optimisations should be delegated to the library and the compiler. Most optimisations should be delegated to the library and the compiler.
(Some) LAPACK and BLAS operations are interfaced.
* **Complete interoperability with python numpy arrays**. * **Complete interoperability with python numpy arrays**.
@ -29,8 +30,6 @@ for numerical computations with the following characteristics/goals :
* **HDF5** : simple interface to hdf5 library for an easy storing/retrieving into/from HDF5 files. * **HDF5** : simple interface to hdf5 library for an easy storing/retrieving into/from HDF5 files.
* **Simple interface to (some) blas/lapack** for matrices, vectors.
* **MPI** : compatibility with boost::mpi interface. * **MPI** : compatibility with boost::mpi interface.

12
doc/reference/c++/arrays/map.rst
View File

@ -10,6 +10,8 @@ Two standard functional constructs are provided :
* *fold* is the reduction of a function on the array. * *fold* is the reduction of a function on the array.
.. _map:
map map
======================================================== ========================================================
* **Purpose** : * **Purpose** :
@ -28,11 +30,11 @@ map
ReturnType map(f) ( ArrayType const & A) ReturnType map(f) ( ArrayType const & A)
where ArrayType models the :ref:`HasImmutableArrayInterface` concept where ArrayType models the :ref:`ImmutableCuboidArray` concept
* with value_type == ValueType1 * with value_type == ValueType1
and ReturnType models the :ref:`HasImmutableArrayInterface` concept and ReturnType models the :ref:`ImmutableCuboidArray` concept
* with the same domain as ArrayType * with the same domain as ArrayType
* with value_type == ValueType2 * with value_type == ValueType2
@ -89,7 +91,7 @@ fold
So, if So, if
* A is a type which models the :ref:`HasImmutableArrayInterface` concept * A is a type which models the :ref:`ImmutableCuboidArray` concept
(e.g. an array , a matrix, a vector, an expression, ...) (e.g. an array , a matrix, a vector, an expression, ...)
* A::value_type is T * A::value_type is T
@ -126,3 +128,7 @@ fold

28
doc/reference/c++/arrays/mapped_fnt.rst
View File

@ -5,25 +5,17 @@
Simple functions on arrays Simple functions on arrays
================================== ==================================
The following functions are mapped The following functions are mapped on the array (using :ref:`map`):
* abs `abs real imag pow cos sin tan cosh sinh tanh acos asin atan exp log sqrt floor`
* real
* imag meaning that e.g. if `A` is an array,
* pow real(A) models :ref:`ImmutableCuboidArray`, with the same size and returns the real part of the elements.
* cos In other words, it applies the function term-by-term.
* sin
* tan .. note::
* cosh
* sinh These functions do NOT compute a new array in memory, they are lazy.
* tanh
* acos
* asin
* atan
* exp
* log
* sqrt
* floor
Example : Example :

101
doc/reference/c++/arrays/matrix.rst
View File

@ -1,101 +0,0 @@
.. highlight:: c
matrix and matrix_view
============================
matrix and matrix_view :
* are the class for matrix and the corresponding view.
* allow **custom memory ordering** (C or Fortran) at compile time.
* model the :ref:`HasImmutableArrayInterface` concept.
Template parameters
----------------------------
* The classes have two template parameters.
.. code-block:: c
template <typename ValueType, typename Opt = Option::Default> class matrix_view;
template <typename ValueType, typename Opt = Option::Default> class matrix;
============================ ================================== ========================== ====================================================================
Template parameter Accepted type Access in the class Meaning
============================ ================================== ========================== ====================================================================
ValueType normally a scalar, but any default value_type The type of the element of the array
constructible type (?).
Opt Option::options< ...> opt_type Compile time options, see below.
============================ ================================== ========================== ====================================================================
Options template parameters are described :ref:`here <option_template>`.
The memory order must obviously be only C or Fortran (memory_order is fine, but useless here...).
.. _matrix_constructors:
Constructors
-----------------
Intentionally, matrix and matrix_view have only a few constructors :
========================================== ===========================================================================================
Constructors of matrix Comments
========================================== ===========================================================================================
matrix() - empty matrix of size 0
matrix(size_t, size_t) - from the dimensions. Does NOT initialize the elements of matrix to 0 !
matrix(const matrix &) - copy construction
matrix (PyObject * X) - Construct a new matrix from the data of the Python object X.
NB : X is a borrowed reference, matrix does affect its counting reference.
- it takes a **copy** of the data of X (or of numpy(X)) into C++.
- X is first transformed into a numpy by the python numpy lib itself
(as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type
(e.g. you construct an matrix<double> from a numpy of int....).
matrix(const T & X) - Type T models the :ref:`HasImmutableArrayInterface` concept.
- X must have the appropriate domain dimension (checked at compile time).
- Constructs a new matrix of domain X.domain() and fills it with evaluation of X.
========================================== ===========================================================================================
* Examples ::
matrix<double> Mc(2,2);
matrix<double,Option::Fortran> Mf(2,2);
.. warning::
The constructor from the dimensions does **NOT** initialize the matrix to 0
(because it may not be optimal).
If needed, do it explicitely by `a()=0`;
Constructors of matrix_views
----------------------------------------------
Automatic construction
^^^^^^^^^^^^^^^^^^^^^^^^^^^
matrix_view are normally automatically constructed by making (partial) views, ref:`Slicing`, e.g. ::
matrix<int> A(2,2);
A(range(),2) ; // --> this makes a view...
A() ; // --> this makes a view over the full array
Explicit construction
^^^^^^^^^^^^^^^^^^^^^^^^
To explicitly make a view of an matrix, use make_view or () ::
matrix<int> A(2,2);
make_view(A) //-> a view...
make_view(A) = 13 ; // to assign e.g.
A() = 13; // idem
====================================================================== ===========================================================================================================
Constructors of matrix_view Comments
====================================================================== ===========================================================================================================
matrix_view(const matrix_view &) - Copy construction (shallow copy)
matrix_view(const T & X) - `[Advanced]` T is any type such that X.indexmap() and X.storage() can be used to construct a view.
====================================================================== ===========================================================================================================

40
doc/reference/c++/arrays/memory_management.rst
View File

@ -1,40 +0,0 @@
Memory management
========================
.. highlight:: c
* `View classes` contains a **reference counting** system to the memory block they view.
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<int,2> *p = new array<int,2> (2,3); // create an array p
array_view<int,2> B(*p); // making a view
delete p; // p is gone...
B(0,0) = 314; cout<<B<<endl; // B (and the data) is still alive
* **Python compatibility**
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::
boost::python::object f() {
array<int,2> res;
/// I compute res
return boost::python::object(array_view<int,2>(res)); // Cf section for convertion...
}
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).

12
doc/reference/c++/arrays/multithreading.rst Normal file
View File

@ -0,0 +1,12 @@
Multithreading
====================
TRIQS libraries, and in particular the arrays are NOT thread safe.
In some cases like arrays, it is a deliberate choice for performance.
In most cases, it is because no time was available to develop
this aspect until now (and it was not useful for your projects...).
Help on this matter would be welcomed !

79
doc/reference/c++/arrays/options.rst
View File

@ -1,79 +0,0 @@
.. highlight:: c
.. _option_template:
Options template parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `Option::options` template can take several parameters that determine various aspects of `array` (resp. `matrix`, `vector`) at **compile time**.
These parameters can be given in any order in the `options` template, but only at most only (they all have a default, that can also be changed
using macros for maximum flexibility).
These options parameters determine :
* the storage order of indices in memory at **compile time**.
=============================== ===========================================================================================
Template parameter Meaning
=============================== ===========================================================================================
`Tag::C` `[default]` C-style order
`Tag::Fortran` Fortran-style order ( NB the base index is still 0, not 1 !)
memory_order<i0,i1,i2,... > The tuple <i0,i1,i2...> of size rank determines the storage order of indices in memory
memory_order_p<P> P is a triqs::arrays::Permutations::permutation that determines the storage order in memory
P[0] is the fastest index, P[rank - 1] the slowest index
=============================== ===========================================================================================
Example of custom order ::
custom<Permutation<0,1,2> > // same as index_order_Fortran, the first index is the fastest
custom<Permutation<2,1,0> > // same as index_order_C, the last index is the fastest
custom<Permutation<1,2,0> > // if indices are (i,j,k) : index j is fastest, then k, then i
* whether bound check are done while accessing array elements or slicing the arrays.
=============================== ====================================================================================================
Template parameter Meaning
=============================== ====================================================================================================
`Tag::NoBoundCheck` `[default]` Do no bound check at all. This is the default, for speed !
`Tag::BoundCheck` Do bound checks. Boundary errors throw triqs::arrays::key_error exception (See ??)
=============================== ====================================================================================================
The macro `TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` change the default to `Tag::BoundCheck` (for debugging purposes).
Rational : one may want for some array to activate bound check and catch the exception, while keeping faster unchecked arrays elsewhere.
* whether arrays are initialized at construction.
=============================== ====================================================================================================
Template parameter Meaning
=============================== ====================================================================================================
`Tag::no_init` `[default]` No initialization of the array at construction (fastest).
`Tag::default_init` Initialize with the default constructor of ValueType
`Tag::nan_inf_init` Initialize to nan for floating type and std::limits<ValueType>::infinity() for integer type
as in D e.g. mainly for detecting easily lack of initialization errors.
=============================== ====================================================================================================
Note that :
* The macro `TRIQS_ARRAYS_ENFORCE_INIT_NAN_INF` change the default to `Tag::nan_inf_init`.
* The macro `TRIQS_ARRAYS_ENFORCE_INIT_DEFAULT` change the default to `Tag::default_init`.
* Several simple aliases are defined in the namespace Option for the most current cases :
=============================== ===============================
Option aliases
=============================== ===============================
Option::C Option::options<`Tag::C`>
Option::Default Option::options<`Tag::C`>
Option::Fortran Option::options<`Tag::Fortran>`
=============================== ===============================
* Examples ::
array<long, 3, Option::options<Option::memory_order <2,1,0> > > A0 (2,3,4);
array<long, 3, Option::options<Option::memory_order <0,1,2> > > A1 (2,3,4);
array<long, 3, Option::options<Option::memory_order <1,0,2> > > A2 (2,3,4);
array<long, 3, Option::Fortran > A4 (2,3,4);

18
doc/reference/c++/arrays/python_tools.rst
View File

@ -1,18 +0,0 @@
.. highlight:: c
::
namespace Py_to_C {
template<typename T> struct convert{
static bool possible (boost::python::object x); // returns true iif the conversion of x into a T is possible
static T invoke(boost::python::object x); // do it !
};
}
namespace C_to_Py {
template<typename T> struct convert {
static boost::python::object invoke (T const & x); // convert T into a python object
};
}

64
doc/reference/c++/arrays/shape.rst
View File

@ -1,50 +1,36 @@
.. _Shape: .. _Shape:
Shape, resize Shape & dimensions
================================== ==================================
Lengths **Synopsis**:
----------
.. code-block:: c
template <ImmutableArray A> mini_vector<size_t,R> get_shape(A const &); // R is the rank of A
template<ImmutableArray A> size_t first_dim (A const & x);
template<ImmutableArray A> size_t second_dim (A const & x);
template<ImmutableArray A> size_t third_dim (A const & x);
template<ImmutableArray A> size_t fourth_dim (A const & x);
template<ImmutableArray A> size_t fifth_dim (A const & x);
template<ImmutableArray A> size_t sixth_dim (A const & x);
template<ImmutableArray A> size_t seventh_dim (A const & x);
Shape The shape and dimensions of any object modeling :ref:`ImmutableCuboidArray` is obtained using get_shape and xxx_dim functions :
--------------------
* array, matrix and vector have a method shape() that returns a `shape_type` object .. compileblock::
i.e. a mini_vector<size_t,rank>. DOCUMENT THIS ?
* Example:: #include <triqs/arrays.hpp>
#include <iostream>
using namespace triqs::arrays;
int main () {
auto a = array<double,2> (2,3);
std::cout << get_shape(a)<< std::endl;
std::cout << first_dim(a)<< std::endl;
std::cout << second_dim(a)<< std::endl;
}
array<double,2> A(2,3);
A.shape()[0] == 2;
A.shape()[1] == 3;
Resize
--------
* The value classes array, matrix and vector can be resized.
* **Synopsis**:
.. cpp:function:: void resize(size_t, ..., size_t)
* **Examples** ::
array<double,2> A(2,3);
A.resize ( make_shape (5,5) )
matrix<double,2> M;
M.resize( 3,3);
vector<double> V;
V.resize(10);
* Views can not be resized.
resize_or_check_if_view
----------------------------
.. cpp:function:: void resize_or_check_if_view(ArrayType const & A, shape_t)
* If A is a value : resize A
* If A is a view : check that the shape if the shape_t and throw an exception if not.

22
doc/reference/c++/arrays/slicing.rst
View File

@ -11,15 +11,18 @@ Various kind of partial views and slices can be made on arrays and matrices.
* Partial views uses the ( ) operator, as the evaluation of the array:: * Partial views uses the ( ) operator, as the evaluation of the array::
array<T,2> A(10,10); // defines an array array<T,2> A(10,10); // defines an array
A ( 1, range(0,2) ) // 1d slice A(1, range(0,2) ) // 1d slice
A ( 1, range() ) // 1d slice taking all the second dim 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. A(range(0,10,2), range(0,10,2)) // a 2d slice viewing every each elements with even coordinates.
array_view<T,1> SL( A(0,range(0,3))); // naming the view array_view<T,1> SL = A(0,range(0,3)); // naming the view. No data copied here !
auto SL = A(0,range(0,3)); // C++0x with auto [check this] array_view<T,1> SL ( A(0,range(0,3))); // same thing !
auto SL = A(0,range(0,3)); // even simpler with C++11.
// CAREFUL : this is a weak view !!!! -> to be explained.
* **Return type** : * **Return type** :
@ -29,7 +32,10 @@ Various kind of partial views and slices can be made on arrays and matrices.
* BUT : (1d) slices of matrix or matrix_view return vector_view. * BUT : (1d) slices of matrix or matrix_view return vector_view.
* 0d slices of anything are converted to the `value_type` of the array. * 0d slices of anything are converted to the `value_type` of the array.
The `range` type Memory Weak view
^^^^^^^^^^^^^^^^^^^^^
The `range` type
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
`range` mimics the python `range`. It can be constructed with : `range` mimics the python `range`. It can be constructed with :
@ -87,7 +93,7 @@ The `ellipsis` type
template<typename ArrayType> template<typename ArrayType>
array<typename ArrayType::value_type, ArrayType::rank-1> sum0 (ArrayType const & A) { array<typename ArrayType::value_type, ArrayType::rank-1> sum0 (ArrayType const & A) {
array<typename ArrayType::value_type, ArrayType::rank-1> res = A(0,ellipsis()); array<typename ArrayType::value_type, ArrayType::rank-1> res = A(0,ellipsis());
for (size_t u =1; u< A.len(0); ++u) res += A(u,ellipsis()); for (size_t u =1; u< first_dim(A); ++u) res += A(u,ellipsis());
return res; return res;
} }

98
doc/reference/c++/arrays/vector.rst
View File

@ -1,98 +0,0 @@
.. highlight:: c
vector and vector_view
============================
vector and vector_view :
* are the class for a vector and the corresponding view.
* model the :ref:`HasImmutableArrayInterface` concept.
Template parameters
----------------------------
* The classes have two template parameters.
.. code-block:: c
template <typename ValueType, typename Opt = Option::Default> class vector_view;
template <typename ValueType, typename Opt = Option::Default> class vector;
============================ ================================== ========================== ====================================================================
Template parameter Accepted type Access in the class Meaning
============================ ================================== ========================== ====================================================================
ValueType normally a scalar, but any default value_type The type of the element of the vector
constructible type (?).
Opt Option::options< ...> opt_type Compile time options, see below.
============================ ================================== ========================== ====================================================================
Options template parameters are described :ref:`here <option_template>`.
The memory order is obviously useless here...
.. _vector_constructors:
Constructors
-----------------
Intentionally, vector and vector_view have only a few constructors :
========================================== ===========================================================================================
Constructors of vector Comments
========================================== ===========================================================================================
vector() - empty vector of size 0
vector(size_t) - from the dimension. Does **NOT** initialize the elements of the vector to 0 !
vector(const vector &) - copy construction
vector (PyObject * X) - Construct a new vector from the data of the Python object X.
NB : X is a borrowed reference, vector does affect its counting reference.
- it takes a **copy** of the data of X (or of numpy(X)) into C++.
- X is first transformed into a numpy by the python numpy lib itself
(as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type
(e.g. you construct an vector<double> from a numpy of int....).
vector(const T & X) - Type T models the :ref:`HasImmutableArrayInterface` concept.
- X must have the appropriate domain (checked at compile time).
- Constructs a new vector of domain X.domain() and fills it with evaluation of X.
========================================== ===========================================================================================
* Examples ::
vector<int> A(10,2);
A()=0; // init A to 0
.. warning::
The constructor from the dimensions does **NOT** initialize the vector to 0
(because it may not be optimal).
If needed, do it explicitely by `a()=0`;
Constructors of vector_views
----------------------------------------------
Automatic construction
^^^^^^^^^^^^^^^^^^^^^^^^^^^
vector_view are normally automatically constructed by making (partial) views, ref:`Slicing`, e.g. ::
tqa::vector<int> A(2,2);
A(range(),2) ; // --> this makes a view...
A() ; // --> this makes a view over the full array
Explicit construction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To explicitly make a view of an vector, use make_view ::
vector<int> A(2,2);
make_view(A) //-> a view...
make_view(A) = 13 ; // to assign e.g.
====================================================================== ===========================================================================================================
Constructors of vector_view Comments
====================================================================== ===========================================================================================================
vector_view(const array_view &) - Copy construction (shallow copy)
vector_view(const T & X) - `[Advanced]` T is any type such that X.indexmap() and X.storage() can be used to construct a view.
====================================================================== ===========================================================================================================

55
doc/reference/c++/arrays/view_or_not_view.rst
View File

@ -1,42 +1,65 @@
.. highlight:: c .. highlight:: c
A fundamental distinction : value classes vs view classes .. _view_vs_regular:
Regular type vs view type
================================================================= =================================================================
A fundamental distinction in TRIQS is the difference between the `value class` A fundamental distinction in TRIQS is the difference between the `regular type`
and the corresponding `view classes`. and the corresponding `view types`.
* The **value classes** : e.g. array, matrix, vector, ... have a `value semantic` : * The **regular types**
* They are default constructible. * Following the definition of A. Stepanov, a regular type is a *value*, much like an int, a double,
* When copied, assigned, they make deep copy. or a std::vector. Cf http://www.stepanovpapers.com/DeSt98.pdf (I added move semantics to the definition).
* They resize themselves under assignment if necessary (like e.g. std::vector).
In many respect, they behave like a std::vector for these matters. * It has `value semantics`, more precisely ::
* The **view classes** : e.g. array_view, matrix_view, vector_view, ... have a `reference semantic`. T a; // default constructible
T a = b; T a (b); // copy constructible
a = b; // assignment
a == b; a != b; // Equality.
* They are just partial or complete views of the corresponding value class. with the following properties ::
T a = b; assert(a==b);
T a; a=b; is equivalent to T a=b;
T a=c; T b=c; a=d; assert(b==c);
* When copied, assigned, it makes deep copy of the data and resizes itself if necessary (like e.g. std::vector).
* Examples :
* std::vector<T>
* triqs::arrays::array<T,R>, triqs::arrays::matrix<T>, triqs::arrays::vector<T>
* The **view types**
* They have a `reference semantics`.
* They are just partial or complete views of the corresponding regular type.
* They never make deep copy, either in copying, constructing, transforming to python, * They never make deep copy, either in copying, constructing, transforming to python,
* They can not be resized. * They can not be resized.
* They are useful to work on arrays, matrices, or on some part thereof, without making copies * They are useful to work on arrays, matrices, or on some part thereof, without making copies
(e.g. on a slice of an array, a column of a matrix). (e.g. on a slice of an array, a column of a matrix).
* Examples :
Each class is therefore provided in two flavors, and it is crucial for the user * triqs::arrays::array_view<T,R>, triqs::arrays::matrix_view, triqs::arrays::vector_view<T>
Many triqs containers (array, matrix, green functions)
is therefore provided in two flavors, and it is crucial for the user
to learn and understand their difference in order to use them appropriately. to learn and understand their difference in order to use them appropriately.
This distinction extends to more complex objects in TRIQS, such as Green functions.
Behaviour comparison table between regular and view types
Behaviour comparison table between value and view classes
------------------------------------------------------------ ------------------------------------------------------------
A detailed comparison of the behaviour of the two type of classes is provided in the following table. A detailed comparison of the behaviour of the two type of types is provided in the following table.
=================== ======================================================================= ====================================================================================== =================== ======================================================================= ======================================================================================
Topics value class (e.g. array, matrix, vector) view (e.g. array_view, matrix_view, vector_view) Topics regular type (e.g. array, matrix, vector) view type (e.g. array_view, matrix_view, vector_view)
=================== ======================================================================= ====================================================================================== =================== ======================================================================= ======================================================================================
Contructors - Constructors create a new fresh memory block. - Constructors only make another view of the data. Contructors - Constructors create a new fresh memory block. - Constructors only make another view of the data.
Default Contructor - Default constructor creates an empty array - No default constructor (what would it view ?). Default Contructor - Default constructor creates an empty array - No default constructor (what would it view ?).

66
doc/reference/c++/arrays/views.rst
View File

@ -1,66 +0,0 @@
.. highlight:: c
View classes and their constructors
==============================================================================
* A view class (array_view, matrix_view, vector_view) is used to present a
partial (or complete) view of an array, matrix, vector.
Basically it should be understood as a reference to the data of the viewed object,
dressed to model the :ref:`MutableArray` 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.
* There are two ways to make a view :
* explicit construction, by calling a constructor or the make_view function
* automatic construction : views are the results of slicing the array
* In the following, we will discuss only array_view, since matrix_view and vector_view
behaves exactly in a similar way.
Explicit construction of a 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 ....
====================================================================== =====================================================================================================
The function make_view can also be used to make a view.
Example ::
array<int,2> A(2,2);
array_view<int,2> V(A);
auto V2 = make_view(A);
struct view_keeper {
array_view<int,2> V;
Memory management
------------------------
View classes contains a reference counting system to the memory block they view
(i.e. a std::shared_ptr).
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<int,2> *p = new array<int,2> (2,3); // create an array p
array_view<int,2> B(*p); // making a view
delete p; // p is gone...
B(0,0) = 314; cout<<B<<endl; // B (and the data) is still alive
NB : This means that constructing a new view is cheap but still : document here the question of proxy ??

9
doc/reference/c++/contents.rst
View File

@ -1,4 +1,4 @@
Reference: C++ librairies C++ librairies
########################## ##########################
.. toctree:: .. toctree::
@ -6,11 +6,10 @@ Reference: C++ librairies
learn/intro learn/intro
arrays/contents arrays/contents
gf/contents
clef/contents
mctools/intro mctools/intro
det_manip/det_manip det_manip/det_manip
gf/contents
parameters/parameters parameters/parameters
gf/intro
clef/contents
lectures/contents lectures/contents
utilities/intro.rst utilities/contents

243
doc/reference/c++/gf/concepts.rst
View File

@ -1,35 +1,43 @@
.. highlight:: c .. highlight:: c
Green functions Concepts
################# #################
Here are the concepts and techniques related to the Green functions. A Green function is simply a function, which has :
All Green functions are implemented as a gf<Descriptor> and gf_view<Descriptor> where : * a `domain` for its variable(s) (e.g. Matsubara/real time/frequencies, Legendre coefficients).
* a `target` space, i.e. the value of the Green function which can be :
* Descriptor contains everything specific to the Green function * a scalar (double, complex)
(number of variables, domain of definition, interpolation techniques, etc...). * a matrix,
* another Green function (See below, currying Green functions ... REF ... ).
* The gf/gf_view class implements the generic part (hdf5, view mechanism, interaction with clef library, etc...). In this section, we define the general concepts for these objects.
We first present the concept of the Descriptor, and the concepts of its elements. First, we need to distinguish the `domain` on which the function is defined
In a second part, we present a more detailed description of gf/gf_view. from its representation in a computer, which we call a `mesh`.
Pure functions on domains .. note::
==============================
This formalize a mathematical function : "mesh" should be understood here in a general and abstract way,
as the representation of the domain in the computer.
In most cases, it is indeed a real mesh on a domain (e.g. a Brillouin zone),
but the set of Legendre coefficients is also a mesh in our sense.
* it has a domain of definition We will therefore now formally define the concept for `domain`, for `mesh`,
* it can be called on any point of the domain, as a *pure* function, i.e. without any side effect. the notion of `pure function on a domain` (i.e. a mathematical Green function)
and the notion of `function on a grid`.
Domain concept
.. _Concept_Domain:
Domain
------------------------------------------------- -------------------------------------------------
* **Purpose** : The domain of definition of a function. It is a mathematical definition of the domain, * **Purpose** : The domain of definition of a function. It is a mathematical definition of the domain,
and does not contain any mesh, or details on its representation in a computer. and does not contain any mesh, or details on its representation in a computer.
* **Refines** : CopyConstructible, DefaultContructible, EqualComparable, BoostSerializable, H5-serializable. * **Refines** : RegularType, BoostSerializable, H5-serializable.
* **Definition** : * **Definition** :
@ -43,17 +51,22 @@ Domain concept
* **Examples** : * **Examples** :
* Matsubara frequencies (boson/fermion) * Matsubara frequencies (boson/fermion)
* Matsubara time * Matsubara time
* Real frequencies * Real frequencies
* Real time * Real time
* Brillouin zone * Brillouin zone
* Cartesian product of previous domains to build multi-variable functions.
.. _Concept_PureFunctionOnDomain:
PureFunctionOnDomain PureFunctionOnDomain
----------------------- -----------------------
* **Purpose** : A function from a domain to a target space. * **Purpose** :
A mathematical (pure) function from a domain to a target space.
* it has a domain of definition
* it can be called on any point of the domain, as a *pure* function, i.e. without any side effect.
* **Refines** : * **Refines** :
@ -73,22 +86,20 @@ PureFunctionOnDomain
* NB : Note that the return type of the function is *NOT* part of the concept, * NB : Note that the return type of the function is *NOT* part of the concept,
it has to be deduced by the compiler (using C++11 decltype, std::result_of, eg..). it has to be deduced by the compiler (using C++11 decltype, std::result_of, eg..).
Functions stored on a mesh .. note::
================================ Probably domain_t should also be deduced from the return type of domain ... TO BE CORRECTED
A special kind of function is those stored on a mesh.
The mesh can be regular or not, multi-dimensionnal.
We first define the concept of a mesh, and then the concept of a function discretized over that mesh. .. _Concept_Mesh:
Mesh concept Mesh
------------------------------------------------- -------------------------------------------------
* **Purpose** : A mesh over a domain, and more generally the practical representation of the domain in a computer. * **Purpose** : A mesh over a domain, and more generally the practical representation of the domain in a computer.
It does not really need to be a mesh : e.g. if the function is represented on a polynomial basis, 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.) it is the parameters of this representation (max number of coordinates, e.g.)
* **Refines** : CopyConstructible, DefaultContructible, EqualComparable, BoostSerializable, H5-serializable. * **Refines** : RegularType, HasConstIterator BoostSerializable, H5-serializable.
* **Definition** : * **Definition** :
@ -107,38 +118,23 @@ Mesh concept
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
| size_t index_to_linear(index_t const &) const | Flattening the index of the mesh into a contiguous linear index | | size_t index_to_linear(index_t const &) const | Flattening the index of the mesh into a contiguous linear index |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
| mesh_point_t | See below | | mesh_point_t | A type modelling MeshPoint concept (see below). |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
| mesh_point_t operator[](index_t const & index ) const | From an index, return a mesh_point_t containing this a ref to this mesh and | | mesh_point_t operator[](index_t const & index ) const | From an index, return a mesh_point_t containing this a ref to this mesh and |
| | the index. | | | the index. |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
| free function | |
| foreach ( mesh_t, lambda) | ??????????????????????????????????? |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
| mesh_pt_generator<mesh_t> iterator | A generator of all the mesh points. | | mesh_pt_generator<mesh_t> iterator | A generator of all the mesh points. |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
| iterator begin()/end() const | Standard access to iterator on the mesh | | const_iterator begin()/end() const | Standard access to iterator on the mesh |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ | const_iterator cbegin()/cend() const | Standard access to iterator on the mesh |
| friend bool operator == (mesh_t const& M1, mesh_t const &M2) | Comparison between meshes |
+--------------------------------------------------------------+-------------------------------------------------------------------------------+ +--------------------------------------------------------------+-------------------------------------------------------------------------------+
.. _Concept_MeshPoint:
* **Examples** : Some domains and the corresponding possible meshes. MeshPoint
+-----------------------------------------------------+--------------------------------------------------------+
| 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
------------------------------------------------- -------------------------------------------------
* **Purpose** : Abstraction of a point on a mesh. A little more than a ref to the mesh and a index. * **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 | | void reset() | Reset the mesh point to the first point |
+------------------------------------------------+-----------------------------------------------------------------------------+ +------------------------------------------------+-----------------------------------------------------------------------------+
| cast_t | type of the corresponding domain point | | cast_t | == mesh_t::domain_t::point_t |
| operator cast_t() const | cast to the corresponding domain point | | operator cast_t() const | *implicit* cast to the corresponding domain point |
+------------------------------------------------+-----------------------------------------------------------------------------+
| Implements the basic operations on the domain | Only for non composite mesh |
| by using the cast operation | |
+------------------------------------------------+-----------------------------------------------------------------------------+ +------------------------------------------------+-----------------------------------------------------------------------------+
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. * **Discussion** :
The interest of having such a structure is that :
* The gf function has a operator()(mesh_t::mesh_point_t) (see below) which is a direct access to the data on the grid. A MeshPoint is just an index of a point on the mesh, and containers like gf can easily be overloaded for this type
Hence if MP is a such a MeshPoint, g(MP) is equivalent to something like g.data_on_grid_at_index( MP.index) 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 // example of g, a Green function in Matsubara frequencies w
for (auto w : g.mesh()) 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) // 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<double> // In this expression, w is casted to the domain_t::point_t, here a complex<double>
// which allows to evaluate the function // 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<mesh_t> const &) const | Calling on a grid_pt gives direct access to the value on a grid point. |
| auto & operator ( grid_pt<mesh_t> 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<std::string,arity> |
+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| 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<Descriptor> 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<triqs::gf::gf>` is available here.

38
doc/reference/c++/gf/contents.rst
View File

@ -1,40 +1,20 @@
.. _greenfunctions: .. _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. The TRIQS library provides a generic container `gf` and its view `gf_view`, to store and manipulate
various 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
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
intro
gf_and_view
concepts concepts
meshes meshes
the_four_basic_GFs tail
fourier fourier
cookbook/contents gf_misc
implementation_notes

59
doc/reference/c++/gf/cookbook/imaginary.rst
View File

@ -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 <triqs/gf/imfreq.hpp>
#include <triqs/arrays.hpp>
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<imfreq>(beta, stat, shape, n_freq);
};
An alternative declaration with an explicit construction of the underlying mesh:
.. compileblock::
#include <triqs/gf/imfreq.hpp>
using namespace triqs::gf;
int main(){
double beta=10;
int Nfreq =100;
auto fermionic_imfreq_mesh = make_gf_mesh<imfreq>(beta,triqs::gf::Fermion,Nfreq);
auto GF = make_gf<imfreq>(fermionic_imfreq_mesh, triqs::arrays::make_shape(1,1), local::tail(1,1));
}
Learn more in the full referencen, see :ref:`greenfunctions` Learn more in the full referencen, see :ref:`greenfunctions`
Create a Matsubara time Green function
--------------------------------------
.. compileblock::
#include <triqs/gf/imtime.hpp>
#include <triqs/arrays.hpp>
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<imtime>(beta, stat, shape, n_times);
};

27
doc/reference/c++/gf/cookbook/real.rst
View File

@ -1,34 +1,13 @@
Create a real time Green function
---------------------------------
.. compileblock::
#include <triqs/gf/retime.hpp>
#include <triqs/arrays.hpp>
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<triqs::gf::retime>
auto GF=make_gf<retime>(tmin, tmax, n_times, shape);
};
Create a real frequency Green function Create a real frequency Green function
-------------------------------------- --------------------------------------
.. compileblock:: .. compileblock::
#include <triqs/arrays.hpp> #include <triqs/arrays.hpp>
#include <triqs/gf/refreq.hpp> #include <triqs/gfs/refreq.hpp>
using triqs::gf::make_gf; using triqs::gfs::make_gf;
using triqs::gf::refreq; using triqs::gfs::refreq;
int main() { int main() {
double wmin=0; double wmin=0;

88
doc/reference/c++/gf/gf_and_view.rst Normal file
View File

@ -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<typename Variable, typename Target=matrix_valued, typename Opt=void> class gf; // the regular type
template<typename Variable, typename Target=matrix_valued, typename Opt=void> 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<gf_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<Gs...> Cartesian product of gf<Gs> ... 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<Variable, Target, Opt> ( ....) ;
This is the recommended way to construct `gf` objects.
Cf examples in various specializations.
Member types
-----------------
Member functions
---------------------
Non-member functions
------------------------

36
doc/reference/c++/gf/gf_block.rst Normal file
View File

@ -0,0 +1,36 @@
.. highlight:: c
.. _gf_block:
gf<block_index, G> or block_gf<G>
===================================================
This is a specialisation of :ref:`gf_and_view` for block functions.
Domain & mesh
----------------
Singularity
-------------
Factories
-------------
Interpolation method
---------------------
Data storage
---------------
HDF5 storage convention
---------------------------
Examples
---------

80
doc/reference/c++/gf/gf_imfreq.rst Normal file
View File

@ -0,0 +1,80 @@
.. highlight:: c
.. _gf_imfreq:
gf<imfreq, matrix_valued> & gf<imfreq, scalar_valued>
==========================================================
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<imfreq,Opt> 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<double>.
* 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 <triqs/gfs/imfreq.hpp>
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<imfreq>(beta, Fermion, make_shape(1,1), n_freq);
};
An alternative declaration with an explicit construction of the underlying mesh:
.. compileblock::
#include <triqs/gfs/imfreq.hpp>
using namespace triqs::gfs;
int main(){
double beta=10;
int Nfreq =100;
auto GF = make_gf<imfreq>(mesh<imfreq>{beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1));
// or even simpler
auto GF2 = make_gf<imfreq>({beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1));
}

57
doc/reference/c++/gf/gf_imtime.rst Normal file
View File

@ -0,0 +1,57 @@
.. highlight:: c
.. _gf_imtime:
gf<imtime>
===================================================
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<size_t,2> shape, local::tail_view const & t)
make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax=1025, mesh_kind mk= half_bins)
make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax, mesh_kind mk, local::tail_view const & t)
Interpolation method
---------------------
Data storage
---------------
HDF5 storage convention
---------------------------
Examples
---------
.. compileblock::
#include <triqs/gfs/imtime.hpp>
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<imtime>(beta, stat, shape, n_times);
};

16
doc/reference/c++/gf/gf_misc.rst Normal file
View File

@ -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};

36
doc/reference/c++/gf/gf_prod.rst Normal file
View File

@ -0,0 +1,36 @@
.. highlight:: c
.. _gf_prod:
gf<cartesian_product<M...>, 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
---------

60
doc/reference/c++/gf/gf_refreq.rst Normal file
View File

@ -0,0 +1,60 @@
.. highlight:: c
.. _gf_refreq:
gf<refreq>
===================================================
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<size_t,2> shape, local::tail_view const & t)
make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector<size_t,2> shape)
make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector<size_t,2> shape, mesh_kind mk)
Interpolation method
---------------------
Data storage
---------------
HDF5 storage convention
---------------------------
Examples
---------
.. compileblock::
#include <triqs/gfs/retime.hpp>
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<triqs::gfs::retime>
auto GF=make_gf<retime>(tmin, tmax, n_times, shape);
};

57
doc/reference/c++/gf/gf_retime.rst Normal file
View File

@ -0,0 +1,57 @@
.. highlight:: c
.. _gf_retime:
gf<retime>
===================================================
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<size_t,2> shape)
make_gf(double tmin, double tmax, size_t n_points, tqa::mini_vector<size_t,2> shape, mesh_kind mk)
Interpolation method
---------------------
Data storage
---------------
HDF5 storage convention
---------------------------
Examples
---------
.. compileblock::
#include <triqs/gfs/refreq.hpp>
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<refreq>(wmin, wmax, n_freq, shape);
};

75
doc/reference/c++/gf/implementation_notes.rst Normal file
View File

@ -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<mesh_t> 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<triqs::gf::gf>` 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<std::string,arity> |
+------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
| 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).

43
doc/reference/c++/gf/intro.rst Normal file
View File

@ -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.

16
doc/reference/c++/gf/meshes.rst
View File

@ -30,8 +30,8 @@ How to access to a mesh point with its index
.. compileblock:: .. compileblock::
#include <triqs/gf/refreq.hpp> #include <triqs/gfs/refreq.hpp>
using namespace triqs::gf; using namespace triqs::gfs;
int main() { int main() {
@ -59,8 +59,8 @@ In this case, we look for the closest mesh point, but can need the distance of t
.. compileblock:: .. compileblock::
#include <triqs/gf/refreq.hpp> #include <triqs/gfs/refreq.hpp>
using namespace triqs::gf; using namespace triqs::gfs;
int main() { int main() {
double wmin = 0.0; double wmin = 0.0;
@ -132,8 +132,8 @@ How to access to the closest mesh point
.. compileblock:: .. compileblock::
#include <triqs/gf/two_real_times.hpp> #include <triqs/gfs/two_real_times.hpp>
using namespace triqs::gf; using namespace triqs::gfs;
int main() { int main() {
double tmax = 1.0; double tmax = 1.0;
@ -152,8 +152,8 @@ How to access to a mesh point with its index
.. compileblock:: .. compileblock::
#include <triqs/gf/two_real_times.hpp> #include <triqs/gfs/two_real_times.hpp>
using namespace triqs::gf; using namespace triqs::gfs;
int main() { int main() {
double tmax = 1.0; double tmax = 1.0;

46
doc/reference/c++/gf/plan.rst Normal file
View File

@ -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.

7
doc/reference/c++/gf/tail.rst Normal file
View File

@ -0,0 +1,7 @@
.. highlight:: c
.. _gf_tail:
High frequency tail
===========================

46
doc/reference/c++/gf/the_four_basic_GFs.rst
View File

@ -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<size_t,2> shape)``
``make_gf(double tmin, double tmax, size_t n_points, tqa::mini_vector<size_t,2> shape, mesh_kind mk)``
Real frequency
---------------
``make_gf(MeshType && m, tqa::mini_vector<size_t,2> shape, local::tail_view const & t)``
``make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector<size_t,2> shape)``
``make_gf(double wmin, double wmax, size_t n_freq, tqa::mini_vector<size_t,2> shape, mesh_kind mk)``
Matsubara time
---------------
``make_gf(MeshType && m, tqa::mini_vector<size_t,2> shape, local::tail_view const & t)``
``make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax=1025, mesh_kind mk= half_bins)``
``make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax, mesh_kind mk, local::tail_view const & t)``
Matsubara frequency
--------------------
``make_gf(MeshType && m, tqa::mini_vector<size_t,2> shape, local::tail_view const & t)``
``make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape)``
``make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax)``
``make_gf(double beta, statistic_enum S, tqa::mini_vector<size_t,2> shape, size_t Nmax, local::tail_view const & t)``

14
doc/reference/c++/utilities/contents.rst Normal file
View File

@ -0,0 +1,14 @@
Utilities
*******************************************
.. highlight:: c
.. toctree::
:maxdepth: 1
:numbered:
factory
tupletools
mini_vector
python_include_mess

28
doc/reference/c++/utilities/python_include_mess.rst Normal file
View File

@ -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 <utility/first_include.hpp>
that conditionally includes python if python is to be supported.
(used by all triqs libs, hence the first point).

77
doc/reference/c++/utilities/tupletools.rst Normal file
View File

@ -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<typename Function, typename Tuple> auto apply (Function && f, Tuple const & t);
*Solution* :
.. compileblock::
#include <triqs/utility/tuple_tools.hpp>
#include <iostream>
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<typename Function, typename Tuple> void for_each(Tuple const & t, Function && f);
*Solution* :
.. compileblock::
#include <triqs/utility/tuple_tools.hpp>
#include <iostream>
struct print_t { template<typename T> 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<<x<<" ";});
}

2
doc/reference/python/contents.rst
View File

@ -5,7 +5,7 @@
.. _contents: .. _contents:
Reference: Python libraries Python libraries
================================ ================================
.. toctree:: .. toctree::

5
test/triqs/arrays/diagonal_matrix.cpp
View File

@ -54,6 +54,11 @@ int main(int argc, char **argv) {
std::cout << d<< std::endl; std::cout << d<< std::endl;
std::cout << matrix<int>( 2* d) << std::endl; std::cout << matrix<int>( 2* d) << std::endl;
std::cout << matrix<int>( d * d) << std::endl; std::cout << matrix<int>( 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; return 0;
} }