mirror of
https://github.com/triqs/dft_tools
synced 2024-12-24 13:23:37 +01:00
work on doc
This commit is contained in:
parent
165b44a081
commit
0f524b26fc
@ -4,7 +4,7 @@ Table of contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
installation/install
|
||||
|
@ -1,11 +0,0 @@
|
||||
Concepts, implementation, design ...
|
||||
***************************************
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:numbered:
|
||||
|
||||
concepts
|
||||
|
@ -76,3 +76,21 @@ Put here the array_cython example
|
||||
_testarray.f(a)
|
||||
|
||||
|
||||
Memory management
|
||||
-----------------
|
||||
|
||||
TO BE WRITTEN
|
||||
|
||||
The reference counting system is *compatible* with the Python reference counting (but distinct),
|
||||
if you compile with python support of course.
|
||||
|
||||
As long as you write pure C++ code, you are basically using a shared_ptr to your data block.
|
||||
No python is involved.
|
||||
|
||||
But, if you return your view into a numpy array in python, ownership of your data
|
||||
is automatically transfered to the python interpreter::
|
||||
|
||||
The interpreter then take the responsability of destroying the data when needed (meaning here, long after f has returned,
|
||||
when the python object returned will be cleaned).
|
||||
|
||||
|
||||
|
@ -1,2 +0,0 @@
|
||||
.. highlight:: c
|
||||
|
@ -6,7 +6,7 @@ Operations : array and matrix/vector algebras
|
||||
Operations
|
||||
------------
|
||||
|
||||
Arrays and matrices can be combined in formal algebraic expressions, which models the :ref:`HasImmutableArrayInterface` concept.
|
||||
Arrays and matrices can be combined in formal algebraic expressions, which models the :ref:`ImmutableCuboidArray` concept.
|
||||
This algebraic expressions can therefore be used as RHS of assignment (SEE) or in array/matrix contructors.
|
||||
For example ;
|
||||
|
||||
@ -71,7 +71,7 @@ Indeed, the operations are implemented with the `expression templates` technique
|
||||
The principle is that the result of A+B is **NOT** an array, but a more complex type which stores
|
||||
the expression using the naturally recursive structure of templates.
|
||||
|
||||
Expressions models :ref:`HasImmutableArrayInterface` concept.
|
||||
Expressions models :ref:`ImmutableCuboidArray` concept.
|
||||
They behave like an immutable array : they have a domain, they can be evaluated.
|
||||
Hence they can used *anywhere* an object modeling this concept is accepted, e.g. :
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
====================================================================== =====================================================================================================
|
||||
|
||||
|
@ -13,7 +13,7 @@ We will illustrate it on the `array` class, it is the same for `matrix` and `vec
|
||||
|
||||
* **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,
|
||||
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
|
||||
================= ======================================================================= ======================================================================================
|
||||
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.].
|
||||
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.
|
||||
@ -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.
|
||||
- computing the value if X is an expression.
|
||||
|
||||
* **Optimisation** `[advanced]`
|
||||
Compound operators (+=, -=, * =, /=)
|
||||
-------------------------------------------------
|
||||
|
||||
* **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);
|
||||
|
||||
* **What can be RHS ?**
|
||||
|
||||
Same as for = operator.
|
||||
|
||||
* **Behaviour**
|
||||
|
||||
Similar to for = operator, with obvious changes.
|
||||
|
||||
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...
|
||||
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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;
|
||||
|
||||
|
@ -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
|
@ -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;
|
||||
|
||||
|
||||
|
@ -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
203
doc/reference/c++/arrays/concepts.rst
Normal 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...
|
||||
|
||||
|
||||
|
||||
|
137
doc/reference/c++/arrays/containers/call.rst
Normal file
137
doc/reference/c++/arrays/containers/call.rst
Normal 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
76
doc/reference/c++/arrays/containers/range_ell.rst
Normal 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;
|
||||
}
|
||||
|
||||
|
@ -1,16 +1,12 @@
|
||||
.. highlight:: c
|
||||
|
||||
Compound assignment operators : +=, -=, *=, /=
|
||||
=============================================================
|
||||
.. _arr_reg_assign:
|
||||
|
||||
The `value classes` and the `view classes` have a quite general assignment operator (=),
|
||||
and corresponding compound operators (+=, -=).
|
||||
We will illustrate it on the `array` class, it is the same for `matrix` and `vector`.
|
||||
|
||||
Assignment operator (=)
|
||||
-------------------------------------------------
|
||||
Assignment
|
||||
=========================
|
||||
|
||||
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::
|
||||
|
||||
@ -19,7 +15,7 @@ The `value classes` and the `view classes` have a quite general assignment opera
|
||||
|
||||
* **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,
|
||||
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
|
||||
================= ======================================================================= ======================================================================================
|
||||
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.].
|
||||
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.
|
||||
@ -40,41 +36,10 @@ The `value classes` and the `view classes` have a quite general assignment opera
|
||||
- a copy if X is an array.
|
||||
- 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 (+=, -=, * =, /=)
|
||||
-------------------------------------------------
|
||||
|
||||
|
||||
* **Syntax**
|
||||
* **Syntax**
|
||||
|
||||
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);
|
||||
|
||||
* **Behaviour**
|
||||
* **What can be RHS ?**
|
||||
|
||||
- Domain must match.
|
||||
- X is evaluated and added term by term.
|
||||
Same as for = operator.
|
||||
|
||||
To be written : special operators.
|
||||
* **Behaviour**
|
||||
|
||||
Similar to for = operator, with obvious changes.
|
||||
|
||||
|
@ -1,16 +1,19 @@
|
||||
|
||||
.. 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.
|
||||
We will therefore describe only for the array, and mention the difference for matrix and vector below.
|
||||
|
||||
* As mentioned earlier, they are *values*,
|
||||
so all these constructors make a **copy** of the data, except of course the move constructor.
|
||||
|
||||
Constructors of array
|
||||
---------------------------
|
||||
* array, matrix, vector are regular types (with value semantics).
|
||||
Hence, all these constructors make a **copy** of the data, except of course the move constructor.
|
||||
|
||||
========================================== ===========================================================================================
|
||||
Constructors of array Comments
|
||||
@ -18,66 +21,63 @@ Constructors of array
|
||||
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).
|
||||
Does **NOT** initialize the array elements to 0 ! (see compile time option)
|
||||
------------------------------------------ -------------------------------------------------------------------------------------------
|
||||
array(const array &) Copy 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).
|
||||
- Constructs a new array of domain X.domain() and fills it with evaluation of X.
|
||||
- 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.
|
||||
------------------------------------------ -------------------------------------------------------------------------------------------
|
||||
array(shape_t const &) New array with the corresponding shape (as returned by the function shape. See example
|
||||
in section XXX).
|
||||
------------------------------------------ -------------------------------------------------------------------------------------------
|
||||
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.
|
||||
- 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.
|
||||
.. note:: X is a borrowed reference, array does not affect its counting reference.
|
||||
========================================== ===========================================================================================
|
||||
|
||||
.. warning::
|
||||
The constructor from the dimensions does **NOT** initialize the array to 0
|
||||
(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
|
||||
---------------------------
|
||||
|
||||
* matrix have similar 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(matrix &&) move construction
|
||||
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 Comments
|
||||
========================================== ===========================================================================================
|
||||
========================================== =======================================================================================================
|
||||
vector() empty vector of size 0
|
||||
vector(size_t) from the dimensions. Does NOT initialize the elements of vector to 0 !
|
||||
vector(const vector &) copy construction
|
||||
vector(vector &&) move construction
|
||||
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
|
||||
------------
|
||||
@ -115,3 +115,4 @@ Examples
|
||||
array<long, 3, 0, permutation(1,0,2)> A2(2,3,4);
|
||||
}
|
||||
|
||||
|
146
doc/reference/c++/arrays/containers/regular.rst
Normal file
146
doc/reference/c++/arrays/containers/regular.rst
Normal 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
71
doc/reference/c++/arrays/containers/resize.rst
Normal 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.
|
@ -1,23 +1,25 @@
|
||||
|
||||
.. _Move:
|
||||
|
||||
Move and swap
|
||||
swap & deep_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,
|
||||
it does not affect the data them self.
|
||||
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** :
|
||||
|
||||
.. compileblock::
|
||||
@ -38,9 +40,16 @@ Swap
|
||||
std::cout << "V = "<< V << " W = " << W<< " V view "<< VV<< " W view "<< VW<< std::endl;
|
||||
}
|
||||
|
||||
.. _arr_deep_swap:
|
||||
|
||||
deep_swap
|
||||
--------------
|
||||
|
||||
.. warning::
|
||||
|
||||
Currently implemented only for triqs::vector and triqs::vector_view.
|
||||
|
||||
|
||||
* deep_swap swaps the data in memory.
|
||||
|
||||
* **Example** (compare with swap) :
|
105
doc/reference/c++/arrays/containers/views.rst
Normal file
105
doc/reference/c++/arrays/containers/views.rst
Normal 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 :
|
||||
|
||||
|
||||
|
||||
|
@ -1,4 +1,4 @@
|
||||
Array library
|
||||
Multidimensional arrays
|
||||
*******************************************
|
||||
|
||||
.. highlight:: c
|
||||
@ -7,30 +7,26 @@ Array library
|
||||
:maxdepth: 1
|
||||
:numbered:
|
||||
|
||||
cookbook
|
||||
introduction.rst
|
||||
view_or_not_view
|
||||
basic_classes
|
||||
construct
|
||||
views
|
||||
move_swap
|
||||
introduction
|
||||
concepts
|
||||
containers/regular
|
||||
containers/views
|
||||
shape
|
||||
element_acces
|
||||
slicing
|
||||
view_or_not_view
|
||||
lazy
|
||||
call
|
||||
debug
|
||||
assignment
|
||||
algebras
|
||||
blas_lapack
|
||||
foreach
|
||||
map
|
||||
mapped_fnt
|
||||
algebras
|
||||
move_swap
|
||||
blas_lapack
|
||||
H5
|
||||
Interop_Python
|
||||
IO
|
||||
foreach
|
||||
STL
|
||||
map
|
||||
group_indices
|
||||
debug
|
||||
multithreading
|
||||
FAQ
|
||||
Design/contents.rst
|
||||
|
||||
implementation_notes/contents
|
||||
|
||||
|
@ -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
|
||||
|
@ -141,8 +141,7 @@ Linear algebra
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/arrays.hpp>
|
||||
#include <triqs/arrays/linalg/inverse.hpp>
|
||||
#include <triqs/arrays/linalg/determinant.hpp>
|
||||
#include <triqs/arrays/linalg/det_and_inverse.hpp>
|
||||
|
||||
using triqs::arrays::array; using triqs::arrays::matrix; using triqs::clef::placeholder;
|
||||
int main(){
|
||||
|
@ -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;
|
||||
}
|
||||
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
||||
|
||||
|
@ -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,7 +2,7 @@
|
||||
|
||||
.. _Foreach:
|
||||
|
||||
The foreach construct
|
||||
Loops : the foreach constructs
|
||||
========================================================
|
||||
|
||||
foreach and its variants are a compact and efficient way to
|
||||
|
@ -3,6 +3,10 @@
|
||||
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.
|
||||
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
|
||||
|
12
doc/reference/c++/arrays/implementation_notes/assignment.rst
Normal file
12
doc/reference/c++/arrays/implementation_notes/assignment.rst
Normal file
@ -0,0 +1,12 @@
|
||||
|
||||
.. _impl_assign:
|
||||
|
||||
operator =
|
||||
=============================================================
|
||||
|
||||
Using delegation.
|
||||
Various cases...
|
||||
|
||||
|
||||
|
||||
|
@ -1,4 +1,6 @@
|
||||
|
||||
.. _impl_concepts:
|
||||
|
||||
Concepts
|
||||
=============================================================
|
||||
|
27
doc/reference/c++/arrays/implementation_notes/contents.rst
Normal file
27
doc/reference/c++/arrays/implementation_notes/contents.rst
Normal 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,0 +1,16 @@
|
||||
|
||||
.. _impl_expr_templ:
|
||||
|
||||
Expression template
|
||||
=============================================================
|
||||
|
||||
Principle. Link to lecture ?
|
||||
|
||||
array vs matrix/vector algebra.
|
||||
Use tag to detect.
|
||||
Use concept
|
||||
|
||||
|
||||
|
||||
|
||||
|
@ -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
10
doc/reference/c++/arrays/implementation_notes/hdf5.rst
Normal 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
21
doc/reference/c++/arrays/implementation_notes/indexmaps.rst
Normal 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
13
doc/reference/c++/arrays/implementation_notes/isp.rst
Normal 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
16
doc/reference/c++/arrays/implementation_notes/linalg.rst
Normal 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
11
doc/reference/c++/arrays/implementation_notes/python.rst
Normal file
@ -0,0 +1,11 @@
|
||||
.. _impl_python:
|
||||
|
||||
Interface to python
|
||||
=============================================================
|
||||
|
||||
Files :
|
||||
|
||||
Low level : memory guarantee
|
||||
|
||||
High level : 2 functions for going back and forth.
|
||||
|
@ -0,0 +1,14 @@
|
||||
.. _impl_reinterpretation:
|
||||
|
||||
Reinterpretation
|
||||
=============================================================
|
||||
|
||||
Basic reinterpretation
|
||||
-------------------------
|
||||
|
||||
Grouping indices
|
||||
----------------------
|
||||
|
||||
|
||||
|
||||
|
20
doc/reference/c++/arrays/implementation_notes/storage.rst
Normal file
20
doc/reference/c++/arrays/implementation_notes/storage.rst
Normal 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,0 +1,12 @@
|
||||
|
||||
.. _impl_userclasses:
|
||||
|
||||
User classes : array, matrix, vector
|
||||
=============================================================
|
||||
|
||||
* view and not
|
||||
* move semantic pb of views.
|
||||
* special functions...
|
||||
|
||||
|
||||
|
@ -7,16 +7,17 @@ Rational
|
||||
This library provides a multi-dimensionnal array library
|
||||
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.
|
||||
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.
|
||||
|
||||
* **Genericity, abstraction and performance** :
|
||||
|
||||
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.
|
||||
(Some) LAPACK and BLAS operations are interfaced.
|
||||
|
||||
* **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.
|
||||
|
||||
* **Simple interface to (some) blas/lapack** for matrices, vectors.
|
||||
|
||||
* **MPI** : compatibility with boost::mpi interface.
|
||||
|
||||
|
||||
|
@ -10,6 +10,8 @@ Two standard functional constructs are provided :
|
||||
|
||||
* *fold* is the reduction of a function on the array.
|
||||
|
||||
.. _map:
|
||||
|
||||
map
|
||||
========================================================
|
||||
* **Purpose** :
|
||||
@ -28,11 +30,11 @@ map
|
||||
|
||||
ReturnType map(f) ( ArrayType const & A)
|
||||
|
||||
where ArrayType models the :ref:`HasImmutableArrayInterface` concept
|
||||
where ArrayType models the :ref:`ImmutableCuboidArray` concept
|
||||
|
||||
* 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 value_type == ValueType2
|
||||
@ -89,7 +91,7 @@ fold
|
||||
|
||||
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, ...)
|
||||
|
||||
* A::value_type is T
|
||||
@ -126,3 +128,7 @@ fold
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
@ -5,25 +5,17 @@
|
||||
Simple functions on arrays
|
||||
==================================
|
||||
|
||||
The following functions are mapped
|
||||
The following functions are mapped on the array (using :ref:`map`):
|
||||
|
||||
* abs
|
||||
* real
|
||||
* imag
|
||||
* pow
|
||||
* cos
|
||||
* sin
|
||||
* tan
|
||||
* cosh
|
||||
* sinh
|
||||
* tanh
|
||||
* acos
|
||||
* asin
|
||||
* atan
|
||||
* exp
|
||||
* log
|
||||
* sqrt
|
||||
* floor
|
||||
`abs real imag pow cos sin tan cosh sinh tanh acos asin atan exp log sqrt floor`
|
||||
|
||||
meaning that e.g. if `A` is an array,
|
||||
real(A) models :ref:`ImmutableCuboidArray`, with the same size and returns the real part of the elements.
|
||||
In other words, it applies the function term-by-term.
|
||||
|
||||
.. note::
|
||||
|
||||
These functions do NOT compute a new array in memory, they are lazy.
|
||||
|
||||
Example :
|
||||
|
||||
|
@ -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.
|
||||
====================================================================== ===========================================================================================================
|
||||
|
||||
|
@ -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
12
doc/reference/c++/arrays/multithreading.rst
Normal 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 !
|
||||
|
||||
|
@ -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);
|
||||
|
||||
|
||||
|
@ -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
|
||||
};
|
||||
}
|
||||
|
||||
|
@ -1,50 +1,36 @@
|
||||
.. _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
|
||||
i.e. a mini_vector<size_t,rank>. DOCUMENT THIS ?
|
||||
.. compileblock::
|
||||
|
||||
#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;
|
||||
}
|
||||
|
||||
* Example::
|
||||
|
||||
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.
|
||||
|
@ -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::
|
||||
|
||||
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() ) // 1d slice taking all the second dim
|
||||
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.
|
||||
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
|
||||
auto SL = A(0,range(0,3)); // C++0x with auto [check this]
|
||||
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 !
|
||||
|
||||
auto SL = A(0,range(0,3)); // even simpler with C++11.
|
||||
// CAREFUL : this is a weak view !!!! -> to be explained.
|
||||
|
||||
* **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.
|
||||
* 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 :
|
||||
@ -87,7 +93,7 @@ The `ellipsis` type
|
||||
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< A.len(0); ++u) res += A(u,ellipsis());
|
||||
for (size_t u =1; u< first_dim(A); ++u) res += A(u,ellipsis());
|
||||
return res;
|
||||
}
|
||||
|
||||
|
@ -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.
|
||||
====================================================================== ===========================================================================================================
|
||||
|
||||
|
@ -1,42 +1,65 @@
|
||||
.. 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`
|
||||
and the corresponding `view classes`.
|
||||
A fundamental distinction in TRIQS is the difference between the `regular type`
|
||||
and the corresponding `view types`.
|
||||
|
||||
* The **value classes** : e.g. array, matrix, vector, ... have a `value semantic` :
|
||||
* The **regular types**
|
||||
|
||||
* Following the definition of A. Stepanov, a regular type is a *value*, much like an int, a double,
|
||||
or a std::vector. Cf http://www.stepanovpapers.com/DeSt98.pdf (I added move semantics to the definition).
|
||||
|
||||
* They are default constructible.
|
||||
* When copied, assigned, they make deep copy.
|
||||
* They resize themselves under assignment if necessary (like e.g. std::vector).
|
||||
* It has `value semantics`, more precisely ::
|
||||
|
||||
In many respect, they behave like a std::vector for these matters.
|
||||
T a; // default constructible
|
||||
T a = b; T a (b); // copy constructible
|
||||
a = b; // assignment
|
||||
a == b; a != b; // Equality.
|
||||
|
||||
* The **view classes** : e.g. array_view, matrix_view, vector_view, ... have a `reference semantic`.
|
||||
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 value class.
|
||||
* 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 can not be resized.
|
||||
* 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).
|
||||
|
||||
* Examples :
|
||||
|
||||
* triqs::arrays::array_view<T,R>, triqs::arrays::matrix_view, triqs::arrays::vector_view<T>
|
||||
|
||||
Each class is therefore provided in two flavors, and it is crucial for the user
|
||||
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.
|
||||
|
||||
This distinction extends to more complex objects in TRIQS, such as Green functions.
|
||||
|
||||
|
||||
Behaviour comparison table between value and view classes
|
||||
Behaviour comparison table between regular and view types
|
||||
------------------------------------------------------------
|
||||
|
||||
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.
|
||||
Default Contructor - Default constructor creates an empty array - No default constructor (what would it view ?).
|
||||
|
@ -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 ??
|
||||
|
||||
|
@ -1,4 +1,4 @@
|
||||
Reference: C++ librairies
|
||||
C++ librairies
|
||||
##########################
|
||||
|
||||
.. toctree::
|
||||
@ -6,11 +6,10 @@ Reference: C++ librairies
|
||||
|
||||
learn/intro
|
||||
arrays/contents
|
||||
gf/contents
|
||||
clef/contents
|
||||
mctools/intro
|
||||
det_manip/det_manip
|
||||
gf/contents
|
||||
parameters/parameters
|
||||
gf/intro
|
||||
clef/contents
|
||||
lectures/contents
|
||||
utilities/intro.rst
|
||||
utilities/contents
|
||||
|
@ -1,35 +1,43 @@
|
||||
.. 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 :
|
||||
|
||||
* a scalar (double, complex)
|
||||
* a matrix,
|
||||
* another Green function (See below, currying Green functions ... REF ... ).
|
||||
|
||||
In this section, we define the general concepts for these objects.
|
||||
|
||||
* Descriptor contains everything specific to the Green function
|
||||
(number of variables, domain of definition, interpolation techniques, etc...).
|
||||
First, we need to distinguish the `domain` on which the function is defined
|
||||
from its representation in a computer, which we call a `mesh`.
|
||||
|
||||
* The gf/gf_view class implements the generic part (hdf5, view mechanism, interaction with clef library, etc...).
|
||||
.. note::
|
||||
|
||||
"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.
|
||||
|
||||
We first present the concept of the Descriptor, and the concepts of its elements.
|
||||
In a second part, we present a more detailed description of gf/gf_view.
|
||||
We will therefore now formally define the concept for `domain`, for `mesh`,
|
||||
the notion of `pure function on a domain` (i.e. a mathematical Green function)
|
||||
and the notion of `function on a grid`.
|
||||
|
||||
Pure functions on domains
|
||||
==============================
|
||||
|
||||
This formalize a mathematical function :
|
||||
.. _Concept_Domain:
|
||||
|
||||
* 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.
|
||||
|
||||
Domain concept
|
||||
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.
|
||||
|
||||
* **Refines** : CopyConstructible, DefaultContructible, EqualComparable, BoostSerializable, H5-serializable.
|
||||
* **Refines** : RegularType, BoostSerializable, H5-serializable.
|
||||
|
||||
* **Definition** :
|
||||
|
||||
@ -43,17 +51,22 @@ Domain concept
|
||||
|
||||
* **Examples** :
|
||||
|
||||
* Matsubara frequencies (boson/fermion)
|
||||
* Matsubara time
|
||||
* Real frequencies
|
||||
* Real time
|
||||
* Brillouin zone
|
||||
* Matsubara frequencies (boson/fermion)
|
||||
* Matsubara time
|
||||
* Real frequencies
|
||||
* Real time
|
||||
* Brillouin zone
|
||||
* Cartesian product of previous domains to build multi-variable functions.
|
||||
|
||||
.. _Concept_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** :
|
||||
|
||||
@ -73,22 +86,20 @@ PureFunctionOnDomain
|
||||
* 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..).
|
||||
|
||||
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.
|
||||
It does not really need to be a mesh : e.g. if the function is represented on a polynomial basis,
|
||||
it is the parameters of this representation (max number of coordinates, e.g.)
|
||||
|
||||
* **Refines** : CopyConstructible, DefaultContructible, EqualComparable, BoostSerializable, H5-serializable.
|
||||
* **Refines** : RegularType, HasConstIterator BoostSerializable, H5-serializable.
|
||||
|
||||
* **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 |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
| 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 |
|
||||
| | the index. |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
| free function | |
|
||||
| foreach ( mesh_t, lambda) | ??????????????????????????????????? |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
| mesh_pt_generator<mesh_t> iterator | A generator of all the mesh points. |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
| iterator begin()/end() const | Standard access to iterator on the mesh |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
| friend bool operator == (mesh_t const& M1, mesh_t const &M2) | Comparison between meshes |
|
||||
| const_iterator begin()/end() const | Standard access to iterator on the mesh |
|
||||
| const_iterator cbegin()/cend() const | Standard access to iterator on the mesh |
|
||||
+--------------------------------------------------------------+-------------------------------------------------------------------------------+
|
||||
|
||||
.. _Concept_MeshPoint:
|
||||
|
||||
* **Examples** : Some domains and the corresponding possible meshes.
|
||||
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
| Domain Type | What does the corresponding mesh type contain ? |
|
||||
+=====================================================+========================================================+
|
||||
| Matsubara frequencies | Nmax, the max number of Matsubara Freq. |
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
| Matsubara time | The time slicing is on a mesh, or the Legendre mesh is |
|
||||
| | we store the function with Legendre representation. |
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
| Real frequencies | Parameters of the mesh in frequency |
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
| Real time | |
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
| Brillouin zone | parameters of the mesh over the BZ, symmetry ? |
|
||||
+-----------------------------------------------------+--------------------------------------------------------+
|
||||
|
||||
|
||||
MeshPoint concept
|
||||
MeshPoint
|
||||
-------------------------------------------------
|
||||
|
||||
* **Purpose** : Abstraction of a point on a mesh. A little more than a ref to the mesh and a index.
|
||||
@ -168,148 +164,33 @@ MeshPoint concept
|
||||
+------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
| void reset() | Reset the mesh point to the first point |
|
||||
+------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
| cast_t | type of the corresponding domain point |
|
||||
| operator cast_t() const | cast to the corresponding domain point |
|
||||
+------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
| Implements the basic operations on the domain | Only for non composite mesh |
|
||||
| by using the cast operation | |
|
||||
| cast_t | == mesh_t::domain_t::point_t |
|
||||
| operator cast_t() const | *implicit* cast to the corresponding domain point |
|
||||
+------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
|
||||
The MeshPoint mechanism
|
||||
---------------------------
|
||||
For one dimensional mesh, we also require that the MeshPoint implement the basic arithmetic operations
|
||||
using the cast.
|
||||
|
||||
A MeshPoint is just a storage of a reference to the mesh and the index of the point in a custom structure.
|
||||
The interest of having such a structure is that :
|
||||
* **Discussion** :
|
||||
|
||||
* The gf function has a operator()(mesh_t::mesh_point_t) (see below) which is a direct access to the data on the grid.
|
||||
Hence if MP is a such a MeshPoint, g(MP) is equivalent to something like g.data_on_grid_at_index( MP.index)
|
||||
A MeshPoint is just an index of a point on the mesh, and containers like gf can easily be overloaded for this type
|
||||
to have a direct access to the grid (Cf [] operator of gf).
|
||||
|
||||
* MP however can be casted to a point in the domain and therefore it *is* a domain_t::point_t as well.
|
||||
However, since the MeshPoint can be implicitely casted into the domain point, simple
|
||||
expression like ::
|
||||
|
||||
As a result, g(MP) = 1/(MP + 2) makes senses iif it makes senses in the domain.
|
||||
g[p] = 1/ (p +2)
|
||||
|
||||
* Moreover, because of the iterator on the mesh, one can write ::
|
||||
make sense and fill the corresponding point wiht the evaluation of 1/ (p+2) in the domain.
|
||||
|
||||
As a result, because iterating on a mesh result in a series of object modelling MeshPoint,
|
||||
one can write naturally ::
|
||||
|
||||
// example of g, a Green function in Matsubara frequencies w
|
||||
for (auto w : g.mesh())
|
||||
g(w) = 1/(w + 2)
|
||||
g[w] = 1/(w + 2)
|
||||
// This runs overs the mesh, and fills the function with 1/(w+2)
|
||||
// In this expression, w is casted to the domain_t::point_t, here a complex<double>
|
||||
// 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.
|
||||
|
||||
|
@ -1,40 +1,20 @@
|
||||
.. _greenfunctions:
|
||||
|
||||
The Green function class
|
||||
========================
|
||||
Green functions
|
||||
=================
|
||||
|
||||
The TRIQS library has a class called ``gf`` which allows you to use easily a whole set of Green functions.
|
||||
|
||||
You can use as variable(s)
|
||||
|
||||
* real time(s),
|
||||
|
||||
* real frequency(ies),
|
||||
|
||||
* Matsubara time(s),
|
||||
|
||||
* Matsubara frequency(ies),
|
||||
|
||||
* or other variables that you can define.
|
||||
|
||||
More generally, the variable is a point of a ``domain``
|
||||
|
||||
The value of the Green function on a point of the domain can be a scalar, a matrix or whatever you want (this type is called type ``target_t``).
|
||||
|
||||
You can group several green functions into *blocks* (for example, one block per orbital, or per wave vector...).
|
||||
|
||||
Fourier transforms are implemented for these Green functions:
|
||||
|
||||
real time <-> real frequency
|
||||
|
||||
Matsubara time <-> Matsubara frequency
|
||||
The TRIQS library provides a generic container `gf` and its view `gf_view`, to store and manipulate
|
||||
various Green functions.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro
|
||||
gf_and_view
|
||||
concepts
|
||||
meshes
|
||||
the_four_basic_GFs
|
||||
tail
|
||||
fourier
|
||||
cookbook/contents
|
||||
gf_misc
|
||||
implementation_notes
|
||||
|
@ -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`
|
||||
|
||||
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);
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
||||
|
@ -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
|
||||
--------------------------------------
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/arrays.hpp>
|
||||
#include <triqs/gf/refreq.hpp>
|
||||
#include <triqs/gfs/refreq.hpp>
|
||||
|
||||
using triqs::gf::make_gf;
|
||||
using triqs::gf::refreq;
|
||||
using triqs::gfs::make_gf;
|
||||
using triqs::gfs::refreq;
|
||||
|
||||
int main() {
|
||||
double wmin=0;
|
||||
|
88
doc/reference/c++/gf/gf_and_view.rst
Normal file
88
doc/reference/c++/gf/gf_and_view.rst
Normal 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
36
doc/reference/c++/gf/gf_block.rst
Normal 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
80
doc/reference/c++/gf/gf_imfreq.rst
Normal 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
57
doc/reference/c++/gf/gf_imtime.rst
Normal 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
16
doc/reference/c++/gf/gf_misc.rst
Normal 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
36
doc/reference/c++/gf/gf_prod.rst
Normal 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
60
doc/reference/c++/gf/gf_refreq.rst
Normal 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
57
doc/reference/c++/gf/gf_retime.rst
Normal 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
75
doc/reference/c++/gf/implementation_notes.rst
Normal 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
43
doc/reference/c++/gf/intro.rst
Normal 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.
|
||||
|
||||
|
||||
|
@ -30,8 +30,8 @@ How to access to a mesh point with its index
|
||||
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/gf/refreq.hpp>
|
||||
using namespace triqs::gf;
|
||||
#include <triqs/gfs/refreq.hpp>
|
||||
using namespace triqs::gfs;
|
||||
|
||||
int main() {
|
||||
|
||||
@ -59,8 +59,8 @@ In this case, we look for the closest mesh point, but can need the distance of t
|
||||
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/gf/refreq.hpp>
|
||||
using namespace triqs::gf;
|
||||
#include <triqs/gfs/refreq.hpp>
|
||||
using namespace triqs::gfs;
|
||||
|
||||
int main() {
|
||||
double wmin = 0.0;
|
||||
@ -132,8 +132,8 @@ How to access to the closest mesh point
|
||||
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/gf/two_real_times.hpp>
|
||||
using namespace triqs::gf;
|
||||
#include <triqs/gfs/two_real_times.hpp>
|
||||
using namespace triqs::gfs;
|
||||
|
||||
int main() {
|
||||
double tmax = 1.0;
|
||||
@ -152,8 +152,8 @@ How to access to a mesh point with its index
|
||||
|
||||
.. compileblock::
|
||||
|
||||
#include <triqs/gf/two_real_times.hpp>
|
||||
using namespace triqs::gf;
|
||||
#include <triqs/gfs/two_real_times.hpp>
|
||||
using namespace triqs::gfs;
|
||||
|
||||
int main() {
|
||||
double tmax = 1.0;
|
||||
|
46
doc/reference/c++/gf/plan.rst
Normal file
46
doc/reference/c++/gf/plan.rst
Normal 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
7
doc/reference/c++/gf/tail.rst
Normal file
@ -0,0 +1,7 @@
|
||||
.. highlight:: c
|
||||
|
||||
.. _gf_tail:
|
||||
|
||||
High frequency tail
|
||||
===========================
|
||||
|
@ -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
14
doc/reference/c++/utilities/contents.rst
Normal 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
28
doc/reference/c++/utilities/python_include_mess.rst
Normal 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
77
doc/reference/c++/utilities/tupletools.rst
Normal 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<<" ";});
|
||||
}
|
||||
|
||||
|
||||
|
@ -5,7 +5,7 @@
|
||||
|
||||
.. _contents:
|
||||
|
||||
Reference: Python libraries
|
||||
Python libraries
|
||||
================================
|
||||
|
||||
.. toctree::
|
||||
|
@ -54,6 +54,11 @@ int main(int argc, char **argv) {
|
||||
std::cout << d<< std::endl;
|
||||
std::cout << matrix<int>( 2* 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;
|
||||
}
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user