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
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 -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
91 Bigarray.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
108 abstract 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
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 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
404 operations, 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
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 Two-dimensional arrays
428 module Array2 : sig end
429 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 Three-dimensional arrays
439 module Array3 : sig end
440 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 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 Return the generic Bigarray corresponding to the given zero-dimensional
454 Bigarray.
455 Since 4.05.0
458 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
462 ray.t
463 Return the generic Bigarray corresponding to the given one-dimensional
465 Bigarray.
466 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
470 ray.t
471 Return the generic Bigarray corresponding to the given two-dimensional
473 Bigarray.
474 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
478 ray.t
479 Return the generic Bigarray corresponding to the given three-dimen‐
481 sional Bigarray.
482 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
486 Array0.t
487 Return the zero-dimensional Bigarray corresponding to the given generic
489 Bigarray.
490 Since 4.05.0
493 Raises Invalid_argument if the generic Bigarray does not have exactly
496 zero dimension.
497 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
501 Array1.t
502 Return the one-dimensional Bigarray corresponding to the given generic
504 Bigarray.
505 Raises Invalid_argument if the generic Bigarray does not have exactly
508 one dimension.
509 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
513 Array2.t
514 Return the two-dimensional Bigarray corresponding to the given generic
516 Bigarray.
517 Raises Invalid_argument if the generic Bigarray does not have exactly
520 two dimensions.
521 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
525 Array3.t
526 Return the three-dimensional Bigarray corresponding to the given
528 generic Bigarray.
529 Raises Invalid_argument if the generic Bigarray does not have exactly
532 three dimensions.
533 Re-shaping Bigarrays
538 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
539 Genarray.t
540 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional
543 array of dimensions d1 ... dN . The returned array and the original
544 array b share their data and have the same layout. For instance,
545 assuming that b is a one-dimensional array of dimension 12, reshape b
546 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
547 has C layout, the element (x,y) of b' corresponds to the element x * 3
548 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
549 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
550 must have exactly the same number of elements as the original Bigarray
551 b . That is, the product of the dimensions of b must be equal to i1 *
552 ... * iN . Otherwise, Invalid_argument is raised.
553 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
557 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
559 sional arrays.
560 Since 4.05.0
563 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
567 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
569 sional arrays.
570 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
574 Array2.t
575 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
577 sional arrays.
578 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
582 'b, 'c) Array3.t
583 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
585 sional arrays.
586OCamldoc 2020-09-01 Bigarray(3)