Manual conversion¶
CARMA provides a set of functions for manual conversion of Numpy arrays and Armadillo matrices. Manual conversion should be used when fine grained control of memory is required.
Numpy to Armadillo¶
Functions to convert Numpy arrays to Armadillo matrices, vectors or cubes
Matrix¶
-
arma::Mat<T> arr_to_mat(py::array<T>& arr, bool copy=false)
Convert Numpy array to Armadillo matrix. When borrowing the the array, copy=false, if it is not well-behaved we perform a in-place swap to a well behaved array
If the array is 1D we create a column oriented matrix (N, 1)
Parameters: - arr – numpy array to be converted
- copy – copy the memory of the array, default is false
Raises: - runtime_error – if n_dims > 2 or memory is not initialised (nullptr)
- runtime_error – if copy is false and the array is not well-behaved and not writable as this prevents an inplace-swap.
-
arma::Mat<T> arr_to_mat(const py::array<T>& arr)
Copy the memory of the Numpy array in the conversion to Armadillo matrix.
If the array is 1D we create a column oriented matrix (N, 1)
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims > 2 or memory is not initialised (nullptr)
-
arma::Mat<T> arr_to_mat(py::array<T>&& arr)
Steal the memory of the Numpy array in the conversion to Armadillo matrix. If the memory is not well-behaved we steal a copy of the array
If the array is 1D we create a column oriented matrix (N, 1)
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims > 2 or memory is not initialised (nullptr)
-
const arma::Mat<T> arr_to_mat_view(const py::array<T>& arr)
Copy the memory of the Numpy array in the conversion to Armadillo matrix if not well behaved otherwise borrow.
If the array is 1D we create a column oriented matrix (N, 1)
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims > 2 or memory is not initialised (nullptr)
Vector¶
-
arma::Col<T> arr_to_col(py::array<T>& arr, bool copy=false)
Convert Numpy array to Armadillo column. When borrowing the the array, copy=false, if it is not well-behaved we perform a in-place swap to a well behaved array
Parameters: - arr – numpy array to be converted
- copy – copy the memory of the array, default is false
Raises: - runtime_error – if n_cols > 1 or memory is not initialised (nullptr)
- runtime_error – if copy is false and the array is not well-behaved and not writable as this prevents an inplace-swap.
-
arma::Col<T> arr_to_col(const py::array<T>& arr)
Copy the memory of the Numpy array in the conversion to Armadillo column.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_cols > 1 or memory is not initialised (nullptr)
-
arma::Col<T> arr_to_col(py::array<T>&& arr)
Steal the memory of the Numpy array in the conversion to Armadillo column. If the memory is not well-behaved we steal a copy of the array
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_cols > 1 or memory is not initialised (nullptr)
-
const arma::Col<T> arr_to_col_view(const py::array<T>& arr)
Create a read-only view on the array as a Armadillo Col. Copy the memory of the Numpy array in the conversion to Armadillo column if not well_behaved otherwise borrow the array.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_cols > 1 or memory is not initialised (nullptr)
-
arma::Row<T> arr_to_row(py::array<T>& arr, bool copy=false)
Convert Numpy array to Armadillo row. When borrowing the the array, copy=false, if it is not well-behaved we perform a in-place swap to a well behaved array
Parameters: - arr – numpy array to be converted
- copy – copy the memory of the array, default is false
Raises: - runtime_error – if n_rows > 1 or memory is not initialised (nullptr)
- runtime_error – if copy is false and the array is not well-behaved and not writable as this prevents an inplace-swap.
-
arma::Row<T> arr_to_col(const py::array<T>& arr)
Copy the memory of the Numpy array in the conversion to Armadillo row.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_rows > 1 or memory is not initialised (nullptr)
-
arma::Row<T> arr_to_col(py::array<T>&& arr)
Steal the memory of the Numpy array in the conversion to Armadillo row. If the memory is not well-behaved we steal a copy of the array
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_cols > 1 or memory is not initialised (nullptr)
-
const arma::Row<T> arr_to_col_view(const py::array<T>& arr)
Create a read-only view on the array as a Armadillo Col. Copy the memory of the Numpy array if not well_behaved otherwise borrow the array.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_rows > 1 or memory is not initialised (nullptr)
Cube¶
-
arma::Cube<T> arr_to_cube(py::array<T>& arr, bool copy=false)
Convert Numpy array to Armadillo Cube. When borrowing the the array, copy=false, if it is not well-behaved we perform a in-place swap to a well behaved array
Parameters: - arr – numpy array to be converted
- copy – copy the memory of the array, default is false
Raises: - runtime_error – if n_dims < 3 or memory is not initialised (nullptr)
- runtime_error – if copy is false and the array is not well-behaved and not writable as this prevents an inplace-swap.
-
arma::Cube<T> arr_to_cube(const py::array<T>& arr)
Copy the memory of the Numpy array in the conversion to Armadillo Cube.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims < 3 or memory is not initialised (nullptr)
-
arma::Cube<T> arr_to_cube(py::array<T>&& arr)
Steal the memory of the Numpy array in the conversion to Armadillo Cube. If the memory is not well-behaved we steal a copy of the array
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims < 3 or memory is not initialised (nullptr)
-
const arma::Cube<T> arr_to_cube_view(const py::array<T>& arr)
Create a read-only view on the array as a Armadillo Cube. Copy the memory of the Numpy array if not well_behaved otherwise borrow the array.
Parameters: arr – numpy array to be converted Raises: runtime_error – if n_dims < 3 or memory is not initialised (nullptr)
to_arma¶
to_arma
is a convenience wrapper around the arr_to_*
functions and has the same behaviour and rules. For example,
arma::Mat<double> mat = to_arma::from<arma::Mat<double>>(arr, copy=false);
-
template <typename armaT> armaT to_arma::from(const py::array_t<eT>& arr)
-
template <typename armaT> armaT to_arma::from(py::array_t<eT>& arr, bool copy)
-
template <typename armaT> armaT to_arma::from( py::array_t<eT>&& arr)
Armadillo to Numpy¶
This section documents the functions to convert Armadillo matrices, vectors or cubes to Numpy arrays.
Matrix¶
-
py::array_t<T> mat_to_arr(arma::Mat<T>& src, bool copy=false)
Convert Armadillo matrix to Numpy array, note the returned array will have column contiguous memory (F-order)
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false which steals the memory
-
py::array_t<T> mat_to_arr(const arma::Mat<T>& src)
Copy the memory of the Armadillo matrix in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> mat_to_arr(arma::Mat<T>&& src)
Steal the memory of the Armadillo matrix in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> mat_to_arr(arma::Mat<T>* src, bool copy=false)
Convert Armadillo matrix to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false
Vector¶
-
py::array_t<T> col_to_arr(arma::Col<T>& src, bool copy=false)
Convert Armadillo col to Numpy array, note the returned array will have column contiguous memory (F-order)
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false which steals the memory
-
py::array_t<T> col_to_arr(const arma::Col<T>& src)
Copy the memory of the Armadillo Col in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> col_to_arr(arma::Col<T>&& src)
Steal the memory of the Armadillo Col in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> col_to_arr(arma::Col<T>* src, bool copy=false)
Convert Armadillo Col to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false
-
py::array_t<T> row_to_arr(arma::Row<T>& src, bool copy=false)
Convert Armadillo Row to Numpy array, note the returned array will have column contiguous memory (F-order)
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false which steals the memory
-
py::array_t<T> row_to_arr(const arma::Row<T>& src)
Copy the memory of the Armadillo Row in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> row_to_arr(arma::Row<T>&& src)
Steal the memory of the Armadillo Row in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> row_to_arr(arma::Row<T>* src, bool copy=false)
Convert Armadillo Row to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false
Cube¶
-
py::array_t<T> cube_to_arr(arma::Cube<T>& src, bool copy=false)
Convert Armadillo Cube to Numpy array, note the returned array will have column contiguous memory (F-order)
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false which steals the memory
-
py::array_t<T> Cube_to_arr(const arma::Cube<T>& src)
Copy the memory of the Armadillo Cube in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> cube_to_arr(arma::Cube<T>&& src)
Steal the memory of the Armadillo cube in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
py::array_t<T> cube_to_arr(arma::Cube<T>* src, bool copy=false)
Convert Armadillo matrix to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false
to_numpy¶
to_numpy
has overloads for Mat<T>
, Row<T>
, Col<T>
and Cube<T>
.
It should be called with e.g. to_numpy<arma::Mat<double>>(m)
-
template <typename armaT> py::array_t<eT> to_numpy_view(const armaT<eT>& src)
Create ‘view’ on Armadillo object as non-writeable Numpy array. :note: the returned array will have F order memory. :param src: armadillo object to be converted.
-
template <typename armaT> py::array_t<eT> to_numpy(armaT<eT>& src, bool copy=false)
Convert Armadillo object to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false which steals the memory
-
template <typename armaT> py::array_t<eT> to_numpy(const armaT<eT>& src)
Copy the memory of the Armadillo object in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
template <typename armaT> py::array_t<eT> to_numpy(armaT<eT>&& src)
Steal the memory of the Armadillo object in the conversion to Numpy array.
Note: the returned array will have F order memory. Parameters: src – armadillo object to be converted.
-
template <typename armaT> py::array_t<eT> to_numpy(armaT<eT>* src)
Convert Armadillo object to Numpy array.
Note: the returned array will have F order memory.
Parameters: - src – armadillo object to be converted.
- copy – copy the memory of the array, default is false
Automatic conversion – Type caster¶
CARMA provides a type caster which enables automatic conversion using pybind11.
Warning
carma should included in every compilation unit where automated type casting occurs, otherwise undefined behaviour will occur.
Note
The underlying casting function has overloads for {const lvalue, lvalue, rvalue, pointer}
Armadillo objects of type {Mat, Col, Row, Cube}
.
Return policies¶
Pybind11 provides a number of return value policies of which a subset is supported:
To pass the return value policy set it in the binding function:
m.def("example_function", &example_function, return_value_policy::copy);
-
return_value_policy::move
move/steal the memory from the armadillo object
-
return_value_policy::automatic
move/steal the memory from the armadillo object
-
return_value_policy::take_ownership
move/steal the memory from the armadillo object
-
return_value_policy::copy
copy the memory from the armadillo object
ArrayStore¶
ArrayStore is a convenience class for storing the memory in a C++ class.
Warning
The ArrayStore owns the data, the returned numpy arrays are views that are tied to the lifetime of ArrayStore.
-
template <typename armaT> ArrayStore
-
mat armaT
Matrix containing the memory of the array.
-
ArrayStore
(py::array_t<T>& arr, bool copy)¶ Class constructor
Parameters: - arr – Numpy array to be stored as Armadillo matrix
- steal – Take ownership of the array if not copy
-
template <typename armaT> ArrayStore(const arma & src)
Class constructor, object is copied
Parameters: src – Armadillo object to be stored
-
template <typename armaT> ArrayStore(armaT& src, copy)
Class constructor, object is copied or moved/stolen
Parameters: src – Armadillo object to be stored
-
template <typename armaT> ArrayStore(armaT && src)
Class constructor, object is moved
Parameters: mat – Armadillo object to be stored
-
get_view
(bool writeable)¶ Obtain a view of the memory as Numpy array.
Parameters: writeable – Mark array as writeable
-
set_array
(py::array_t<T> & arr, bool copy)¶ Store new array in the ArrayStore.
Parameters: - arr – Numpy array to be stored as Armadillo matrix
- copy – Take ownership of the array or copy
-
template <typename T> set_data(const armaT& src)
Store new matrix in the ArrayStore, object is copied.
Parameters: src – Armadillo object to be stored
-
template <typename T> set_data(armaT& src, bool copy)
Store new object in the ArrayStore, copied or moved.
Parameters: src – Armadillo object to be stored, matrix is copied
-
template <typename T> set_data(arma::Mat<T> && src)
Store new matrix in the ArrayStore, object is moved.
Parameters: src – Armadillo matrix to be stored
-
NdArray flags¶
Utility functions to check flags of numpy arrays.
-
bool is_f_contiguous(const py::array_t<T> & arr)
Check if Numpy array’s memory is Fotran contiguous.
Parameters: arr – numpy array to be checked
-
bool is_c_contiguous(const py::array_t<T> & arr)
Check if Numpy array’s memory is C contiguous.
Parameters: arr – numpy array to be checked
-
bool is_writable(const py::array_t<T> & arr)
Check if Numpy array’s memory is mutable.
Parameters: arr – numpy array to be checked
-
bool is_owndata(const py::array_t<T> & arr)
Check if Numpy array’s memory is owned by numpy.
Parameters: arr – numpy array to be checked
-
bool is_aligned(const py::array_t<T> & arr)
Check if Numpy array’s memory is aligned.
Parameters: arr – numpy array to be checked
-
bool requires_copy(const py::array_t<T> & arr)
Check if Numpy array memory needs to be copied out, is true when either not writable, owndata or is not aligned.
Parameters: arr – numpy array to be checked
-
void set_not_owndata(py::array_t<T> & arr)
Set Numpy array’s flag OWNDATA to false.
Parameters: arr – numpy array to be changed
-
void set_not_writeable(py::array_t<T> & arr)
Set Numpy array’s flag WRITEABLE to false.
Parameters: arr – numpy array to be changed