1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
.. Copyright (c) 2016, Johan Mabille, Sylvain Corlay and Wolf Vollprecht
Distributed under the terms of the BSD 3-Clause License.
The full license is in the file LICENSE, distributed with this software.
Build and configuration
=======================
Build
-----
*xtensor* build supports the following options:
- ``BUILD_TESTS``: enables the ``xtest`` and ``xbenchmark`` targets (see below).
- ``DOWNLOAD_GTEST``: downloads ``gtest`` and builds it locally instead of using a binary installation.
- ``GTEST_SRC_DIR``: indicates where to find the ``gtest`` sources instead of downloading them.
- ``XTENSOR_ENABLE_ASSERT``: activates the assertions in *xtensor*.
- ``XTENSOR_CHECK_DIMENSION``: turns on ``XTENSOR_ENABLE_ASSERT`` and activates dimension checks in *xtensor*.
Note that the dimensions check should not be activated if you expect ``operator()`` to perform broadcasting.
- ``XTENSOR_USE_XSIMD``: enables simd acceleration in *xtensor*. This requires that you have xsimd_ installed
on your system.
- ``XTENSOR_USE_TBB``: enables parallel assignment loop. This requires that you have you have tbb_ installed
on your system.
- Optionally use ``XTENSOR_TBB_THRESHOLD`` to set a minimum size to trigger parallel assignment (default is 0)
- ``XTENSOR_USE_OPENMP``: enables parallel assignment loop using OpenMP. This requires that OpenMP is available on your system.
All these options are disabled by default. Enabling ``DOWNLOAD_GTEST`` or
setting ``GTEST_SRC_DIR`` enables ``BUILD_TESTS``.
If the ``BUILD_TESTS`` option is enabled, the following targets are available:
- xtest: builds an run the test suite.
- xbenchmark: builds and runs the benchmarks.
For instance, building the test suite of *xtensor* with assertions enabled:
.. code::
mkdir build
cd build
cmake -DBUILD_TESTS=ON -DXTENSOR_ENABLE_ASSERT=ON ../
make xtest
Building the test suite of *xtensor* where the sources of ``gtest`` are
located in e.g. ``/usr/share/gtest``:
.. code::
mkdir build
cd build
cmake -DGTEST_SRC_DIR=/usr/share/gtest ../
make xtest
.. _configuration-label:
Configuration
-------------
*xtensor* can be configured via macros, which must be defined *before*
including any of its header. Here is a list of available macros:
- ``XTENSOR_ENABLE_ASSERT``: enables assertions in xtensor, such as bound check.
- ``XTENSOR_ENABLE_CHECK_DIMENSION``: enables the dimensions check in *xtensor*. Note that this option should not be turned
on if you expect ``operator()`` to perform broadcasting.
- ``XTENSOR_USE_XSIMD``: enables SIMD acceleration in *xtensor*. This requires that you have xsimd_ installed
on your system.
- ``XTENSOR_USE_TBB``: enables parallel assignment loop. This requires that you have you have tbb_ installed
on your system.
- ``XTENSOR_USE_OPENMP``: enables parallel assignment loop using OpenMP. This requires that OpenMP is available on your system.
- ``XTENSOR_DEFAULT_DATA_CONTAINER(T, A)``: defines the type used as the default data container for tensors and arrays. ``T``
is the ``value_type`` of the container and ``A`` its ``allocator_type``.
- ``XTENSOR_DEFAULT_SHAPE_CONTAINER(T, EA, SA)``: defines the type used as the default shape container for tensors and arrays.
``T`` is the ``value_type`` of the data container, ``EA`` its ``allocator_type``, and ``SA`` is the ``allocator_type``
of the shape container.
- ``XTENSOR_DEFAULT_LAYOUT``: defines the default layout (row_major, column_major, dynamic) for tensors and arrays. We *strongly*
discourage using this macro, which is provided for testing purpose. Prefer defining alias types on tensor and array
containers instead.
- ``XTENSOR_DEFAULT_TRAVERSAL``: defines the default traversal order (row_major, column_major) for algorithms and iterators on tensors
and arrays. We *strongly* discourage using this macro, which is provided for testing purpose.
Build the documentation
-----------------------
First install the tools required to build the documentation:
.. code::
conda install breathe doxygen sphinx_rtd_theme -c conda-forge
You can then build the documentation:
.. code::
cd docs
make html
Type ``make help`` to see the list of available documentation targets.
.. _xsimd: https://github.com/xtensor-stack/xsimd
.. _tbb: https://www.threadingbuildingblocks.org
|
