ceph/src/boost/libs/python/doc/numpy/reference/ndarray.rst

   1 ndarray
   2 =======
   3
   4 .. contents :: Table of Contents
   5
   6 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.
   7
   8 .. _ndarray: http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html
   9 .. _dtype: http://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html#data-type-objects-dtype
  10
  11  ``<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
  12
  13
  14
  15 synopsis
  16 --------
  17
  18 ::
  19
  20   namespace boost
  21   {
  22   namespace python
  23   {
  24   namespace numpy
  25   {
  26
  27   class ndarray : public object
  28   {
  29
  30   public:
  31
  32     enum bitflag
  33     {
  34       NONE=0x0, C_CONTIGUOUS=0x1, F_CONTIGUOUS=0x2, V_CONTIGUOUS=0x1|0x2,
  35       ALIGNED=0x4, WRITEABLE=0x8, BEHAVED=0x4|0x8,
  36       CARRAY_RO=0x1|0x4, CARRAY=0x1|0x4|0x8, CARRAY_MIS=0x1|0x8,
  37       FARRAY_RO=0x2|0x4, FARRAY=0x2|0x4|0x8, FARRAY_MIS=0x2|0x8,
  38       UPDATE_ALL=0x1|0x2|0x4, VARRAY=0x1|0x2|0x8, ALL=0x1|0x2|0x4|0x8
  39     };
  40
  41     ndarray view(dtype const & dt) const;
  42     ndarray astype(dtype const & dt) const;
  43     ndarray copy() const;
  44     int const shape(int n) const;
  45     int const strides(int n) const;
  46     char * get_data() const;
  47     dtype get_dtype() const;
  48     python::object get_base() const;
  49     void set_base(object const & base);
  50     Py_intptr_t const * get_shape() const;
  51     Py_intptr_t const * get_strides() const;
  52     int const get_nd() const;
  53
  54     bitflag const get_flags() const;
  55
  56     ndarray transpose() const;
  57     ndarray squeeze() const;
  58     ndarray reshape(tuple const & shape) const;
  59     object scalarize() const;
  60   };
  61
  62   ndarray zeros(tuple const & shape, dtype const & dt);
  63   ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);
  64
  65   ndarray empty(tuple const & shape, dtype const & dt);
  66   ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);
  67
  68   ndarray array(object const & obj);
  69   ndarray array(object const & obj, dtype const & dt);
  70
  71   template <typename Container>
  72   ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner);
  73   template <typename Container>
  74   ndarray from_data(void const * data, dtype const & dt, Container shape, Container strides, object const & owner);
  75
  76   ndarray from_object(object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
  77   ndarray from_object(object const & obj, dtype const & dt,int nd, ndarray::bitflag flags=ndarray::NONE);
  78   ndarray from_object(object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE);
  79   ndarray from_object(object const & obj, int nd_min, int nd_max,ndarray::bitflag flags=ndarray::NONE);
  80   ndarray from_object(object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE);
  81   ndarray from_object(object const & obj, ndarray::bitflag flags=ndarray::NONE)
  82
  83   ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b) ;
  84   ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b);
  85
  86   }
  87
  88
  89 constructors
  90 ------------
  91
  92 ::
  93
  94   ndarray view(dtype const & dt) const;
  95
  96 :Returns: new ndarray with old ndarray data cast as supplied dtype
  97
  98 ::
  99
 100   ndarray astype(dtype const & dt) const;
 101
 102 :Returns: new ndarray with old ndarray data converted to supplied dtype
 103
 104 ::
 105
 106   ndarray copy() const;
 107
 108 :Returns: Copy of calling ndarray object
 109
 110 ::
 111
 112   ndarray transpose() const;
 113
 114 :Returns:  An ndarray with the rows and columns interchanged
 115
 116 ::
 117
 118   ndarray squeeze() const;
 119
 120 :Returns:  An ndarray with all unit-shaped dimensions removed
 121
 122 ::
 123
 124   ndarray reshape(tuple const & shape) const;
 125
 126 :Requirements: The new ``shape`` of the ndarray must be supplied as a tuple
 127
 128 :Returns:  An ndarray with the same data but reshaped to the ``shape`` supplied
 129
 130
 131 ::
 132
 133   object scalarize() const;
 134
 135 :Returns: A scalar if the ndarray has only one element, otherwise it returns the entire array
 136
 137 ::
 138
 139   ndarray zeros(tuple const & shape, dtype const & dt);
 140   ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);
 141
 142 :Requirements: The following parameters must be supplied as required :
 143
 144                 * the ``shape`` or the size of all dimensions, as a tuple
 145                 * the ``dtype`` of the data
 146                 * the ``nd`` size for a square shaped ndarray
 147                 * the ``shape`` Py_intptr_t
 148
 149 :Returns:  A new ndarray with the given shape and data type, with data initialized to zero.
 150
 151 ::
 152
 153   ndarray empty(tuple const & shape, dtype const & dt);
 154   ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);
 155
 156
 157 :Requirements: The following parameters must be supplied :
 158
 159                 * the ``shape`` or the size of all dimensions, as a tuple
 160                 * the ``dtype`` of the data
 161                 * the ``shape`` Py_intptr_t
 162
 163 :Returns:  A new ndarray with the given shape and data type, with data left uninitialized.
 164
 165 ::
 166
 167   ndarray array(object const & obj);
 168   ndarray array(object const & obj, dtype const & dt);
 169
 170 :Returns:  A new ndarray from an arbitrary Python sequence, with dtype of each element specified optionally
 171
 172 ::
 173
 174   template <typename Container>
 175   inline ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner)
 176
 177 :Requirements: The following parameters must be supplied :
 178
 179                 * the ``data`` which is a generic C++ data container
 180                 * the dtype ``dt`` of the data
 181                 * the ``shape`` of the ndarray as Python object
 182                 * the ``strides`` of each dimension of the array as a Python object
 183                 * the ``owner`` of the data, in case it is not the ndarray itself
 184
 185 :Returns: ndarray with attributes and data supplied
 186
 187 :Note: The ``Container`` typename must be one that is convertible to a std::vector or python object type
 188
 189 ::
 190
 191   ndarray from_object(object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
 192
 193 :Requirements: The following parameters must be supplied :
 194
 195                 * the ``obj`` Python object to convert to ndarray
 196                 * the dtype ``dt`` of the data
 197                 * minimum number of dimensions ``nd_min`` of the ndarray as Python object
 198                 * maximum number of dimensions ``nd_max`` of the ndarray as Python object
 199                 * optional ``flags`` bitflags
 200
 201 :Returns: ndarray constructed with dimensions and data supplied as parameters
 202
 203 ::
 204
 205   inline ndarray from_object(object const & obj, dtype const & dt, int nd, ndarray::bitflag flags=ndarray::NONE);
 206
 207 :Requirements: The following parameters must be supplied :
 208
 209                 * the ``obj`` Python object to convert to ndarray
 210                 * the dtype ``dt`` of the data
 211                 * number of dimensions ``nd`` of the ndarray as Python object
 212                 * optional ``flags`` bitflags
 213
 214 :Returns: ndarray with dimensions ``nd`` x ``nd`` and suplied parameters
 215
 216 ::
 217
 218   inline ndarray from_object(object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE)
 219
 220 :Requirements: The following parameters must be supplied :
 221
 222                 * the ``obj`` Python object to convert to ndarray
 223                 * the dtype ``dt`` of the data
 224                 * optional ``flags`` bitflags
 225
 226 :Returns: Supplied Python object as ndarray
 227
 228 ::
 229
 230   ndarray from_object(object const & obj, int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE);
 231
 232 :Requirements: The following parameters must be supplied :
 233
 234                 * the ``obj`` Python object to convert to ndarray
 235                 * minimum number of dimensions ``nd_min`` of the ndarray as Python object
 236                 * maximum number of dimensions ``nd_max`` of the ndarray as Python object
 237                 * optional ``flags`` bitflags
 238
 239 :Returns: ndarray with supplied dimension limits and parameters
 240
 241 :Note: dtype need not be supplied here
 242
 243 ::
 244
 245   inline ndarray from_object(object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE);
 246
 247 :Requirements: The following parameters must be supplied :
 248
 249                 * the ``obj`` Python object to convert to ndarray
 250                 * the dtype ``dt`` of the data
 251                 * number of dimensions ``nd`` of the ndarray as Python object
 252                 * optional ``flags`` bitflags
 253
 254 :Returns: ndarray of ``nd`` x ``nd`` dimensions constructed from the supplied object
 255
 256 ::
 257
 258   inline ndarray from_object(object const & obj, ndarray::bitflag flags=ndarray::NONE)
 259
 260 :Requirements: The following parameters must be supplied :
 261
 262                 * the ``obj`` Python object to convert to ndarray
 263                 * optional ``flags`` bitflags
 264
 265 :Returns: ndarray of same dimensions and dtype as supplied Python object
 266
 267
 268 accessors
 269 ---------
 270
 271 ::
 272
 273   int const shape(int n) const;
 274
 275 :Returns: The size of the n-th dimension of the ndarray
 276
 277 ::
 278
 279   int const strides(int n) const;
 280
 281 :Returns: The stride of the nth dimension.
 282
 283 ::
 284
 285   char * get_data() const;
 286
 287 :Returns: Array's raw data pointer as a char
 288
 289 :Note: This returns char so stride math works properly on it.User will have to reinterpret_cast it.
 290
 291 ::
 292
 293   dtype get_dtype() const;
 294
 295 :Returns: Array's data-type descriptor object (dtype)
 296
 297
 298 ::
 299
 300   object get_base() const;
 301
 302 :Returns: Object that owns the array's data, or None if the array owns its own data.
 303
 304
 305 ::
 306
 307   void set_base(object const & base);
 308
 309 :Returns: Set the object that owns the array's data. Exercise caution while using this
 310
 311
 312 ::
 313
 314   Py_intptr_t const * get_shape() const;
 315
 316 :Returns: Shape of the array as an array of integers
 317
 318
 319 ::
 320
 321   Py_intptr_t const * get_strides() const;
 322
 323 :Returns: Stride of the array as an array of integers
 324
 325
 326 ::
 327
 328   int const get_nd() const;
 329
 330 :Returns: Number of array dimensions
 331
 332
 333 ::
 334
 335   bitflag const get_flags() const;
 336
 337 :Returns: Array flags
 338
 339 ::
 340
 341   inline ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b)
 342
 343 :Returns: bitflag logically OR-ed as (a | b)
 344
 345 ::
 346
 347   inline ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b)
 348
 349 :Returns: bitflag logically AND-ed as (a & b)
 350
 351
 352 Example(s)
 353 ----------
 354
 355 ::
 356
 357   namespace p = boost::python;
 358   namespace np = boost::python::numpy;
 359
 360   p::object tu = p::make_tuple('a','b','c') ;
 361   np::ndarray example_tuple = np::array (tu) ;
 362
 363   p::list l ;
 364   np::ndarray example_list = np::array (l) ;
 365
 366   np::dtype dt = np::dtype::get_builtin<int>();
 367   np::ndarray example_list1 = np::array (l,dt);
 368
 369   int data[] = {1,2,3,4} ;
 370   p::tuple shape = p::make_tuple(4) ;
 371   p::tuple stride = p::make_tuple(4) ;
 372   p::object own ;
 373   np::ndarray data_ex = np::from_data(data,dt,shape,stride,own);
 374
 375   uint8_t mul_data[][4] = {{1,2,3,4},{5,6,7,8},{1,3,5,7}};
 376   shape = p::make_tuple(3,2) ;
 377   stride = p::make_tuple(4,2) ;
 378   np::dtype dt1 = np::dtype::get_builtin<uint8_t>();
 379
 380   np::ndarray mul_data_ex = np::from_data(mul_data,dt1, p::make_tuple(3,4),p::make_tuple(4,1),p::object());
 381   mul_data_ex = np::from_data(mul_data,dt1, shape,stride,p::object());
 382