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

Work on doc

Browse Source
This commit is contained in:
Olivier Parcollet 2013-08-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 Prerequisite
------------ ------------
The TRIQS library relies on a certain number of standard libraries described in The TRIQS library relies on a certain number of standard libraries and tools described in
the :ref:`list of requirements <requirements>`. Here are instructions to install 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: these necessary libraries on two standard systems:
.. toctree:: .. toctree::
@ -35,12 +37,21 @@ Installation steps
$ cmake -DCMAKE_INSTALL_PREFIX=path_to_install_directory ../src $ 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:: #. Compile the code, run the tests and install the library::
$ make $ make
$ make test $ make test
$ make install $ 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 #. After the installation TRIQS has been installed using the standard UNIX
scheme: scheme:
@ -53,15 +64,16 @@ Installation steps
* shared items in ``path_to_install_directory/share/triqs``. * shared items in ``path_to_install_directory/share/triqs``.
Further details Further reading
--------------- ------------------
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
installation/install_options
installation/python installation/python
installation/clang installation/clang
installation/intel
installation/install_options
installation/changelog installation/changelog
..
installation/intel

43
doc/installation/clang.rst
View File

@ -1,47 +1,44 @@
.. index:: clang .. index:: clang
.. _clang:
.. highlight:: bash .. highlight:: bash
.. _install_clang:
Using clang compiler 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. *clang* compiler is **highly recommended** for anyone developing in C++ since :
* It implements most of the new C++11 standard.
clang/llvm is now the standard compiler on OS X, but it is open source * It is standard compliant (C++11).
and works very well on linux too. * 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>`_, In any case, it is also very easy to compile clang from source, just follow the
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
`instructions <http://clang.llvm.org/get_started.html#build>`_. `instructions <http://clang.llvm.org/get_started.html#build>`_.
Usage 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 ... 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. :: 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 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 :: This opens an interface with your main installation options shown ::
BUILD_SHARED_LIBS ON BUILD_SHARED_LIBS ON
Build_CTHyb ON
Build_Documentation OFF Build_Documentation OFF
Build_HubbardI ON
Build_Triqs_General_Tools_Test ON Build_Triqs_General_Tools_Test ON
Build_Wien2k ON
CMAKE_INSTALL_PREFIX /home/parcolle/BUILD2/Triqs_dynamic/INSTALL_DIR CMAKE_INSTALL_PREFIX /home/parcolle/BUILD2/Triqs_dynamic/INSTALL_DIR
Install_dev OFF Install_dev OFF
LAPACK_LIBS /usr/lib/liblapack.so;/usr/lib/libblas.so;/usr/lib/libpthread.so;/usr/lib/libblas.so 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`. 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 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. 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). 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. (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 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. 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 python
brew install doxygen 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: :: 4. Now install virtualenv: ::
pip install virtualenv pip install virtualenv
@ -61,12 +64,16 @@ yield the ones located in ``$HOME/mypython``.
pip install numpy pip install numpy
pip install h5py pip install h5py
pip install scipy 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 tornado
pip install pyzmq pip install pyzmq
pip install jinja2
pip install ipython pip install ipython
pip install cython pip install cython
6. If you wish to compile the documentation locally, install sphinx, its dependencies and mathjax: :: 6. If you wish to compile the documentation locally, install sphinx, its dependencies and mathjax: ::
pip install sphinx 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. :: * You can install any python package for this local python installation, e.g. ::
easy_install --upgrade ipython 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 already in your system, can be freely downloaded and installed. All the
libraries and tools used by TRIQS are listed in the table: 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 Libraries/tools Version Comment
================== ================ ================================================================================ ================== ================ ================================================================================
mpi e.g., openmpi Parallelism mpi openmpi Parallelism
Since standard linux distributions (and macports on OS X) Since standard linux distributions (and macports on OS X)
now provides openmpi, even on laptops, we avoid the unnecessary complication now provides openmpi, even on laptops, we avoid the unnecessary complication
of maintaining a non parallel version of TRIQS of maintaining a non parallel version of TRIQS
@ -23,34 +58,11 @@ python >= 2.6.5
scipy python mathematical library scipy python mathematical library
numpy python scientific library numpy python scientific library
h5py python interface to hdf5 library h5py python interface to hdf5 library
mpi4py python MPI
sphinx >= 1.0.1 python documentation tools (to compile documentation) sphinx >= 1.0.1 python documentation tools (to compile documentation)
pyparsing Tool for sphinx (to compile documentation) pyparsing Tool for sphinx (to compile documentation)
matplotlib >= 0.99 python 2D plotting library matplotlib >= 0.99 python 2D plotting library
cython >=0.17 cython package 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: 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. .. 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.

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

@ -3,63 +3,55 @@
Operations : array and matrix/vector algebras 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. Arrays and matrices can be combined in formal algebraic expressions, which models the :ref:`ImmutableCuboidArray` concept.
This algebraic expressions can therefore be used as RHS of assignment (SEE) or in array/matrix contructors. This algebraic expressions can therefore be used in assignment array/matrix contructors.
For example ; For example:
.. compileblock:: .. compileblock::
#include <triqs/arrays.hpp> #include <triqs/arrays.hpp>
using triqs::arrays::array; using triqs::arrays::array; using triqs::clef::placeholder;
int main() { int main() {
array<long,2> A (2,2), B(2,2), C; // init
C= A + 2*B; placeholder<0> i_; placeholder<1> j_;
array<long,2> D = A+ 2*B; array<long,2> A (2,2), B(2,2);
array<double,2> F = 0.5 * A; // Type promotion is automatic 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 Arrays vs matrices
---------------------- ----------------------
Because their multiplication is not the same, arrays and matrices algebras can not be mixed. 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 :: 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 :
array<long,2> A; .. compileblock::
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 :: #include <triqs/arrays.hpp>
using namespace triqs::arrays;
A + make_matrix_view(M); //--> OK. 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:: .. note::
Making view is cheap, it only copies the index systems. Nevertheless Making such a view is very cheap, it only copies the index systems. Nevertheless
this can still cause severe overhead in very intense loops. 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 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. 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, 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 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** : * It is much better for **optimization** :
@ -102,6 +94,8 @@ but with several advantages :
in an optimal way, allowing machine-dependent optimization. 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. * 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 :: 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 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. 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. 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. * 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) +-------------------------------------------------------+-------------------------------------------------------------------------+
| Members | Comment |
================================================================================================== ============================================================================= +=======================================================+=========================================================================+
Elements Comment | domain_type == cuboid_domain<Rank> | Type of the domain, with rank `Rank` |
================================================================================================== ============================================================================= +-------------------------------------------------------+-------------------------------------------------------------------------+
domain_type Type of the domain. | domain_type [const &] domain() const | Access to the domain. |
domain_type [const &] domain() const Access to the domain. +-------------------------------------------------------+-------------------------------------------------------------------------+
value_type Type of the element of the array | 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). +-------------------------------------------------------+-------------------------------------------------------------------------+
================================================================================================== ============================================================================= | value_type [const &] operator() (size_t ... i) const | Evaluation. Must have exactly rank argument (checked at compiled time). |
+-------------------------------------------------------+-------------------------------------------------------------------------+
* **Examples** : * **Examples** :
* array, array_view, matrix, matrix_view, vector, vector_view. * array, array_view, matrix, matrix_view, vector, vector_view.
@ -69,65 +70,102 @@ MutableCuboidArray
* **Purpose** : An array where the data can be modified... * **Purpose** : An array where the data can be modified...
* **Refines** : :ref:`ImmutableCuboidArray`. * **Refines** : :ref:`ImmutableCuboidArray`.
* **Definition**
* **Definition** ([A] denotes something optional). +----------------------------------------------+-----------------------------------------------------------------------------+
| Members | Comment |
* The class derives from : TRIQS_CONCEPT_TAG_NAME(MutableCuboidArray) +==============================================+=============================================================================+
| value_type & operator() (size_t ... i) | Element access: Must have exactly rank argument (checked at compiled time). |
================================================================================================== ============================================================================= +----------------------------------------------+-----------------------------------------------------------------------------+
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** : * **Examples** :
* array, array_view, matrix, matrix_view, vector, vector_view. * 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:
ImmutableMatrix ImmutableMatrix
------------------------------------------------------------------- -------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that : * Refines :ref:`ImmutableCuboidArray`
* the rank of the domain must be 2 * If A is the type :
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableMatrix).
* ImmutableMatrix<A> == true_type
* A::domain_type::rank ==2
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
.. _ImmutableVector: .. _ImmutableVector:
ImmutableVector ImmutableVector
------------------------------------------------------------------- -------------------------------------------------------------------
Same as :ref:`ImmutableCuboidArray`, except that : * Refines :ref:`ImmutableCuboidArray`
* the rank of the domain must be 1 * If A is the type :
* the class must derive from TRIQS_CONCEPT_TAG_NAME(ImmutableVector).
* 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:
MutableMatrix MutableMatrix
------------------------------------------------------------------- -------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that : * Refines :ref:`MutableCuboidArray`
* the rank of the domain must be 2 * If A is the type :
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableMatrix).
* 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:
MutableVector MutableVector
------------------------------------------------------------------- -------------------------------------------------------------------
Same as :ref:`MutableCuboidArray`, except that : * Refines :ref:`MutableCuboidArray`
* the rank of the domain must be 1 * If A is the type :
* the class must derive from TRIQS_CONCEPT_TAG_NAME(MutableVector).
* 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] Why concepts ? [Advanced]
@ -153,7 +191,7 @@ Example :
#include <iostream> #include <iostream>
namespace triqs { namespace arrays { // better to put it in this namespace for ADL... 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 array_view<T,1> data; // the diagonal stored as a 1d array
@ -167,8 +205,12 @@ Example :
typedef T value_type; typedef T value_type;
T operator()(size_t i, size_t j) const { return (i==j ? data(i) : 0);} // just kronecker... 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 /// TESTING

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

@ -1,6 +1,6 @@
.. highlight:: c .. highlight:: c
.. _arr_reg_call: .. _arr_call:
Operator() Operator()
================================== ==================================
@ -15,6 +15,9 @@ Operator()
`clef expression` operator()( `at least a lazy argument` ) const (3) `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: .. _arr_element_access:
(1) 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.

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

@ -5,55 +5,40 @@
Assignment 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`. 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:: * (1) just make a copy of X.
template<typename RHS> array & operator=(const RHS & X); * (2) **RHS** can be anything that models the :ref:`ImmutableCuboidArray` concept
template<typename RHS> array_view & operator=(const RHS & X);
* **What can be RHS ?** e.g. : array, array_view, matrix, matrix_view,
but also formal expression (See , e.g. A+B), or any custom object of your choice.
RHS can be ... anything that models the :ref:`ImmutableCuboidArray` concept ! `Effect` : all the elements viewed by the view are replaced
by the evaluation of RHS.
e.g. : array, array_view, matrix, matrix_view, .. warning::
but also formal expression (See , e.g. A+B), or any custom object of your choice.
* **Behaviour** In both cases, if needed, the container is resized.
================= ======================================================================= ====================================================================================== Hence **assignment invalidates all pointers and views to it**.
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.
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). * 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. Hence, all these constructors make a **copy** of the data, except of course the move constructor.
========================================== =========================================================================================== +---------------------------------+------------------------------------------------------------------------------------------+
Constructors of array Comments | Constructors of array | Comments |
========================================== =========================================================================================== +=================================+==========================================================================================+
array() Empty array of size 0 | array() | Empty array of size 0 |
------------------------------------------ ------------------------------------------------------------------------------------------- +---------------------------------+------------------------------------------------------------------------------------------+
array(size_t, ...., size_t) From the lengths of the array dimensions, with Rank arguments (checked at compile time). | array(size_t, ...., size_t) | From the lengths of the array dimensions, with Rank arguments (checked at compile time). |
------------------------------------------ ------------------------------------------------------------------------------------------- +---------------------------------+------------------------------------------------------------------------------------------+
array(const array &) Copy construction | array(const array &) | Copy construction |
------------------------------------------ ------------------------------------------------------------------------------------------- +---------------------------------+------------------------------------------------------------------------------------------+
array(array &&) Move construction | array(array &&) | Move construction |
------------------------------------------ ------------------------------------------------------------------------------------------- +---------------------------------+------------------------------------------------------------------------------------------+
array(const T & X) Type T models the :ref:`ImmutableCuboidArray` concept. | array(const T & X) | Type T models the :ref:`ImmutableCuboidArray` concept. |
| | - X must have the appropriate domain (checked at compile time). |
- X must have the appropriate domain (checked at compile time). | | - Constructs a new array of domain X.domain() and fills it with evaluation of X. |
- Constructs a new array of domain X.domain() and fills it with evaluation of X. +---------------------------------+------------------------------------------------------------------------------------------+
------------------------------------------ ------------------------------------------------------------------------------------------- | array(shape_t const &) | New array with the corresponding shape (as returned by the function shape. See example |
array(shape_t const &) New array with the corresponding shape (as returned by the function shape. See example | | in section XXX). |
in section XXX). +---------------------------------+------------------------------------------------------------------------------------------+
------------------------------------------ ------------------------------------------------------------------------------------------- | array(std::initializer_list<T>) | Initialization from a initializer_list of T. Enable for rank==1 only |
array(PyObject * X) Construct a new array from the Python object X. +---------------------------------+------------------------------------------------------------------------------------------+
| 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++. | | - it takes a **copy** of the data of X (or of numpy(X)) into C++. |
- X is first transformed into a numpy by the python numpy lib itself | | - X is first transformed into a numpy by the python numpy lib itself |
(as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type | | (as if you call numpy.array(X)) if X is not a numpy array or an array of the wrong type |
(e.g. you construct an array<double,2> from a numpy of int....), and | | (e.g. you construct an array<double,2> from a numpy of int....), and |
copied into the array. | | copied into the array. |
.. note:: X is a borrowed reference, array does not affect its counting reference. | | .. note:: X is a borrowed reference, array does not affect its counting reference. |
========================================== =========================================================================================== +---------------------------------+------------------------------------------------------------------------------------------+
.. warning:: .. warning::
The constructor from the dimensions does **NOT** initialize the array to 0 The constructor from the dimensions does **NOT** initialize the array to 0

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

@ -7,9 +7,9 @@ array, matrix & vector
.. code-block:: c .. code-block:: c
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;
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;
template <typename ValueType, ull_t OptionsFlags=0> class vector; template <typename ValueType, ull_t OptionsFlags=0> class vector;
where triqs::ull_t is the type defined by : 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 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. 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 parameters
---------------------------- ----------------------------
============================ ============================== ========================== ==================================================================== +-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
Template parameter Accepted type Access in the class Meaning | 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 | ValueType | any regular type (typically a | value_type | The type of the element of the array |
scalar). | | scalar). | | |
Rank int rank The rank of the array +-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
OptionsFlags ull_t Compile time options, see below. | Rank | int | rank | The rank of the array |
TraversalOrder ull_t Compile time options, see below. +-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
============================ ============================== ========================== ==================================================================== | :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. .. toctree::
The possible flags are accessible via a constexpr ull_t in triqs::arrays or a macro : :hidden:
======================== =======================================
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.
template_parameters
Member types Member types
----------------- --------------------------------------
=================== ====================================== +--------------+----------------------------------------------------------+
Member type Definitions | Member type | Definitions |
=================== ====================================== +==============+==========================================================+
value_type ValueType | value_type | ValueType |
view_type The corresponding view type +--------------+----------------------------------------------------------+
| view_type | The corresponding view type |
+--------------+----------------------------------------------------------+
| regular_type | The corresponding regular type i.e. the container itself |
+--------------+----------------------------------------------------------+
=================== ====================================== Member constexpr
--------------------------------------
+--------+------+-------------------------------+
| Member | Type | Definitions |
+========+======+===============================+
| rank | int | Rank of the container (Rank |
| | | for array), 2 for matrix, 1 |
| | | for vector |
+--------+------+-------------------------------+
Member functions Member functions
--------------------- ---------------------
============================================= ============================================== +-------------------------------------------+------------------------------------------+
Member function Meaning | Member function | Meaning |
============================================= ============================================== +===========================================+==========================================+
:ref:`(constructor)<arr_reg_constr>` | :ref:`(constructor)<arr_reg_constr>` | |
(destructor) +-------------------------------------------+------------------------------------------+
:ref:`operator =<arr_reg_assign>` assigns values to the container | (destructor) | |
:ref:`operator ()<arr_reg_call>` element of access/views/lazy expressions +-------------------------------------------+------------------------------------------+
| :ref:`operator =<arr_reg_assign>` | assigns values to the container |
+-------------------------------------------+------------------------------------------+
begin/cbegin returns iterator to the beginning | :ref:`operator +=,-=,*=,/=<arr_comp_ops>` | compound assignment operators |
end/cend returns iterator to the end +-------------------------------------------+------------------------------------------+
:ref:`resize<arr_resize>` resize the container | :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:: .. toctree::
@ -122,6 +108,7 @@ end/cend returns iterator to the end
reg_constructors reg_constructors
reg_assign reg_assign
comp_ops
call call
resize resize
STL STL
@ -130,17 +117,19 @@ Non-member functions
------------------------ ------------------------
============================================= ============================================== +---------------------------------+-------------------------------------------+
Member function Meaning | Member function | Meaning |
============================================= ============================================== +=================================+===========================================+
:ref:`swap<arr_swap>` | :ref:`swap<arr_swap>` | Swap of 2 containers |
:ref:`deep_swap<arr_deep_swap>` +---------------------------------+-------------------------------------------+
| :ref:`deep_swap<arr_deep_swap>` | Deep swap of the data of 2 containers ??? |
============================================= ============================================== +---------------------------------+-------------------------------------------+
| :ref:`operator\<\<<arr_stream>` | Writing to stream |
+---------------------------------+-------------------------------------------+
.. toctree:: .. toctree::
:hidden: :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

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

@ -9,9 +9,9 @@ Views
.. code-block:: c .. code-block:: c
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array_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, ull_t TraversalOrder=0> class matrix_view;
template <typename ValueType, ull_t OptionsFlags=0> class vector_view; template <typename ValueType, ull_t OptionsFlags=0> class vector_view;
where triqs::ull_t is the type defined by : 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; 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. * 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, * The views model the :ref:`MutableCuboidArray`, :ref:`MutableMatrix`, :ref:`MutableVector`, like the corresponding regular type.
dressed to model the "`MutableX`" concept.
* A view class behaves like the value class when called, put in expression, ... * Views have `view semantics`, i.e. their behave like a reference to the data, they are not regular type.
but differs from it by its behaviour under copy and assignment. In particular, they never make copy of the data.
It has a reference semantics : like a pointer or a reference, it does not make a deep copy of the data See :ref:`view_vs_regular` for a detailed discussion of the difference between a regular type and its corresponding view.
when copied. See :ref:`view_vs_regular` for a detailed discussion of the difference between array and array_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**
====================================================================== ===================================================================================================== Views offers a strong guarantee of the existence of the data, like a std::shared_ptr.
Constructors of array_view Comments Cf :ref:`arr_view_memory` for details.
====================================================================== =====================================================================================================
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 ....
====================================================================== =====================================================================================================
Template parameters
----------------------------
Memory management +-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+
| 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 view_or_not_view
lazy lazy
foreach foreach
simple_fnt
map map
mapped_fnt
algebras algebras
move_swap move_swap
play_with_concept
blas_lapack blas_lapack
H5 H5
Interop_Python 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 foreach and its variants are a compact and efficient way to
perform some action of the kind 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 While this kind of construct is equivalent to write manually the *for* loops, it has

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

@ -1,5 +1,7 @@
.. highlight:: c .. highlight:: c
.. _arr_map_fold:
Functional constructs : map & fold Functional constructs : map & fold
########################################### ###########################################
@ -28,16 +30,14 @@ map
Then map(f) is a function:: Then map(f) is a function::
ReturnType map(f) ( ArrayType const & A) template<ImmutableCuboidArray A> auto map(f) (A const &)
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 * with the same domain as A
* with value_type == ValueType2
and ReturnType models the :ref:`ImmutableCuboidArray` concept
* with the same domain as ArrayType
* 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) , * 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 :: or the compiler does not know which std::abs you are talking about ::
@ -51,7 +51,7 @@ map
.. compileblock:: .. compileblock::
#include <triqs/arrays.hpp> #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() { int main() {
// declare and init a matrix // declare and init a matrix
placeholder<0> i_; placeholder<1> j_; placeholder<0> i_; placeholder<1> j_;
@ -60,14 +60,10 @@ map
// the mapped function // the mapped function
auto F = triqs::arrays::map([](int i) { return i*2.5;}); auto F = triqs::arrays::map([](int i) { return i*2.5;});
matrix<double> B; std::cout<< "A = " << A << std::endl;
B = F(A); std::cout<< "F(A) = " << F(A) << std::endl; // oops no computation done
std::cout<< A << B<< std::endl; std::cout<< "F(A) = " << make_matrix(F(A)) << std::endl;
std::cout<< "3*F(2*A) = " << make_matrix(3*F(2*A)) << 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;
} }
@ -112,12 +108,12 @@ fold
Many algorithms can be written in form of map/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 The function :ref:`arr_fnt_sum` which returns the sum of all the elements of the array is implemented as ::
(this function already exists in the lib, cf ???) ::
template <class A> template <class A>
typename A::value_type sum(A const & a) { return fold ( std::plus<typename A::value_type>()) (a); } typename A::value_type sum(A const & a) { return fold ( std::plus<typename A::value_type>()) (a); }
Note in this example : Note in this example :
* the simplicity of the code * 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 mctools/intro
det_manip/det_manip det_manip/det_manip
parameters/parameters parameters/parameters
lectures/contents
utilities/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; double beta=10;
int Nfreq =100; 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 // or even simpler
auto GF2 = make_gf<imfreq>({beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1)); auto GF2 = make_gf<imfreq>({beta,Fermion,Nfreq}, make_shape(1,1), local::tail(1,1));
} }