You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
See `Pybind11's CMake build system documentation <https://pybind11.readthedocs.io/en/stable/compiling.html#building-with-cmake>`_ or `CARMA's examples <https://github.com/RUrlus/carma/blob/stable/examples/CMakeLists.txt>`_ for a start.
19
18
20
-
Carma provides both tests and examples that can be compiled without any additional libraries, although you will need additional libraries to use Armadillo in practice.
21
-
22
-
.. note:: The Pybind11 and Armadillo libraries are linked with `carma` as submodule in `third_party` directory. To get them using :bash:`git clone`, don't forget to use :bash:`--recursive` option.
23
-
24
-
Manual compilation
25
-
******************
26
-
27
-
Although using a build system is suggested, the :bash:`examples/example.cpp` can be compiled with:
arma::Mat<double> mat = carma::arr_to_mat<double>(arr);
162
-
163
-
// normally you do something useful here ...
164
-
arma::Mat<double> result = arma::Mat<double>(arr.shape(0), arr.shape(1), arma::fill::randu);
165
-
166
-
// convert to Numpy array and return
167
-
return carma::mat_to_arr(result);
168
-
}
71
+
You can borrow the underlying memory of a Numpy array using the ``arr_to_*(py::array_t<T>, copy=false)``. The Armadillo object should not be returned without a copy out. Use this when you want to modify the memory in-place. If the array is not well behaved, see :doc:`Memory Management -- well behaved <well_behaved>`, the data is copied to a well-behaved memory and swapped in place of the input array. If ``copy=true`` is equivalent to the copy approach below.
169
72
170
-
Update array
171
-
************
172
-
173
-
.. code-block:: c++
174
-
175
-
#include <armadillo>
176
-
#include <carma/carma.h>
177
-
#include <pybind11/pybind11.h>
178
-
#include <pybind11/numpy.h>
179
-
180
-
void update_example(py::array_t<double> & arr) {
181
-
// convert to armadillo matrix without copying.
182
-
arma::Mat<double> mat = carma::arr_to_mat<double>(arr);
183
-
184
-
// normally you do something useful here with mat ...
185
-
mat += arma::Mat<double>(arr.shape(0), arr.shape(1), arma::fill::randu);
186
-
187
-
// update Numpy array buffer
188
-
carma::update_array(mat, arr);
189
-
}
73
+
.. note:: the size of the Armadillo object is not allowed change when you borrow.
190
74
191
75
Transfer ownership
192
-
******************
76
+
------------------
193
77
194
-
If you want to transfer ownership to the C++ side you can use:
78
+
You can transfer ownership to Armadillo using steal or copy.
For automatic conversion you specify the desired Armadillo type for either or both the return type and the function parameter.
231
-
When calling the function from Python, Pybind11 will call `carma`'s type caster when a Numpy array is passed or returned.
232
-
233
-
.. warning:: Make sure to include `carma` in every compilation unit that makes use of the type caster, not including it results in undefined behaviour.
// type caster will take care of casting `result` to a Numpy array.
248
-
return result;
249
-
}
83
+
If you want to take ownership of the underlying memory but don't want to copy the
84
+
data you can steal the array. The Armadillo object can be safely returned out without a copy. There are multiple compile time definitions on how the memory is stolen, see :doc:`Configuration <configuration>` for details. If the memory of the
85
+
array is not well-behaved a copy of the memory is stolen.
250
86
251
-
.. warning::
252
-
253
-
The automatic conversion will **not** copy the Numpy array's memory when converting to Armadillo objects.
254
-
When converting back to Numpy arrays the memory will **not** be copied when converting back from matrices but **will be** copied from a vector or cube.
255
-
See :doc:`Memory Management <memory_management>` for details.
87
+
After stealing the Armadillo behaves as if has allocated the memory itself, hence it will also clean the memory upon destruction.
256
88
257
-
ArrayStore
258
-
**********
89
+
.. note:: the size of the Armadillo object is allowed change after stealing.
259
90
260
-
There are use-cases where you would want to keep the data in C++ and only return when requested.
261
-
For example, you write an Ordinary Least Squares (OLS) class and you want to store the residuals, covariance matrix, ... in C++ for when additional tests need to be run on the values without converting back and forth.
91
+
Copy
92
+
****
262
93
263
-
ArrayStore is a convenience class that provides conversion methods back and forth.
264
-
It is intended to used as an attribute such as below:
94
+
If you want to give Armadillo full control of underlying memory but also want to keep Numpy as owner you should copy. The Armadillo object can be safely returned out without a copy. If the memory of the array is not well-behaved a copy of the memory is used instead.
265
95
266
-
.. code-block:: c++
96
+
.. note:: the size of the Armadillo object is allowed change after copying.
The ArrayStore owns the data, the returned numpy arrays are views that
313
-
are tied to the lifetime of ArrayStore.
98
+
View
99
+
----
100
+
101
+
If you want to have a read-only view on the underlying memory you can use ``arr_to_*_view``. If the underlying memory is not well-behaved it will be copied.
0 commit comments