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