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