1ndarray 2======= 3 4.. contents :: Table of Contents 5 6A `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 15synopsis 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 89constructors 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 268accessors 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 352Example(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 383