The C++ Vector and Matrix Types

PyUblas defines Ublas-compatible C++ types, namely :ctype:`numpy_vector` and :ctype:`numpy_matrix`. These are defined in pyublas/numpy.hpp.

Introduction

:ctype:`numpy_vector` is derived from Ublas’s vector and may be used in the same places as the latter, in the same ways. There is only one difference:

:ctype:`numpy_vector` will not copy your data unless you ask it to.

:ctype:`numpy_vector` internally uses Numpy arrays to store data. Unlike the native Ublas vector<T>, :ctype:`numpy_vector` has reference or “handle” semantics: Copy-constructing and assigning only makes a new reference to the existing vector’s data. Unlike native Ublas, it will not make a copy. Consider this example:

numpy_vector<double> a(5);
std::fill(a.begin(), a.end(), 17);

numpy_vector<double> b(a); // only references a's data
b[2] = 0;

std::cout << a[2] << std::endl; // prints "0".

If you want the data to be copied, you must say so explicitly:

numpy_vector<double> c(a.size());
c.assign(a); // actually copies a's data
c[2] = 17;

std::cout << a[2] << std::endl; // still prints "0".
std::cout << c[2] << std::endl; // prints "17".

If you follow these simple rules, it’s easy to write code that works the same for both :ctype:`ublas::vector` and :ctype:`numpy_vector`. (Note that here, as in the rest of this documentation, the same discussion applies without change to :ctype:`numpy_matrix` as well.)

Warning

The assign method does not resize its target to the size of its operand–this is something you have to do by hand if you use the above recipe.

You should be aware of another difference: Indexed access to :ctype:`numpy_vector` is much slower than iterator access. Iterators achieve the same speed as “regular” Ublas, while indexed access adds some extra instructions to find the real start of the array in the presence of negative slices. As is true of much of the rest of C++:

Note

Use iterators whenever possible.

Also see Gaah! Why is this garbage so slow?

Reference Documentation

#include <pyublas/numpy.hpp>

Interacting with Boost.Bindings

PyUblas contains special code to support interacting with the Boost.Bindings library.

If you want to activate this support, define the macro :cmacro:`PYUBLAS_HAVE_BOOST_BINDINGS` before including pyublas/numpy.hpp.

Boost.Bindings works seamlessly with :ctype:`numpy_vector`. For :ctype:`numpy_matrix`, you need to explicitly downcast it to the :ctype:`ublas::matrix` type. You may do so by simply calling the :cfunc:`as_ublas` method.