LCPQ/dft_tools
3
0
Fork 0
mirror of https://github.com/triqs/dft_tools synced 2024-12-24 13:23:37 +01:00
Code Issues Releases Wiki Activity

Work on doc

Browse Source
This commit is contained in:
Olivier Parcollet 2013-08-27 19:17:17 +02:00
parent 3b29e9bf9d
commit d6c74f95c5
29 changed files with 887 additions and 504 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/install.rst
View File

@ -10,8 +10,10 @@ Installation
Prerequisite
------------
The TRIQS library relies on a certain number of standard libraries described in
the :ref:`list of requirements <requirements>`. Here are instructions to install
The TRIQS library relies on a certain number of standard libraries and tools described in
the :ref:`list of requirements <requirements>`. Beware in particular to the :ref:`C++ compilers<require_cxx_compilers>`
and to :ref:`Scientific Python tools<python_install>`.
Here are instructions to install
these necessary libraries on two standard systems:
.. toctree::
@ -35,12 +37,21 @@ Installation steps
$ cmake -DCMAKE_INSTALL_PREFIX=path_to_install_directory ../src
If you omit CMAKE_INSTALL_PREFIX, the default `path_to_install_directory` is ./INSTALL_DIR.
Configuration options are described :ref:`here<install_options>`.
#. Compile the code, run the tests and install the library::
$ make
$ make test
$ make install
.. note::
We remind you that on multicore machine, make's option -jN (where N is the number of cores)
greatly speed up the compilation e.g. make -j8 on a 8 cores machine...
#. After the installation TRIQS has been installed using the standard UNIX
scheme:
@ -53,15 +64,16 @@ Installation steps
* shared items in ``path_to_install_directory/share/triqs``.
Further details
---------------
Further reading
------------------
.. toctree::
:maxdepth: 1
installation/install_options
installation/python
installation/clang
installation/intel
installation/install_options
installation/changelog
..
installation/intel

43
doc/installation/clang.rst
View File

@ -1,47 +1,44 @@
.. index:: clang
.. _clang:
.. highlight:: bash
.. _install_clang:
Using clang compiler
==========================
clang++ compiler is **highly recommended** for anyone developing in C++ since :
**clang/llvm** is one of the very best C++ compilers, with gcc.
It is open source, on linux and OS X (where it is now the standard compiler provided by Apple).
* It has very nice and useful error messages, much nicer than intel or gcc.
* It implements most of the new C++11 standard.
*clang* compiler is **highly recommended** for anyone developing in C++ since :
clang/llvm is now the standard compiler on OS X, but it is open source
and works very well on linux too.
* It is standard compliant (C++11).
* It has very nice and useful error messages, much nicer than intel or gcc (even thought gcc is catching up...).
It really makes little sense to develop with e.g. gcc 4.6 today, specially with a library like TRIQS,
which uses a lot of metaprogramming.
Version
---------
Note however that for *production* compilations, gcc, specially recent versions, still produces in general
a slighly more optimal code for TRIQS applications, also the difference is small.
* TRIQS compiles on clang, version 3.0 and later.
It is highly recommended to use the latest stable on linux (3.3), and the default compiler on Os X (Mountain lion).
* Recommended version is 3.1 (latest stable).
Get and install clang on linux
---------------------------------------------
Get and install clang
------------------------
Precompiled versions are available at the `LLVM dowload page <http://llvm.org/releases/download.html>`_,
use it. Just untar them, and add the directory in your path.
If you have precompiled version in the `LLVM dowload page <http://llvm.org/releases/download.html>`_,
use it. E.g. on Ubuntu 12.04 LTS ::
wget http://llvm.org/releases/3.1/clang+llvm-3.1-x86_64-linux-ubuntu_12.04.tar.gz
tar xzf clang+llvm-3.1-x86_64-linux-ubuntu_12.04
sudo mv clang+llvm-3.1-x86_64-linux-ubuntu_12.04 /opt/clang
# add /opt/clang/bin to your path
# use clang++...
Otherwise, it is in fact quite easy to compile clang from source, just follow the
In any case, it is also very easy to compile clang from source, just follow the
`instructions <http://clang.llvm.org/get_started.html#build>`_.
Usage
--------------
In the current version, when compiling with clang, say (provided clang++ is your path of course) ::
To use clang ::
CXX=clang++ cmake path_to_TRIQS_source_directory .... others options ...
.. note::
On Os X, the options -std=c++11 and -stdlib=libc++ are automatically added by the TRIQS installation script.

62
doc/installation/install_options.rst
View File

@ -12,7 +12,7 @@ Specifying the compiler or compile/link flags
To specify the compiler with cmake one may use the CXX, CXXFLAGS variables, e.g. ::
CXX=clang++ CXXFLAGS cmake path_to_TRIQS_source_directory .....
CXX=clang++ CXXFLAGS=XXXX cmake path_to_TRIQS_source_directory .....
Customize the installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -24,11 +24,8 @@ You can then customize the installation options using the :program:`ccmake` prog
This opens an interface with your main installation options shown ::
BUILD_SHARED_LIBS ON
Build_CTHyb ON
Build_Documentation OFF
Build_HubbardI ON
Build_Triqs_General_Tools_Test ON
Build_Wien2k ON
CMAKE_INSTALL_PREFIX /home/parcolle/BUILD2/Triqs_dynamic/INSTALL_DIR
Install_dev OFF
LAPACK_LIBS /usr/lib/liblapack.so;/usr/lib/libblas.so;/usr/lib/libpthread.so;/usr/lib/libblas.so
@ -46,61 +43,4 @@ You may change all other installation options (like locations of libraries, the
After having corrected your options you may build, test and install TRIQS as described in :ref:`installation`.
.. _install_without_boost:
Installation with your own version of boost [-DBOOST_INSTALL_DIR=...]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you have a sufficiently recent version of boost already installed in your system you may
link TRIQS with it instead of compiling a new version of boost from sources.
In this case, the cmake instruction is ::
cmake path_to_TRIQS_source_directory -DBOOST_INSTALL_DIR=root_path_to_Boost_installation ....
The cmake option `DBOOST_INSTALL_DIR` is the path to the **boost** libraries.
The default value is :
* BOOST_INSTALL_DIR : /usr
So if boost is at the right place, you can just say::
cmake path_to_TRIQS_source_directory
**Obviously, you should not specify `DBOOST_SOURCE_DIR` in this case!**
.. _static_dyn :
Static versus dynamic linking [-DBUILD_SHARED_LIBS=OFF]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TRIQS can be compiled in two different ways:
* **dynamic linking** [default] :
This is the standard python procedure and the default choice.
All the C++ codes are compiled in shared libraries and loaded dynamically at runtime by the python interpreter.
With this technique however, you have to properly set the PYTHONPATH environment variable to the TRIQS installation directory in order
for python to be able to find the module. To avoid errors, TRIQS provides a
tiny script :file:`path_to_TRIQS_install_directory/bin/pytriqs` that sets up this variable for you and launch the python interpreter.
* **static linking** :
An alternative is to compile a new interpreter statically.
Here the C++ modules are linked with libpython2.x.a to create a *new python interpreter* :file:`path_to_TRIQS_install_directory/bin/pytriqs`
that contains these modules as *built-in* modules.
Though it is not as standard and extensible as the dynamic linking, this technique has several advantages :
* It avoids opening dynamic libs, which simplifies code profiling for example.
* It may be more stable on some cluster machines (the boost.mpi modules in this case is also linked statically).
In any case, both the scripts and the way to call them remain the same in both cases::
pytriqs myscript.py
The choice is made with the cmake option ::
-DBUILD_SHARED_LIBS=OFF/ON

13
doc/installation/osx_lion.rst
View File

@ -9,8 +9,8 @@ Installing required libraries on Mac OS X
This installation guide has been tried on Mountain Lion. It may work for older
versions of Mac OS X but previous versions of Mac OS X are not supported.
NB: The installation of TRIQS under previous versions of OS X requires installing clang (via Xcode) or gcc 4.7 (via MacPorts).
On Mountain Lion, clang (llvm) replaces gcc 4.2 as the default C++ compiler.
NB: The installation of TRIQS under previous versions of OS X requires installing clang (via Xcode).
(On Mountain Lion, clang (llvm) replaces gcc 4.2 as the default C++ compiler).
We strongly recommend the following installation procedure, which provides a clean way to set up all dependencies, so that all
of them are compatible with each other. Only the installation via homebrew is supported for the Mac.
@ -36,6 +36,9 @@ Installation of the dependencies
brew install python
brew install doxygen
#AFTER THE FIX IN BOOST AND BREW : IN PROGRESS
#brew install boost --without-single --with-mpi --with-c++11
4. Now install virtualenv: ::
pip install virtualenv
@ -61,12 +64,16 @@ yield the ones located in ``$HOME/mypython``.
pip install numpy
pip install h5py
pip install scipy
pip install git+https://github.com/matplotlib/matplotlib.git#egg=matplotlib-dev
pip install mpi4py
pip install matplotlib
#pip install git+https://github.com/matplotlib/matplotlib.git#egg=matplotlib-dev
pip install tornado
pip install pyzmq
pip install jinja2
pip install ipython
pip install cython
6. If you wish to compile the documentation locally, install sphinx, its dependencies and mathjax: ::
pip install sphinx

3
doc/installation/python.rst
View File

@ -60,7 +60,8 @@ Usage
* You can install any python package for this local python installation, e.g. ::
easy_install --upgrade ipython
easy_install --upgrade cython
and you have the latest ipython notebook....
and you have the latest ipython notebook, and cython

62
doc/installation/requirements.rst
View File

@ -9,10 +9,45 @@ TRIQS is built upon several python and C++ libraries, which, if not present
already in your system, can be freely downloaded and installed. All the
libraries and tools used by TRIQS are listed in the table:
.. _require_cxx_compilers:
C++ compilers
-----------------
TRIQS is written in C++, i.e. in the **C++11** standard as defined by the ISO.
A recent compiler is therefore mandatory.
There are 3 categories of C++ compilers.
* Standard compliant C++ compilers (recommended and supported).
* :ref:`clang 3.3<install_clang>` and higher.
* g++ 4.8.1 and higher
* Obsolete compilers.
TRIQS compiles on them, but they lack full C++11 support.
Therefore TRIQS may be slower, since some optimisations are disabled in the library
and they may not be supported in later release.
* g++ 4.6.4 to 4.8.0
* C++98 compilers.
Compilers implementing previous version of the C++ standard (c++98) do not work, and
will *never* be supported. This includes :
* g++ before 4.6
* Intel icc 12.0 and below.
Libraries
---------------
================== ================ ================================================================================
Libraries/tools Version Comment
================== ================ ================================================================================
mpi e.g., openmpi Parallelism
mpi openmpi Parallelism
Since standard linux distributions (and macports on OS X)
now provides openmpi, even on laptops, we avoid the unnecessary complication
of maintaining a non parallel version of TRIQS
@ -23,34 +58,11 @@ python >= 2.6.5
scipy python mathematical library
numpy python scientific library
h5py python interface to hdf5 library
mpi4py python MPI
sphinx >= 1.0.1 python documentation tools (to compile documentation)
pyparsing Tool for sphinx (to compile documentation)
matplotlib >= 0.99 python 2D plotting library
cython >=0.17 cython package
================== ================ ================================================================================
\* designates the libraries included in the Enthought python distribution.
C++11
-----
The current version of TRIQS use the new C++11 standard, and therefore require a recent C++ compiler.
Tested compilers include:
* g++ 4.6.3, 4.7
* clang++ 3.1
* icc 13.0
Note that older compilers will *never* be supported for current and future version of TRIQS.
Older releases may accept older compilers.
F90
---
For the Wien2TRIQS interface only.
Tested compilers include:
* ifort
* gfortran

7
doc/installation/ubuntu.rst
View File

@ -22,10 +22,11 @@ Install the following packages which are necessary to build TRIQS and use it::
Optionally, you may be interested in:
* How to *simply* upgrade the ipython notebook with :ref:`virtualenv <virtualenv>` to the latest version?
* How to *simply* upgrade the ipython notebook and Cython with :ref:`virtualenv <virtualenv>` to the latest version?
* How to use the nice :ref:`clang <clang>` C++ compiler?
* How to use the nice and recommended :ref:`clang <install_clang>` C++ compiler?
* How to use :ref:`Intel <icc>` C++ compiler?
..
* How to use :ref:`Intel <icc>` C++ compiler?
.. warning:: you need the latest version of Cython (>=.17, downloadable on Cython.org). If Cython is not found, specify the location of the executable with the option -DCYTHON_EXECUTABLE.

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

@ -3,65 +3,57 @@
Operations : array and matrix/vector algebras
=======================================================
Operations
------------
Arithmetic operations
-----------------------------
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 ;
This algebraic expressions can therefore be used in assignment array/matrix contructors.
For example:
.. compileblock::
#include <triqs/arrays.hpp>
using triqs::arrays::array;
using triqs::arrays::array; using triqs::clef::placeholder;
int main() {
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
// init
placeholder<0> i_; placeholder<1> j_;
array<long,2> A (2,2), B(2,2);
A(i_,j_) << i_ + j_ ;
B(i_,j_) << i_ - j_ ;
// use expressions
array<long,2> C = A+ 2*B;
array<double,2> D = 0.5 * A; // Type promotion is automatic
std::cout<< "A= "<< A<< std::endl;
std::cout<< "B= "<< B<< std::endl;
std::cout<< "C= "<< C<< std::endl;
std::cout<< "D= "<< D<< std::endl;
}
Arrays vs matrices
----------------------
Because their multiplication is not the same, arrays and matrices algebras can not be mixed.
Mixing them in expression would therefore be meaningless and it is therefore not allowed ::
array<long,2> A;
matrix<long,2> M;
M + A; // --> ERROR. Rejected by the compiler.
However, you can always make a matrix_view from a array of rank 2 ::
Mixing them in expression would therefore be meaningless and it is therefore not allowed.
However, you can always use e.g. `matrix_view` from a array of rank 2 :
A + make_matrix_view(M); //--> OK.
.. compileblock::
#include <triqs/arrays.hpp>
using namespace triqs::arrays;
int main() {
array<long,2> A(2,2); matrix<long,2> M(2,2);
//M + A; // --> ERROR. Rejected by the compiler.
M + make_matrix_view(A); //--> OK.
}
.. note::
Making view is cheap, it only copies the index systems. Nevertheless
this can still cause severe overhead in very intense loops.
Making such a view is very cheap, it only copies the index systems. Nevertheless
this can still cause significant overhead in very intense loops by disturbing
optimizers.
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**
- Similar to assignment, but it makes the operation
- For matrices, scalar is correctly interpreted as a scalar matrix.
Performance
---------------------------------------------
@ -92,7 +84,7 @@ is in fact rewritten by the compiler into ::
instead of making a chain of temporaries (C/2, 2*B, 2*B + C/2...) that "ordinary" object-oriented programming would produce.
As a result, the produced code is as fast as if you were writing the loop yourself,
but with several advantages :
but with several advantages:
* It is more **compact** and **readable** : you don't have to write the loop, and the indices range are computed automatically.
* It is much better for **optimization** :
@ -101,7 +93,9 @@ but with several advantages :
* For example, since the traversal order of indices is decided at compile time, the library can traverse the data
in an optimal way, allowing machine-dependent optimization.
* The library can perform easy optimisations behind the scene when possible, e.g. for vector it can use blas.
Expressions are lazy....
---------------------------
Note that expressions are lazy objects. It does nothing when constructed, it just "record" the mathematical expression ::
auto e = A + 2*B; // expression, purely formal, no computation is done
@ -111,4 +105,3 @@ Note that expressions are lazy objects. It does nothing when constructed, it jus
array<long,2> D(e); // now really makes the computation and store the result in D.
D = 2*A +B; // reassign D to the evaluation of the expression.

118
doc/reference/c++/arrays/concepts.rst
View File

@ -44,18 +44,19 @@ ImmutableCuboidArray
* NB : It does not need to be stored in memory. A formal expression, e.g. model this concept.
* **Definition** ([A] denotes something optional).
* **Definition** ([...] 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).
================================================================================================== =============================================================================
+-------------------------------------------------------+-------------------------------------------------------------------------+
| Members | Comment |
+=======================================================+=========================================================================+
| domain_type == cuboid_domain<Rank> | Type of the domain, with rank `Rank` |
+-------------------------------------------------------+-------------------------------------------------------------------------+
| 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.
@ -69,65 +70,102 @@ MutableCuboidArray
* **Purpose** : An array where the data can be modified...
* **Refines** : :ref:`ImmutableCuboidArray`.
* **Definition**
* **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).
================================================================================================== =============================================================================
+----------------------------------------------+-----------------------------------------------------------------------------+
| Members | Comment |
+==============================================+=============================================================================+
| 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.
.. _ImmutableArray:
ImmutableArray
-------------------------------------------------------------------
* Refines :ref:`ImmutableCuboidArray`
* If X is the type :
* ImmutableArray<A> == true_type
NB : this traits marks the fact that X belongs to the Array algebra.
.. _ImmutableMatrix:
ImmutableMatrix
-------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that :
* Refines :ref:`ImmutableCuboidArray`
* the rank of the domain must be 2
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableMatrix).
* If A is the type :
* ImmutableMatrix<A> == true_type
* A::domain_type::rank ==2
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
.. _ImmutableVector:
ImmutableVector
-------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that :
* Refines :ref:`ImmutableCuboidArray`
* the rank of the domain must be 1
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableVector).
* If A is the type :
* ImmutableMatrix<A> == true_type
* A::domain_type::rank ==1
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
.. _MutableArray:
MutableArray
-------------------------------------------------------------------
* Refines :ref:`MutableCuboidArray`
* If A is the type :
* ImmutableArray<A> == true_type
* MutableArray<A> == true_type
NB : this traits marks the fact that X belongs to the Array algebra.
.. _MutableMatrix:
MutableMatrix
-------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that :
* Refines :ref:`MutableCuboidArray`
* the rank of the domain must be 2
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableMatrix).
* If A is the type :
* ImmutableMatrix<A> == true_type
* MutableMatrix<A> == true_type
* A::domain_type::rank ==2
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
.. _MutableVector:
MutableVector
-------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that :
* Refines :ref:`MutableCuboidArray`
* the rank of the domain must be 1
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableVector).
* If A is the type :
* ImmutableMatrix<A> == true_type
* MutableMatrix<A> == true_type
* A::domain_type::rank ==1
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
Why concepts ? [Advanced]
@ -153,7 +191,7 @@ Example :
#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) {
template<typename T> class immutable_diagonal_matrix_view {
array_view<T,1> data; // the diagonal stored as a 1d array
@ -167,8 +205,12 @@ Example :
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;}
friend std::ostream & operator<<(std::ostream & out, immutable_diagonal_matrix_view const & d)
{return out<<"diagonal_matrix "<<d.data;}
};
// Marking this class as belonging to the Matrix & Vector algebra.
template<typename T> struct ImmutableMatrix<immutable_diagonal_matrix_view<T>> : std::true_type{};
}}
/// TESTING

7
doc/reference/c++/arrays/containers/call.rst
View File

@ -1,6 +1,6 @@
.. highlight:: c
.. _arr_reg_call:
.. _arr_call:
Operator()
==================================
@ -14,7 +14,10 @@ Operator()
view_type operator()( size_t | range | ellipsis ) const (2b)
`clef expression` operator()( `at least a lazy argument` ) const (3)
This is valid for both the container (e.g. array), and the view (e.g. array_view).
.. _arr_element_access:
(1) Element access

16
doc/reference/c++/arrays/containers/compound_ops.rst Normal file
View File

@ -0,0 +1,16 @@
.. highlight:: c
.. _arr_comp_ops:
Compound assignment operators (+=, -=, * =, /=)
-------------------------------------------------
**Synopsis** ::
template<typename RHS> THIS_TYPE & operator += (const RHS & X);
template<typename RHS> THIS_TYPE & operator -= (const RHS & X);
template<typename RHS> THIS_TYPE & operator *= (const Scalar & S);
template<typename RHS> THIS_TYPE & operator /= (const Scalar & S);
The containers and the view have compound operators.

63
doc/reference/c++/arrays/containers/memory.rst Normal file
View File

@ -0,0 +1,63 @@
.. highlight:: c
.. _arr_view_memory:
View 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 fully compliant C++11 compiler` (in particular, `rvalue reference for *this` must be implemented)
allowing therefore for better performance on such compiler, in some loops.
Older supported compiler will therefore generate code with lower performances.
* 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 ::
TO BE WRITTEN

18
doc/reference/c++/arrays/containers/rebind.rst Normal file
View File

@ -0,0 +1,18 @@
.. highlight:: c
.. _arr_rebind:
rebind
==================================
* **Synopsis**:
.. cpp:function:: void rebind(array_view const & a)
Rebinds the view
After this method, the view points to the same as a.
Following the :ref:`memory management rules <arr_view_memory>`, if nothing else views the
data originally pointed to by the view, this data is destroyed.

83
doc/reference/c++/arrays/containers/reg_assign.rst
View File

@ -5,55 +5,40 @@
Assignment
=========================
The `value classes` and the `view classes` have a quite general assignment operator.
**Synopsis** ::
array & operator=(array const & X); (1)
template<ImmutableCuboidArray RHS> array & operator=(RHS const & X); (2)
The container 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::
template<typename RHS> array & operator=(const RHS & X);
template<typename RHS> array_view & operator=(const RHS & X);
* **What can be RHS ?**
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.
* **Behaviour**
================= ======================================================================= ======================================================================================
Topic value class : array, matrix, vector view: array_view, matrix_view, vector_view
================= ======================================================================= ======================================================================================
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.
================= ======================================================================= ======================================================================================
* By evaluation of X, we mean :
- a copy if X is an array.
- computing the value if X is an expression.
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.
* (1) just make a copy of X.
* (2) **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.
`Effect` : all the elements viewed by the view are replaced
by the evaluation of RHS.
.. warning::
In both cases, if needed, the container is resized.
Hence **assignment invalidates all pointers and views to it**.
Move assign operator
---------------------------
**Synopsis** ::
array & operator=(array && X);
Standard move assign operator.
Move the data of X as data of `*this`.

56
doc/reference/c++/arrays/containers/reg_constructors.rst
View File

@ -15,34 +15,34 @@ 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
========================================== ===========================================================================================
array() Empty array of size 0
------------------------------------------ -------------------------------------------------------------------------------------------
array(size_t, ...., size_t) From the lengths of the array dimensions, with Rank arguments (checked at compile time).
------------------------------------------ -------------------------------------------------------------------------------------------
array(const array &) Copy construction
------------------------------------------ -------------------------------------------------------------------------------------------
array(array &&) Move construction
------------------------------------------ -------------------------------------------------------------------------------------------
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.
------------------------------------------ -------------------------------------------------------------------------------------------
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.
- 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.
========================================== ===========================================================================================
+---------------------------------+------------------------------------------------------------------------------------------+
| Constructors of array | Comments |
+=================================+==========================================================================================+
| array() | Empty array of size 0 |
+---------------------------------+------------------------------------------------------------------------------------------+
| array(size_t, ...., size_t) | From the lengths of the array dimensions, with Rank arguments (checked at compile time). |
+---------------------------------+------------------------------------------------------------------------------------------+
| array(const array &) | Copy construction |
+---------------------------------+------------------------------------------------------------------------------------------+
| array(array &&) | Move construction |
+---------------------------------+------------------------------------------------------------------------------------------+
| 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. |
+---------------------------------+------------------------------------------------------------------------------------------+
| array(shape_t const &) | New array with the corresponding shape (as returned by the function shape. See example |
| | in section XXX). |
+---------------------------------+------------------------------------------------------------------------------------------+
| array(std::initializer_list<T>) | Initialization from a initializer_list of T. Enable for rank==1 only |
+---------------------------------+------------------------------------------------------------------------------------------+
| explicit array(PyObject * X) | Construct a new array from the Python object X. |
| | - 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

153
doc/reference/c++/arrays/containers/regular.rst
View File

@ -7,9 +7,9 @@ array, matrix & vector
.. 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;
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 :
@ -30,91 +30,77 @@ where triqs::ull_t is the type defined by :
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.
============================ ============================== ========================== ====================================================================
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| 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 |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| :ref:`OptionsFlags<arr_templ_par_opt>` | ull_t | opt_flags | Compile time options |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| :ref:`TraversalOrder<arr_templ_par_to>` | ull_t | | Traversal Order for all loops |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
* Rank is only present for array, since matrix have rank 2 and vector rank 1.
NB: 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
======================== =======================================
.. toctree::
:hidden:
Defaults can be modified with the macros :
template_parameters
* `TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` : enforce BoundCheck by default (slows down codes ! Use only for debugging purposes).
Member types
--------------------------------------
* 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.
+--------------+----------------------------------------------------------+
| Member type | Definitions |
+==============+==========================================================+
| value_type | ValueType |
+--------------+----------------------------------------------------------+
| view_type | The corresponding view type |
+--------------+----------------------------------------------------------+
| regular_type | The corresponding regular type i.e. the container itself |
+--------------+----------------------------------------------------------+
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 constexpr
--------------------------------------
+--------+------+-------------------------------+
| Member | Type | Definitions |
+========+======+===============================+
| rank | int | Rank of the container (Rank |
| | | for array), 2 for matrix, 1 |
| | | for vector |
+--------+------+-------------------------------+
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
============================================= ==============================================
+-------------------------------------------+------------------------------------------+
| Member function | Meaning |
+===========================================+==========================================+
| :ref:`(constructor)<arr_reg_constr>` | |
+-------------------------------------------+------------------------------------------+
| (destructor) | |
+-------------------------------------------+------------------------------------------+
| :ref:`operator =<arr_reg_assign>` | assigns values to the container |
+-------------------------------------------+------------------------------------------+
| :ref:`operator +=,-=,*=,/=<arr_comp_ops>` | compound assignment operators |
+-------------------------------------------+------------------------------------------+
| :ref:`operator ()<arr_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 |
+-------------------------------------------+------------------------------------------+
| bool is_empty() const | Is the array empty ? |
+-------------------------------------------+------------------------------------------+
.. toctree::
@ -122,6 +108,7 @@ end/cend returns iterator to the end
reg_constructors
reg_assign
comp_ops
call
resize
STL
@ -130,17 +117,19 @@ Non-member functions
------------------------
============================================= ==============================================
Member function Meaning
============================================= ==============================================
:ref:`swap<arr_swap>`
:ref:`deep_swap<arr_deep_swap>`
============================================= ==============================================
+---------------------------------+-------------------------------------------+
| Member function | Meaning |
+=================================+===========================================+
| :ref:`swap<arr_swap>` | Swap of 2 containers |
+---------------------------------+-------------------------------------------+
| :ref:`deep_swap<arr_deep_swap>` | Deep swap of the data of 2 containers ??? |
+---------------------------------+-------------------------------------------+
| :ref:`operator\<\<<arr_stream>` | Writing to stream |
+---------------------------------+-------------------------------------------+
.. toctree::
:hidden:
swap
stream

23
doc/reference/c++/arrays/containers/stream.rst Normal file
View File

@ -0,0 +1,23 @@
.. highlight:: c
.. _arr_stream:
operator <<
==================================
**Synopsis**::
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0>
std::ostream & operator << (std::ostream & out, array_view<ValueType,Rank,OptionsFlags,TraversalOrder> const &);
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0>
std::ostream & operator << (std::ostream & out, matrix_view<ValueType,OptionsFlags,TraversalOrder> const &);
template <typename ValueType, ull_t OptionsFlags=0>
std::ostream & operator << (std::ostream & out, vector_view<ValueType,OptionsFlags> const &);
Prints the view (or the container since the view is trivially build from the container)
to the stream out.

51
doc/reference/c++/arrays/containers/template_parameters.rst Normal file
View File

@ -0,0 +1,51 @@
Template parameters of the containers and views
======================================================
.. _arr_templ_par_opt:
OptionFlags
----------------------------
* 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).
.. _arr_templ_par_to:
TraversalOrder
----------------------------
* 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.

61
doc/reference/c++/arrays/containers/view_assign.rst Normal file
View File

@ -0,0 +1,61 @@
.. highlight:: c
.. _arr_view_assign:
Assignment to views
=========================
**Synopsis** :
template<typename RHS>
array_view & operator=(RHS const & X);
The `view classes` have a quite general assignment operator.
We will illustrate it on the `array_view` class, it is the same for `matrix` and `vector`.
* **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.
`Effect` : all the elements viewed by the view are replaced
by the evaluation of RHS.
.. warning::
The shape of the view and of RHS must match exactly or behaviour is undefined.
If the debug macro, :ref:`TRIQS_ARRAYS_ENFORCE_BOUNDCHECK<arr_debug_macro>` is defined,
this condition is checked at runtime.
.. note::
We could lower this condition, since we don't need a domain here, just the evaluation
on the indices...
* A scalar.
`Effect` : all elements viewed by the view are set to this scalar.
NB : no move assign operator
---------------------------------------
Note that **there is no move assign operators for views**.
If RHS is an rvalue reference, the regular operator = is called, that
makes a copy of the data of RHS into the elements viewed by the view.
This behaviour is consistent with the fact that views are *not* regular types.
For example ::
array<double,2> A(3,3);
A(range(0,2), range(0,2)) = any_function_returning_a_new_2x2_array(....);
In this case, the expected behaviour is that the part of A views by view at l.h.s
is filled by the result of the function. There can not be any move semantics here.
As a result, std::swap algorithm does not work properly for view, hence it has
been explicitely *deleted*. A swap function (found by ADL) is provided instead.

45
doc/reference/c++/arrays/containers/view_constructors.rst Normal file
View File

@ -0,0 +1,45 @@
.. highlight:: c
.. _arr_view_constr:
Constructors of views
================================
Note that in practice, you rarely explicitly construct a view.
Views are normally automatically built by the :ref:`() operator<arr_call>`.
Constructors of array_view
---------------------------------------
Views have `view semantics`, i.e. they **never** make a copy of the data.
====================================================================== =====================================================================================================
Constructors of array_view Comments
====================================================================== =====================================================================================================
array_view(const array_view &) Copy construction (makes a shallow copy)
array_view(const T & X) T is any type such that X.indexmap() and X.storage() can be used to construct a view.
REF to concept here ....
====================================================================== =====================================================================================================
+-----------------------------------+---------------------------------------------------------------------------------------+
| Constructors of array_view | Comments |
+===================================+=======================================================================================+
| array_view(const array_view &) | Copy construction: create a new view, viewing the same data. Does **not** copy data |
+-----------------------------------+---------------------------------------------------------------------------------------+
| array_view(const T & X) | T is any type such that X.indexmap() and X.storage() can be used to construct a view. |
+-----------------------------------+---------------------------------------------------------------------------------------+
| array_view(array_view &&) | Move construction (trivial here, a copy constructor is very quick anyway). |
+-----------------------------------+---------------------------------------------------------------------------------------+
| explicit array_view(PyObject * X) | Construct an array_view from the Python object X. Type and rank must match exactly, |
| | or an exception if thrown |
+-----------------------------------+---------------------------------------------------------------------------------------+
| | .. note:: X is a borrowed reference, array does not affect its counting reference. |
+-----------------------------------+---------------------------------------------------------------------------------------+
Constructors of matrix_view, vector_view
------------------------------------------------
Similar to array_view

186
doc/reference/c++/arrays/containers/views.rst
View File

@ -9,9 +9,9 @@ Views
.. 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;
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 :
@ -19,87 +19,127 @@ where triqs::ull_t is the type defined by :
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.
* A `view` is give access to a restricted portion of the array, matrix or vector, i.e. a `partial view` of the data.
The view can also be `complete` (i.e. show all the container).
* Basically X_view should be understood as a reference to the data of the viewed object,
dressed to model the "`MutableX`" concept.
* The views model the :ref:`MutableCuboidArray`, :ref:`MutableMatrix`, :ref:`MutableVector`, like the corresponding regular type.
* 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.
* Views have `view semantics`, i.e. their behave like a reference to the data, they are not regular type.
In particular, they never make copy of the data.
See :ref:`view_vs_regular` for a detailed discussion of the difference between a regular type and its corresponding view.
* Views are largely interoperable : it is easy and quick to take a matrix_view of an array, or vice versa.
Cf constructors belows.
* **Memory Management**
====================================================================== =====================================================================================================
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 ....
====================================================================== =====================================================================================================
Views offers a strong guarantee of the existence of the data, like a std::shared_ptr.
Cf :ref:`arr_view_memory` for details.
Memory management
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 |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| :ref:`OptionsFlags<arr_templ_par_opt>` | ull_t | opt_flags | Compile time options |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| :ref:`TraversalOrder<arr_templ_par_to>` | ull_t | | Traversal Order for all loops |
+-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
NB: Rank is only present for array, since matrix have rank 2 and vector rank 1.
.. toctree::
:hidden:
template_parameters
Member types
--------------------------------------
+--------------+----------------------------------------------------------+
| Member type | Definitions |
+==============+==========================================================+
| value_type | ValueType |
+--------------+----------------------------------------------------------+
| view_type | The corresponding view type, i.e. the view itself |
+--------------+----------------------------------------------------------+
| regular_type | The corresponding regular type |
+--------------+----------------------------------------------------------+
Member constexpr
--------------------------------------
+--------+------+-------------------------------+
| Member | Type | Definitions |
+========+======+===============================+
| rank | int | Rank of the container (Rank |
| | | for array), 2 for matrix, 1 |
| | | for vector |
+--------+------+-------------------------------+
Member functions
---------------------
+-------------------------------------------+------------------------------------------+
| Member function | Meaning |
+===========================================+==========================================+
| :ref:`(constructor)<arr_view_constr>` | |
+-------------------------------------------+------------------------------------------+
| (destructor) | |
+-------------------------------------------+------------------------------------------+
| :ref:`operator =<arr_view_assign>` | assigns values to the container |
+-------------------------------------------+------------------------------------------+
| :ref:`operator +=,-=,*=,/=<arr_comp_ops>` | compound assignment operators |
+-------------------------------------------+------------------------------------------+
| :ref:`operator ()<arr_call>` | element of access/views/lazy expressions |
+-------------------------------------------+------------------------------------------+
| begin/cbegin | returns iterator to the beginning |
+-------------------------------------------+------------------------------------------+
| end/cend | returns iterator to the end |
+-------------------------------------------+------------------------------------------+
| :ref:`rebind<arr_rebind>` | rebind the view |
+-------------------------------------------+------------------------------------------+
| bool is_empty() const | Is the array empty ? |
+-------------------------------------------+------------------------------------------+
.. note::
views can not be resized.
.. toctree::
:hidden:
view_constructors
view_assign
comp_ops
call
rebind
STL
Non-member functions
------------------------
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 :
+---------------------------------+-------------------------------------------+
| Member function | Meaning |
+=================================+===========================================+
| :ref:`swap<arr_swap>` | Swap of 2 containers |
+---------------------------------+-------------------------------------------+
| :ref:`deep_swap<arr_deep_swap>` | Deep swap of the data of 2 containers ??? |
+---------------------------------+-------------------------------------------+
| :ref:`operator\<\<<arr_stream>` | Writing to stream |
+---------------------------------+-------------------------------------------+
.. toctree::
:hidden:
stream

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

@ -15,10 +15,11 @@ Multidimensional arrays
view_or_not_view
lazy
foreach
simple_fnt
map
mapped_fnt
algebras
move_swap
play_with_concept
blas_lapack
H5
Interop_Python

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

@ -8,7 +8,7 @@ Loops : the foreach constructs
foreach and its variants are a compact and efficient way to
perform some action of the kind
*For all elements of the arrays, do something*
*For all indices of the array, do something*
While this kind of construct is equivalent to write manually the *for* loops, it has

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

@ -1,5 +1,7 @@
.. highlight:: c
.. _arr_map_fold:
Functional constructs : map & fold
###########################################
@ -27,17 +29,15 @@ map
ValueType2 f(ValueType1)
Then map(f) is a function::
template<ImmutableCuboidArray A> auto map(f) (A const &)
ReturnType map(f) ( ArrayType const & A)
where ArrayType models the :ref:`ImmutableCuboidArray` concept
with :
* A::value_type == ValueType1
* The returned type of map(f) models the :ref:`ImmutableCuboidArray` concept
* with value_type == ValueType1
and ReturnType models the :ref:`ImmutableCuboidArray` concept
* with the same domain as ArrayType
* with value_type == ValueType2
* with the same domain as A
* with value_type == ValueType2
* N.B. : Some cases require explicit cast, e.g. for the standard abs function (already defined in arrays/mapped_function.hpp) ,
or the compiler does not know which std::abs you are talking about ::
@ -51,7 +51,7 @@ map
.. compileblock::
#include <triqs/arrays.hpp>
using triqs::arrays::matrix; using triqs::clef::placeholder;
using triqs::arrays::matrix; using triqs::arrays::make_matrix; using triqs::clef::placeholder;
int main() {
// declare and init a matrix
placeholder<0> i_; placeholder<1> j_;
@ -60,14 +60,10 @@ map
// the mapped function
auto F = triqs::arrays::map([](int i) { return i*2.5;});
matrix<double> B;
B = F(A);
std::cout<< A << B<< std::endl;
// works also with expressions of course
B = F( 2*A );
B = B + 3* F(2*A); // ok that is just an example...
std::cout<< A << B<< std::endl;
std::cout<< "A = " << A << std::endl;
std::cout<< "F(A) = " << F(A) << std::endl; // oops no computation done
std::cout<< "F(A) = " << make_matrix(F(A)) << std::endl;
std::cout<< "3*F(2*A) = " << make_matrix(3*F(2*A)) << std::endl;
}
@ -112,12 +108,12 @@ fold
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 ???) ::
The function :ref:`arr_fnt_sum` which returns the sum of all the elements of the array is implemented as ::
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

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

@ -1,41 +0,0 @@
.. highlight:: c
.. _Mapped:
Simple functions on arrays
==================================
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`
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 :
.. compileblock::
#include <triqs/arrays.hpp>
using triqs::arrays::matrix; using triqs::clef::placeholder;
int main(){
placeholder<0> i_; placeholder<1> j_;
matrix<double> A(2,2);
A(i_,j_) << i_ - j_ ;
std::cout << "A = "<<A << std::endl;
std::cout << "abs(A)= "<<matrix<double>(abs(A))<< std::endl;
}

59
doc/reference/c++/arrays/play_with_concept.rst Normal file
View File

@ -0,0 +1,59 @@
.. highlight:: c
.. _arr_play_concept:
.. warning::
This part is alpha : work in progress. May change at any time.
Using basic concepts
###########################################
make_immutable_array
-------------------------------
**Synopsis**::
template<typename Expr, int ... ph> auto make_immutable_array(Expr const &, clef::pair<ph,range> ...); (1)
template<typename Function> auto make_immutable_array(Function, range ...); (2)
* (1)
From a clef expression, and a range for each placeholder in the expression, build
a lazy object modelling :ref:`ImmutableCuboidArray` concept, with the domain built from the ranges :
Parameters are :
* expr The lazy expression
* i_=R : `i_` is a placeholder, R a range. The `i_=R` produce a clef::pair of `i_` and R , which is the parameter.
* (2)
From a function object and a set of range, build
a lazy object modelling :ref:`ImmutableCuboidArray` concept, with the domain built from the ranges :
**Example** :
.. compileblock::
#include <triqs/arrays.hpp>
#include <triqs/arrays/make_immutable_array.hpp>
using triqs::arrays::array; using triqs::arrays::range; using triqs::clef::placeholder;
int main() {
placeholder<0> i_; placeholder<1> j_;
auto a = make_immutable_array( 1.0/(2 + i_ + j_), i_= range(0,2), j_=range(0,2));
std::cout << "a = " << a << std::endl;
std::cout << "a = " << array<double,2>(a) << std::endl;
// or if you prefer using a lambda...
auto b = make_immutable_array ( [](int i, int j) { return i-j;}, range (0,2), range(0,2));
std::cout << "b = " << b << std::endl;
std::cout << "b = " << array<double,2>(b) << std::endl;
}

70
doc/reference/c++/arrays/simple_fnt.rst Normal file
View File

@ -0,0 +1,70 @@
.. highlight:: c
.. _arr_simple_fun:
Simple array functions
==================================
The following functions work for any object modeling :ref:`ImmutableCuboidArray` concept.
In this section, we present some simple functions already in the library.
It is however very easy to create new one using the usual functional constructions :ref:`map and fold<arr_map_fold>`.
Element-wise functions
---------------------------
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`
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.
sum
---------------
**Synopsis**::
template<ImmutableCuboidArray A> A::value_type sum (A const &);
template<ImmutableCuboidArray A> A::value_type prod (A const &);
Returns the sum (resp. product) of the all the elements of the array.
max_element, min_element
-------------------------------
**Synopsis**::
template<ImmutableCuboidArray A> A::value_type max_element (A const &);
template<ImmutableCuboidArray A> A::value_type min_element (A const &);
Returns the maximum/minimum element of the array (provided that value_type is an ordered type of course...).
Examples
-----------------
.. compileblock::
#include <triqs/arrays.hpp>
#include <triqs/arrays/algorithms.hpp>
using triqs::arrays::matrix; using triqs::clef::placeholder;
int main() {
// declare and init a matrix
placeholder<0> i_; placeholder<1> j_;
matrix<int> A (2,2); A(i_,j_) << i_ - j_ ;
std::cout << "A = " << A << std::endl;
std::cout << "abs(A)= " << matrix<double>(abs(A)) << std::endl;
std::cout << "sum(A) = " << sum(A) << std::endl;
std::cout << "max_element(A) = " << max_element(A) << std::endl;
std::cout << "min_element(A) = " << min_element(A) << std::endl;
std::cout << "min_element(abs(A)) = " << min_element(abs(A)) << std::endl;
}

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

@ -12,6 +12,5 @@ C++ libraries
mctools/intro
det_manip/det_manip
parameters/parameters
lectures/contents
utilities/contents

2
doc/reference/c++/gf/gf_imfreq.rst
View File

@ -71,7 +71,7 @@ An alternative declaration with an explicit construction of the underlying mesh:
double beta=10;
int Nfreq =100;
auto GF = make_gf<imfreq>(mesh<imfreq>{beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1));
auto GF = make_gf<imfreq>(gf_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));
}