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 ```` 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 ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner); template 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 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(); 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(); 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());