Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit cdb310143f.

C++ Boost

(NumPy)


ndarray

A ndarray is an N-dimensional array which contains items of the same type and size, where N is the number of dimensions and is specified in the form of a shape tuple. Optionally, the numpy dtype for the objects contained may also be specified.

<boost/python/numpy/ndarray.hpp> contains the structures and methods necessary to move raw data between C++ and Python and create ndarrays from the data

synopsis

namespace boost
{
namespace python
{
namespace numpy
{

class ndarray : public object
{

public:

  enum bitflag
  {
    NONE=0x0, C_CONTIGUOUS=0x1, F_CONTIGUOUS=0x2, V_CONTIGUOUS=0x1|0x2,
    ALIGNED=0x4, WRITEABLE=0x8, BEHAVED=0x4|0x8,
    CARRAY_RO=0x1|0x4, CARRAY=0x1|0x4|0x8, CARRAY_MIS=0x1|0x8,
    FARRAY_RO=0x2|0x4, FARRAY=0x2|0x4|0x8, FARRAY_MIS=0x2|0x8,
    UPDATE_ALL=0x1|0x2|0x4, VARRAY=0x1|0x2|0x8, ALL=0x1|0x2|0x4|0x8
  };

  ndarray view(dtype const & dt) const;
  ndarray astype(dtype const & dt) const;
  ndarray copy() const;
  int const shape(int n) const;
  int const strides(int n) const;
  char * get_data() const;
  dtype get_dtype() const;
  python::object get_base() const;
  void set_base(object const & base);
  Py_intptr_t const * get_shape() const;
  Py_intptr_t const * get_strides() const;
  int const get_nd() const;

  bitflag const get_flags() const;

  ndarray transpose() const;
  ndarray squeeze() const;
  ndarray reshape(tuple const & shape) const;
  object scalarize() const;
};

ndarray zeros(tuple const & shape, dtype const & dt);
ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);

ndarray empty(tuple const & shape, dtype const & dt);
ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);

ndarray array(object const & obj);
ndarray array(object const & obj, dtype const & dt);

template <typename Container>
ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner);
template <typename Container>
ndarray from_data(void const * data, dtype const & dt, Container shape, Container strides, object const & owner);

ndarray from_object(object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
ndarray from_object(object const & obj, dtype const & dt,int nd, ndarray::bitflag flags=ndarray::NONE);
ndarray from_object(object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE);
ndarray from_object(object const & obj, int nd_min, int nd_max,ndarray::bitflag flags=ndarray::NONE);
ndarray from_object(object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE);
ndarray from_object(object const & obj, ndarray::bitflag flags=ndarray::NONE)

ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b) ;
ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b);

}

constructors

ndarray view(dtype const & dt) const;
Returns

new ndarray with old ndarray data cast as supplied dtype

ndarray astype(dtype const & dt) const;
Returns

new ndarray with old ndarray data converted to supplied dtype

ndarray copy() const;
Returns

Copy of calling ndarray object

ndarray transpose() const;
Returns

An ndarray with the rows and columns interchanged

ndarray squeeze() const;
Returns

An ndarray with all unit-shaped dimensions removed

ndarray reshape(tuple const & shape) const;
Requirements

The new shape of the ndarray must be supplied as a tuple

Returns

An ndarray with the same data but reshaped to the shape supplied

object scalarize() const;
Returns

A scalar if the ndarray has only one element, otherwise it returns the entire array

ndarray zeros(tuple const & shape, dtype const & dt);
ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);
Requirements

The following parameters must be supplied as required :

  • the shape or the size of all dimensions, as a tuple

  • the dtype of the data

  • the nd size for a square shaped ndarray

  • the shape Py_intptr_t

Returns

A new ndarray with the given shape and data type, with data initialized to zero.

ndarray empty(tuple const & shape, dtype const & dt);
ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);
Requirements

The following parameters must be supplied :

  • the shape or the size of all dimensions, as a tuple

  • the dtype of the data

  • the shape Py_intptr_t

Returns

A new ndarray with the given shape and data type, with data left uninitialized.

ndarray array(object const & obj);
ndarray array(object const & obj, dtype const & dt);
Returns

A new ndarray from an arbitrary Python sequence, with dtype of each element specified optionally

template <typename Container>
inline ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner)
Requirements

The following parameters must be supplied :

  • the data which is a generic C++ data container

  • the dtype dt of the data

  • the shape of the ndarray as Python object

  • the strides of each dimension of the array as a Python object

  • the owner of the data, in case it is not the ndarray itself

Returns

ndarray with attributes and data supplied

Note

The Container typename must be one that is convertible to a std::vector or python object type

ndarray from_object(object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • the dtype dt of the data

  • minimum number of dimensions nd_min of the ndarray as Python object

  • maximum number of dimensions nd_max of the ndarray as Python object

  • optional flags bitflags

Returns

ndarray constructed with dimensions and data supplied as parameters

inline ndarray from_object(object const & obj, dtype const & dt, int nd, ndarray::bitflag flags=ndarray::NONE);
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • the dtype dt of the data

  • number of dimensions nd of the ndarray as Python object

  • optional flags bitflags

Returns

ndarray with dimensions nd x nd and suplied parameters

inline ndarray from_object(object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE)
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • the dtype dt of the data

  • optional flags bitflags

Returns

Supplied Python object as ndarray

ndarray from_object(object const & obj, int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • minimum number of dimensions nd_min of the ndarray as Python object

  • maximum number of dimensions nd_max of the ndarray as Python object

  • optional flags bitflags

Returns

ndarray with supplied dimension limits and parameters

Note

dtype need not be supplied here

inline ndarray from_object(object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE);
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • the dtype dt of the data

  • number of dimensions nd of the ndarray as Python object

  • optional flags bitflags

Returns

ndarray of nd x nd dimensions constructed from the supplied object

inline ndarray from_object(object const & obj, ndarray::bitflag flags=ndarray::NONE)
Requirements

The following parameters must be supplied :

  • the obj Python object to convert to ndarray

  • optional flags bitflags

Returns

ndarray of same dimensions and dtype as supplied Python object

accessors

int const shape(int n) const;
Returns

The size of the n-th dimension of the ndarray

int const strides(int n) const;
Returns

The stride of the nth dimension.

char * get_data() const;
Returns

Array’s raw data pointer as a char

Note

This returns char so stride math works properly on it.User will have to reinterpret_cast it.

dtype get_dtype() const;
Returns

Array’s data-type descriptor object (dtype)

object get_base() const;
Returns

Object that owns the array’s data, or None if the array owns its own data.

void set_base(object const & base);
Returns

Set the object that owns the array’s data. Exercise caution while using this

Py_intptr_t const * get_shape() const;
Returns

Shape of the array as an array of integers

Py_intptr_t const * get_strides() const;
Returns

Stride of the array as an array of integers

int const get_nd() const;
Returns

Number of array dimensions

bitflag const get_flags() const;
Returns

Array flags

inline ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b)
Returns

bitflag logically OR-ed as (a | b)

inline ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b)
Returns

bitflag logically AND-ed as (a & b)

Example(s)

namespace p = boost::python;
namespace np = boost::python::numpy;

p::object tu = p::make_tuple('a','b','c') ;
np::ndarray example_tuple = np::array (tu) ;

p::list l ;
np::ndarray example_list = np::array (l) ;

np::dtype dt = np::dtype::get_builtin<int>();
np::ndarray example_list1 = np::array (l,dt);

int data[] = {1,2,3,4} ;
p::tuple shape = p::make_tuple(4) ;
p::tuple stride = p::make_tuple(4) ;
p::object own ;
np::ndarray data_ex = np::from_data(data,dt,shape,stride,own);

uint8_t mul_data[][4] = {{1,2,3,4},{5,6,7,8},{1,3,5,7}};
shape = p::make_tuple(3,2) ;
stride = p::make_tuple(4,2) ;
np::dtype dt1 = np::dtype::get_builtin<uint8_t>();

np::ndarray mul_data_ex = np::from_data(mul_data,dt1, p::make_tuple(3,4),p::make_tuple(4,1),p::object());
mul_data_ex = np::from_data(mul_data,dt1, shape,stride,p::object());