dft_tools/doc/reference/arrays/containers/template_parameters.rst

Template parameters of the containers and views
======================================================

.. _arr_templ_par_to:

TraversalOrder
----------------------------

* TraversalOrder is a type encoding of the optimal traversal in memory.
  Default is void, corresponding to  as regular C-style ordering (slowest index first).

* The traversal of the arrays (iterators, foreach loop) will be written and optimised for this 
  order.

* It is indeed sometimes necessary to know *at compile time* the traversal order to generate
  an optimal code. The default (C-style) is sufficient is most cases, but not always...

* More explanations here...

* Note that this notion is completely independent of the real memory layout of the array, 
  which is a runtime parameter.

  The code will be correct for any order, but may be faster for the TraversalOrder.
  
* TraversalOrder is not present for vector since there is only one possibility in 1d.

* TODO : document the various possibility beyond C style.

+--------------------------+------------------------------------------------------------+
| TraversalOrder           | Meaning                                                    |
+==========================+============================================================+
| void                     | C style traversal (lowest index first).                    |
+--------------------------+------------------------------------------------------------+
| _traversal_fortran       | Fortran style traversal (last index first)                 |
+--------------------------+------------------------------------------------------------+
| _traversal_dynamical     | Traverse in the order specified by the memory layout       |
+--------------------------+------------------------------------------------------------+
| _traversal_custom<2,1,0> | Traverse in the order specified by the permutation (2,1,0) |
+--------------------------+------------------------------------------------------------+
Work on doc 2013-08-27 19:17:17 +02:00			`Template parameters of the containers and views`
			`======================================================`

			`.. _arr_templ_par_to:`

			`TraversalOrder`
			`----------------------------`

[arrays] Important changes in implementation. - Simplify group_indices - Only for C ordered, remove complex compile time. - Could be generalized to non C ordered, but no need. - Fix slice for custom orders. - Generalize the group_indices for the custom order. - Add c_ordered_transposed_view (useful ?) - Improve slice, special for ellipsis (quicker). - Simplify TraversalOrder - Assignement. Specialize one case for speed. - use FORCEINLINE in foreach, according to speed test for clang - add one speed test - Modify iterators for better speed. - along the lines decided for the foreach - update doc. 2014-09-07 14:34:10 +02:00			`* TraversalOrder is a type encoding of the optimal traversal in memory.`
			`Default is void, corresponding to as regular C-style ordering (slowest index first).`

			`* The traversal of the arrays (iterators, foreach loop) will be written and optimised for this`
Work on doc 2013-08-27 19:17:17 +02:00			`order.`

[arrays] Important changes in implementation. - Simplify group_indices - Only for C ordered, remove complex compile time. - Could be generalized to non C ordered, but no need. - Fix slice for custom orders. - Generalize the group_indices for the custom order. - Add c_ordered_transposed_view (useful ?) - Improve slice, special for ellipsis (quicker). - Simplify TraversalOrder - Assignement. Specialize one case for speed. - use FORCEINLINE in foreach, according to speed test for clang - add one speed test - Modify iterators for better speed. - along the lines decided for the foreach - update doc. 2014-09-07 14:34:10 +02:00			`* It is indeed sometimes necessary to know at compile time the traversal order to generate`
			`an optimal code. The default (C-style) is sufficient is most cases, but not always...`
Work on doc 2013-08-27 19:17:17 +02:00
[arrays] Important changes in implementation. - Simplify group_indices - Only for C ordered, remove complex compile time. - Could be generalized to non C ordered, but no need. - Fix slice for custom orders. - Generalize the group_indices for the custom order. - Add c_ordered_transposed_view (useful ?) - Improve slice, special for ellipsis (quicker). - Simplify TraversalOrder - Assignement. Specialize one case for speed. - use FORCEINLINE in foreach, according to speed test for clang - add one speed test - Modify iterators for better speed. - along the lines decided for the foreach - update doc. 2014-09-07 14:34:10 +02:00			`* More explanations here...`
Work on doc 2013-08-27 19:17:17 +02:00
[arrays] Important changes in implementation. - Simplify group_indices - Only for C ordered, remove complex compile time. - Could be generalized to non C ordered, but no need. - Fix slice for custom orders. - Generalize the group_indices for the custom order. - Add c_ordered_transposed_view (useful ?) - Improve slice, special for ellipsis (quicker). - Simplify TraversalOrder - Assignement. Specialize one case for speed. - use FORCEINLINE in foreach, according to speed test for clang - add one speed test - Modify iterators for better speed. - along the lines decided for the foreach - update doc. 2014-09-07 14:34:10 +02:00			`* Note that this notion is completely independent of the real memory layout of the array,`
			`which is a runtime parameter.`
Work on doc 2013-08-27 19:17:17 +02:00
[arrays] Important changes in implementation. - Simplify group_indices - Only for C ordered, remove complex compile time. - Could be generalized to non C ordered, but no need. - Fix slice for custom orders. - Generalize the group_indices for the custom order. - Add c_ordered_transposed_view (useful ?) - Improve slice, special for ellipsis (quicker). - Simplify TraversalOrder - Assignement. Specialize one case for speed. - use FORCEINLINE in foreach, according to speed test for clang - add one speed test - Modify iterators for better speed. - along the lines decided for the foreach - update doc. 2014-09-07 14:34:10 +02:00			`The code will be correct for any order, but may be faster for the TraversalOrder.`

			`* TraversalOrder is not present for vector since there is only one possibility in 1d.`

			`* TODO : document the various possibility beyond C style.`

			`+--------------------------+------------------------------------------------------------+`
			`\| TraversalOrder \| Meaning \|`
			`+==========================+============================================================+`
			`\| void \| C style traversal (lowest index first). \|`
			`+--------------------------+------------------------------------------------------------+`
			`\| _traversal_fortran \| Fortran style traversal (last index first) \|`
			`+--------------------------+------------------------------------------------------------+`
			`\| _traversal_dynamical \| Traverse in the order specified by the memory layout \|`
			`+--------------------------+------------------------------------------------------------+`
			`\| _traversal_custom<2,1,0> \| Traverse in the order specified by the permutation (2,1,0) \|`
			`+--------------------------+------------------------------------------------------------+`
Work on doc 2013-08-27 19:17:17 +02:00