PyUblas defines Ublas-compatible C++ types, namely numpy_vector and numpy_matrix. These are defined in pyublas/numpy.hpp.
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:
numpy_vector will not copy your data unless you ask it to.
numpy_vector internally uses Numpy arrays to store data. Unlike the native Ublas vector<T>, 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 ublas::vector and numpy_vector. (Note that here, as in the rest of this documentation, the same discussion applies without change to 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 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?
#include <pyublas/numpy.hpp>
template <class ValueType>, in namespace pyublas.
Only members that are not already part of the Boost.Ublas “Storage” Concept are shown.
Public type definitions:
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
typedef ValueType value_type;
typedef const ValueType &const_reference;
typedef ValueType &reference;
typedef const ValueType *const_pointer;
typedef ValueType *pointer;
Construct a new numpy_array. If you use the empty constructor, the array is in an invalid state until numpy_array::resize() is called. Calling any other member function will result in undefined behavior.
A const member function.
A const member function.
A const member function.
A const member function.
A const member function.
A const member function.
Return a handle to the underlying Numpy array object. If the array is unitialized, the function may return a handle to None.
A const member function.
template <class ValueType>, in namespace pyublas.
Construct a new numpy_vector instance.
The (ndim, dims) constructor form can be used to specify the Python-side shape of the array at construction time. This is extended by the (ndim, dims, ae) form, which allows to specify the vector expression from which the vector is initialized, along with its Python-side shape. Both the initializer and the Python-side shape are assumed to yield identical vector sizes.
Observe that PyObject handles are implicitly convertible to numpy_array, so that you can invoke the constructor simply by feeding it a boost::python::handle.
If you use the empty constructor, the vector is in an invalid state until numpy_vector::resize() is called. In this state, calling numpy_vector::is_valid(), numpy_vector::size() and numpy_vector::resize() is allowed. Calling any other member function results in undefined behavior.
Return the number of dimensions of this array.
A const member function.
Return an array of numpy_vector::ndim() entries, each of which is the size of the array along one dimension. in elements.
A const member function.
Return an array of numpy_vector::ndim() entries, each of which is the stride along one dimension, in bytes. Divide by numpy_vector::itemsize() to convert this to element-wise strides.
A const member function.
Return the size (in bytes) of each element of the array.
A const member function.
A const member function.
Return the element at the index (i), (i,j), (i,j,k), (i,j,k,l). It is up to you to ensure that the array has the same number of dimensions, otherwise the results are undefined.
Also available as const member functions.
Same operation as numpy.reshape().
Return a view of the array that seems contiguous, by only looking at every numpy_vector::min_stride()‘th element.
Also available as a const member function.
Downcast this instance to the underlying boost::numeric::ublas::vector<ValueType>.
Also available as a const member function.
Return a Boost.Python handle (which is essentially an auto-refcounting PyObject *) to the underlying Numpy array. If the matrix is empty, the function may return a handle to None.
A const member function.
template <class ValueType>, in namespace pyublas.
If you use this type as a argument type in a function called from Python, the converted vector will respect non-contiguous slices automatically. See What about slices?
Inherits from boost::numeric::ublas::vector_slice.
Warning
Ublas only provides single-dimensional strides. Multi-dimensional numpy slices (such as zeros((5,5))[:3,:3]) can easily become too complex to be represented using these slices. In this case, the from-Python conversion fails with a ValueError.
Observe that PyObject handles are implicitly convertible to numpy_array, so that you can invoke the constructor simply by feeding it a boost::python::handle.
Return the number of dimensions of this array.
A const member function.
Return an array of numpy_strided_vector::ndim() entries, each of which is the size of the array along one dimension. in elements.
A const member function.
Return an array of numpy_strided_vector::ndim() entries, each of which is the stride along one dimension, in bytes. Divide by numpy_strided_vector::itemsize() to convert this to element-wise strides.
A const member function.
The smallest stride used in the underlying array, in bytes. Divide by numpy_strided_vector::itemsize() to convert this to element-wise strides.
A const member function.
Return the size (in bytes) of each element of the array.
A const member function.
A const member function.
Return the element at the index (i), (i,j), (i,j,k), (i,j,k,l). It is up to you to ensure that the array has the same number of dimensions, otherwise the results are undefined.
Also available as const member functions.
Downcast this instance to the underlying boost::numeric::ublas::vector<ValueType>.
Also available as a const member function.
Return a Boost.Python handle (which is essentially an auto-refcounting PyObject *) to the underlying Numpy array. If the matrix is empty, the function may return a handle to None.
A const member function.
template <class ValueType, class Orientation=boost::numeric::ublas::row_major>, in namespace pyublas.
Observe that PyObject handles are implicitly convertible to numpy_array, so that you can invoke the constructor simply by feeding it a boost::python::handle.
If you use the empty constructor, the matrix is in an invalid state until numpy_matrix::resize() is called. Calling any other member function will result in undefined behavior.
Also available as a const member function.
Return a handle to the underlying Numpy array object. If the matrix is empty, the function may return a handle to None.
A const member function.
template <class Contained>, in namespace pyublas.
Contained can be numpy_vector or numpy_matrix. If arguments of this type are converted from Python, they will also accept the value None. In that case, the resulting Contained will be invalid if None is passed in. See Can I pass None for an argument that gets converted to numpy_vector?
Return a reference to the Contained array.
Return a pointer to the Contained array.
PyUblas contains special code to support interacting with the Boost.Bindings library.
If you want to activate this support, define the macro PYUBLAS_HAVE_BOOST_BINDINGS before including pyublas/numpy.hpp.
Boost.Bindings works seamlessly with numpy_vector. For numpy_matrix, you need to explicitly downcast it to the ublas::matrix type. You may do so by simply calling the as_ublas() method.