From d6c74f95c5c7d4d72d6d2652d900819548d07d9a Mon Sep 17 00:00:00 2001 From: Olivier Parcollet Date: Tue, 27 Aug 2013 19:17:17 +0200 Subject: [PATCH] Work on doc --- doc/install.rst | 26 ++- doc/installation/clang.rst | 43 ++-- doc/installation/install_options.rst | 62 +----- doc/installation/osx_lion.rst | 13 +- doc/installation/python.rst | 3 +- doc/installation/requirements.rst | 62 +++--- doc/installation/ubuntu.rst | 7 +- doc/reference/c++/arrays/algebras.rst | 79 ++++---- doc/reference/c++/arrays/concepts.rst | 118 +++++++---- doc/reference/c++/arrays/containers/call.rst | 7 +- .../c++/arrays/containers/compound_ops.rst | 16 ++ .../c++/arrays/containers/memory.rst | 63 ++++++ .../c++/arrays/containers/rebind.rst | 18 ++ .../c++/arrays/containers/reg_assign.rst | 83 ++++---- .../arrays/containers/reg_constructors.rst | 56 +++--- .../c++/arrays/containers/regular.rst | 153 +++++++------- .../c++/arrays/containers/stream.rst | 23 +++ .../arrays/containers/template_parameters.rst | 51 +++++ .../c++/arrays/containers/view_assign.rst | 61 ++++++ .../arrays/containers/view_constructors.rst | 45 +++++ doc/reference/c++/arrays/containers/views.rst | 186 +++++++++++------- doc/reference/c++/arrays/contents.rst | 3 +- doc/reference/c++/arrays/foreach.rst | 2 +- doc/reference/c++/arrays/map.rst | 38 ++-- doc/reference/c++/arrays/mapped_fnt.rst | 41 ---- .../c++/arrays/play_with_concept.rst | 59 ++++++ doc/reference/c++/arrays/simple_fnt.rst | 70 +++++++ doc/reference/c++/contents.rst | 1 - doc/reference/c++/gf/gf_imfreq.rst | 2 +- 29 files changed, 887 insertions(+), 504 deletions(-) create mode 100644 doc/reference/c++/arrays/containers/compound_ops.rst create mode 100644 doc/reference/c++/arrays/containers/memory.rst create mode 100644 doc/reference/c++/arrays/containers/rebind.rst create mode 100644 doc/reference/c++/arrays/containers/stream.rst create mode 100644 doc/reference/c++/arrays/containers/template_parameters.rst create mode 100644 doc/reference/c++/arrays/containers/view_assign.rst create mode 100644 doc/reference/c++/arrays/containers/view_constructors.rst delete mode 100644 doc/reference/c++/arrays/mapped_fnt.rst create mode 100644 doc/reference/c++/arrays/play_with_concept.rst create mode 100644 doc/reference/c++/arrays/simple_fnt.rst diff --git a/doc/install.rst b/doc/install.rst index 0e8736cd..558696f0 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -10,8 +10,10 @@ Installation Prerequisite ------------ -The TRIQS library relies on a certain number of standard libraries described in -the :ref:`list of 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 `. Beware in particular to the :ref:`C++ compilers` +and to :ref:`Scientific Python tools`. +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`. + #. 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 + diff --git a/doc/installation/clang.rst b/doc/installation/clang.rst index 090f9222..9c35e15a 100644 --- a/doc/installation/clang.rst +++ b/doc/installation/clang.rst @@ -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 `_, +use it. Just untar them, and add the directory in your path. -If you have precompiled version in the `LLVM dowload page `_, -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 `_. 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. diff --git a/doc/installation/install_options.rst b/doc/installation/install_options.rst index 1fd54531..ffbd5b9d 100644 --- a/doc/installation/install_options.rst +++ b/doc/installation/install_options.rst @@ -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 diff --git a/doc/installation/osx_lion.rst b/doc/installation/osx_lion.rst index 2d6da7a9..900d6e60 100644 --- a/doc/installation/osx_lion.rst +++ b/doc/installation/osx_lion.rst @@ -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 diff --git a/doc/installation/python.rst b/doc/installation/python.rst index 8db52f03..2a806202 100644 --- a/doc/installation/python.rst +++ b/doc/installation/python.rst @@ -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 diff --git a/doc/installation/requirements.rst b/doc/installation/requirements.rst index 9d0a75b4..c43c4aaa 100644 --- a/doc/installation/requirements.rst +++ b/doc/installation/requirements.rst @@ -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` 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 diff --git a/doc/installation/ubuntu.rst b/doc/installation/ubuntu.rst index a1fd8539..ad7ca91d 100644 --- a/doc/installation/ubuntu.rst +++ b/doc/installation/ubuntu.rst @@ -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 ` to the latest version? + * How to *simply* upgrade the ipython notebook and Cython with :ref:`virtualenv ` to the latest version? - * How to use the nice :ref:`clang ` C++ compiler? + * How to use the nice and recommended :ref:`clang ` C++ compiler? - * How to use :ref:`Intel ` C++ compiler? +.. + * How to use :ref:`Intel ` 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. diff --git a/doc/reference/c++/arrays/algebras.rst b/doc/reference/c++/arrays/algebras.rst index c25e834c..0abeb66c 100644 --- a/doc/reference/c++/arrays/algebras.rst +++ b/doc/reference/c++/arrays/algebras.rst @@ -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 - using triqs::arrays::array; + using triqs::arrays::array; using triqs::clef::placeholder; int main() { - array A (2,2), B(2,2), C; - C= A + 2*B; - array D = A+ 2*B; - array F = 0.5 * A; // Type promotion is automatic + // init + placeholder<0> i_; placeholder<1> j_; + array A (2,2), B(2,2); + A(i_,j_) << i_ + j_ ; + B(i_,j_) << i_ - j_ ; + + // use expressions + array C = A+ 2*B; + array 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 A; - matrix 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 + using namespace triqs::arrays; + int main() { + array A(2,2); matrix 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 array & operator += (const RHS & X); - template array & operator -= (const RHS & X); - template array & operator *= (const Scalar & S); - template 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 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. - diff --git a/doc/reference/c++/arrays/concepts.rst b/doc/reference/c++/arrays/concepts.rst index 09b77200..a964efe2 100644 --- a/doc/reference/c++/arrays/concepts.rst +++ b/doc/reference/c++/arrays/concepts.rst @@ -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 | 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 == 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 == 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 == 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 == true_type + * MutableArray == 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 == true_type + * MutableMatrix == 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 == true_type + * MutableMatrix == 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 namespace triqs { namespace arrays { // better to put it in this namespace for ADL... - template class immutable_diagonal_matrix_view : TRIQS_CONCEPT_TAG_NAME(ImmutableMatrix) { + template class immutable_diagonal_matrix_view { array_view 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 "< struct ImmutableMatrix> : std::true_type{}; }} /// TESTING diff --git a/doc/reference/c++/arrays/containers/call.rst b/doc/reference/c++/arrays/containers/call.rst index e27e46c2..e43bb290 100644 --- a/doc/reference/c++/arrays/containers/call.rst +++ b/doc/reference/c++/arrays/containers/call.rst @@ -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 diff --git a/doc/reference/c++/arrays/containers/compound_ops.rst b/doc/reference/c++/arrays/containers/compound_ops.rst new file mode 100644 index 00000000..6fe49d29 --- /dev/null +++ b/doc/reference/c++/arrays/containers/compound_ops.rst @@ -0,0 +1,16 @@ +.. highlight:: c + +.. _arr_comp_ops: + +Compound assignment operators (+=, -=, * =, /=) +------------------------------------------------- + +**Synopsis** :: + + template THIS_TYPE & operator += (const RHS & X); + template THIS_TYPE & operator -= (const RHS & X); + template THIS_TYPE & operator *= (const Scalar & S); + template THIS_TYPE & operator /= (const Scalar & S); + +The containers and the view have compound operators. + diff --git a/doc/reference/c++/arrays/containers/memory.rst b/doc/reference/c++/arrays/containers/memory.rst new file mode 100644 index 00000000..aa1190fd --- /dev/null +++ b/doc/reference/c++/arrays/containers/memory.rst @@ -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 *p = new array (2,3); // create an array p + array_view B = *p; // making a view + delete p; // p is gone... + B(0,0) = 314; cout<) + the reference counting is again incremented, and the memory guarantee holds. + +* Explicit construction of weak views is intentionally not documented here. + It is designed to be (almost) an implementation detail. + +* The () operator returns a weak view `on a 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 + + + + + diff --git a/doc/reference/c++/arrays/containers/rebind.rst b/doc/reference/c++/arrays/containers/rebind.rst new file mode 100644 index 00000000..4ee9be50 --- /dev/null +++ b/doc/reference/c++/arrays/containers/rebind.rst @@ -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 `, if nothing else views the + data originally pointed to by the view, this data is destroyed. + + diff --git a/doc/reference/c++/arrays/containers/reg_assign.rst b/doc/reference/c++/arrays/containers/reg_assign.rst index 9a4be1b0..c6a55fca 100644 --- a/doc/reference/c++/arrays/containers/reg_assign.rst +++ b/doc/reference/c++/arrays/containers/reg_assign.rst @@ -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 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 array & operator=(const RHS & X); - template 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 array & operator += (const RHS & X); - template array & operator -= (const RHS & X); - template array & operator *= (const Scalar & S); - template 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`. diff --git a/doc/reference/c++/arrays/containers/reg_constructors.rst b/doc/reference/c++/arrays/containers/reg_constructors.rst index a18356ae..a4b4676a 100644 --- a/doc/reference/c++/arrays/containers/reg_constructors.rst +++ b/doc/reference/c++/arrays/containers/reg_constructors.rst @@ -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 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) | 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 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 diff --git a/doc/reference/c++/arrays/containers/regular.rst b/doc/reference/c++/arrays/containers/regular.rst index 9871dbb3..ce19b875 100644 --- a/doc/reference/c++/arrays/containers/regular.rst +++ b/doc/reference/c++/arrays/containers/regular.rst @@ -7,9 +7,9 @@ array, matrix & vector .. code-block:: c - template class array; - template class matrix; - template class vector; + template class array; + template class matrix; + template 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` | ull_t | opt_flags | Compile time options | ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ +| :ref:`TraversalOrder` | 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)` -(destructor) -:ref:`operator =` assigns values to the container -:ref:`operator ()` element of access/views/lazy expressions - - -begin/cbegin returns iterator to the beginning -end/cend returns iterator to the end -:ref:`resize` resize the container - -============================================= ============================================== ++-------------------------------------------+------------------------------------------+ +| Member function | Meaning | ++===========================================+==========================================+ +| :ref:`(constructor)` | | ++-------------------------------------------+------------------------------------------+ +| (destructor) | | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator =` | assigns values to the container | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator +=,-=,*=,/=` | compound assignment operators | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator ()` | element of access/views/lazy expressions | ++-------------------------------------------+------------------------------------------+ +| begin/cbegin | returns iterator to the beginning | ++-------------------------------------------+------------------------------------------+ +| end/cend | returns iterator to the end | ++-------------------------------------------+------------------------------------------+ +| :ref:`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` -:ref:`deep_swap` - -============================================= ============================================== ++---------------------------------+-------------------------------------------+ +| Member function | Meaning | ++=================================+===========================================+ +| :ref:`swap` | Swap of 2 containers | ++---------------------------------+-------------------------------------------+ +| :ref:`deep_swap` | Deep swap of the data of 2 containers ??? | ++---------------------------------+-------------------------------------------+ +| :ref:`operator\<\<` | Writing to stream | ++---------------------------------+-------------------------------------------+ .. toctree:: :hidden: - swap + stream diff --git a/doc/reference/c++/arrays/containers/stream.rst b/doc/reference/c++/arrays/containers/stream.rst new file mode 100644 index 00000000..2f6d3d09 --- /dev/null +++ b/doc/reference/c++/arrays/containers/stream.rst @@ -0,0 +1,23 @@ +.. highlight:: c + +.. _arr_stream: + +operator << +================================== + +**Synopsis**:: + + template + std::ostream & operator << (std::ostream & out, array_view const &); + + template + std::ostream & operator << (std::ostream & out, matrix_view const &); + + template + std::ostream & operator << (std::ostream & out, vector_view const &); + +Prints the view (or the container since the view is trivially build from the container) +to the stream out. + + + diff --git a/doc/reference/c++/arrays/containers/template_parameters.rst b/doc/reference/c++/arrays/containers/template_parameters.rst new file mode 100644 index 00000000..4f5dad4c --- /dev/null +++ b/doc/reference/c++/arrays/containers/template_parameters.rst @@ -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. + + + diff --git a/doc/reference/c++/arrays/containers/view_assign.rst b/doc/reference/c++/arrays/containers/view_assign.rst new file mode 100644 index 00000000..15189f37 --- /dev/null +++ b/doc/reference/c++/arrays/containers/view_assign.rst @@ -0,0 +1,61 @@ +.. highlight:: c + +.. _arr_view_assign: + +Assignment to views +========================= + +**Synopsis** : + + template + 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` 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 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. diff --git a/doc/reference/c++/arrays/containers/view_constructors.rst b/doc/reference/c++/arrays/containers/view_constructors.rst new file mode 100644 index 00000000..90a051b1 --- /dev/null +++ b/doc/reference/c++/arrays/containers/view_constructors.rst @@ -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`. + +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 diff --git a/doc/reference/c++/arrays/containers/views.rst b/doc/reference/c++/arrays/containers/views.rst index d0ecb5d5..cd52a9e3 100644 --- a/doc/reference/c++/arrays/containers/views.rst +++ b/doc/reference/c++/arrays/containers/views.rst @@ -9,9 +9,9 @@ Views .. code-block:: c - template class array_view; - template class matrix_view; - template class vector_view; + template class array_view; + template class matrix_view; + template 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` | ull_t | opt_flags | Compile time options | ++-----------------------------------------+-------------------------------+-------------------------------+--------------------------------------+ +| :ref:`TraversalOrder` | 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)` | | ++-------------------------------------------+------------------------------------------+ +| (destructor) | | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator =` | assigns values to the container | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator +=,-=,*=,/=` | compound assignment operators | ++-------------------------------------------+------------------------------------------+ +| :ref:`operator ()` | element of access/views/lazy expressions | ++-------------------------------------------+------------------------------------------+ +| begin/cbegin | returns iterator to the beginning | ++-------------------------------------------+------------------------------------------+ +| end/cend | returns iterator to the end | ++-------------------------------------------+------------------------------------------+ +| :ref:`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 *p = new array (2,3); // create an array p - array_view B = *p; // making a view - delete p; // p is gone... - B(0,0) = 314; cout<) - the reference counting is again incremented, and the memory guarantee holds. - -* Explicit construction of weak views is intentionally not documented here. - It is designed to be (almost) an implementation detail. - -* The () operator returns a weak view `on a modern C++11 compiler`, - allowing therefore for better performance on such compiler, in some loops. - (in particular, `rvalue reference for *this` must be implemented). - -* It is however necessary for the advanced user to know about this implementation detail, - because in some convolved cases, the memory guarantee may not hold. - Example : ++---------------------------------+-------------------------------------------+ +| Member function | Meaning | ++=================================+===========================================+ +| :ref:`swap` | Swap of 2 containers | ++---------------------------------+-------------------------------------------+ +| :ref:`deep_swap` | Deep swap of the data of 2 containers ??? | ++---------------------------------+-------------------------------------------+ +| :ref:`operator\<\<` | Writing to stream | ++---------------------------------+-------------------------------------------+ +.. toctree:: + :hidden: + stream diff --git a/doc/reference/c++/arrays/contents.rst b/doc/reference/c++/arrays/contents.rst index 7fad9f58..aee45891 100644 --- a/doc/reference/c++/arrays/contents.rst +++ b/doc/reference/c++/arrays/contents.rst @@ -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 diff --git a/doc/reference/c++/arrays/foreach.rst b/doc/reference/c++/arrays/foreach.rst index 9f3d81c0..4294409e 100644 --- a/doc/reference/c++/arrays/foreach.rst +++ b/doc/reference/c++/arrays/foreach.rst @@ -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 diff --git a/doc/reference/c++/arrays/map.rst b/doc/reference/c++/arrays/map.rst index 86766357..5407e68a 100644 --- a/doc/reference/c++/arrays/map.rst +++ b/doc/reference/c++/arrays/map.rst @@ -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 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 - 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 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 typename A::value_type sum(A const & a) { return fold ( std::plus()) (a); } + + Note in this example : * the simplicity of the code diff --git a/doc/reference/c++/arrays/mapped_fnt.rst b/doc/reference/c++/arrays/mapped_fnt.rst deleted file mode 100644 index 773f9c9c..00000000 --- a/doc/reference/c++/arrays/mapped_fnt.rst +++ /dev/null @@ -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 - using triqs::arrays::matrix; using triqs::clef::placeholder; - - int main(){ - placeholder<0> i_; placeholder<1> j_; - matrix A(2,2); - A(i_,j_) << i_ - j_ ; - - std::cout << "A = "<