3
0
mirror of https://github.com/triqs/dft_tools synced 2024-12-25 13:53:40 +01:00
dft_tools/doc/reference/c++/arrays/map.rst
Olivier Parcollet 3fe400d34c doc : split c++ code from rst
- examples split from the rst file using a python script (split_code).
- Final result for the doc is unchanged.
- examples are compiled and tested with the other tests.
- examples' code have been clang-formatted, with triqs style.
- doc compiles much faster, and with the same options as the rest of the
  test.
- examples are added as tests, so they are run by make test, as simple C
  tests.
- done for the tutorials and the reference.
- autocompile removed (changed into triqs_example directive).
- add triqs_example :
   - make a literal include of the source code.
   - runs the compiled example
   - add, as before, the result to the source code in the doc.
- added the script split_code, used to make the changes automatically,
  maybe for later reuse. (in _tools)
2014-05-31 23:00:16 +02:00

113 lines
2.6 KiB
ReStructuredText

.. highlight:: c
.. _arr_map_fold:
Functional constructs : map & fold
###########################################
Two standard functional constructs are provided :
* *map* that promotes a function acting on the array element to an array function, acting
element by element.
* *fold* is the reduction of a function on the array.
.. _map:
map
========================================================
* **Purpose** :
map promotes any function into an `array function`, acting term by term.
* **Synopsis** ::
template<class F> auto map (F f);
If `f` is a function, or a function object ::
T2 f(T1)
Then map(f) is a function::
template<ImmutableCuboidArray A> auto map(f) (A const &)
with :
* A::value_type == T1
* The returned type of map(f) models the :ref:`ImmutableCuboidArray` concept
* with the same domain as A
* with value_type == T2
* **Example** :
.. triqs_example:: ./map_0.cpp
fold
========================================================
* **Purpose** :
fold implements the folding (or reduction) on the array.
* **Syntax** :
If `f` is a function, or a function object of synopsis (T, R being 2 types) ::
R f (R , T)
then ::
auto F = fold(f);
is a callable object which can fold any array of value_type T.
So, if
* A is a type which models the :ref:`ImmutableCuboidArray` concept
(e.g. an array , a matrix, a vector, an expression, ...)
* A::value_type is T
then ::
fold (f) ( A, R init = R() ) = f(f(f(f(init, a(0,0)), a(0,1)),a(0,2)),a(0,3), ....)
Note that :
* The order of traversal is the same as foreach.
* The precise return type of fold is an implementation detail, depending on the precise type of f,
use auto to keep it.
* The function f will be inlined if possible, leading to efficient algorithms.
* fold is implemented using a foreach loop, hence it is efficient.
* **Example** :
Many algorithms can be written in form of map/fold.
The function :ref:`arr_fnt_sum` which returns the sum of all the elements of the array is implemented as ::
template <class A>
typename A::value_type sum(A const & a) { return fold ( std::plus<>()) (a); }
or the Frobenius norm of a matrix,
.. math::
\sum_{i=0}^{N-1} \sum_{j=0}^{N-1} | a_{ij} | ^2
reads :
.. triqs_example:: ./map_1.cpp
Note in this example :
* the simplicity of the code
* the genericity : it is valid for any dimension of array.
* internally, the library will rewrite it as a series of for loop, ordered in the TraversalOrder of the array
and inline the lambda.