ndarray

.. contents :: Table of Contents

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.

.. _ndarray: http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html .. _dtype: http://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html#data-type-objects-dtype

<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());