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 383