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 'big arrays', 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 'big arrays' and standard OCaml arrays are
26 as follows:
27 -Big arrays are not limited in size, unlike OCaml arrays. (Normal
29 float arrays are limited to 2,097,151 elements on a 32-bit platform,
30 and normal arrays of other types to 4,194,303 elements.)
31 -Big arrays 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 -Big arrays can only contain integers and floating-point numbers, while
37 OCaml arrays can contain arbitrary OCaml data types.
38 -Big arrays 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 big arrays 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 -Big arrays support interesting high-level operations that normal
51 arrays do not provide efficiently, such as extracting sub-arrays and
52 'slicing' a multi-dimensional array along certain dimensions, all with‐
53 out any 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 Big arrays support all the OCaml ad-hoc polymorphic operations:
60 -comparisons ( = , <> , <= , etc, as well as Pervasives.compare );
62 -hashing (module Hash );
64 -and structured input-output (the functions from the Marshal module, as
66 well as Pervasives.output_value and Pervasives.input_value ).
67 === Element kinds ===
76 === Big arrays can contain elements of the following kinds: - IEEE sin‐
79 gle precision (32 bits) floating-point numbers (Bigarray.float32_elt),
80 - IEEE double precision (64 bits) floating-point numbers (Bigar‐
81 ray.float64_elt), - IEEE single precision (2 * 32 bits) floating-point
82 complex numbers (Bigarray.complex32_elt), - IEEE double precision (2 *
83 64 bits) floating-point complex numbers (Bigarray.complex64_elt), -
84 8-bit integers (signed or unsigned) (Bigarray.int8_signed_elt or Bigar‐
85 ray.int8_unsigned_elt), - 16-bit integers (signed or unsigned) (Bigar‐
86 ray.int16_signed_elt or Bigarray.int16_unsigned_elt), - OCaml integers
87 (signed, 31 bits on 32-bit architectures, 63 bits on 64-bit architec‐
88 tures) (Bigarray.int_elt), - 32-bit signed integers (Bigar‐
89 ray.int32_elt), - 64-bit signed integers (Bigarray.int64_elt), - plat‐
90 form-native signed integers (32 bits on 32-bit architectures, 64 bits
91 on 64-bit architectures) (Bigarray.nativeint_elt). Each element kind
92 is represented at the type level by one of the *_elt types defined
93 below (defined with a single constructor instead of abstract types for
94 technical injectivity reasons). ===
95 type float32_elt =
98 | Float32_elt
99 type float64_elt =
104 | Float64_elt
105 type int8_signed_elt =
110 | Int8_signed_elt
111 type int8_unsigned_elt =
116 | Int8_unsigned_elt
117 type int16_signed_elt =
122 | Int16_signed_elt
123 type int16_unsigned_elt =
128 | Int16_unsigned_elt
129 type int32_elt =
134 | Int32_elt
135 type int64_elt =
140 | Int64_elt
141 type int_elt =
146 | Int_elt
147 type nativeint_elt =
152 | Nativeint_elt
153 type complex32_elt =
158 | Complex32_elt
159 type complex64_elt =
164 | Complex64_elt
165 type ('a, 'b) kind =
170 | Float32 : (float, float32_elt) kind
171 | Float64 : (float, float64_elt) kind
172 | Int8_signed : (int, int8_signed_elt) kind
173 | Int8_unsigned : (int, int8_unsigned_elt) kind
174 | Int16_signed : (int, int16_signed_elt) kind
175 | Int16_unsigned : (int, int16_unsigned_elt) kind
176 | Int32 : (int32, int32_elt) kind
177 | Int64 : (int64, int64_elt) kind
178 | Int : (int, int_elt) kind
179 | Nativeint : (nativeint, nativeint_elt) kind
180 | Complex32 : (Complex.t, complex32_elt) kind
181 | Complex64 : (Complex.t, complex64_elt) kind
182 | Char : (char, int8_unsigned_elt) kind
183 To each element kind is associated an OCaml type, which is the type of
186 OCaml values that can be stored in the big array or read back from it.
187 This type is not necessarily the same as the type of the array elements
188 proper: for instance, a big array whose elements are of kind
189 float32_elt contains 32-bit single precision floats, but reading or
190 writing one of its elements from OCaml uses the OCaml type float ,
191 which is 64-bit double precision floats.
192 The GADT type ('a, 'b) kind captures this association of an OCaml type
194 'a for values read or written in the big array, and of an element kind
195 'b which represents the actual contents of the big array. Its construc‐
196 tors list all possible associations of OCaml types with element kinds,
197 and are re-exported below for backward-compatibility reasons.
198 Using a generalized algebraic datatype (GADT) here allows to write
200 well-typed polymorphic functions whose return type depend on the argu‐
201 ment type, such as:
202 let zero : type a b. (a, b) kind -> a = function | Float32 -> 0.0 |
205 Complex32 -> Complex.zero | Float64 -> 0.0 | Complex64 -> Complex.zero
206 | Int8_signed -> 0 | Int8_unsigned -> 0 | Int16_signed -> 0 |
207 Int16_unsigned -> 0 | Int32 -> 0l | Int64 -> 0L | Int -> 0 | Nativeint
208 -> 0n | Char -> '\000'
209 val float32 : (float, float32_elt) kind
214 See Bigarray.char .
216 val float64 : (float, float64_elt) kind
220 See Bigarray.char .
222 val complex32 : (Complex.t, complex32_elt) kind
226 See Bigarray.char .
228 val complex64 : (Complex.t, complex64_elt) kind
232 See Bigarray.char .
234 val int8_signed : (int, int8_signed_elt) kind
238 See Bigarray.char .
240 val int8_unsigned : (int, int8_unsigned_elt) kind
244 See Bigarray.char .
246 val int16_signed : (int, int16_signed_elt) kind
250 See Bigarray.char .
252 val int16_unsigned : (int, int16_unsigned_elt) kind
256 See Bigarray.char .
258 val int : (int, int_elt) kind
262 See Bigarray.char .
264 val int32 : (int32, int32_elt) kind
268 See Bigarray.char .
270 val int64 : (int64, int64_elt) kind
274 See Bigarray.char .
276 val nativeint : (nativeint, nativeint_elt) kind
280 See Bigarray.char .
282 val char : (char, int8_unsigned_elt) kind
286 As shown by the types of the values above, big arrays of kind
288 float32_elt and float64_elt are accessed using the OCaml type float .
289 Big arrays of complex kinds complex32_elt , complex64_elt are accessed
290 with the OCaml type Complex.t . Big arrays of integer kinds are
291 accessed using the smallest OCaml integer type large enough to repre‐
292 sent the array elements: int for 8- and 16-bit integer bigarrays, as
293 well as OCaml-integer bigarrays; int32 for 32-bit integer bigarrays;
294 int64 for 64-bit integer bigarrays; and nativeint for platform-native
295 integer bigarrays. Finally, big arrays of kind int8_unsigned_elt can
296 also be accessed as arrays of characters instead of arrays of small
297 integers, by using the kind value char instead of int8_unsigned .
298 val kind_size_in_bytes : ('a, 'b) kind -> int
302 kind_size_in_bytes k is the number of bytes used to store an element of
305 type k .
306 Since 4.03.0
309 === Array layouts ===
314 type c_layout =
317 | C_layout_typ
318 See Bigarray.fortran_layout .
321 type fortran_layout =
324 | Fortran_layout_typ
325 To facilitate interoperability with existing C and Fortran code, this
328 library supports two different memory layouts for big arrays, one com‐
329 patible with the C conventions, the other compatible with the Fortran
330 conventions.
331 In the C-style layout, array indices start at 0, and multi-dimensional
333 arrays are laid out in row-major format. That is, for a two-dimen‐
334 sional array, all elements of row 0 are contiguous in memory, followed
335 by all elements of row 1, etc. In other terms, the array elements at
336 (x,y) and (x, y+1) are adjacent in memory.
337 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
339 sional arrays are laid out in column-major format. That is, for a
340 two-dimensional array, all elements of column 0 are contiguous in mem‐
341 ory, followed by all elements of column 1, etc. In other terms, the
342 array elements at (x,y) and (x+1, y) are adjacent in memory.
343 Each layout style is identified at the type level by the phantom types
345 Bigarray.c_layout and Bigarray.fortran_layout respectively.
346 === Supported layouts The GADT type 'a layout represents one of the two
351 supported memory layouts: C-style or Fortran-style. Its constructors
352 are re-exported as values below for backward-compatibility reasons. ===
353 type 'a layout =
356 | C_layout : c_layout layout
357 | Fortran_layout : fortran_layout layout
358 val c_layout : c_layout layout
364 val fortran_layout : fortran_layout layout
369 === Generic arrays (of arbitrarily many dimensions) ===
375 module Genarray : sig end
378 === Zero-dimensional arrays ===
385 module Array0 : sig end
388 Zero-dimensional arrays. The Array0 structure provides operations simi‐
391 lar to those of Bigarray.Genarray , but specialized to the case of
392 zero-dimensional arrays that only contain a single scalar value. Stat‐
393 ically knowing the number of dimensions of the array allows faster
394 operations, and more precise static type-checking.
395 Since 4.05.0
398 === One-dimensional arrays ===
403 module Array1 : sig end
406 One-dimensional arrays. The Array1 structure provides operations simi‐
409 lar to those of Bigarray.Genarray , but specialized to the case of
410 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
411 structures below provide operations specialized for two- and
412 three-dimensional arrays.) Statically knowing the number of dimensions
413 of the array allows faster operations, and more precise static
414 type-checking.
415 === Two-dimensional arrays ===
420 module Array2 : sig end
423 Two-dimensional arrays. The Array2 structure provides operations simi‐
426 lar to those of Bigarray.Genarray , but specialized to the case of
427 two-dimensional arrays.
428 === Three-dimensional arrays ===
433 module Array3 : sig end
436 Three-dimensional arrays. The Array3 structure provides operations sim‐
439 ilar to those of Bigarray.Genarray , but specialized to the case of
440 three-dimensional arrays.
441 === Coercions between generic big arrays and fixed-dimension big arrays
446 ===
447 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
450 ray.t
451 Return the generic big array corresponding to the given zero-dimen‐
453 sional big array.
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 big array corresponding to the given one-dimensional
464 big array.
465 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
469 ray.t
470 Return the generic big array corresponding to the given two-dimensional
472 big array.
473 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
477 ray.t
478 Return the generic big array corresponding to the given three-dimen‐
480 sional big array.
481 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
485 Array0.t
486 Return the zero-dimensional big array corresponding to the given
488 generic big array. Raise Invalid_argument if the generic big array
489 does not have exactly zero dimension.
490 Since 4.05.0
493 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
497 Array1.t
498 Return the one-dimensional big array corresponding to the given generic
500 big array. Raise Invalid_argument if the generic big array does not
501 have exactly one dimension.
502 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
506 Array2.t
507 Return the two-dimensional big array corresponding to the given generic
509 big array. Raise Invalid_argument if the generic big array does not
510 have exactly two dimensions.
511 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
515 Array3.t
516 Return the three-dimensional big array corresponding to the given
518 generic big array. Raise Invalid_argument if the generic big array
519 does not have exactly three dimensions.
520 === Re-shaping big arrays ===
525 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
528 Genarray.t
529 reshape b [|d1;...;dN|] converts the big array b to a N -dimensional
532 array of dimensions d1 ... dN . The returned array and the original
533 array b share their data and have the same layout. For instance,
534 assuming that b is a one-dimensional array of dimension 12, reshape b
535 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
536 has C layout, the element (x,y) of b' corresponds to the element x * 3
537 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
538 sponds to the element x + (y - 1) * 4 of b . The returned big array
539 must have exactly the same number of elements as the original big array
540 b . That is, the product of the dimensions of b must be equal to i1 *
541 ... * iN . Otherwise, Invalid_argument is raised.
542 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
546 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
548 sional arrays.
549 Since 4.05.0
552 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
556 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
558 sional arrays.
559 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
563 Array2.t
564 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
566 sional arrays.
567 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
571 'b, 'c) Array3.t
572 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
574 sional arrays.
575OCamldoc 2019-02-02 Bigarray(3)