3
0
mirror of https://github.com/triqs/dft_tools synced 2024-12-25 05:43:40 +01:00

Restructuring documentation.

A first general restructuration of the doc according to the pattern [tour|tutorial|reference].
In the reference part, objects are documented per topic.
In each topic, [definition|c++|python|hdf5] (not yet implemented)
This commit is contained in:
tayral 2014-10-17 17:15:19 +01:00
parent a9e5f20c39
commit edd1ff4529
316 changed files with 519 additions and 696 deletions

View File

@ -53,8 +53,9 @@ ENDFOREACH()
endmacro()
# Dive and find the doxygen sources
add_subdirectory(reference/c++)
add_subdirectory(tutorials/c++)
add_subdirectory(reference/)
add_subdirectory(tutorials/)
add_subdirectory(tour/)
# Build the doxygen
set(DOXYGEN_HTML_OUTPUT ./html/doxy_triqs)

View File

@ -124,7 +124,7 @@ pygments_style = 'sphinx'
# Options for doxylink extension
# -----------------------------
doxylink = { 'doxy' : ('@CMAKE_CURRENT_BINARY_DIR@/doxy.tag', 'doxy_triqs') }
doxylink = { 'doxy': ('@CMAKE_CURRENT_BINARY_DIR@/doxy.tag', 'doxy_triqs') }
# Options for HTML output
@ -146,7 +146,7 @@ html_context = {'header_title': 'triqs',
['About TRIQS', 'about']
]}
#html_theme_options = { "pagewidth": "80em", "documentwidth" : "60em" }
#html_theme_options = { "pagewidth": "80em", "documentwidth": "60em" }
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".

View File

@ -6,22 +6,68 @@ Documentation
A quick tour
------------
A little tour of some aspects of TRIQS and its applications, at the Python level.
.. toctree::
:maxdepth: 1
tutorials/python/contents
tutorials/c++/contents
tour/getting_started/get_started
tour/green
tour/tight_binding
tour/ctqmc
tour/dmft
tour/ipt
Tutorials
----------
Learn how to use TRIQS step by step, both in Python and c++ !
.. toctree::
:maxdepth: 1
tutorials/gfs_tutorial
tutorials/array_tutorial
tutorials/det_manip_tutorial
Reference manual
-----------------
This is the reference manual for the Python and the C++ libraries.
.. toctree::
:maxdepth: 1
reference/using_the_lib/contents
Code reference
~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
reference/gfs/contents
reference/lattice_tools/contents
reference/plotting_protocols/contents
reference/montecarlo/contents
reference/operators/contents
reference/random_generator/contents
reference/arrays/contents
reference/clef/contents
reference/hdf5/contents
reference/determinant_manipulation/contents
reference/statistical_analysis/contents
Developer tools
~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 2
:maxdepth: 1
reference/python/contents
reference/c++/contents
reference/conventions
reference/using_the_lib/profiling
reference/wrap_generator/contents
reference/utilities/contents
Version compatibility
---------------------

View File

@ -1,4 +1 @@
add_all_subdirectories_with_cmakelist()

View File

@ -7,7 +7,7 @@ How do I iterate on my array ?
-----------------------------------
There are different way to iterate on the element of an array, recommended in this order from the most simple/efficient to the most complex/slow :
There are different way to iterate on the element of an array, recommended in this order from the most simple/efficient to the most complex/slow:
* To assign data into an array, the simplest and efficient way is to use
automatic assignment with lazy expressions, Cf :ref:`Lazy`.

View File

@ -1,6 +1,6 @@
.. highlight:: c
Operations : array and matrix/vector algebras
Operations: array and matrix/vector algebras
=======================================================
Arithmetic operations
@ -36,8 +36,8 @@ The principle is that the result of A+B is **NOT** an array, but a more complex
the expression using the naturally recursive structure of templates.
Expressions models :ref:`ImmutableCuboidArray` concept.
They behave like an immutable array : they have a domain, they can be evaluated.
Hence they can used *anywhere* an object modeling this concept is accepted, e.g. :
They behave like an immutable array: they have a domain, they can be evaluated.
Hence they can used *anywhere* an object modeling this concept is accepted, e.g.:
* array, matrix contruction
* operator =, +=, -=, ...
@ -58,8 +58,8 @@ instead of making a chain of temporaries (C/2, 2*B, 2*B + C/2...) that "ordinary
As a result, the produced code is as fast as if you were writing the loop yourself,
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** :
* 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**:
* What you want is to tell the compiler/library to compute this expression, not *how* to do it optimally on a given machine.
* For example, since the traversal order of indices is decided at compile time, the library can traverse the data

View File

@ -23,7 +23,7 @@ matrix product
The * operator map the matrix x matrix and matrix x vector product.
Example : matrix * matrix and * vector ...
Example: matrix * matrix and * vector ...
.. triqs_example:: ./blas_lapack_0.cpp
For types that lapack do not use, a generic version of the matrix product is provided.
@ -36,7 +36,7 @@ Matrix inversion
The inverse function return a lazy inverse of any object which has ImmutableMatrix concept
and can therefore be mixed with any other matrix expression.
Example : TO BE WRITTEN
Example: TO BE WRITTEN
LU decomposition

View File

@ -35,14 +35,14 @@ object, without side effects.
ImmutableCuboidArray
----------------------------
* **Purpose** :
* **Purpose**:
The most abstract definition of something that behaves like an immutable array on a cuboid domain.
* it has a cuboid domain (hence a rank).
* it can be evaluated on any value of the indices in the domain
* NB : It does not need to be stored in memory. For example, a formal expression models this concept.
* NB: It does not need to be stored in memory. For example, a formal expression models this concept.
* **Definition** ([...] denotes something optional).
@ -58,7 +58,7 @@ ImmutableCuboidArray
| 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 expressions.
@ -67,8 +67,8 @@ ImmutableCuboidArray
MutableCuboidArray
-------------------------
* **Purpose** : An array where the data can be modified.
* **Refines** : :ref:`ImmutableCuboidArray`.
* **Purpose**: An array where the data can be modified.
* **Refines**: :ref:`ImmutableCuboidArray`.
* **Definition**
@ -78,7 +78,7 @@ MutableCuboidArray
| 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.
.. _ImmutableArray:
@ -92,7 +92,7 @@ ImmutableArray
* ImmutableArray<A> == true_type
NB : this traits marks the fact that X belongs to the Array algebra.
NB: this traits marks the fact that X belongs to the Array algebra.
.. _ImmutableMatrix:
@ -101,12 +101,12 @@ ImmutableMatrix
* Refines :ref:`ImmutableCuboidArray`
* If A is the type :
* If A is the type:
* ImmutableMatrix<A> == true_type
* A::domain_type::rank == 2
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
NB: this traits marks the fact that X belongs to the MatrixVector algebra.
.. _ImmutableVector:
@ -115,12 +115,12 @@ ImmutableVector
* Refines :ref:`ImmutableCuboidArray`
* If A is the type :
* If A is the type:
* ImmutableMatrix<A> == true_type
* A::domain_type::rank == 1
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
NB: this traits marks the fact that X belongs to the MatrixVector algebra.
.. _MutableArray:
@ -130,12 +130,12 @@ MutableArray
* Refines :ref:`MutableCuboidArray`
* If A is the type :
* 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.
NB: this traits marks the fact that X belongs to the Array algebra.
.. _MutableMatrix:
@ -144,13 +144,13 @@ MutableMatrix
* Refines :ref:`MutableCuboidArray`
* If A is the type :
* If A is the type:
* ImmutableMatrix<A> == true_type
* MutableMatrix<A> == true_type
* A::domain_type::rank ==2
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
NB: this traits marks the fact that X belongs to the MatrixVector algebra.
.. _MutableVector:
@ -159,13 +159,13 @@ MutableVector
* Refines :ref:`MutableCuboidArray`
* If A is the type :
* If A is the type:
* ImmutableMatrix<A> == true_type
* MutableMatrix<A> == true_type
* A::domain_type::rank ==1
NB : this traits marks the fact that X belongs to the MatrixVector algebra.
NB: this traits marks the fact that X belongs to the MatrixVector algebra.
Why concepts ? [Advanced]

View File

@ -10,8 +10,8 @@ Standard iterators are provided that model the boost Mutable_ForwardIterator and
The iterator implements also two additional methods :
* it can be casted to a bool : it is true iif the iteration is not at end.
* it.indices() : returns const & to the indices at the point of the iteration.
* it can be casted to a bool: it is true iif the iteration is not at end.
* it.indices(): returns const & to the indices at the point of the iteration.
Examples::
@ -19,7 +19,7 @@ Examples::
for (auto it = A.begin(); it; ++it) *it =it.indices()[0] + 10 *it.indices()[1];
Some examples of usage :
Some examples of usage:
.. triqs_example:: ./STL_0.cpp

View File

@ -55,12 +55,12 @@ the return type is a (partial) view of the container.
The special case (2a) (no argument) returns a complete view of the object
(equivalent to view_type(* this)).
The return type of the () operator is :
The return type of the () operator is:
* Partial views of array or array_view return a array_view.
* Partial views of vector or vector_view return a vector_view.
* 2d partial views of matrix or matrix_view return a matrix_view.
* BUT : (1d) partial view of matrix or matrix_view return a vector_view.
* BUT: (1d) partial view of matrix or matrix_view return a vector_view.
Example
@ -80,17 +80,17 @@ Example
-------------------------------------------------
* The containers and their views can be used with the triqs::clef library :
* The containers and their views can be used with the triqs::clef library:
* Using the clef library offers a quick and efficient way to fill an array with multiple advantages :
* Using the clef library offers a quick and efficient way to fill an array with multiple advantages:
* It is simpler and more readeable than a series of for loops.
* It is usually more optimal since the for loops are automatically written in the TraversalOrder of the
array.
* NB : the expression can be (and are) inlined by the compilers...
* NB: the expression can be (and are) inlined by the compilers...
* **Example** :
* **Example**:
.. triqs_example:: ./call_2.cpp
.. note::

View File

@ -14,5 +14,5 @@ Compound assignment operators (+=, -=, * =, /=)
The containers and the view have compound operators.
*NB* : These operators make no sense for const views, and result in a compile error.
*NB*: These operators make no sense for const views, and result in a compile error.

View File

@ -5,9 +5,9 @@
range
=========
`range` mimics the Python `range`. Arguments of the constructor can be :
`range` mimics the Python `range`. Arguments of the constructor can be:
* no argument : it then takes the whole set of indices in the dimension (like `:` in python) ::
* no argument: it then takes the whole set of indices in the dimension (like `:` in python) ::
A(range(), 0) // take the first column of A
@ -16,7 +16,7 @@ range
A(range (0,3), 0) // means A(0,0), A(1,0), A(2,0)
.. warning::
the second element is excluded : range(0,3) is 0,1,2, like in Python.
the second element is excluded: range(0,3) is 0,1,2, like in Python.
* three arguments : a range with a step ::
@ -34,9 +34,9 @@ ellipsis
* Example:
.. triqs_example:: ./range_ell_0.cpp
* NB : there can be at most one ellipsis per expression (otherwise it would be meaningless).
* NB: there can be at most one ellipsis per expression (otherwise it would be meaningless).
* Example of usage :
* Example of usage:
Ellipsis are useful to write generic algorithms. For example, imagine that you want to sum
arrays on their first index :

View File

@ -14,7 +14,7 @@ rebind
.. cpp:function:: void rebind(array_view const & a)
.. cpp:function:: void rebind(array_const_view const & a)
* **Effect** :
* **Effect**:
Rebinds the view

View File

@ -20,10 +20,10 @@ We will illustrate it on the `array` class, it is the same for `matrix` and `vec
* (2) **RHS** can be anything that models the :ref:`ImmutableCuboidArray` concept
e.g. : array, array_view, matrix, matrix_view,
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
`Effect`: all the elements viewed by the view are replaced
by the evaluation of RHS.
.. warning::

View File

@ -18,13 +18,13 @@ where triqs::ull_t is the type defined by :
typedef unsigned long long ull_t;
* The library provides three basic containers :
* The library provides three basic containers:
* array : general (rectangular) `N`-dimensionnal array; models :ref:`MutableCuboidArray` concept.
* matrix : models the :ref:`MutableMatrix` concept.
* vector : models the :ref:`MutableVector` concept.
* array: general (rectangular) `N`-dimensionnal array; models :ref:`MutableCuboidArray` concept.
* matrix: models the :ref:`MutableMatrix` concept.
* vector: models the :ref:`MutableVector` concept.
and the corresponding view classes : array_view, matrix_view, vector_view (Cf :ref:`partial_views`).
and the corresponding view classes: array_view, matrix_view, vector_view (Cf :ref:`partial_views`).
* The matrix and vector are very similar to an array of dimension 2 and 1 respectivily,
except for their algebra. Array form an array algebra, where operation are done element-wise, while matrix and vector

View File

@ -27,7 +27,7 @@ resize
As for std::vector, resize invalidate all pointers to the data of the container
(they may move in memory, to maintain data contiguity).
Views are invalidated too : more precisely, because of the memory guarantee provided by the views,
Views are invalidated too: more precisely, because of the memory guarantee provided by the views,
the view is still valid (code will not crash), but it does *not* view the container anymore...
Illustration :
@ -42,5 +42,5 @@ resize_or_check_if_view
.. cpp:function:: void resize_or_check_if_view(ArrayType const & A, shape_t)
* If A is a value : resize A
* If A is a view : check that the shape if the shape_t and throw an exception if not.
* If A is a value: resize A
* If A is a view: check that the shape if the shape_t and throw an exception if not.

View File

@ -2,7 +2,7 @@
swap & deep_swap
==================================
There are two possible interpretation of "swapping two arrays" :
There are two possible interpretation of "swapping two arrays":
either use 3 moves like std::swap, i.e. swapping the pointer to the data in memory,
or making a deep swap, i.e. really swapping all the elements in memeory.

View File

@ -7,7 +7,7 @@ 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 :
The possible flags are accessible via a constexpr ull_t in triqs::arrays or a macro:
======================== =======================================
Macro constexpr equivalent
@ -19,7 +19,7 @@ OptionFlags
======================== =======================================
Defaults can be modified with the macros :
Defaults can be modified with the macros:
* `TRIQS_ARRAYS_ENFORCE_BOUNDCHECK` : enforce BoundCheck by default (slows down codes ! Use only for debugging purposes).
@ -42,7 +42,7 @@ 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
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.

View File

@ -5,7 +5,7 @@
Assignment to views
=========================
**Synopsis** :
**Synopsis**:
template<typename RHS> array_view & operator=(RHS const & X);
@ -15,14 +15,14 @@ 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 :
* **RHS** can be:
* Anything that models the :ref:`ImmutableCuboidArray` concept
e.g. : array, array_view, matrix, matrix_view,
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* :
*Effect*:
Every elements viewed by the view are replaced by the evaluation of RHS.
*Precondition*
@ -32,16 +32,16 @@ We will illustrate it on the `array_view` class, it is the same for `matrix` and
If the debug macro, :ref:`TRIQS_ARRAYS_ENFORCE_BOUNDCHECK<arr_debug_macro>` is defined,
this condition is checked at runtime.
NB : We could lower this condition, since we don't need a domain here, just the evaluation on the indices...
NB: We could lower this condition, since we don't need a domain here, just the evaluation on the indices...
* A scalar.
*Effect* :
*Effect*:
Every elements viewed by the view are set to this scalar, except for the matrix_view,
where the matrix is set to the identity.
NB : no move assignment operator
NB: no move assignment operator
---------------------------------------
Note that **there is no move assignment operators for views**.

View File

@ -38,7 +38,7 @@ where triqs::ull_t is the type defined by :
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.
* Views are largely interoperable: it is easy and quick to take a matrix_view of an array, or vice versa.
Cf constructors belows.
* Const views can be constructed from a view, but the reverse is not true (Cf constructors).

View File

@ -7,7 +7,7 @@ Bound checking and debug macros
===================================
To be fast, by default, no check are made on the indices while accessing elements or slicing.
However, checks can be activated in two ways :
However, checks can be activated in two ways:
* Adding the `BOUND_CHECK` option

View File

@ -2,7 +2,7 @@
.. _Foreach:
Loops : the foreach constructs
Loops: the foreach constructs
========================================================
foreach and its variants are a compact and efficient way to
@ -12,7 +12,7 @@ perform some action of the kind
While this kind of construct is equivalent to write manually the *for* loops, it has
several advantages :
several advantages:
* it is more compact, less error prone (one does not need to specify the bounds in the loop).
@ -48,7 +48,7 @@ in the order specified by the TraversalOrder flag of the array.
* As a result this is always equally or more optimized than a manually written loop.
Example :
Example:
.. triqs_example:: ./foreach_0.cpp
.. note::

View File

@ -10,4 +10,4 @@ Grouping indices
* **Syntax** :
* **Example** :
* **Example**:

View File

@ -1,6 +1,6 @@
.. highlight:: c
h5::array_proxy : a simple proxy to the array in file
h5::array_proxy: a simple proxy to the array in file
===========================================================
.. warning::

View File

@ -4,12 +4,12 @@ Simple read/write operations of an array (or a view)
============================================================================
Given an array (or an array_view), the functions `h5::write` and `h5::read` write and read it to/from the file
or any subgroup thereof. For example :
or any subgroup thereof. For example:
.. triqs_example:: ./h5_rw_0.cpp
.. triqs_example:: examples_code/h5_rw.cpp
Note that :
Note that:
* The data in the hdf5 file are stored in C order.

View File

@ -1,6 +1,6 @@
.. highlight:: c
h5::array_stack : stacking arrays or scalars
h5::array_stack: stacking arrays or scalars
================================================================
h5::array_stack writes a sequences of arrays of the same shape (or of scalars) into an hdf5 array with one more dimension, unlimited in the stacking direction.
@ -11,7 +11,7 @@ It is typically used to store a Monte-Carlo data series for later analysis.
* If the base of the stack is a simple number (double, int, ...), R=0.
* The syntax is simple :
* The syntax is simple:
* The << operator piles up an array/scalar onto the stack.
* The ++ operator advances by one slice in the stack.
@ -19,7 +19,7 @@ It is typically used to store a Monte-Carlo data series for later analysis.
* The stack is bufferized in memory (`bufsize` parameter), so that the file access does not happen too often.
* NB : beware to complex numbers ---> REF TO COMPLEX
* NB: beware to complex numbers ---> REF TO COMPLEX
Reference
------------

View File

@ -22,8 +22,8 @@ Domain
-------------------------------------------------
* **Purpose** : The domain of definition of the array, i.e. the possible value of the indices.
* **Refines** : BoostSerializable, Printable
* **Definition** :
* **Refines**: BoostSerializable, Printable
* **Definition**:
+------------------------------------------------------------------+-------------------------------------------------------+
| Elements | Comment |
@ -49,7 +49,7 @@ Domain
Typically, this is is a multi-index for an array, matrix, ...., e.g.
* Cuboid<rank> : standard hyperrectangular arrays. This is little more than the tuple of the lengths.
* Cuboid<rank>: standard hyperrectangular arrays. This is little more than the tuple of the lengths.
* triangle, .... ?
.. _HasImmutableArrayInterface:
@ -57,12 +57,12 @@ Domain
HasImmutableArrayInterface
-------------------------------------------------
* **Purpose** : The most abstract definition of something that behaves like an immutable array.
* **Purpose**: The most abstract definition of something that behaves like an immutable array.
* it has a domain (hence a rank).
* it can be evaluated on any value of the indices in the domain
* By combining the generator of the domain with the evaluation, it is therefore easy to
iterate on the values of such an object.
* 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|B] denotes that the return type maybe A or B).
@ -75,15 +75,15 @@ HasImmutableArrayInterface
[ value_type | value_type const &] operator[] (domain_type::index_value_type const &) const Evaluation.
================================================================================================== =============================================================
* **Examples** :
* **Examples**:
* array, array_view, matrix, matrix_view, vector, vector_view (all implemented as Indexmap_Storage_Pair)
* array expressions (in which case the returns are not const & since they are computed, not stored).
IndexGenerator
-------------------------------------------------
* **Purpose** : Generate the indices of a domain.
* **Purpose**: Generate the indices of a domain.
* **Definition** :
* **Definition**:
============================================================== ==================================================================================================
Elements Comment
@ -107,13 +107,13 @@ IndexGenerator
IndexMap
-------------------------------------------------
* **Purpose** :
* **Purpose**:
* Store the mapping of the index domain to a linear array.
* It is basically a function : indices --> 1d position, the bijection between the indices
* It is basically a function: indices --> 1d position, the bijection between the indices
of an element and its position in the memory block.
* **Refines** : BoostSerializable, Printable
* **Definition** :
* **Refines**: BoostSerializable, Printable
* **Definition**:
======================================================================== ==================================================================================================
Elements Comment
@ -124,12 +124,12 @@ IndexMap
* can be constructed from domain_type const &
* size_t operator[] (domain_type::index_value_type const & key ) const The mapping itself.
* iterator A type modeling IndexMapIterator, which is the optimal memory traversal.
NB : the order of indices is chosen for optimal traversal of memory, it
NB: the order of indices is chosen for optimal traversal of memory, it
does not need to be "natural".
cuboid_map also provides a natural_iterator for that purpose.
======================================================================== ==================================================================================================
* The type also has to define two free functions and to specialize a template :
* The type also has to define two free functions and to specialize a template:
========================================================== ==================================================================================================
Elements Comment
@ -138,31 +138,31 @@ IndexMap
map M2
* bool raw_copy_possible (M1, M2) Is the assignment of an array/matrix/vector with map M2 into an array/matrix/vector with map M1
doable with raw copy
* struct indexmap_iterator_adapter< It, I > Metafunction :
* struct indexmap_iterator_adapter< It, I > Metafunction:
- I is the IndexMap class
- It any similar IndexMapIterator which returns (in ::type) the IndexMapIterator on I
with the same order traversal as It.
Example : It is a IndexMapIterator on I1 stored in C order, I is in Fortran order,
Example: It is a IndexMapIterator on I1 stored in C order, I is in Fortran order,
the result will be an IndexMapIterator on I that presents the data of I in C order
This is used in copying array with different indexmaps.
========================================================== ==================================================================================================
* **Examples** :
* **Examples**:
* cuboid_map<IterationOrder> : a map of the cuboid indices in a fixed order in memory.
IndexMapIterator
-------------------------------------------------
* **Purpose** :
* **Purpose**:
* A basic iterator on an IndexMap which can be dereferenced into the shift of successive elements compared to the start of the memory block.
* These iterators are kept as simple as possible, so that it is easy to implement new indices maps and their iterators.
* NB : In particular, they are *not* necessary STL-compliant. The array_iterator class will
* NB: In particular, they are *not* necessary STL-compliant. The array_iterator class will
take such an iterator and a Storage and produce a true, STL compliant iterator on the array (iterator_adapter).
* **Definition** :
* **Definition**:
========================================================== ==================================================================================================
Elements Comment
@ -186,13 +186,13 @@ IndexMapIterator
Storage
-------------------------------------------------
* **Purpose** :
* **Purpose**:
* The storage of the array in memory, e.g. plain C++ array, a numpy, etc...
* A Storage keeps the reference to the memory block where the array is stored.
* NB : This memory block can be typically shared between various arrays and views,
* NB: This memory block can be typically shared between various arrays and views,
so the Storage is just a reference. The memory is deallocated only
when all storages referencing it has been destroyed.
* **Refines** : BoostSerializable
* **Refines**: BoostSerializable
* **Definition** :
====================================================== ==================================================================================================
@ -227,7 +227,7 @@ StorageOrder concept
* Store the order of indices in memory.
* Can be fixed at compile time, or dynamically (not implemented).
* **Refines** : BoostSerializable
* **Refines**: BoostSerializable
* **Definition** :
====================================================== ==================================================================================================
@ -243,7 +243,7 @@ StorageOrder concept
====================================================== ==================================================================================================
* The type also has to define the == operator :
* The type also has to define the == operator:
========================================================== ==================================================================================================
Elements Comment

View File

@ -7,12 +7,12 @@ Cuboid formula
* **Notations** :
* R = rank
* index : (i0,...,i_{R-1})
* Lengths : (L0, ... , L_{R-1})
* Strides : (S0, ... , S_{R-1})
* index: (i0,...,i_{R-1})
* Lengths: (L0, ... , L_{R-1})
* Strides: (S0, ... , S_{R-1})
* position = start_shift + \sum_{j=0}^{R-1} i_j S_j
* **Strides for compact cuboid** :
* **Strides for compact cuboid**:
If :math:`\sigma(i)` is the i-th index in memory (0 the first, R-1 the last one), we have
@ -26,14 +26,14 @@ Cuboid formula
\end{align*}
* **Slicing the cuboid** :
* **Slicing the cuboid**:
* Argument of the slice : (R0, R1, ..., R_{R-1}), with R_i = range : (start,end,step)
* Argument of the slice: (R0, R1, ..., R_{R-1}), with R_i = range: (start,end,step)
for the moment, if R_i = E_i, a number, consider it as a special range of length 1.
* new index (k0,...., k_{R-1}).
i_u = R_u.start + k_u * R_u.step
* Compute the new strides : Sn_j
* Compute the new strides: Sn_j
.. math::
:nowrap:
@ -49,7 +49,7 @@ Cuboid formula
Sn_j &= S_j * R_j.start
\end{align*}
* Now : for the cases R_i = E_i, just drop the index.
* Now: for the cases R_i = E_i, just drop the index.

View File

@ -1,6 +1,6 @@
.. _impl_func:
Functional aspect : fold, map, mapped functions
Functional aspect: fold, map, mapped functions
=============================================================
map and fold

View File

@ -9,7 +9,7 @@ Concepts
----------
Implementation : cuboid map
Implementation: cuboid map
----------------------------
* domain with foreach

View File

@ -4,7 +4,7 @@
IndexmapStoragePair implementation class
=============================================================
* goal : a generic implementation of the container, view or not.
* goal: a generic implementation of the container, view or not.
* lazy description
* rvalue ref !

View File

@ -3,9 +3,9 @@
Interface to python
=============================================================
Files :
Files:
Low level : memory guarantee
Low level: memory guarantee
High level : 2 functions for going back and forth.
High level: 2 functions for going back and forth.

View File

@ -11,18 +11,18 @@ In this section, IM denotes some IndexMaps.
* It is a meta-function that computes the type of the resulting indexmap
* It is a function that computes the resulting indexmap.
* The array/matrix/vector classes and their views, when called with the () operator, will :
* The array/matrix/vector classes and their views, when called with the () operator, will:
* forward all the arguments and their types to IndexMaps::slice, to compute the new indexmap IM2.
* If IM2 is of dimension 0, return a value_type & or const & (it is a simple number, not an array).
* Otherwise : return a new view, made of IM2 and the same data as for the original object.
* Otherwise: return a new view, made of IM2 and the same data as for the original object.
* Possible slices are defined by the IndexMap type.
Slicing an class C with IndexMap I1 produces a class C2_view, with IndexMap I2,
i.e. a new sliced IndexMap on the same data.
* **Examples** :
* array and array_view can be sliced :
* **Examples**:
* array and array_view can be sliced:
``
array<T,2> A(10,10); : defines an array
A(1,2) : element access.
@ -31,7 +31,7 @@ In this section, IM denotes some IndexMaps.
``
* matrix, matrix_view when sliced, return vector_view or matrix_view.
* One can be much more general : e.g. slicing the diagonal of a matrix, etc...
* One can be much more general: e.g. slicing the diagonal of a matrix, etc...
@ -45,7 +45,7 @@ In this section, IM denotes some IndexMaps.
template<typename IM, typename ArgsTuple>
struct slice< IM, ArgsTuple> { typedef IM2 type; };
//In namespace IndexMaps :
//In namespace IndexMaps:
template<typename IM, typename ArgsTuple>
typename result_of::slice<IM,ArgsTuple>::type slice(IM const &, ArgsTuple args);

View File

@ -9,7 +9,7 @@ Concept
The storage concept...
Implementation : shared_block
Implementation: shared_block
------------------------------

View File

@ -24,39 +24,39 @@ and a physical storage S in the computer (a block of memory), denoted as an Inde
* a C++ shared pointer to a memory block.
* a reference to a numpy array.
This design has several consequences :
This design has several consequences:
* **Interoperability** : classes are widely interoperable, e.g. one can add a array and a matrix (if dimensions are ok of course).
* **Interoperability**: classes are widely interoperable, e.g. one can add a array and a matrix (if dimensions are ok of course).
one can also add a python numpy and a C++ array without any further coding.
* It is straighforward to construct a matrix_view<T> from an array<T,2>, since it is the same couple <I,S>,
just interpreted differently.
* It is easy to view a array<T,4> as a matrix by gathering indices (properly ordered in memory) :
* It is easy to view a array<T,4> as a matrix by gathering indices (properly ordered in memory):
one just has to provide a new IndexMap I2 to see the same data.
[ --> very useful for vertex computation in many body...]
* Slicing, or partial view is very natural : it is just a function on indexmaps : I--> I2,
* Slicing, or partial view is very natural: it is just a function on indexmaps: I--> I2,
independantly of any storage.
Quick guide through the implementation
=============================================================
The implementation is divided into basically 4 parts :
The implementation is divided into basically 4 parts:
* Storages : implements two storages shared_block and numpy
* Storages: implements two storages shared_block and numpy
* IndexMaps : implements cuboid index map, its domain and iterators
* IndexMaps: implements cuboid index map, its domain and iterators
* impl/indexmap_storage_pair.hpp : the basic implementation class for all user class.
* impl/indexmap_storage_pair.hpp: the basic implementation class for all user class.
It is basically just a couple of an indexmap and a storage, with shallow copy.
It also forward the slices to the indexmap and construct the correct views.
* upper level :
* user class : array, array_view, matrix, matrix_view, vector, vector_view
* expression.hpp : boost proto expression
* numpy_interface.hpp : helper to get numpy into array
* upper level:
* user class: array, array_view, matrix, matrix_view, vector, vector_view
* expression.hpp: boost proto expression
* numpy_interface.hpp: helper to get numpy into array
* lapack/blas interface
* hdf5 support.

View File

@ -1,7 +1,7 @@
.. _impl_userclasses:
User classes : array, matrix, vector
User classes: array, matrix, vector
=============================================================
* view and not

View File

@ -5,7 +5,7 @@ Rational
This library provides a multi-dimensionnal array library
for numerical computations with the following characteristics/goals :
for numerical computations with the following characteristics/goals:
* **Simplicity of use** :
@ -14,7 +14,7 @@ for numerical computations with the following characteristics/goals :
programmers. We do *a lot* of array manipulations, and we want to maintain
*readable* codes.
* **Genericity, abstraction and performance** :
* **Genericity, abstraction and performance**:
We want to have simple, readeable code, with the same (or better) speed than manually written low-level code.
Most optimisations should be delegated to the library and the compiler.
@ -29,9 +29,9 @@ for numerical computations with the following characteristics/goals :
* create a array in C++, and return it as a numpy.
* mix the various kind of arrays transparently in C++ expressions.
* **HDF5** : simple interface to hdf5 library to ease storing/retrieving into/from HDF5 files.
* **HDF5**: simple interface to hdf5 library to ease storing/retrieving into/from HDF5 files.
* **MPI** : compatibility with boost::mpi interface.
* **MPI**: compatibility with boost::mpi interface.

View File

@ -5,18 +5,18 @@
Interaction with CLEF expressions
============================================
* The containers and their view classes can be used with the :doc:`../clef/contents` library :
* The containers and their view classes can be used with the :doc:`../clef/contents` library:
* They can be called with CLEF expressions.
* :doc:`Automatic assignment<../clef/assign>` has been set up.
* Using the CLEF library offers a quick and efficient way to fill an array with multiple advantages :
* Using the CLEF library offers a quick and efficient way to fill an array with multiple advantages:
* It is simpler and more readeable than a series of for loops.
* It is usually more optimal since the for loops are automatically written in the TraversalOrder of the array.
* **Example** :
* **Example**:
.. triqs_example:: ./lazy_0.cpp
.. note::

View File

@ -2,10 +2,10 @@
.. _arr_map_fold:
Functional constructs : map & fold
Functional constructs: map & fold
###########################################
Two standard functional constructs are provided :
Two standard functional constructs are provided:
* *map* that promotes a function acting on the array element to an array function, acting
element by element.
@ -32,14 +32,14 @@ map
template<ImmutableCuboidArray A> auto map(f) (A const &)
with :
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** :
* **Example**:
.. triqs_example:: ./map_0.cpp
fold
@ -71,7 +71,7 @@ fold
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 :
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,
@ -79,7 +79,7 @@ fold
* The function f will be inlined if possible, leading to efficient algorithms.
* fold is implemented using a foreach loop, hence it is efficient.
* **Example** :
* **Example**:
Many algorithms can be written in form of map/fold.
@ -96,10 +96,10 @@ fold
reads :
.. triqs_example:: ./map_1.cpp
Note in this example :
Note in this example:
* the simplicity of the code
* the genericity : it is valid for any dimension of array.
* 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.

View File

@ -4,7 +4,7 @@
.. warning::
This part is alpha : work in progress. May change at any time.
This part is alpha: work in progress. May change at any time.
Using basic concepts
###########################################
@ -20,7 +20,7 @@ make_immutable_array
* (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 :
a lazy object modelling :ref:`ImmutableCuboidArray` concept, with the domain built from the ranges:
Parameters are :
@ -29,9 +29,9 @@ make_immutable_array
* (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 :
a lazy object modelling :ref:`ImmutableCuboidArray` concept, with the domain built from the ranges:
**Example** :
**Example**:
.. triqs_example:: ./play_with_concept_0.cpp

View File

@ -28,7 +28,7 @@ and the corresponding `view types`.
* When copied, assigned, it makes deep copy of the data and resizes itself if necessary (like e.g. std::vector).
* Examples :
* Examples:
* std::vector<T>
* triqs::arrays::array<T,R>, triqs::arrays::matrix<T>, triqs::arrays::vector<T>
@ -43,7 +43,7 @@ and the corresponding `view types`.
* They are useful to work on arrays, matrices, or on some part thereof, without making copies
(e.g. on a slice of an array, a column of a matrix).
* Examples :
* Examples:
* triqs::arrays::array_view<T,R>, triqs::arrays::matrix_view, triqs::arrays::vector_view<T>

View File

@ -1,22 +0,0 @@
C++
=============
.. warning::
This documentation is work in progress.
.. toctree::
:maxdepth: 1
conventions
using_the_lib/contents
arrays/contents
gf/contents
clef/contents
mctools/intro
det_manip/contents
parameters/parameters
statistics/contents
utilities/contents
using_the_lib/profiling

View File

@ -1,5 +0,0 @@
# Doxygen sources
set_property(GLOBAL APPEND PROPERTY DOXYGEN_SOURCES ${TRIQS_SOURCE_DIR}/triqs/parameters/parameters.hpp)
all_tests()

View File

@ -1,141 +0,0 @@
Parameters
===============
.. warning::
Library of beta quality.
Documentation : just intro/tutorial, reference doc in progress.
Introduction
--------------
The purpose of the class parameters is to handle program input parameters.
It provides a convenient way to pass several parameters of different types to a program.
Parameters can be stored in a parameters object and accessed in a manner which is reminiscent of a Python dict:
.. code-block:: c
parameters P;
P["x"] = 3.14;
y = P["x"];
In Python the syntax is similar:
.. code-block:: python
import parameters as params
P = params.Parameters()
P['x'] = 3.14
y = P['x']
The class implements the following features:
* storage of parameters of any type, including arrays
* C-like cast operations, such as integral type to double conversion as well as lexical cast to arithmetic types
* Python interface
* type checking
* hdf5 I/O operations
* write contents to std::ostream
* the class is boost-serializable
parameter_defaults
-----------------------------
When parameters are used within a program, a number of them are usually optional, in
the sense that they need not be provided by the user. This either means that the program
can run without them, or meaningful default values can be provided.
Other parameters, on the other hand, may be required to be provided by the user.
These typically are parameters for which one cannot provide meaningful default values.
These cases can be handled in a consistent manner using the parameter_defaults class.
An object of this class allows to specify the name, type and documentation for all
required and optional parameters. Default values are provided for optional parameters:
.. code-block:: c
parameter_defaults pdef;
pdef.required("Beta", double(), "Inverse temperature")
.optional("N_time", int(100), "Number of time points")
.optional("N_freq", int(200), "Number of frequencies")
;
The default_parameters object serves two main purposes: Firstly, the input parameters can
be checked for completeness and correctness, i.e. they can be checked if all required parameters
are provided and have correct type.
Secondly, the optional parameters provided through the input parameters can be checked whether they
have correct type. Those which are not provided can be added to the input parameter set with
their respective default values.
Both steps are performed through the update method of the parameter class:
.. code-block:: c
parameters P;
P["Beta"] = 3.14;
P.update(pdef);
Given that the parameter_defaults are complete, the resulting parameter object contains all
parameters that the program will eventually access.
Finally, the information stored in the defaults can be used to generate the help of the program,
by printing a list of its parameters:
.. code-block:: c
std::cout<<pdef<<std::endl;
See below for more detailed working code examples.
For detailed information on how to use the parameter and parameter_defaults classes within a program, refer to the **TRIQS solver coding guidelines**.
Headers
--------------
The parameter class and the parameter_defaults class are declared in the header
triqs/utility/parameters.hpp
Doxygen documentation
-------------------------
The :doxy:`full C++ parameter documentation<triqs::utility::parameters>` and
the :doxy:`parameter_defaults documentation<triqs::utility::parameter_defaults>` are available here.
Parameter example
-------------
.. triqs_example:: ./parameters_0.cpp
Parameter default value example
-------------
.. triqs_example:: ./parameters_1.cpp
Python example
-------------
.. code-block:: python
import parameters as params
P = params.Parameters()
P['num'] = 2.3
P['str'] = "hello world"
print P
dct = { 'a' : 10, 'b' : "a string"}
P.update(dct) # update from a dictionary
print P
import numpy as np
a = np.array([[1,2],[3,4]])
P['A'] = a # add an array
print P
P.update2( c = 4, d= "u") # update from an initializer list
print P

View File

@ -1,28 +0,0 @@
#include <triqs/parameters.hpp>
using triqs::params::parameters;
#include <triqs/arrays.hpp>
int main() {
parameters P;
/*
P["a"] = long(1);
P["d"] = 2.7;
P["a_string"] = std::string("-14.3");
P["char_string"] = "-14.3";
triqs::arrays::array<double, 2> A(2, 2);
A() = 0;
A(0, 0) = 1.3;
A(1, 1) = -8.2;
P["A"] = A;
std::cout << "A:" << P["A"] << std::endl;
long a = P["a"];
double x = P["a"]; // cast to double from long
double y = P["a_string"]; // lexical cast to double from string
std::cout << y << std::endl;
*/
return 0;
}

View File

@ -1,19 +0,0 @@
#include <triqs/parameters.hpp>
using triqs::params::parameters;
int main() {
/*
parameters P;
P["Beta"] = 3.14;
parameter_defaults pdef;
pdef.required("Beta", double(), "Inverse temperature").optional("Alpha", int(1000), "An integer").optional("Gamma", double(0.9),
"A double");
std::cout << pdef << std::endl; // print a comprehensive list of parameters:
std::cout << P << std::endl;
P.update(pdef); // check whether required parameters are present and update optional ones
std::cout << P << std::endl;
*/
}

View File

@ -7,7 +7,7 @@ Automatic assignment of containers
Another use of expression is the automatic assignment of containers.
**Synopsis** :
**Synopsis**:
If C is a container, ::
@ -64,6 +64,6 @@ into ::
A complete example :
A complete example:
.. triqs_example:: ./assign_1.cpp

Some files were not shown because too many files have changed in this diff Show More