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