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
218 | Float32 -> 0.0 | Complex32 -> Complex.zero
219 | Float64 -> 0.0 | Complex64 -> Complex.zero
220 | Int8_signed -> 0 | Int8_unsigned -> 0
221 | Int16_signed -> 0 | Int16_unsigned -> 0
222 | Int32 -> 0l | Int64 -> 0L
223 | Int -> 0 | Nativeint -> 0n
224 | Char -> '\000'
225
226
227
228
229 val float32 : (float, float32_elt) kind
230
231 See Bigarray.char .
232
233
234
235 val float64 : (float, float64_elt) kind
236
237 See Bigarray.char .
238
239
240
241 val complex32 : (Complex.t, complex32_elt) kind
242
243 See Bigarray.char .
244
245
246
247 val complex64 : (Complex.t, complex64_elt) kind
248
249 See Bigarray.char .
250
251
252
253 val int8_signed : (int, int8_signed_elt) kind
254
255 See Bigarray.char .
256
257
258
259 val int8_unsigned : (int, int8_unsigned_elt) kind
260
261 See Bigarray.char .
262
263
264
265 val int16_signed : (int, int16_signed_elt) kind
266
267 See Bigarray.char .
268
269
270
271 val int16_unsigned : (int, int16_unsigned_elt) kind
272
273 See Bigarray.char .
274
275
276
277 val int : (int, int_elt) kind
278
279 See Bigarray.char .
280
281
282
283 val int32 : (int32, int32_elt) kind
284
285 See Bigarray.char .
286
287
288
289 val int64 : (int64, int64_elt) kind
290
291 See Bigarray.char .
292
293
294
295 val nativeint : (nativeint, nativeint_elt) kind
296
297 See Bigarray.char .
298
299
300
301 val char : (char, int8_unsigned_elt) kind
302
303 As shown by the types of the values above, Bigarrays of kind
304 float32_elt and float64_elt are accessed using the OCaml type float .
305 Bigarrays of complex kinds complex32_elt , complex64_elt are accessed
306 with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
307 using the smallest OCaml integer type large enough to represent the
308 array elements: int for 8- and 16-bit integer Bigarrays, as well as
309 OCaml-integer Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
310 64-bit integer Bigarrays; and nativeint for platform-native integer
311 Bigarrays. Finally, Bigarrays of kind int8_unsigned_elt can also be
312 accessed as arrays of characters instead of arrays of small integers,
313 by using the kind value char instead of int8_unsigned .
314
315
316
317 val kind_size_in_bytes : ('a, 'b) kind -> int
318
319
320 kind_size_in_bytes k is the number of bytes used to store an element of
321 type k .
322
323
324 Since 4.03.0
325
326
327
328
329 Array layouts
330 type c_layout =
331 | C_layout_typ
332
333
334 See Bigarray.fortran_layout .
335
336
337 type fortran_layout =
338 | Fortran_layout_typ
339
340
341 To facilitate interoperability with existing C and Fortran code, this
342 library supports two different memory layouts for Bigarrays, one com‐
343 patible with the C conventions, the other compatible with the Fortran
344 conventions.
345
346 In the C-style layout, array indices start at 0, and multi-dimensional
347 arrays are laid out in row-major format. That is, for a two-dimen‐
348 sional array, all elements of row 0 are contiguous in memory, followed
349 by all elements of row 1, etc. In other terms, the array elements at
350 (x,y) and (x, y+1) are adjacent in memory.
351
352 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
353 sional arrays are laid out in column-major format. That is, for a
354 two-dimensional array, all elements of column 0 are contiguous in mem‐
355 ory, followed by all elements of column 1, etc. In other terms, the
356 array elements at (x,y) and (x+1, y) are adjacent in memory.
357
358 Each layout style is identified at the type level by the phantom types
359 Bigarray.c_layout and Bigarray.fortran_layout respectively.
360
361
362
363
364 Supported layouts
365 The GADT type 'a layout represents one of the two supported memory lay‐
366 outs: C-style or Fortran-style. Its constructors are re-exported as
367 values below for backward-compatibility reasons.
368
369 type 'a layout =
370 | C_layout : c_layout layout
371 | Fortran_layout : fortran_layout layout
372
373
374
375
376
377 val c_layout : c_layout layout
378
379
380
381
382 val fortran_layout : fortran_layout layout
383
384
385
386
387
388 Generic arrays (of arbitrarily many dimensions)
389 module Genarray : sig end
390
391
392
393
394
395
396 Zero-dimensional arrays
397 module Array0 : sig end
398
399
400 Zero-dimensional arrays. The Array0 structure provides operations simi‐
401 lar to those of Bigarray.Genarray , but specialized to the case of
402 zero-dimensional arrays that only contain a single scalar value. Stat‐
403 ically knowing the number of dimensions of the array allows faster
404 operations, and more precise static type-checking.
405
406
407 Since 4.05.0
408
409
410
411
412 One-dimensional arrays
413 module Array1 : sig end
414
415
416 One-dimensional arrays. The Array1 structure provides operations simi‐
417 lar to those of Bigarray.Genarray , but specialized to the case of
418 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
419 structures below provide operations specialized for two- and
420 three-dimensional arrays.) Statically knowing the number of dimensions
421 of the array allows faster operations, and more precise static
422 type-checking.
423
424
425
426
427 Two-dimensional arrays
428 module Array2 : sig end
429
430
431 Two-dimensional arrays. The Array2 structure provides operations simi‐
432 lar to those of Bigarray.Genarray , but specialized to the case of
433 two-dimensional arrays.
434
435
436
437
438 Three-dimensional arrays
439 module Array3 : sig end
440
441
442 Three-dimensional arrays. The Array3 structure provides operations sim‐
443 ilar to those of Bigarray.Genarray , but specialized to the case of
444 three-dimensional arrays.
445
446
447
448
449 Coercions between generic Bigarrays and fixed-dimension Bigarrays
450 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
451 ray.t
452
453 Return the generic Bigarray corresponding to the given zero-dimensional
454 Bigarray.
455
456
457 Since 4.05.0
458
459
460
461 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
462 ray.t
463
464 Return the generic Bigarray corresponding to the given one-dimensional
465 Bigarray.
466
467
468
469 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
470 ray.t
471
472 Return the generic Bigarray corresponding to the given two-dimensional
473 Bigarray.
474
475
476
477 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
478 ray.t
479
480 Return the generic Bigarray corresponding to the given three-dimen‐
481 sional Bigarray.
482
483
484
485 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
486 Array0.t
487
488 Return the zero-dimensional Bigarray corresponding to the given generic
489 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
490 exactly zero dimension.
491
492
493 Since 4.05.0
494
495
496
497 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
498 Array1.t
499
500 Return the one-dimensional Bigarray corresponding to the given generic
501 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
502 exactly one dimension.
503
504
505
506 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
507 Array2.t
508
509 Return the two-dimensional Bigarray corresponding to the given generic
510 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
511 exactly two dimensions.
512
513
514
515 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
516 Array3.t
517
518 Return the three-dimensional Bigarray corresponding to the given
519 generic Bigarray. Raise Invalid_argument if the generic Bigarray does
520 not have exactly three dimensions.
521
522
523
524
525 Re-shaping Bigarrays
526 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
527 Genarray.t
528
529
530 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional
531 array of dimensions d1 ... dN . The returned array and the original
532 array b share their data and have the same layout. For instance,
533 assuming that b is a one-dimensional array of dimension 12, reshape b
534 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
535 has C layout, the element (x,y) of b' corresponds to the element x * 3
536 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
537 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
538 must have exactly the same number of elements as the original Bigarray
539 b . That is, the product of the dimensions of b must be equal to i1 *
540 ... * iN . Otherwise, Invalid_argument is raised.
541
542
543
544 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
545
546 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
547 sional arrays.
548
549
550 Since 4.05.0
551
552
553
554 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
555
556 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
557 sional arrays.
558
559
560
561 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
562 Array2.t
563
564 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
565 sional arrays.
566
567
568
569 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
570 'b, 'c) Array3.t
571
572 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
573 sional arrays.
574
575
576
577
578
579OCamldoc 2020-02-27 Bigarray(3)