From c5521315eae1512a89eca7b2cdd2515981caa499 Mon Sep 17 00:00:00 2001 From: Tom de Geus Date: Sat, 2 Jun 2018 17:13:33 +0200 Subject: [PATCH] Updated documentation --- docs/cppmat_cartesian.rst | 42 ++- docs/cppmat_cartesian2d.rst | 102 ------ docs/cppmat_cartesian3d.rst | 98 ------ docs/cppmat_fix.rst | 269 +++++++++++++++ docs/cppmat_map.rst | 312 ++++++++++++++++++ docs/cppmat_periodic.rst | 85 ----- docs/cppmat_tiny.rst | 72 ---- docs/cppmat_var_diagonal.rst | 41 +++ ...mat_regular.rst => cppmat_var_regular.rst} | 155 +++++---- docs/cppmat_var_symmetric.rst | 40 +++ docs/cppmat_view.rst | 246 -------------- docs/develop.rst | 7 + docs/index.rst | 173 +++++----- docs/python.rst | 80 ++--- 14 files changed, 890 insertions(+), 832 deletions(-) delete mode 100644 docs/cppmat_cartesian2d.rst delete mode 100644 docs/cppmat_cartesian3d.rst create mode 100644 docs/cppmat_fix.rst create mode 100644 docs/cppmat_map.rst delete mode 100644 docs/cppmat_periodic.rst delete mode 100644 docs/cppmat_tiny.rst create mode 100644 docs/cppmat_var_diagonal.rst rename docs/{cppmat_regular.rst => cppmat_var_regular.rst} (53%) create mode 100644 docs/cppmat_var_symmetric.rst delete mode 100644 docs/cppmat_view.rst diff --git a/docs/cppmat_cartesian.rst b/docs/cppmat_cartesian.rst index 6482163..480be6b 100644 --- a/docs/cppmat_cartesian.rst +++ b/docs/cppmat_cartesian.rst @@ -1,13 +1,11 @@ -.. _cartesian: +.. _var_cartesian: ***************** cppmat::cartesian ***************** -[:download:`tensor.h <../src/cppmat/tensor.h>`, :download:`tensor.cpp <../src/cppmat/tensor.cpp>`] - -Provides classes for 4th- and 2nd order tensors and vectors (the latter essentially coincide with ``std::vector``, but with special methods). For example, a fourth order identity tensor in 3-D is obtained as follows: +Provides classes for 4th- and 2nd order tensors and vectors. For example, a fourth order identity tensor in 3-D is obtained as follows: .. code-block:: cpp @@ -19,18 +17,16 @@ Provides classes for 4th- and 2nd order tensors and vectors (the latter essentia ... + std::cout << A << std::endl; + return 0; } -.. note:: **Tip** - - To print, use the common C++ ``std::cout << A << std::endl;``. To customize formatting use the more classic C syntax ``A.printf("%16.8e");`` +.. tip:: -.. note:: **Tip** + If you know that you will work in a fixed (and small) number of dimensions (e.g. 2 or 3), please consider using :ref:`fix_cartesian` instead of :ref:`var_cartesian`. This is generally more efficient as it can take advantage of the knowledge that the arrays are fixed size and relatively small. Also several loops are unrolled. - If you know that you will work exclusively in 2 or 3 dimensions, please consider using :ref:`cartesian2d` or :ref:`cartesian3d` instead of :ref:`cartesian`. This is generally more efficient as it can take advantage of the knowledge that the arrays are fixed size and relatively small. Also several loops are unrolled. - -.. note:: **Tip** +.. tip:: The notation can be shortened to: @@ -52,11 +48,13 @@ Provides classes for 4th- and 2nd order tensors and vectors (the latter essentia Classes ======= -.. _cartesian_tensor4: +.. _var_cartesian_tensor4: ``cppmat::cartesian::tensor4`` ------------------------------ +[:download:`var_cartesian_tensor4.h <../src/cppmat/var_cartesian_tensor4.h>`, :download:`var_cartesian_tensor4.cpp <../src/cppmat/var_cartesian_tensor4.cpp>`] + 4th-order tensor (rank 4 tensor) of arbitrary dimension. .. code-block:: cpp @@ -65,11 +63,13 @@ Classes A(0,0,0,0) = ... -.. _cartesian_tensor2: +.. _var_cartesian_tensor2: ``cppmat::cartesian::tensor2`` ------------------------------ +[:download:`var_cartesian_tensor2.h <../src/cppmat/var_cartesian_tensor2.h>`, :download:`var_cartesian_tensor2.cpp <../src/cppmat/var_cartesian_tensor2.cpp>`] + 2nd-order tensor (rank 2 tensor) of arbitrary dimension. .. code-block:: cpp @@ -78,11 +78,13 @@ Classes A(0,0) = ... -.. _cartesian_tensor2s: +.. _var_cartesian_tensor2s: ``cppmat::cartesian::tensor2s`` ------------------------------- +[:download:`var_cartesian_tensor2s.h <../src/cppmat/var_cartesian_tensor2s.h>`, :download:`var_cartesian_tensor2s.cpp <../src/cppmat/var_cartesian_tensor2s.cpp>`] + Symmetric 2nd-order tensor. .. code-block:: cpp @@ -101,11 +103,13 @@ For example, for the case of 3 dimensions, the following components are stored: *The remaining components are inferred from symmetry*. -.. _cartesian_tensor2d: +.. _var_cartesian_tensor2d: ``cppmat::cartesian::tensor2d`` ------------------------------- +[:download:`var_cartesian_tensor2d.h <../src/cppmat/var_cartesian_tensor2d.h>`, :download:`var_cartesian_tensor2d.cpp <../src/cppmat/var_cartesian_tensor2d.cpp>`] + diagonal 2nd-order tensor. .. code-block:: cpp @@ -124,11 +128,13 @@ For example, for the case of 3 dimensions, the following components are stored: *The remaining components are imposed to be zero*. -.. _cartesian_vector: +.. _var_cartesian_vector: ``cppmat::cartesian::vector`` ----------------------------- +[:download:`var_cartesian_vector.h <../src/cppmat/var_cartesian_vector.h>`, :download:`var_cartesian_vector.cpp <../src/cppmat/var_cartesian_vector.cpp>`] + Vector (rank 1 tensor) of arbitrary dimension. For example: .. code-block:: cpp @@ -194,7 +200,7 @@ Vector (rank 1 tensor) of arbitrary dimension. For example: Methods ======= -For each class the index operator ``(...)``, the arithmetic operators ``*=``, ``*``,``/=``, ``/``,``+=``, ``+``,``-=``, ``-``, and the comparison operator ``==`` are available. Also, one can use ``.setZero()``, ``.setOnes()``, or ``.setConstant(...)`` to initialize all components to zero, one, or some constant. Furthermore, the following methods are available. +All the methods of :ref:`var_regular_array` (or :ref:`var_regular_matrix`, :ref:`var_symmetric_matrix`, :ref:`var_symmetric_matrix`, or :ref:`var_regular_vector`) are overloaded. In addition the following tensor algebra is available. .. note:: @@ -290,5 +296,5 @@ For each class the index operator ``(...)``, the arithmetic operators ``*=``, `` .. note:: - One can also call the methods as functions using ``cppmmat::ddot(A,B)``, ``cppmmat::dot(A,B)``, ``cppmmat::dyadic(A,B)``, ``cppmmat::cross(A,B)``, ``cppmmat::transpose(A)``, ``cppmmat::transposeR(A)``, ``cppmmat::transposeL(A)``, ``cppmmat::inv(A)``, ``cppmmat::det(A)``, and ``cppmmat::trace(A)``, These methods are just a front end for the class methods described above. + One can also call the methods as functions using ``cppmmat::ddot(A,B)``, ``cppmmat::dot(A,B)``, ``cppmmat::dyadic(A,B)``, ``cppmmat::cross(A,B)``, ``cppmmat::T(A)``, ``cppmmat::RT(A)``, ``cppmmat::LT(A)``, ``cppmmat::inv(A)``, ``cppmmat::det(A)``, and ``cppmmat::trace(A)``, These methods are just a front end for the class methods described above. diff --git a/docs/cppmat_cartesian2d.rst b/docs/cppmat_cartesian2d.rst deleted file mode 100644 index 054131d..0000000 --- a/docs/cppmat_cartesian2d.rst +++ /dev/null @@ -1,102 +0,0 @@ - -.. _cartesian2d: - -******************* -cppmat::cartesian2d -******************* - -[:download:`tensor2.h <../src/cppmat/tensor2.h>`, :download:`tensor2.cpp <../src/cppmat/tensor2.cpp>`] - -A specialization of :ref:`cartesian`, that takes advantage of the knowledge that the arrays are fixed size and small. Also several loops are unrolled. All the functionality and names of :ref:`cartesian` are transferable to :ref:`cartesian2d` and :ref:`cartesian3d`. - -Compared to :ref:`cartesian` the dimension argument must be omitted everywhere. - -.. note:: - - There is no way to automatically switch between :ref:`cartesian2d`, :ref:`cartesian3d`, and :ref:`cartesian`. - -Classes -======= - -.. _cartesian2d_tensor4: - -cppmat::cartesian2d::tensor4 ----------------------------- - -4th-order tensor (rank 4 tensor). - -.. code-block:: cpp - - cppmat::cartesian2d::tensor4 A; - - A(0,0,0,0) = ... - -.. _cartesian2d_tensor2: - -cppmat::cartesian2d::tensor2 ----------------------------- - -2nd-order tensor (rank 2 tensor). - -.. code-block:: cpp - - cppmat::cartesian2d::tensor2 A; - - A(0,0) = ... - -.. _cartesian2d_tensor2s: - -cppmat::cartesian2d::tensor2s ------------------------------ - -Symmetric 2nd-order tensor. - -.. code-block:: cpp - - cppmat::cartesian2d::tensor2s A; - - A(0,0) = ... - -The following components are stored: - -.. code-block:: cpp - - [ X , X ; - X ] - -*The remaining components are inferred from symmetry*. - -.. _cartesian2d_tensor2d: - -cppmat::cartesian2d::tensor2d ------------------------------ - -Diagonal 2nd-order tensor. - -.. code-block:: cpp - - cppmat::cartesian2d::tensor2d A; - - A(0,0) = ... - -The following components are stored: - -.. code-block:: cpp - - [ X ; - X ] - -*The remaining components are imposed to be zero*. - -.. _cartesian2d_vector: - -cppmat::cartesian2d::vector ---------------------------- - -Vector (rank 1 tensor). For example: - -.. code-block:: cpp - - cppmat::cartesian::vector A; - - A(0) = ... diff --git a/docs/cppmat_cartesian3d.rst b/docs/cppmat_cartesian3d.rst deleted file mode 100644 index 17503dd..0000000 --- a/docs/cppmat_cartesian3d.rst +++ /dev/null @@ -1,98 +0,0 @@ - -.. _cartesian3d: - -******************* -cppmat::cartesian3d -******************* - -[:download:`tensor3.h <../src/cppmat/tensor3.h>`, :download:`tensor3.cpp <../src/cppmat/tensor3.cpp>`] - -Identical to :ref:`cartesian2d`, but for 3 dimensions. - -Classes -======= - -.. _cartesian3d_tensor4: - -cppmat::cartesian3d::tensor4 ----------------------------- - -4th-order tensor (rank 4 tensor). - -.. code-block:: cpp - - cppmat::cartesian3d::tensor4 A; - - A(0,0,0,0) = ... - -.. _cartesian3d_tensor2: - -cppmat::cartesian3d::tensor2 ----------------------------- - -2nd-order tensor (rank 2 tensor). - -.. code-block:: cpp - - cppmat::cartesian3d::tensor2 A; - - A(0,0) = ... - -.. _cartesian3d_tensor2s: - -cppmat::cartesian3d::tensor2s ------------------------------ - -Symmetric 2nd-order tensor. - -.. code-block:: cpp - - cppmat::cartesian3d::tensor2s A; - - A(0,0) = ... - -The following components are stored: - -.. code-block:: cpp - - [ X , X , X ; - X , X ; - X ] - -*The remaining components are inferred from symmetry*. - -.. _cartesian3d_tensor2d: - -cppmat::cartesian3d::tensor2d ------------------------------ - -diagonal 2nd-order tensor. - -.. code-block:: cpp - - cppmat::cartesian3d::tensor2d A; - - A(0,0) = ... - -The following components are stored: - -.. code-block:: cpp - - [ X ; - X ; - X ] - -*The remaining components are imposed to be zero*. - -.. _cartesian3d_vector: - -cppmat::cartesian3d::vector ---------------------------- - -Vector (rank 1 tensor). For example: - -.. code-block:: cpp - - cppmat::cartesian::vector A; - - A(0) = ... diff --git a/docs/cppmat_fix.rst b/docs/cppmat_fix.rst new file mode 100644 index 0000000..fd8019f --- /dev/null +++ b/docs/cppmat_fix.rst @@ -0,0 +1,269 @@ + +************ +cppmat::tiny +************ + +.. _fix_regular_array: + +cppmat::tiny::array +==================== + +[:download:`fix_regular_array.h <../src/cppmat/fix_regular_array.h>`, :download:`fix_regular_array.cpp <../src/cppmat/fix_regular_array.cpp>`] + +Class for fixed size, small, n-d arrays. For example for a rank 3 array: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::array A; + + A(0,0,0) = ... + + ... + + return 0; + } + +Compared to :ref:`var_regular_array` the size of the array cannot be dynamically changed. Consequently there is not dynamic memory allocation, often resulting in faster behavior. For the rest, most methods are the same as for :ref:`var_regular_array`, though sometimes slightly more limited in use. + +.. _fix_regular_matrix: + +cppmat::tiny::matrix +==================== + +[:download:`fix_regular_matrix.h <../src/cppmat/fix_regular_matrix.h>`, :download:`fix_regular_matrix.cpp <../src/cppmat/fix_regular_matrix.cpp>`] + +Class for fixed size, small, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::matrix A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_regular_matrix`. + +.. _fix_regular_vector: + +cppmat::tiny::vector +==================== + +[:download:`fix_regular_vector.h <../src/cppmat/fix_regular_vector.h>`, :download:`fix_regular_vector.cpp <../src/cppmat/fix_regular_vector.cpp>`] + +Class for fixed size, small, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::vector A; + + A(0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_regular_vector`. + +.. _fix_symmetric_matrix: + +cppmat::tiny::symmetric::matrix +=============================== + +[:download:`fix_symmetric_matrix.h <../src/cppmat/fix_symmetric_matrix.h>`, :download:`fix_symmetric_matrix.cpp <../src/cppmat/fix_symmetric_matrix.cpp>`] + +Class for fixed size, small, symmetric, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::symmetric::matrix A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_symmetric_matrix`. + +.. _fix_diagonal_matrix: + +cppmat::tiny::diagonal::matrix +============================== + +[:download:`fix_diagonal_matrix.h <../src/cppmat/fix_diagonal_matrix.h>`, :download:`fix_diagonal_matrix.cpp <../src/cppmat/fix_diagonal_matrix.cpp>`] + +Class for fixed size, small, symmetric, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::diagonal::matrix A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_diagonal_matrix`. + +.. _fix_cartesian: + +cppmat::tiny::cartesian +======================= + +.. _fix_cartesian_tensor4: + +``cppmat::tiny::cartesian::tensor4`` +------------------------------------ + +[:download:`fix_cartesian_tensor4.h <../src/cppmat/fix_cartesian_tensor4.h>`, :download:`fix_cartesian_tensor4.cpp <../src/cppmat/fix_cartesian_tensor4.cpp>`] + +Class for fixed size, small, fourth order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::cartesian::tensor4 A; + + A(0,0,0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_cartesian_tensor4`. + +.. _fix_cartesian_tensor2: + +``cppmat::tiny::cartesian::tensor2`` +------------------------------------ + +[:download:`fix_cartesian_tensor2.h <../src/cppmat/fix_cartesian_tensor2.h>`, :download:`fix_cartesian_tensor2.cpp <../src/cppmat/fix_cartesian_tensor2.cpp>`] + +Class for fixed size, small, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::cartesian::tensor2 A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_cartesian_tensor2`. + +.. _fix_cartesian_tensor2s: + +``cppmat::tiny::cartesian::tensor2s`` +------------------------------------- + +[:download:`fix_cartesian_tensor2s.h <../src/cppmat/fix_cartesian_tensor2s.h>`, :download:`fix_cartesian_tensor2s.cpp <../src/cppmat/fix_cartesian_tensor2s.cpp>`] + +Class for fixed size, small, symmetric, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::cartesian::tensor2s A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_cartesian_tensor2s`. + +.. _fix_cartesian_tensor2d: + +``cppmat::tiny::cartesian::tensor2d`` +------------------------------------- + +[:download:`fix_cartesian_tensor2d.h <../src/cppmat/fix_cartesian_tensor2d.h>`, :download:`fix_cartesian_tensor2d.cpp <../src/cppmat/fix_cartesian_tensor2d.cpp>`] + +Class for fixed size, small, diagonal, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::cartesian::tensor2d A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_cartesian_tensor2d`. + +.. _fix_cartesian_vector: + +``cppmat::tiny::cartesian::vector`` +----------------------------------- + +[:download:`fix_cartesian_vector.h <../src/cppmat/fix_cartesian_vector.h>`, :download:`fix_cartesian_vector.cpp <../src/cppmat/fix_cartesian_vector.cpp>`] + +Class for fixed size, small, vector. For a 3-d vector + +.. code-block:: cpp + + #include + + int main() + { + cppmat::tiny::cartesian::vector A; + + A(0,0) = ... + + ... + + return 0; + } + +Most methods are the same as for :ref:`var_cartesian_vector`. diff --git a/docs/cppmat_map.rst b/docs/cppmat_map.rst new file mode 100644 index 0000000..1c17c7e --- /dev/null +++ b/docs/cppmat_map.rst @@ -0,0 +1,312 @@ + +************ +cppmat::view +************ + +.. _map_regular_array: + +cppmat::view::array +=================== + +[:download:`map_regular_array.h <../src/cppmat/map_regular_array.h>`, :download:`map_regular_array.cpp <../src/cppmat/map_regular_array.cpp>`] + +This class can be used to 'view' a ``const`` external pointer. This can be useful to refer to a part of a bigger array. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::array container = cppmat::array::Arange({100,4,2}); + + cppmat::view::array view; + + view.setMap(&container(10)); // equivalent to "view.setMap(&container(10,0,0));" + + std::cout << view << std::endl; + } + +This prints: + +.. code-block:: bash + + 80, 81; + 82, 83; + 84, 85; + 86, 87; + +.. warning:: + + Since C++ performs garbage collection you should use ``cppmat::view`` with care. You are responsible that pointers do not go out of scope. + +.. tip:: + + One can also use the ``Map`` constructor instead of the ``setMap`` method: + + .. code-block:: cpp + + using Mat = cppmat::view::matrix; + + Mat view = Mat::Map(&container(10)); + +.. note:: + + This function cannot make any modification to the view. Its usage is thus somewhat limited. To get a wider functionality use :ref:`fix_regular_array`. For example: + + .. code-block:: cpp + + #include + + int main() + { + cppmat::array container = cppmat::array::Arange({100,4,2}); + + cppmat::tiny::array copy; + + copy.setCopy(container.item(10), container.item(10)+copy.size()); + + std::cout << copy << std::endl; + } + + Note that ``copy`` is now a copy. I.e. any modification to ``copy`` will not result in a modification in ``container``. + + Note that the following syntax could also have been used: + + .. code-block:: cpp + + using Mat = cppmat::tiny::matrix; + + Mat copy = Mat::Copy(container.item(10), container.item(10)+8); + + Or the following: + + .. code-block:: cpp + + using Mat = cppmat::tiny::matrix; + + Mat copy = Mat::Copy(container.item(10)); + + Or the following: + + .. code-block:: cpp + + std::copy(container.item(10), container.item(10)+copy.size(), copy.data()); + +.. _map_regular_matrix: + +cppmat::view::matrix +==================== + +See :ref:`map_regular_array` and :ref:`fix_regular_matrix`. + +.. _map_regular_vector: + +cppmat::view::vector +==================== + +[:download:`map_regular_vector.h <../src/cppmat/map_regular_vector.h>`, :download:`map_regular_vector.cpp <../src/cppmat/map_regular_vector.cpp>`] + +See :ref:`map_regular_array` and :ref:`fix_regular_vector`. + +.. _map_symmetric_matrix: + +cppmat::view::symmetric::matrix +=============================== + +[:download:`map_symmetric_matrix.h <../src/cppmat/map_symmetric_matrix.h>`, :download:`map_symmetric_matrix.cpp <../src/cppmat/map_symmetric_matrix.cpp>`] + +Class to view a pointer to a fixed size, symmetric, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::symmetric::matrix A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_symmetric_matrix`. + +.. _map_diagonal_matrix: + +cppmat::view::diagonal::matrix +============================== + +[:download:`map_diagonal_matrix.h <../src/cppmat/map_diagonal_matrix.h>`, :download:`map_diagonal_matrix.cpp <../src/cppmat/map_diagonal_matrix.cpp>`] + +Class to view a pointer to a fixed size, symmetric, matrices. For example: + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::diagonal::matrix A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_diagonal_matrix`. + +.. _map_cartesian: + +cppmat::view::cartesian +======================= + +.. _map_cartesian_tensor4: + +``cppmat::view::cartesian::tensor4`` +------------------------------------ + +[:download:`map_cartesian_tensor4.h <../src/cppmat/map_cartesian_tensor4.h>`, :download:`map_cartesian_tensor4.cpp <../src/cppmat/map_cartesian_tensor4.cpp>`] + +Class to view a pointer to a fixed size, fourth order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::cartesian::tensor4 A; + + A.setMap(...) + + ... = A(0,0,0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_cartesian_tensor4`. + +.. _map_cartesian_tensor2: + +``cppmat::view::cartesian::tensor2`` +------------------------------------ + +[:download:`map_cartesian_tensor2.h <../src/cppmat/map_cartesian_tensor2.h>`, :download:`map_cartesian_tensor2.cpp <../src/cppmat/map_cartesian_tensor2.cpp>`] + +Class to view a pointer to a fixed size, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::cartesian::tensor2 A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_cartesian_tensor2`. + +.. _map_cartesian_tensor2s: + +``cppmat::view::cartesian::tensor2s`` +------------------------------------- + +[:download:`map_cartesian_tensor2s.h <../src/cppmat/map_cartesian_tensor2s.h>`, :download:`map_cartesian_tensor2s.cpp <../src/cppmat/map_cartesian_tensor2s.cpp>`] + +Class to view a pointer to a fixed size, symmetric, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::cartesian::tensor2s A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_cartesian_tensor2s`. + +.. _map_cartesian_tensor2d: + +``cppmat::view::cartesian::tensor2d`` +------------------------------------- + +[:download:`map_cartesian_tensor2d.h <../src/cppmat/map_cartesian_tensor2d.h>`, :download:`map_cartesian_tensor2d.cpp <../src/cppmat/map_cartesian_tensor2d.cpp>`] + +Class to view a pointer to a fixed size, diagonal, second order tensors. For a 3-d tensor + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::cartesian::tensor2d A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_cartesian_tensor2d`. + +.. _map_cartesian_vector: + +``cppmat::view::cartesian::vector`` +----------------------------------- + +[:download:`map_cartesian_vector.h <../src/cppmat/map_cartesian_vector.h>`, :download:`map_cartesian_vector.cpp <../src/cppmat/map_cartesian_vector.cpp>`] + +Class to view a pointer to a fixed size, vector. For a 3-d vector + +.. code-block:: cpp + + #include + + int main() + { + cppmat::view::cartesian::vector A; + + A.setMap(...) + + ... = A(0,0) + + ... + + return 0; + } + +Most methods are the same as for :ref:`fix_cartesian_vector`. + diff --git a/docs/cppmat_periodic.rst b/docs/cppmat_periodic.rst deleted file mode 100644 index dbf8da6..0000000 --- a/docs/cppmat_periodic.rst +++ /dev/null @@ -1,85 +0,0 @@ - -**************** -cppmat::periodic -**************** - -The classes below are identical to those under :ref:`cppmat`, with the exception that periodic indices can be used. For example ``-1`` will refer to the last index along that dimension (i.e. ``-1 -> N-1``, with ``N = A.shape(i)``), while ``N`` will refer to the first index (``N -> 0``). - -.. _periodic_array: - -cppmat::periodic::array -======================= - -[:download:`periodic_array.h <../src/cppmat/periodic_array.h>`, :download:`periodic_array.cpp <../src/cppmat/periodic_array.cpp>`] - - -.. code-block:: cpp - - #include - - int main() - { - cppmat::array A({10,10,10}); - - A(-1,-1,-1) = ... // last item - - ... - - return 0; - } - -.. note:: - - The entire interface is the same as for :ref:`regular_array`. - -.. _periodic_matrix: - -cppmat::periodic::matrix -======================== - -[:download:`periodic_matrix.h <../src/cppmat/periodic_matrix.h>`, :download:`periodic_matrix.cpp <../src/cppmat/periodic_matrix.cpp>`] - -.. code-block:: cpp - - #include - - int main() - { - cppmat::matrix A(10,10); - - A(-1,-1) = ... // last item - - ... - - return 0; - } - -.. note:: - - The entire interface is the same as for :ref:`regular_matrix`. - -.. _periodic_vector: - -cppmat::periodic::vector -======================== - -[:download:`periodic_vector.h <../src/cppmat/periodic_vector.h>`, :download:`periodic_vector.cpp <../src/cppmat/periodic_vector.cpp>`] - -.. code-block:: cpp - - #include - - int main() - { - cppmat::vector A(10); - - A(-1) = ... // last item - - ... - - return 0; - } - -.. note:: - - The entire interface is the same as for :ref:`regular_vector`. diff --git a/docs/cppmat_tiny.rst b/docs/cppmat_tiny.rst deleted file mode 100644 index 6dba442..0000000 --- a/docs/cppmat_tiny.rst +++ /dev/null @@ -1,72 +0,0 @@ - -.. _tiny: - -************ -cppmat::tiny -************ - -.. _tiny_matrix: - -cppmat::tiny::matrix -==================== - -[:download:`tiny_matrix.h <../src/cppmat/tiny_matrix.h>`, :download:`tiny_matrix.cpp <../src/cppmat/tiny_matrix.cpp>`] - -Class for fixed size, small, 2-d matrices. For example: - -.. code-block:: cpp - - #include - - int main() - { - cppmat::tiny::matrix A; - - A(0,0) = ... - - ... - - return 0; - } - -Compared to :ref:`regular_matrix` the size of the matrix cannot be dynamically changed. Consequently there is not dynamic memory allocation, often resulting in faster behavior. - -.. note:: - - The methods are the same as for :ref:`regular_matrix`. - -.. note:: - - To 'view' a pointer as a matrix, use :ref:`view_tiny_matrix`. - -.. _tiny_vector: - -cppmat::tiny::vector -==================== - -[:download:`tiny_vector.h <../src/cppmat/tiny_vector.h>`, :download:`tiny_vector.cpp <../src/cppmat/tiny_vector.cpp>`] - -Class for fixed size, small, 2-d matrices. For example: - -.. code-block:: cpp - - #include - - int main() - { - cppmat::tiny::vector A; - - A(0) = ... - - ... - - return 0; - } - -.. note:: - - The methods are the same as for :ref:`regular_vector`. - -.. note:: - - To 'view' a pointer as a matrix, use :ref:`view_tiny_vector`. diff --git a/docs/cppmat_var_diagonal.rst b/docs/cppmat_var_diagonal.rst new file mode 100644 index 0000000..e96d78e --- /dev/null +++ b/docs/cppmat_var_diagonal.rst @@ -0,0 +1,41 @@ + +**************** +cppmat::diagonal +**************** + +.. _var_diagonal_matrix: + +cppmat::diagonal::matrix +======================== + +[:download:`var_diagonal_matrix.h <../src/cppmat/var_diagonal_matrix.h>`, :download:`var_diagonal_matrix.cpp <../src/cppmat/var_diagonal_matrix.cpp>`] + +Square, diagonal, matrix, whereby only the diagonal components are stored: + +.. code-block:: cpp + + [ X ; + X ; + X ] + +*The remaining components are imposed to be zero*. This offers memory advantages, but also computational advantages as the library is fed with additional knowledge of the matrix. + +.. code-block:: cpp + + #include + + int main() + { + cppmat::diagonal::matrix A(3,3); + + A(0,0) = ... + + // A(0,1) = ... -> not allowed + // ... = A(0,1) -> allowed, returns zero + + ... + + std::cout << A << std::endl; + + return 0; + } diff --git a/docs/cppmat_regular.rst b/docs/cppmat_var_regular.rst similarity index 53% rename from docs/cppmat_regular.rst rename to docs/cppmat_var_regular.rst index d05404a..73950cf 100644 --- a/docs/cppmat_regular.rst +++ b/docs/cppmat_var_regular.rst @@ -1,18 +1,16 @@ -.. _cppmat: - ****** cppmat ****** -.. _regular_array: +.. _var_regular_array: cppmat::array ============= -[:download:`regular_array.h <../src/cppmat/regular_array.h>`, :download:`regular_array.cpp <../src/cppmat/regular_array.cpp>`] +[:download:`var_regular_array.h <../src/cppmat/var_regular_array.h>`, :download:`var_regular_array.cpp <../src/cppmat/var_regular_array.cpp>`] -Header-only module that provides a C++ class for n-d matrices. For example, a rank 3 matrix is allocated as follows: +A C++ class for dynamically sized n-d arrays. For example, a rank 3 array is allocated as follows: .. code-block:: cpp @@ -26,39 +24,55 @@ Header-only module that provides a C++ class for n-d matrices. For example, a ra ... + std::cout << A << std::endl; + return 0; } .. tip:: - If you know that you will work exclusively with a 2-dimensional matrix, please consider using :ref:`regular_matrix` instead of :ref:`regular_array`. This is generally more efficient. If, on top of that, you want to use only a small matrix, please use the fixed sized :ref:`tiny_matrix`. It doesn't need dynamic memory allocation, and can therefore be considerably faster. For the sake of generality there exist also the classes :ref:`regular_vector` and :ref:`tiny_vector`, which have many similarities to the standard C++ ``std::vector``. + * If you know that you will work exclusively with a rank 1 or 2 array (i.e. a vector or a matrix), consider using :ref:`var_regular_vector`, :ref:`var_regular_matrix`, :ref:`var_symmetric_matrix`, and , :ref:`var_diagonal_matrix`. This can enhance readability and/or efficiency. + + * If your array is not very big and its size is known at compile time consider using :ref:`fix_regular_array` (or the fixed size equivalents of the other classes). This avoids dynamic memory allocation, and usually speeds-up your code. + + * If your array is part of an external array (for example a bigger array) which you want to just read from, consider using :ref:`map_regular_array`. Methods ------- * ``A(i,j,k)`` - Return the entry at ``(i,j,k)``. The number of indices (i.e. ``A(i)``, ``A(i,j)``, ``A(i,j,k)``, ...) generally corresponds to the number of dimensions (see :ref:`matrix-index` for additional directives). + Returns the entry at ``(i,j,k)``. Use this to read or write. + + If the indices are input as ``int`` a negative may also be used, which counts from the last index along that axis. This implies some extra operations, so if you do not use this feature input the indices as ``size_t``. + + The number of indices (i.e. ``A(i)``, ``A(i,j)``, ``A(i,j,k)``, ...) may be lower or equal to the rank, all 'omitted' indices are assumed to be zero. + + See :ref:`array-index` for additional directives. * ``A[i]`` - Returns the ``i``-th entry in the matrix viewed as a list. + Returns the ``i``-th entry of the plain storage. Use this to read or write. * ``A.at(first, last)`` - Returns the entry ``{i,j,k}``, which are stored in a list. The function takes an iterator to the first and the last index of this list. See :ref:`matrix-index-advanced`. + Returns the entry ``{i,j,k}``, which are stored in a list. The function takes an iterator to the first and the last index of this list. See :ref:`array-index-advanced`. * ``A.item(i,j,k)`` - Return an iterator to the entry at ``(i,j,k)``. + Returns an iterator to the entry at ``(i,j,k)``. + +* ``A.index(i)`` + + Returns an iterator to the ``i``-th entry of the plain storage. * ``A.data()``, ``A.begin()``, ``A.end()`` Return an iterator to the data, the first, or the last entry of the matrix. -* ``A.ndim()`` +* ``A.rank()`` - Returns the number of dimensions of the matrix. + Returns the ranks of the array (i.e. the number of axes). * ``A.size()`` @@ -66,7 +80,7 @@ Methods * ``A.shape(i)`` - Returns the shape along dimension ``i``. + Returns the shape along dimension ``i`` (a negative number may be used that counts down from the last axis, e.g. ``A.shape(-1)`` is the same as ``A.shape(A.rank()-1)``. * ``A.shape()`` @@ -80,35 +94,35 @@ Methods Change the shape of the matrix. It is required that the total number of entries does not change. -* ``A.chdim(N)`` +* ``A.chrank(N)`` - Change the number of dimensions to ``N``. This affects the outputted ``shape``. For example: + Change the rank to ``N`` (with shape 1 along the added axes). A reduction of rank is only allowed if the shape is 1 along the reduced axes. - .. code-block:: cpp +* ``A.setZero()``, ``A.setOnes()``, ``A.setConstant(D)``, ``A.setArange()``, ``A.setRandom([start, end])`` - cppmat::array A({10,10}); + Set all entries to zero or one, a constant, the index in the flat storage, or a random value. - A.chdim(3); +* ``A.setCopy(first[, last])`` - Has the result that ``A.shape() == {10,10,1}``. + Copy the individual entries from some external object that is specified using iterators. Note that the flat-size has to match, i.e. ``last - first == size()``. -* ``A.setZero()``, ``A.setOnes()``, ``A.setConstant(...)``, ``A.setArange()`` +* ``A.copyTo(first[, last])`` - Set all entries to zero or one, a constant, or the index in the flat storage. + Copy the individual entries to an external iterator. -* ``A.setCopy(first, last)`` +* ``A.abs()`` - Copy the individual entries from some external object that is specified using iterators. Note that the flat-size has to match, i.e. ``last - first == size()``. + Returns an array with the absolute values of each entry. -* ``A.argmin()``, ``A.argmax()`` +* ``A.norm()`` - Return the array-indices of the minimum/maximum. + Returns the norm (sum of absolute values). -* ``A.argminIndex()``, ``A.argmaxIndex()`` +* ``A.argmin()``, ``A.argmax()`` - Return the plain store index of the minimum/maximum. + Return the plain storage index of the minimum/maximum. -* ``A.minCoeff([axis])``, ``A.maxCoeff([axis])`` +* ``A.min([axis])``, ``A.max([axis])`` Return the minimum or the maximum entry. @@ -120,16 +134,32 @@ Methods Return the mean of all entries, or along one or more axes. -* ``A.average(weights[, axis][, normalize])`` +* ``A.average(weights[, axis, normalize])`` Compute the weighted average of all entries, or along one or more axes. See `NumPy `_ and `Wikipedia `_. Optionally the result can be returned without normalization. +* ``A.where()`` + + Returns a vector with the plain storage indices of all non-zero entries. + +* ``A.equal(D)``, ``A.not_equal(D)``, ``A.greater(D)``, ``A.greater_equal(D)``, ``A.less(D)``, ``A.less_equal(D)`` + + Return array of booleans, based on the condition. + +* ``A.slice(...)`` + + Returns a slice of the array. The input are ``std::vector`` with the indices to select along that axis (these vectors can be also inputted using the ``{...}`` syntax). An empty vector (or simply ``{}``) implies that all indices along that axis are selected. + (Named) constructors -------------------- * ``cppmat::array(shape)`` - Allocate to a certain shape, nothing is initialized. + Allocate to a certain shape, nothing is initialized. The ``shape`` has to be specified as a ``std::vector``, from which the rank is automatically deduced. Alternatively the ``{...}`` notation can be used, to avoid a separate variable. + +* ``cppmat::array::Random(shape[, start, end])`` + + Allocate to a certain shape, set entries to a random value. * ``cppmat::array::Arange(shape)`` @@ -147,16 +177,16 @@ Methods * Allocate to a certain shape, set all entries to a certain constant. -* ``cppmat::array::Copy(shape, first, last)`` +* ``cppmat::array::Copy(shape, first[, last])`` * Allocate to a certain shape, copy the individual entries from some external object that is specified using iterators. Note that the flat-size has to match, i.e. ``last - first == size()``. -.. _matrix-index: +.. _array-index: Indexing -------- -In principle the number of indices should match the dimensions of the matrix (i.e. ``A.ndim()``). Though one can: +In principle the number of indices should match the rank of the array (i.e. ``A.rank()``). Though one can: * Reference to a certain index using a higher-dimensional equivalent. For example: @@ -170,43 +200,13 @@ In principle the number of indices should match the dimensions of the matrix (i. * Refer to the beginning of a block (e.g. a row) by omitting the trailing zero indices. For example, a pointer to the beginning of the second row of the above matrix is obtained by ``&A(1)`` (which is fully equivalent to ``&A(1,0)``). -.. _matrix-iterators: - -Iterators ---------- - -One can obtain iterators to: - -* The beginning of the matrix: - - .. code-block:: cpp - - A.begin() - -* The end of the matrix: - - .. code-block:: cpp - - A.end() - -* A specific point in the matrix - - .. code-block:: cpp - - A.item(i,j,k) - -* The data: - - .. code-block:: cpp - - A.data() +.. tip:: -View ----- + If the indices are input as ``int`` a negative may also be used, which counts from the last index along that axis. To input any *periodic* index (i.e. to turn-off the bound-checks) use ``.setPeriodic(true)`` on the array object. -To print, use the common C++ ``std::cout << A << std::endl;``. To customize formatting use the more classic C syntax ``A.printf("%16.8e");`` + Note that this all does cost extra operations. So, if you do not use this feature, input the indices as ``size_t``. -.. _matrix-index-advanced: +.. _array-index-advanced: Advanced indexing ----------------- @@ -292,12 +292,12 @@ The ``strides`` indicate per axis how many entries one needs to skip to proceed 6 1, 2, -.. _regular_matrix: +.. _var_regular_matrix: cppmat::matrix ============== -[:download:`regular_matrix.h <../src/cppmat/regular_matrix.h>`, :download:`regular_matrix.cpp <../src/cppmat/regular_matrix.cpp>`] +[:download:`var_regular_matrix.h <../src/cppmat/var_regular_matrix.h>`, :download:`var_regular_matrix.cpp <../src/cppmat/var_regular_matrix.cpp>`] Class for 2-d matrices. For example: @@ -316,16 +316,14 @@ Class for 2-d matrices. For example: return 0; } -.. note:: - - The entire interface is the same as for :ref:`regular_array`, though there is obviously no ``chdim`` method. +The entire interface is the same as for :ref:`var_regular_array`, though there is obviously no ``chrank`` method. -.. _regular_vector: +.. _var_regular_vector: cppmat::vector ============== -[:download:`regular_vector.h <../src/cppmat/regular_vector.h>`, :download:`regular_vector.cpp <../src/cppmat/regular_vector.cpp>`] +[:download:`var_regular_vector.h <../src/cppmat/var_regular_vector.h>`, :download:`var_regular_vector.cpp <../src/cppmat/var_regular_vector.cpp>`] Class for 1-d matrices (a.k.a. vectors). For example: @@ -344,11 +342,12 @@ Class for 1-d matrices (a.k.a. vectors). For example: return 0; } -.. note:: +The entire interface is the same as for :ref:`var_regular_array`, though there is obviously no ``chrank`` method. - The entire interface is the same as for :ref:`regular_array`, though there is obviously no ``chdim`` method. +.. tip:: -.. note:: + One can almost seamlessly switch between ``std::vector`` and ``cppmat::vector``. For example the following would work: - Compared to ``std::vector`` this class is not much difference. The only exception that it provides indexing also with round brackets, and automated printing of entries. + .. code-block:: cpp + std::vector A = cppmat::vector::Random(10); diff --git a/docs/cppmat_var_symmetric.rst b/docs/cppmat_var_symmetric.rst new file mode 100644 index 0000000..719a2fd --- /dev/null +++ b/docs/cppmat_var_symmetric.rst @@ -0,0 +1,40 @@ + +***************** +cppmat::symmetric +***************** + +.. _var_symmetric_matrix: + +cppmat::symmetric::matrix +========================= + +[:download:`var_symmetric_matrix.h <../src/cppmat/var_symmetric_matrix.h>`, :download:`var_symmetric_matrix.cpp <../src/cppmat/var_symmetric_matrix.cpp>`] + +Square, symmetric, matrix, whereby only the upper-diagonal components are stored: + +.. code-block:: cpp + + [ X, X, X ; + X, X ; + X ] + +*The remaining components are inferred from symmetry*. This offers memory advantages, but also computational advantages as the library is fed with additional knowledge of the matrix. + +.. code-block:: cpp + + #include + + int main() + { + cppmat::symmetric::matrix A(3,3); + + A(0,0) = ... + + // A(0,1) = ... -> same as A(1,0) = ... + + ... + + std::cout << A << std::endl; + + return 0; + } diff --git a/docs/cppmat_view.rst b/docs/cppmat_view.rst deleted file mode 100644 index 0b6e2de..0000000 --- a/docs/cppmat_view.rst +++ /dev/null @@ -1,246 +0,0 @@ - -.. _view: - -************ -cppmat::view -************ - -.. _view_tiny_matrix: - -cppmat::view::tiny::matrix -========================== - -[:download:`view_tiny_matrix.h <../src/cppmat/view_tiny_matrix.h>`, :download:`view_tiny_matrix.cpp <../src/cppmat/view_tiny_matrix.cpp>`] - -This class can be used to 'view' and external pointer. This can be useful to refer to a part of a bigger matrix. For example: - -.. code-block:: cpp - - #include - - int main() - { - cppmat::array container = cppmat::array::Arange({100,4,2}); - - cppmat::view::tiny::matrix view; - - view.setMap(&container(10)); // equivalent to "view.setMap(&container(10,0,0));" - - std::cout << view << std::endl; - } - -This prints: - -.. code-block:: bash - - 80, 81; - 82, 83; - 84, 85; - 86, 87; - -.. warning:: - - Since C++ performs garbage collection you should use ``cppmat::view`` with care. You are responsible that pointers do not go out of scope. - -.. note:: - - One can also use the ``Map`` constructor instead of the ``setMap`` method: - - .. code-block:: cpp - - using Mat = cppmat::view::tiny::matrix; - - Mat view = Mat::Map(&container(10)); - -.. note:: - - This function cannot make any modification to the view. Its usage is thus somewhat limited. To get a wider functionality use :ref:`tiny_matrix`. For example: - - .. code-block:: cpp - - #include - - int main() - { - cppmat::array container = cppmat::array::Arange({100,4,2}); - - cppmat::tiny::matrix copy; - - copy.setCopy(container.item(10), container.item(10)+copy.size()); - - std::cout << copy << std::endl; - } - - Note that ``copy`` is now a copy. I.e. any modification to ``copy`` will not result in a modification in ``container``. Also note that one could have used - - .. code-block:: cpp - - using Mat = cppmat::tiny::matrix; - - Mat copy = Mat::Copy(container.item(10), container.item(10)+8); - - or - - .. code-block:: cpp - - std::copy(container.item(10), container.item(10)+copy.size(), copy.data()); - -.. _view_tiny_vector: - -cppmat::view::tiny::vector -========================== - -[:download:`view_tiny_vector.h <../src/cppmat/view_tiny_vector.h>`, :download:`view_tiny_vector.cpp <../src/cppmat/view_tiny_vector.cpp>`] - -See :ref:`view_tiny_matrix` and :ref:`tiny_vector`. - -.. _view_cartesian2d: - -cppmat::view::cartesian2d -========================= - -[:download:`view_tensor2.h <../src/cppmat/view_tensor2.h>`, :download:`view_tensor2.cpp <../src/cppmat/view_tensor2.cpp>`] - -This class can be used to 'view' and external pointer. This can be useful to refer to a part of a bigger matrix. For example: - -.. code-block:: cpp - - #include - - int main() - { - cppmat::array container = cppmat::array::Arange({50,50,3}); - - cppmat::view::cartesian2d::tensor2s view; - - view.setMap(&container(10,0)); // equivalent to "view.map(&container(10,0,0));" - - std::cout << view << std::endl; - } - -This prints: - -.. code-block:: bash - - 1500, 1501; - 1501, 1502; - -.. warning:: - - Since C++ performs garbage collection you should use ``cppmat::view`` with care. You are responsible that pointers do not go out of scope. - -.. note:: - - One can also use the ``Map`` constructor instead of the ``setMap`` method: - - .. code-block:: cpp - - using T2s = cppmat::view::cartesian2d::tensor2s; - - T2s view = T2s::Map(&container(10,0)); - -.. note:: - - This function cannot make any modification to the view. Its usage is thus somewhat limited. To get a wider functionality use :ref:`cartesian2d`. For example: - - .. code-block:: cpp - - #include - - int main() - { - cppmat::array container = cppmat::array::Arange({50,50,3}); - - cppmat::cartesian2d::tensor2s copy; - - copy.setCopy(container.item(10,10), container.item(10,10)+copy.size()); - - std::cout << copy << std::endl; - } - - Note that ``copy`` is now a copy. I.e. any modification to ``copy`` will not result in a modification in ``container``. - -Classes -------- - -.. _view_cartesian2d_tensor4: - -cppmat::view::cartesian2d::tensor4 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -4th-order tensor (rank 4 tensor). - -.. _view_cartesian2d_tensor2: - -cppmat::view::cartesian2d::tensor2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -2nd-order tensor (rank 2 tensor). - -.. _view_cartesian2d_tensor2s: - -cppmat::view::cartesian2d::tensor2s -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Symmetric 2nd-order tensor. - -.. _view_cartesian2d_tensor2d: - -cppmat::view::cartesian2d::tensor2d -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Diagonal 2nd-order tensor. - -.. _view_cartesian2d_vector: - -cppmat::view::cartesian2d::vector -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Vector (rank 1 tensor). - -.. _view_cartesian3d: - -cppmat::view::cartesian3d -========================= - -[:download:`view_tensor3.h <../src/cppmat/view_tensor3.h>`, :download:`view_tensor3.cpp <../src/cppmat/view_tensor3.cpp>`] - -See :ref:`view_cartesian2d`. - -Classes -------- - -.. _view_cartesian3d_tensor4: - -cppmat::view::cartesian3d::tensor4 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -4th-order tensor (rank 4 tensor). - -.. _view_cartesian3d_tensor2: - -cppmat::view::cartesian3d::tensor2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -2nd-order tensor (rank 2 tensor). - -.. _view_cartesian3d_tensor2s: - -cppmat::view::cartesian3d::tensor2s -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Symmetric 2nd-order tensor. - -.. _view_cartesian3d_tensor2d: - -cppmat::view::cartesian3d::tensor2d -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Diagonal 2nd-order tensor. - -.. _view_cartesian3d_vector: - -cppmat::view::cartesian3d::vector -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Vector (rank 1 tensor). diff --git a/docs/develop.rst b/docs/develop.rst index 4fa6d94..0da470e 100644 --- a/docs/develop.rst +++ b/docs/develop.rst @@ -3,6 +3,13 @@ Notes for developers ******************** +Structure +========= + +.. image:: hierarchy.svg + :width: 800px + :align: center + Make changes / additions ======================== diff --git a/docs/index.rst b/docs/index.rst index 49a01b4..34e680d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,7 +41,7 @@ cppmat .. note:: - This library is free to use under the `MIT license `_. Any additions are very much appreciated, in terms of suggested functionality, code, documentation, testimonials, word of mouth advertisement, .... Bug reports or feature requests can be filed on `GitHub `_. As always, the code comes with no guarantee. None of the developers can be held responsible for possible mistakes. + This library is free to use under the `MIT license `_. Any additions are very much appreciated, in terms of suggested functionality, code, documentation, testimonials, word of mouth advertisement, .... Bugs or feature requests can be filed on `GitHub `_. As always, the code comes with no guarantee. None of the developers can be held responsible for possible mistakes. .. tip:: @@ -49,91 +49,87 @@ cppmat This header-only module provides C++ classes and several accompanying methods to work with n-d matrices and/or tensors. It's usage, programmatically and from a compilation perspective, is really simple. One just has to ``#include `` and tell your compiler where cppmat is located (and to the C++14 or younger standard). Really, that's it! - Overview ======== -The following classes can be used. - -+-------------------------------------------------------------+--------------------------------------+ -| **Class** | **Description** | -+=============================================================+======================================+ -| :ref:`cppmat::array ` | n-d matrix of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::matrix ` | 2-d matrix of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::vector ` | array (1-d matrix) of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::periodic::array ` | n-d matrix of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::periodic::matrix ` | 2-d matrix of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::periodic::vector ` | array (1-d matrix) of flexible size | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::tiny::matrix ` | small, fixed size, 2-d matrix | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::tiny::vector ` | small, fixed size, array | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian::tensor4 ` | n-d tensor of rank 4 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian::tensor2 ` | n-d tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian::tensor2s ` | n-d symmetric tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian::tensor2d ` | n-d diagonal tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian::vector ` | n-d vector (tensor of rank 1) | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian2d::tensor4 ` | 2-d tensor of rank 4 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian2d::tensor2 ` | 2-d tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian2d::tensor2s ` | 2-d symmetric tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian2d::tensor2d ` | 2-d diagonal tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian2d::vector ` | 2-d vector (tensor of rank 1) | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian3d::tensor4 ` | 3-d tensor of rank 4 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian3d::tensor2 ` | 3-d tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian3d::tensor2s ` | 3-d symmetric tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian3d::tensor2d ` | 3-d diagonal tensor of rank 2 | -+-------------------------------------------------------------+--------------------------------------+ -| :ref:`cppmat::cartesian3d::vector ` | 3-d vector (tensor of rank 1) | -+-------------------------------------------------------------+--------------------------------------+ - -In addition, the following classes are available to view a ``const``-pointer: - -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| **Class** | **Equivalent class** | -+========================================================================+=============================================================+ -| :ref:`cppmat::view::tiny::matrix ` | :ref:`cppmat::tiny::matrix ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::tiny::vector ` | :ref:`cppmat::tiny::vector ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian2d::tensor4 ` | :ref:`cppmat::cartesian2d::tensor4 ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian2d::tensor2 ` | :ref:`cppmat::cartesian2d::tensor2 ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian2d::tensor2s ` | :ref:`cppmat::cartesian2d::tensor2s ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian2d::tensor2d ` | :ref:`cppmat::cartesian2d::tensor2d ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian2d::vector ` | :ref:`cppmat::cartesian2d::vector ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian3d::tensor4 ` | :ref:`cppmat::cartesian3d::tensor4 ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian3d::tensor2 ` | :ref:`cppmat::cartesian3d::tensor2 ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian3d::tensor2s ` | :ref:`cppmat::cartesian3d::tensor2s ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian3d::tensor2d ` | :ref:`cppmat::cartesian3d::tensor2d ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ -| :ref:`cppmat::view::cartesian3d::vector ` | :ref:`cppmat::cartesian3d::vector ` | -+------------------------------------------------------------------------+-------------------------------------------------------------+ +The following dynamically sized classes can be used. + ++-------------------------------------------------------------+----------------------------------+ +| **Class** | **Description** | ++=============================================================+==================================+ +| :ref:`cppmat::array ` | array of arbitrary rank | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::matrix ` | matrix (array of rank 2) | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::vector ` | vector (array of rank 1) | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::symmetric::matrix ` | symmetric, square, matrix | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::diagonal::matrix ` | diagonal, square, matrix | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::cartesian::tensor4 ` | 4th-order tensor | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::cartesian::tensor2 ` | 2nd-order tensor | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::cartesian::tensor2s ` | 2nd-order symmetric tensor | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::cartesian::tensor2d ` | 2nd-order diagonal tensor | ++-------------------------------------------------------------+----------------------------------+ +| :ref:`cppmat::cartesian::vector ` | 1st-order tensor (a.k.a. vector) | ++-------------------------------------------------------------+----------------------------------+ + +Each of these class has a fixed size equivalent (that is usually more efficient): + ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| **Fixed size** | **Dynamical size** | ++===================================================================+=============================================================+ +| :ref:`cppmat::tiny::array ` | :ref:`cppmat::array ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::matrix ` | :ref:`cppmat::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::vector ` | :ref:`cppmat::vector ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::symmetric::matrix ` | :ref:`cppmat::symmetric::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::diagonal::matrix ` | :ref:`cppmat::diagonal::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::cartesian::tensor4 ` | :ref:`cppmat::cartesian::tensor4 ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::cartesian::tensor2 ` | :ref:`cppmat::cartesian::tensor2 ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::cartesian::tensor2s ` | :ref:`cppmat::cartesian::tensor2s ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::cartesian::tensor2d ` | :ref:`cppmat::cartesian::tensor2d ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ +| :ref:`cppmat::tiny::cartesian::vector ` | :ref:`cppmat::cartesian::vector ` | ++-------------------------------------------------------------------+-------------------------------------------------------------+ + +Each fixed size class has an equivalent which can view a ``const``-pointer (with limited functionality): + ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| **View pointer** | **Fixed size** | ++===================================================================+===================================================================+ +| :ref:`cppmat::view::array ` | :ref:`cppmat::tiny::array ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::matrix ` | :ref:`cppmat::tiny::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::vector ` | :ref:`cppmat::tiny::vector ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::symmetric::matrix ` | :ref:`cppmat::tiny::symmetric::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::diagonal::matrix ` | :ref:`cppmat::tiny::diagonal::matrix ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::cartesian::tensor4 ` | :ref:`cppmat::tiny::cartesian::tensor4 ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::cartesian::tensor2 ` | :ref:`cppmat::tiny::cartesian::tensor2 ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::cartesian::tensor2s ` | :ref:`cppmat::tiny::cartesian::tensor2s ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::cartesian::tensor2d ` | :ref:`cppmat::tiny::cartesian::tensor2d ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ +| :ref:`cppmat::view::cartesian::vector ` | :ref:`cppmat::tiny::cartesian::vector ` | ++-------------------------------------------------------------------+-------------------------------------------------------------------+ + Example ======= @@ -159,13 +155,12 @@ Contents .. toctree:: :maxdepth: 1 - cppmat_regular.rst - cppmat_periodic.rst - cppmat_tiny.rst + cppmat_var_regular.rst + cppmat_var_symmetric.rst + cppmat_var_diagonal.rst cppmat_cartesian.rst - cppmat_cartesian2d.rst - cppmat_cartesian3d.rst - cppmat_view.rst + cppmat_fix.rst + cppmat_map.rst copy.rst compile.rst python.rst diff --git a/docs/python.rst b/docs/python.rst index ac3471b..d94166f 100644 --- a/docs/python.rst +++ b/docs/python.rst @@ -7,49 +7,41 @@ Python interface This library includes provides an interface to `pybind11 `_ such that an interface to NumPy arrays is automatically provided when including a function with any of the cppmat classes: -+-----------------------------------+---------------------------+ -| **cppmat class** | **Rank of NumPy-array** | -+===================================+===========================+ -| ``cppmat::array`` | n | -+-----------------------------------+---------------------------+ -| ``cppmat::matrix`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::vector`` | 1 | -+-----------------------------------+---------------------------+ -| ``cppmat::tiny::matrix`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::tiny::vector`` | 1 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian::tensor4`` | 4 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian::tensor2`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian::tensor2s`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian::tensor2d`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian::vector`` | 1 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian2d::tensor4`` | 4 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian2d::tensor2`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian2d::tensor2s`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian2d::tensor2d`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian2d::vector`` | 1 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian3d::tensor4`` | 4 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian3d::tensor2`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian3d::tensor2s`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian3d::tensor2d`` | 2 | -+-----------------------------------+---------------------------+ -| ``cppmat::cartesian3d::vector`` | 1 | -+-----------------------------------+---------------------------+ ++---------------------------------------+---------------------------+ +| **cppmat class** | **Rank of NumPy-array** | ++=======================================+===========================+ +| ``cppmat::array`` | n | ++---------------------------------------+---------------------------+ +| ``cppmat::matrix`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::vector`` | 1 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::array`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::matrix`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::vector`` | 1 | ++---------------------------------------+---------------------------+ +| ``cppmat::cartesian::tensor4`` | 4 | ++---------------------------------------+---------------------------+ +| ``cppmat::cartesian::tensor2`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::cartesian::tensor2s`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::cartesian::tensor2d`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::cartesian::vector`` | 1 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::cartesian::tensor4`` | 4 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::cartesian::tensor2`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::cartesian::tensor2s`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::cartesian::tensor2d`` | 2 | ++---------------------------------------+---------------------------+ +| ``cppmat::tiny::cartesian::vector`` | 1 | ++---------------------------------------+---------------------------+ .. note:: **Warning** @@ -59,7 +51,7 @@ This library includes provides an interface to `pybind11 `` and ````.) + (The same holds for the classes under ``cppmat::tiny::cartesian`` To use this feature one has to: