.TH "Bigarray" 3o 2020-01-30 OCamldoc "OCaml library"
.SH NAME
Bigarray \- Large, multi-dimensional, numerical arrays.
.SH Module
Module   Bigarray
.SH Documentation
.sp
Module
.BI "Bigarray"
 : 
.B sig  end

.sp
Large, multi\-dimensional, numerical arrays\&.
.sp
This module implements multi\-dimensional arrays of integers and
floating\-point numbers, thereafter referred to as \&'Bigarrays\&',
to distinguish them from the standard OCaml arrays described in
.B Array
\&.
.sp
The implementation allows efficient sharing of large numerical
arrays between OCaml code and C or Fortran numerical libraries\&.
.sp
The main differences between \&'Bigarrays\&' and standard OCaml
arrays are as follows:
.sp
\-Bigarrays are not limited in size, unlike OCaml arrays\&.
(Normal float arrays are limited to 2,097,151 elements on a 32\-bit
platform, and normal arrays of other types to 4,194,303 elements\&.)
.sp
\-Bigarrays are multi\-dimensional\&.  Any number of dimensions
between 0 and 16 is supported\&.  In contrast, OCaml arrays
are mono\-dimensional and require encoding multi\-dimensional
arrays as arrays of arrays\&.
.sp
\-Bigarrays can only contain integers and floating\-point numbers,
while OCaml arrays can contain arbitrary OCaml data types\&.
.sp
\-Bigarrays provide more space\-efficient storage of
integer and floating\-point elements than normal OCaml arrays, in
particular because they support \&'small\&' types such as
single\-precision floats and 8 and 16\-bit integers, in addition to
the standard OCaml types of double\-precision floats and 32 and
64\-bit integers\&.
.sp
\-The memory layout of Bigarrays is entirely compatible with that
of arrays in C and Fortran, allowing large arrays to be passed
back and forth between OCaml code and C / Fortran code with no
data copying at all\&.
.sp
\-Bigarrays support interesting high\-level operations that normal
arrays do not provide efficiently, such as extracting sub\-arrays
and \&'slicing\&' a multi\-dimensional array along certain dimensions,
all without any copying\&.

Users of this module are encouraged to do 
.B open Bigarray
in their
source, then refer to array types and operations via short dot
notation, e\&.g\&. 
.B Array1\&.t
or 
.B Array2\&.sub
\&.
.sp
Bigarrays support all the OCaml ad\-hoc polymorphic operations:
.sp
\-comparisons (
.B =
, 
.B <>
, 
.B <=
, etc, as well as 
.B compare
);
.sp
\-hashing (module 
.B Hash
);
.sp
\-and structured input\-output (the functions from the
.B Marshal
module, as well as 
.B output_value
and 
.B input_value
)\&.


.sp

.sp
.sp

.PP
.SS Element kinds

.PP

.PP
Bigarrays can contain elements of the following kinds:
.sp
\-IEEE single precision (32 bits) floating\-point numbers
(
.B Bigarray\&.float32_elt
),
.sp
\-IEEE double precision (64 bits) floating\-point numbers
(
.B Bigarray\&.float64_elt
),
.sp
\-IEEE single precision (2 * 32 bits) floating\-point complex numbers
(
.B Bigarray\&.complex32_elt
),
.sp
\-IEEE double precision (2 * 64 bits) floating\-point complex numbers
(
.B Bigarray\&.complex64_elt
),
.sp
\-8\-bit integers (signed or unsigned)
(
.B Bigarray\&.int8_signed_elt
or 
.B Bigarray\&.int8_unsigned_elt
),
.sp
\-16\-bit integers (signed or unsigned)
(
.B Bigarray\&.int16_signed_elt
or 
.B Bigarray\&.int16_unsigned_elt
),
.sp
\-OCaml integers (signed, 31 bits on 32\-bit architectures,
63 bits on 64\-bit architectures) (
.B Bigarray\&.int_elt
),
.sp
\-32\-bit signed integers (
.B Bigarray\&.int32_elt
),
.sp
\-64\-bit signed integers (
.B Bigarray\&.int64_elt
),
.sp
\-platform\-native signed integers (32 bits on 32\-bit architectures,
64 bits on 64\-bit architectures) (
.B Bigarray\&.nativeint_elt
)\&.

Each element kind is represented at the type level by one of the
.B *_elt
types defined below (defined with a single constructor instead
of abstract types for technical injectivity reasons)\&.
.PP
.I type float32_elt 
=
 | Float32_elt
 
.sp

.sp
.I type float64_elt 
=
 | Float64_elt
 
.sp

.sp
.I type int8_signed_elt 
=
 | Int8_signed_elt
 
.sp

.sp
.I type int8_unsigned_elt 
=
 | Int8_unsigned_elt
 
.sp

.sp
.I type int16_signed_elt 
=
 | Int16_signed_elt
 
.sp

.sp
.I type int16_unsigned_elt 
=
 | Int16_unsigned_elt
 
.sp

.sp
.I type int32_elt 
=
 | Int32_elt
 
.sp

.sp
.I type int64_elt 
=
 | Int64_elt
 
.sp

.sp
.I type int_elt 
=
 | Int_elt
 
.sp

.sp
.I type nativeint_elt 
=
 | Nativeint_elt
 
.sp

.sp
.I type complex32_elt 
=
 | Complex32_elt
 
.sp

.sp
.I type complex64_elt 
=
 | Complex64_elt
 
.sp

.sp
.I type 
.B ('a, 'b)
.I kind 
=
 | Float32
.B : 
.B (float, float32_elt) kind
 | Float64
.B : 
.B (float, float64_elt) kind
 | Int8_signed
.B : 
.B (int, int8_signed_elt) kind
 | Int8_unsigned
.B : 
.B (int, int8_unsigned_elt) kind
 | Int16_signed
.B : 
.B (int, int16_signed_elt) kind
 | Int16_unsigned
.B : 
.B (int, int16_unsigned_elt) kind
 | Int32
.B : 
.B (int32, int32_elt) kind
 | Int64
.B : 
.B (int64, int64_elt) kind
 | Int
.B : 
.B (int, int_elt) kind
 | Nativeint
.B : 
.B (nativeint, nativeint_elt) kind
 | Complex32
.B : 
.B (Complex.t, complex32_elt) kind
 | Complex64
.B : 
.B (Complex.t, complex64_elt) kind
 | Char
.B : 
.B (char, int8_unsigned_elt) kind
 
.sp
To each element kind is associated an OCaml type, which is
the type of OCaml values that can be stored in the Bigarray
or read back from it\&.  This type is not necessarily the same
as the type of the array elements proper: for instance,
a Bigarray whose elements are of kind 
.B float32_elt
contains
32\-bit single precision floats, but reading or writing one of
its elements from OCaml uses the OCaml type 
.B float
, which is
64\-bit double precision floats\&.
.sp
The GADT type 
.B (\&'a, \&'b) kind
captures this association
of an OCaml type 
.B \&'a
for values read or written in the Bigarray,
and of an element kind 
.B \&'b
which represents the actual contents
of the Bigarray\&. Its constructors list all possible associations
of OCaml types with element kinds, and are re\-exported below for
backward\-compatibility reasons\&.
.sp
Using a generalized algebraic datatype (GADT) here allows writing
well\-typed polymorphic functions whose return type depend on the
argument type, such as:
.sp

.B 
.B   let zero : type a b\&. (a, b) kind \-> a = function
.B     | Float32 \-> 0\&.0 | Complex32 \-> Complex\&.zero
.B     | Float64 \-> 0\&.0 | Complex64 \-> Complex\&.zero
.B     | Int8_signed \-> 0 | Int8_unsigned \-> 0
.B     | Int16_signed \-> 0 | Int16_unsigned \-> 0
.B     | Int32 \-> 0l | Int64 \-> 0L
.B     | Int \-> 0 | Nativeint \-> 0n
.B     | Char \-> \&'\(rs000\&'
.B 


.sp

.I val float32 
: 
.B (float, float32_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val float64 
: 
.B (float, float64_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val complex32 
: 
.B (Complex.t, complex32_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val complex64 
: 
.B (Complex.t, complex64_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int8_signed 
: 
.B (int, int8_signed_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int8_unsigned 
: 
.B (int, int8_unsigned_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int16_signed 
: 
.B (int, int16_signed_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int16_unsigned 
: 
.B (int, int16_unsigned_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int 
: 
.B (int, int_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int32 
: 
.B (int32, int32_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val int64 
: 
.B (int64, int64_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val nativeint 
: 
.B (nativeint, nativeint_elt) kind
.sp
See 
.B Bigarray\&.char
\&.

.sp

.I val char 
: 
.B (char, int8_unsigned_elt) kind
.sp
As shown by the types of the values above,
Bigarrays of kind 
.B float32_elt
and 
.B float64_elt
are
accessed using the OCaml type 
.B float
\&.  Bigarrays of complex kinds
.B complex32_elt
, 
.B complex64_elt
are accessed with the OCaml type
.B Complex\&.t
\&. Bigarrays of
integer kinds are accessed using the smallest OCaml integer
type large enough to represent the array elements:
.B int
for 8\- and 16\-bit integer Bigarrays, as well as OCaml\-integer
Bigarrays; 
.B int32
for 32\-bit integer Bigarrays; 
.B int64
for 64\-bit integer Bigarrays; and 
.B nativeint
for
platform\-native integer Bigarrays\&.  Finally, Bigarrays of
kind 
.B int8_unsigned_elt
can also be accessed as arrays of
characters instead of arrays of small integers, by using
the kind value 
.B char
instead of 
.B int8_unsigned
\&.

.sp

.I val kind_size_in_bytes 
: 
.B ('a, 'b) kind -> int
.sp

.B kind_size_in_bytes k
is the number of bytes used to store
an element of type 
.B k
\&.

.sp
.B "Since"
4.03.0

.sp

.PP
.SS Array layouts

.PP
.I type c_layout 
=
 | C_layout_typ
 
.sp
See 
.B Bigarray\&.fortran_layout
\&.

.sp
.I type fortran_layout 
=
 | Fortran_layout_typ
 
.sp
To facilitate interoperability with existing C and Fortran code,
this library supports two different memory layouts for Bigarrays,
one compatible with the C conventions,
the other compatible with the Fortran conventions\&.
.sp
In the C\-style layout, array indices start at 0, and
multi\-dimensional arrays are laid out in row\-major format\&.
That is, for a two\-dimensional array, all elements of
row 0 are contiguous in memory, followed by all elements of
row 1, etc\&.  In other terms, the array elements at 
.B (x,y)
and 
.B (x, y+1)
are adjacent in memory\&.
.sp
In the Fortran\-style layout, array indices start at 1, and
multi\-dimensional arrays are laid out in column\-major format\&.
That is, for a two\-dimensional array, all elements of
column 0 are contiguous in memory, followed by all elements of
column 1, etc\&.  In other terms, the array elements at 
.B (x,y)
and 
.B (x+1, y)
are adjacent in memory\&.
.sp
Each layout style is identified at the type level by the
phantom types 
.B Bigarray\&.c_layout
and 
.B Bigarray\&.fortran_layout
respectively\&.

.sp

.PP
.SS Supported layouts
.sp
The GADT type 
.B \&'a layout
represents one of the two supported
memory layouts: C\-style or Fortran\-style\&. Its constructors are
re\-exported as values below for backward\-compatibility reasons\&.
.PP
.I type 
.B 'a
.I layout 
=
 | C_layout
.B : 
.B c_layout layout
 | Fortran_layout
.B : 
.B fortran_layout layout
 
.sp

.sp

.I val c_layout 
: 
.B c_layout layout
.sp

.sp

.I val fortran_layout 
: 
.B fortran_layout layout
.sp

.sp

.PP
.SS Generic arrays (of arbitrarily many dimensions)

.PP
.I module Genarray : 
.B sig  end

.sp

.sp

.PP
.SS Zero-dimensional arrays

.PP
.I module Array0 : 
.B sig  end

.sp
Zero\-dimensional arrays\&. The 
.B Array0
structure provides operations
similar to those of 
.B Bigarray\&.Genarray
, but specialized to the case
of zero\-dimensional arrays that only contain a single scalar value\&.
Statically knowing the number of dimensions of the array allows
faster operations, and more precise static type\-checking\&.

.sp
.B "Since"
4.05.0

.sp

.PP
.SS One-dimensional arrays

.PP
.I module Array1 : 
.B sig  end

.sp
One\-dimensional arrays\&. The 
.B Array1
structure provides operations
similar to those of
.B Bigarray\&.Genarray
, but specialized to the case of one\-dimensional arrays\&.
(The 
.B Bigarray\&.Array2
and 
.B Bigarray\&.Array3
structures below provide operations
specialized for two\- and three\-dimensional arrays\&.)
Statically knowing the number of dimensions of the array allows
faster operations, and more precise static type\-checking\&.

.sp

.PP
.SS Two-dimensional arrays

.PP
.I module Array2 : 
.B sig  end

.sp
Two\-dimensional arrays\&. The 
.B Array2
structure provides operations
similar to those of 
.B Bigarray\&.Genarray
, but specialized to the
case of two\-dimensional arrays\&.

.sp

.PP
.SS Three-dimensional arrays

.PP
.I module Array3 : 
.B sig  end

.sp
Three\-dimensional arrays\&. The 
.B Array3
structure provides operations
similar to those of 
.B Bigarray\&.Genarray
, but specialized to the case
of three\-dimensional arrays\&.

.sp

.PP
.SS Coercions between generic Bigarrays and fixed-dimension Bigarrays

.PP

.I val genarray_of_array0 
: 
.B ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genarray.t
.sp
Return the generic Bigarray corresponding to the given zero\-dimensional
Bigarray\&.

.sp
.B "Since"
4.05.0

.sp

.I val genarray_of_array1 
: 
.B ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genarray.t
.sp
Return the generic Bigarray corresponding to the given one\-dimensional
Bigarray\&.

.sp

.I val genarray_of_array2 
: 
.B ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genarray.t
.sp
Return the generic Bigarray corresponding to the given two\-dimensional
Bigarray\&.

.sp

.I val genarray_of_array3 
: 
.B ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genarray.t
.sp
Return the generic Bigarray corresponding to the given three\-dimensional
Bigarray\&.

.sp

.I val array0_of_genarray 
: 
.B ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
.sp
Return the zero\-dimensional Bigarray corresponding to the given
generic Bigarray\&.  Raise 
.B Invalid_argument
if the generic Bigarray
does not have exactly zero dimension\&.

.sp
.B "Since"
4.05.0

.sp

.I val array1_of_genarray 
: 
.B ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array1.t
.sp
Return the one\-dimensional Bigarray corresponding to the given
generic Bigarray\&.  Raise 
.B Invalid_argument
if the generic Bigarray
does not have exactly one dimension\&.

.sp

.I val array2_of_genarray 
: 
.B ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array2.t
.sp
Return the two\-dimensional Bigarray corresponding to the given
generic Bigarray\&.  Raise 
.B Invalid_argument
if the generic Bigarray
does not have exactly two dimensions\&.

.sp

.I val array3_of_genarray 
: 
.B ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array3.t
.sp
Return the three\-dimensional Bigarray corresponding to the given
generic Bigarray\&.  Raise 
.B Invalid_argument
if the generic Bigarray
does not have exactly three dimensions\&.

.sp

.PP
.SS Re-shaping Bigarrays

.PP

.I val reshape 
: 
.B ('a, 'b, 'c) Genarray.t ->
.B   int array -> ('a, 'b, 'c) Genarray.t
.sp

.B reshape b [|d1;\&.\&.\&.;dN|]
converts the Bigarray 
.B b
to a
.B N
\-dimensional array of dimensions 
.B d1
\&.\&.\&.
.B dN
\&.  The returned
array and the original array 
.B b
share their data
and have the same layout\&.  For instance, assuming that 
.B b
is a one\-dimensional array of dimension 12, 
.B reshape b [|3;4|]
returns a two\-dimensional array 
.B b\&'
of dimensions 3 and 4\&.
If 
.B b
has C layout, the element 
.B (x,y)
of 
.B b\&'
corresponds
to the element 
.B x * 3 + y
of 
.B b
\&.  If 
.B b
has Fortran layout,
the element 
.B (x,y)
of 
.B b\&'
corresponds to the element
.B x + (y \- 1) * 4
of 
.B b
\&.
The returned Bigarray must have exactly the same number of
elements as the original Bigarray 
.B b
\&.  That is, the product
of the dimensions of 
.B b
must be equal to 
.B i1 * \&.\&.\&. * iN
\&.
Otherwise, 
.B Invalid_argument
is raised\&.

.sp

.I val reshape_0 
: 
.B ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
.sp
Specialized version of 
.B Bigarray\&.reshape
for reshaping to
zero\-dimensional arrays\&.

.sp
.B "Since"
4.05.0

.sp

.I val reshape_1 
: 
.B ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
.sp
Specialized version of 
.B Bigarray\&.reshape
for reshaping to
one\-dimensional arrays\&.

.sp

.I val reshape_2 
: 
.B ('a, 'b, 'c) Genarray.t ->
.B   int -> int -> ('a, 'b, 'c) Array2.t
.sp
Specialized version of 
.B Bigarray\&.reshape
for reshaping to
two\-dimensional arrays\&.

.sp

.I val reshape_3 
: 
.B ('a, 'b, 'c) Genarray.t ->
.B   int -> int -> int -> ('a, 'b, 'c) Array3.t
.sp
Specialized version of 
.B Bigarray\&.reshape
for reshaping to
three\-dimensional arrays\&.

.sp
