1Bigarray(3) OCaml library Bigarray(3)
2
6 Bigarray - Large, multi-dimensional, numerical arrays.
7
9 Module Bigarray
10
12 Module Bigarray
13 : sig end
14 Large, multi-dimensional, numerical arrays.
17 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 The implementation allows efficient sharing of large numerical arrays
23 between OCaml code and C or Fortran numerical libraries.
24 The main differences between 'Bigarrays' and standard OCaml arrays are
26 as follows:
27 -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 -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 -Bigarrays can only contain integers and floating-point numbers, while
37 OCaml arrays can contain arbitrary OCaml data types.
38 -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 -The memory layout of Bigarrays is entirely compatible with that of ar‐
46 rays 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 -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 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 Bigarrays support all the OCaml ad-hoc polymorphic operations:
60 -comparisons ( = , <> , <= , etc, as well as compare );
62 -hashing (module Hash );
64 -and structured input-output (the functions from the Marshal module, as
66 well as output_value and input_value ).
67 Element kinds
76 Bigarrays can contain elements of the following kinds:
77 -IEEE single precision (32 bits) floating-point numbers ( Bigar‐
79 ray.float32_elt ),
80 -IEEE double precision (64 bits) floating-point numbers ( Bigar‐
82 ray.float64_elt ),
83 -IEEE single precision (2 * 32 bits) floating-point complex numbers (
85 Bigarray.complex32_elt ),
86 -IEEE double precision (2 * 64 bits) floating-point complex numbers (
88 Bigarray.complex64_elt ),
89 -8-bit integers (signed or unsigned) ( Bigarray.int8_signed_elt or Bi‐
91 garray.int8_unsigned_elt ),
92 -16-bit integers (signed or unsigned) ( Bigarray.int16_signed_elt or
94 Bigarray.int16_unsigned_elt ),
95 -OCaml integers (signed, 31 bits on 32-bit architectures, 63 bits on
97 64-bit architectures) ( Bigarray.int_elt ),
98 -32-bit signed integers ( Bigarray.int32_elt ),
100 -64-bit signed integers ( Bigarray.int64_elt ),
102 -platform-native signed integers (32 bits on 32-bit architectures, 64
104 bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
105 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 ab‐
108 stract types for technical injectivity reasons).
109 type float32_elt =
111 | Float32_elt
112 type float64_elt =
117 | Float64_elt
118 type int8_signed_elt =
123 | Int8_signed_elt
124 type int8_unsigned_elt =
129 | Int8_unsigned_elt
130 type int16_signed_elt =
135 | Int16_signed_elt
136 type int16_unsigned_elt =
141 | Int16_unsigned_elt
142 type int32_elt =
147 | Int32_elt
148 type int64_elt =
153 | Int64_elt
154 type int_elt =
159 | Int_elt
160 type nativeint_elt =
165 | Nativeint_elt
166 type complex32_elt =
171 | Complex32_elt
172 type complex64_elt =
177 | Complex64_elt
178 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 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 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 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 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 val float32 : (float, float32_elt) kind
230 See Bigarray.char .
232 val float64 : (float, float64_elt) kind
236 See Bigarray.char .
238 val complex32 : (Complex.t, complex32_elt) kind
242 See Bigarray.char .
244 val complex64 : (Complex.t, complex64_elt) kind
248 See Bigarray.char .
250 val int8_signed : (int, int8_signed_elt) kind
254 See Bigarray.char .
256 val int8_unsigned : (int, int8_unsigned_elt) kind
260 See Bigarray.char .
262 val int16_signed : (int, int16_signed_elt) kind
266 See Bigarray.char .
268 val int16_unsigned : (int, int16_unsigned_elt) kind
272 See Bigarray.char .
274 val int : (int, int_elt) kind
278 See Bigarray.char .
280 val int32 : (int32, int32_elt) kind
284 See Bigarray.char .
286 val int64 : (int64, int64_elt) kind
290 See Bigarray.char .
292 val nativeint : (nativeint, nativeint_elt) kind
296 See Bigarray.char .
298 val char : (char, int8_unsigned_elt) kind
302 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 ar‐
308 ray 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 Bi‐
311 garrays. Finally, Bigarrays of kind int8_unsigned_elt can also be ac‐
312 cessed as arrays of characters instead of arrays of small integers, by
313 using the kind value char instead of int8_unsigned .
314 val kind_size_in_bytes : ('a, 'b) kind -> int
318 kind_size_in_bytes k is the number of bytes used to store an element of
321 type k .
322 Since 4.03.0
325 Array layouts
330 type c_layout =
331 | C_layout_typ
332 See Bigarray.fortran_layout .
335 type fortran_layout =
338 | Fortran_layout_typ
339 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 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 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 Each layout style is identified at the type level by the phantom types
359 Bigarray.c_layout and Bigarray.fortran_layout respectively.
360 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 type 'a layout =
370 | C_layout : c_layout layout
371 | Fortran_layout : fortran_layout layout
372 val c_layout : c_layout layout
378 val fortran_layout : fortran_layout layout
383 Generic arrays (of arbitrarily many dimensions)
389 module Genarray : sig end
390 Zero-dimensional arrays
397 module Array0 : sig end
398 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 op‐
404 erations, and more precise static type-checking.
405 Since 4.05.0
408 One-dimensional arrays
413 module Array1 : sig end
414 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 three-di‐
420 mensional arrays.) Statically knowing the number of dimensions of the
421 array allows faster operations, and more precise static type-checking.
422 Two-dimensional arrays
427 module Array2 : sig end
428 Two-dimensional arrays. The Array2 structure provides operations simi‐
431 lar to those of Bigarray.Genarray , but specialized to the case of
432 two-dimensional arrays.
433 Three-dimensional arrays
438 module Array3 : sig end
439 Three-dimensional arrays. The Array3 structure provides operations sim‐
442 ilar to those of Bigarray.Genarray , but specialized to the case of
443 three-dimensional arrays.
444 Coercions between generic Bigarrays and fixed-dimension Bigarrays
449 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
450 ray.t
451 Return the generic Bigarray corresponding to the given zero-dimensional
453 Bigarray.
454 Since 4.05.0
457 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
461 ray.t
462 Return the generic Bigarray corresponding to the given one-dimensional
464 Bigarray.
465 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
469 ray.t
470 Return the generic Bigarray corresponding to the given two-dimensional
472 Bigarray.
473 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
477 ray.t
478 Return the generic Bigarray corresponding to the given three-dimen‐
480 sional Bigarray.
481 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
485 ray0.t
486 Return the zero-dimensional Bigarray corresponding to the given generic
488 Bigarray.
489 Since 4.05.0
492 Raises Invalid_argument if the generic Bigarray does not have exactly
495 zero dimension.
496 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
500 ray1.t
501 Return the one-dimensional Bigarray corresponding to the given generic
503 Bigarray.
504 Raises Invalid_argument if the generic Bigarray does not have exactly
507 one dimension.
508 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
512 ray2.t
513 Return the two-dimensional Bigarray corresponding to the given generic
515 Bigarray.
516 Raises Invalid_argument if the generic Bigarray does not have exactly
519 two dimensions.
520 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
524 ray3.t
525 Return the three-dimensional Bigarray corresponding to the given
527 generic Bigarray.
528 Raises Invalid_argument if the generic Bigarray does not have exactly
531 three dimensions.
532 Re-shaping Bigarrays
537 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
538 Genarray.t
539 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional ar‐
542 ray of dimensions d1 ... dN . The returned array and the original ar‐
543 ray b share their data and have the same layout. For instance, assum‐
544 ing that b is a one-dimensional array of dimension 12, reshape b
545 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
546 has C layout, the element (x,y) of b' corresponds to the element x * 3
547 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
548 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
549 must have exactly the same number of elements as the original Bigarray
550 b . That is, the product of the dimensions of b must be equal to i1 *
551 ... * iN . Otherwise, Invalid_argument is raised.
552 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
556 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
558 sional arrays.
559 Since 4.05.0
562 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
566 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
568 sional arrays.
569 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
573 Array2.t
574 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
576 sional arrays.
577 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
581 'b, 'c) Array3.t
582 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
584 sional arrays.
585OCamldoc 2021-01-26 Bigarray(3)