]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |