1Bigarray(3) OCaml library Bigarray(3)
2
3
4
6 Bigarray - Large, multi-dimensional, numerical arrays.
7
9 Module Bigarray
10
12 Module Bigarray
13 : sig end
14
15
16 Large, multi-dimensional, numerical arrays.
17
18 This module implements multi-dimensional arrays of integers and float‐
19 ing-point numbers, thereafter referred to as 'Bigarrays', to distin‐
20 guish them from the standard OCaml arrays described in Array .
21
22 The implementation allows efficient sharing of large numerical arrays
23 between OCaml code and C or Fortran numerical libraries.
24
25 The main differences between 'Bigarrays' and standard OCaml arrays are
26 as follows:
27
28 -Bigarrays are not limited in size, unlike OCaml arrays. (Normal float
29 arrays are limited to 2,097,151 elements on a 32-bit platform, and nor‐
30 mal arrays of other types to 4,194,303 elements.)
31
32 -Bigarrays are multi-dimensional. Any number of dimensions between 0
33 and 16 is supported. In contrast, OCaml arrays are mono-dimensional
34 and require encoding multi-dimensional arrays as arrays of arrays.
35
36 -Bigarrays can only contain integers and floating-point numbers, while
37 OCaml arrays can contain arbitrary OCaml data types.
38
39 -Bigarrays provide more space-efficient storage of integer and float‐
40 ing-point elements than normal OCaml arrays, in particular because they
41 support 'small' types such as single-precision floats and 8 and 16-bit
42 integers, in addition to the standard OCaml types of double-precision
43 floats and 32 and 64-bit integers.
44
45 -The memory layout of Bigarrays is entirely compatible with that of
46 arrays in C and Fortran, allowing large arrays to be passed back and
47 forth between OCaml code and C / Fortran code with no data copying at
48 all.
49
50 -Bigarrays support interesting high-level operations that normal arrays
51 do not provide efficiently, such as extracting sub-arrays and 'slicing'
52 a multi-dimensional array along certain dimensions, all without any
53 copying.
54
55 Users of this module are encouraged to do open Bigarray in their
56 source, then refer to array types and operations via short dot nota‐
57 tion, e.g. Array1.t or Array2.sub .
58
59 Bigarrays support all the OCaml ad-hoc polymorphic operations:
60
61 -comparisons ( = , <> , <= , etc, as well as compare );
62
63 -hashing (module Hash );
64
65 -and structured input-output (the functions from the Marshal module, as
66 well as output_value and input_value ).
67
68
69
70
71
72
73
74
75 Element kinds
76 Bigarrays can contain elements of the following kinds:
77
78 -IEEE single precision (32 bits) floating-point numbers ( Bigar‐
79 ray.float32_elt ),
80
81 -IEEE double precision (64 bits) floating-point numbers ( Bigar‐
82 ray.float64_elt ),
83
84 -IEEE single precision (2 * 32 bits) floating-point complex numbers (
85 Bigarray.complex32_elt ),
86
87 -IEEE double precision (2 * 64 bits) floating-point complex numbers (
88 Bigarray.complex64_elt ),
89
90 -8-bit integers (signed or unsigned) ( Bigarray.int8_signed_elt or
91 Bigarray.int8_unsigned_elt ),
92
93 -16-bit integers (signed or unsigned) ( Bigarray.int16_signed_elt or
94 Bigarray.int16_unsigned_elt ),
95
96 -OCaml integers (signed, 31 bits on 32-bit architectures, 63 bits on
97 64-bit architectures) ( Bigarray.int_elt ),
98
99 -32-bit signed integers ( Bigarray.int32_elt ),
100
101 -64-bit signed integers ( Bigarray.int64_elt ),
102
103 -platform-native signed integers (32 bits on 32-bit architectures, 64
104 bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
105
106 Each element kind is represented at the type level by one of the *_elt
107 types defined below (defined with a single constructor instead of
108 abstract types for technical injectivity reasons).
109
110 type float32_elt =
111 | Float32_elt
112
113
114
115
116 type float64_elt =
117 | Float64_elt
118
119
120
121
122 type int8_signed_elt =
123 | Int8_signed_elt
124
125
126
127
128 type int8_unsigned_elt =
129 | Int8_unsigned_elt
130
131
132
133
134 type int16_signed_elt =
135 | Int16_signed_elt
136
137
138
139
140 type int16_unsigned_elt =
141 | Int16_unsigned_elt
142
143
144
145
146 type int32_elt =
147 | Int32_elt
148
149
150
151
152 type int64_elt =
153 | Int64_elt
154
155
156
157
158 type int_elt =
159 | Int_elt
160
161
162
163
164 type nativeint_elt =
165 | Nativeint_elt
166
167
168
169
170 type complex32_elt =
171 | Complex32_elt
172
173
174
175
176 type complex64_elt =
177 | Complex64_elt
178
179
180
181
182 type ('a, 'b) kind =
183 | Float32 : (float, float32_elt) kind
184 | Float64 : (float, float64_elt) kind
185 | Int8_signed : (int, int8_signed_elt) kind
186 | Int8_unsigned : (int, int8_unsigned_elt) kind
187 | Int16_signed : (int, int16_signed_elt) kind
188 | Int16_unsigned : (int, int16_unsigned_elt) kind
189 | Int32 : (int32, int32_elt) kind
190 | Int64 : (int64, int64_elt) kind
191 | Int : (int, int_elt) kind
192 | Nativeint : (nativeint, nativeint_elt) kind
193 | Complex32 : (Complex.t, complex32_elt) kind
194 | Complex64 : (Complex.t, complex64_elt) kind
195 | Char : (char, int8_unsigned_elt) kind
196
197
198 To each element kind is associated an OCaml type, which is the type of
199 OCaml values that can be stored in the Bigarray or read back from it.
200 This type is not necessarily the same as the type of the array elements
201 proper: for instance, a Bigarray whose elements are of kind float32_elt
202 contains 32-bit single precision floats, but reading or writing one of
203 its elements from OCaml uses the OCaml type float , which is 64-bit
204 double precision floats.
205
206 The GADT type ('a, 'b) kind captures this association of an OCaml type
207 'a for values read or written in the Bigarray, and of an element kind
208 'b which represents the actual contents of the Bigarray. Its construc‐
209 tors list all possible associations of OCaml types with element kinds,
210 and are re-exported below for backward-compatibility reasons.
211
212 Using a generalized algebraic datatype (GADT) here allows writing
213 well-typed polymorphic functions whose return type depend on the argu‐
214 ment type, such as:
215
216
217 let zero : type a b. (a, b) kind -> a = function | Float32 -> 0.0 |
218 Complex32 -> Complex.zero | Float64 -> 0.0 | Complex64 -> Complex.zero
219 | Int8_signed -> 0 | Int8_unsigned -> 0 | Int16_signed -> 0 |
220 Int16_unsigned -> 0 | Int32 -> 0l | Int64 -> 0L | Int -> 0 | Nativeint
221 -> 0n | Char -> '\000'
222
223
224
225
226 val float32 : (float, float32_elt) kind
227
228 See Bigarray.char .
229
230
231
232 val float64 : (float, float64_elt) kind
233
234 See Bigarray.char .
235
236
237
238 val complex32 : (Complex.t, complex32_elt) kind
239
240 See Bigarray.char .
241
242
243
244 val complex64 : (Complex.t, complex64_elt) kind
245
246 See Bigarray.char .
247
248
249
250 val int8_signed : (int, int8_signed_elt) kind
251
252 See Bigarray.char .
253
254
255
256 val int8_unsigned : (int, int8_unsigned_elt) kind
257
258 See Bigarray.char .
259
260
261
262 val int16_signed : (int, int16_signed_elt) kind
263
264 See Bigarray.char .
265
266
267
268 val int16_unsigned : (int, int16_unsigned_elt) kind
269
270 See Bigarray.char .
271
272
273
274 val int : (int, int_elt) kind
275
276 See Bigarray.char .
277
278
279
280 val int32 : (int32, int32_elt) kind
281
282 See Bigarray.char .
283
284
285
286 val int64 : (int64, int64_elt) kind
287
288 See Bigarray.char .
289
290
291
292 val nativeint : (nativeint, nativeint_elt) kind
293
294 See Bigarray.char .
295
296
297
298 val char : (char, int8_unsigned_elt) kind
299
300 As shown by the types of the values above, Bigarrays of kind
301 float32_elt and float64_elt are accessed using the OCaml type float .
302 Bigarrays of complex kinds complex32_elt , complex64_elt are accessed
303 with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
304 using the smallest OCaml integer type large enough to represent the
305 array elements: int for 8- and 16-bit integer Bigarrays, as well as
306 OCaml-integer Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
307 64-bit integer Bigarrays; and nativeint for platform-native integer
308 Bigarrays. Finally, Bigarrays of kind int8_unsigned_elt can also be
309 accessed as arrays of characters instead of arrays of small integers,
310 by using the kind value char instead of int8_unsigned .
311
312
313
314 val kind_size_in_bytes : ('a, 'b) kind -> int
315
316
317 kind_size_in_bytes k is the number of bytes used to store an element of
318 type k .
319
320
321 Since 4.03.0
322
323
324
325
326 Array layouts
327 type c_layout =
328 | C_layout_typ
329
330
331 See Bigarray.fortran_layout .
332
333
334 type fortran_layout =
335 | Fortran_layout_typ
336
337
338 To facilitate interoperability with existing C and Fortran code, this
339 library supports two different memory layouts for Bigarrays, one com‐
340 patible with the C conventions, the other compatible with the Fortran
341 conventions.
342
343 In the C-style layout, array indices start at 0, and multi-dimensional
344 arrays are laid out in row-major format. That is, for a two-dimen‐
345 sional array, all elements of row 0 are contiguous in memory, followed
346 by all elements of row 1, etc. In other terms, the array elements at
347 (x,y) and (x, y+1) are adjacent in memory.
348
349 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
350 sional arrays are laid out in column-major format. That is, for a
351 two-dimensional array, all elements of column 0 are contiguous in mem‐
352 ory, followed by all elements of column 1, etc. In other terms, the
353 array elements at (x,y) and (x+1, y) are adjacent in memory.
354
355 Each layout style is identified at the type level by the phantom types
356 Bigarray.c_layout and Bigarray.fortran_layout respectively.
357
358
359
360
361 Supported layouts
362 The GADT type 'a layout represents one of the two supported memory lay‐
363 outs: C-style or Fortran-style. Its constructors are re-exported as
364 values below for backward-compatibility reasons.
365
366 type 'a layout =
367 | C_layout : c_layout layout
368 | Fortran_layout : fortran_layout layout
369
370
371
372
373
374 val c_layout : c_layout layout
375
376
377
378
379 val fortran_layout : fortran_layout layout
380
381
382
383
384
385 Generic arrays (of arbitrarily many dimensions)
386 module Genarray : sig end
387
388
389
390
391
392
393 Zero-dimensional arrays
394 module Array0 : sig end
395
396
397 Zero-dimensional arrays. The Array0 structure provides operations simi‐
398 lar to those of Bigarray.Genarray , but specialized to the case of
399 zero-dimensional arrays that only contain a single scalar value. Stat‐
400 ically knowing the number of dimensions of the array allows faster
401 operations, and more precise static type-checking.
402
403
404 Since 4.05.0
405
406
407
408
409 One-dimensional arrays
410 module Array1 : sig end
411
412
413 One-dimensional arrays. The Array1 structure provides operations simi‐
414 lar to those of Bigarray.Genarray , but specialized to the case of
415 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
416 structures below provide operations specialized for two- and
417 three-dimensional arrays.) Statically knowing the number of dimensions
418 of the array allows faster operations, and more precise static
419 type-checking.
420
421
422
423
424 Two-dimensional arrays
425 module Array2 : sig end
426
427
428 Two-dimensional arrays. The Array2 structure provides operations simi‐
429 lar to those of Bigarray.Genarray , but specialized to the case of
430 two-dimensional arrays.
431
432
433
434
435 Three-dimensional arrays
436 module Array3 : sig end
437
438
439 Three-dimensional arrays. The Array3 structure provides operations sim‐
440 ilar to those of Bigarray.Genarray , but specialized to the case of
441 three-dimensional arrays.
442
443
444
445
446 Coercions between generic Bigarrays and fixed-dimension Bigarrays
447 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
448 ray.t
449
450 Return the generic Bigarray corresponding to the given zero-dimensional
451 Bigarray.
452
453
454 Since 4.05.0
455
456
457
458 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
459 ray.t
460
461 Return the generic Bigarray corresponding to the given one-dimensional
462 Bigarray.
463
464
465
466 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
467 ray.t
468
469 Return the generic Bigarray corresponding to the given two-dimensional
470 Bigarray.
471
472
473
474 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
475 ray.t
476
477 Return the generic Bigarray corresponding to the given three-dimen‐
478 sional Bigarray.
479
480
481
482 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
483 Array0.t
484
485 Return the zero-dimensional Bigarray corresponding to the given generic
486 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
487 exactly zero dimension.
488
489
490 Since 4.05.0
491
492
493
494 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
495 Array1.t
496
497 Return the one-dimensional Bigarray corresponding to the given generic
498 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
499 exactly one dimension.
500
501
502
503 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
504 Array2.t
505
506 Return the two-dimensional Bigarray corresponding to the given generic
507 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
508 exactly two dimensions.
509
510
511
512 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
513 Array3.t
514
515 Return the three-dimensional Bigarray corresponding to the given
516 generic Bigarray. Raise Invalid_argument if the generic Bigarray does
517 not have exactly three dimensions.
518
519
520
521
522 Re-shaping Bigarrays
523 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
524 Genarray.t
525
526
527 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional
528 array of dimensions d1 ... dN . The returned array and the original
529 array b share their data and have the same layout. For instance,
530 assuming that b is a one-dimensional array of dimension 12, reshape b
531 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
532 has C layout, the element (x,y) of b' corresponds to the element x * 3
533 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
534 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
535 must have exactly the same number of elements as the original Bigarray
536 b . That is, the product of the dimensions of b must be equal to i1 *
537 ... * iN . Otherwise, Invalid_argument is raised.
538
539
540
541 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
542
543 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
544 sional arrays.
545
546
547 Since 4.05.0
548
549
550
551 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
552
553 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
554 sional arrays.
555
556
557
558 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
559 Array2.t
560
561 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
562 sional arrays.
563
564
565
566 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
567 'b, 'c) Array3.t
568
569 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
570 sional arrays.
571
572
573
574
575
576OCamldoc 2019-07-30 Bigarray(3)