package nx

  1. Overview
  2. Docs

Module Bigarray_extSource

include module type of struct include Bigarray end

Element kinds

Bigarrays can contain elements of the following kinds:

Each element kind is represented at the type level by one of the *_elt types defined below (defined with a single constructor instead of abstract types for technical injectivity reasons).

  • since 4.07 Moved from otherlibs to stdlib.
  • since 5.2 Added float16_elt element kind.
Sourcetype float16_elt = Bigarray.float16_elt =
  1. | Float16_elt
Sourcetype float32_elt = Bigarray.float32_elt =
  1. | Float32_elt
Sourcetype float64_elt = Bigarray.float64_elt =
  1. | Float64_elt
Sourcetype int8_signed_elt = Bigarray.int8_signed_elt =
  1. | Int8_signed_elt
Sourcetype int8_unsigned_elt = Bigarray.int8_unsigned_elt =
  1. | Int8_unsigned_elt
Sourcetype int16_signed_elt = Bigarray.int16_signed_elt =
  1. | Int16_signed_elt
Sourcetype int16_unsigned_elt = Bigarray.int16_unsigned_elt =
  1. | Int16_unsigned_elt
Sourcetype int32_elt = Bigarray.int32_elt =
  1. | Int32_elt
Sourcetype int64_elt = Bigarray.int64_elt =
  1. | Int64_elt
Sourcetype int_elt = Bigarray.int_elt =
  1. | Int_elt
Sourcetype nativeint_elt = Bigarray.nativeint_elt =
  1. | Nativeint_elt
Sourcetype complex32_elt = Bigarray.complex32_elt =
  1. | Complex32_elt
Sourcetype complex64_elt = Bigarray.complex64_elt =
  1. | Complex64_elt

Array layouts

Sourcetype c_layout = Bigarray.c_layout =
  1. | C_layout_typ
Sourcetype fortran_layout = Bigarray.fortran_layout =
  1. | Fortran_layout_typ

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.

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 (x,y) and (x, y+1) are adjacent in memory.

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 (x,y) and (x+1, y) are adjacent in memory.

Each layout style is identified at the type level by the phantom types Bigarray.c_layout and Bigarray.fortran_layout respectively.

Supported layouts

The GADT type '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.

Sourcetype 'a layout = 'a Bigarray.layout =
  1. | C_layout : c_layout layout
  2. | Fortran_layout : fortran_layout layout
Sourceval c_layout : c_layout layout
Sourceval fortran_layout : fortran_layout layout

Generic arrays (of arbitrarily many dimensions)

Zero-dimensional arrays

One-dimensional arrays

Two-dimensional arrays

Three-dimensional arrays

Coercions between generic Bigarrays and fixed-dimension Bigarrays

Sourceval genarray_of_array0 : ('a, 'b, 'c) Bigarray.Array0.t -> ('a, 'b, 'c) Bigarray.Genarray.t

Return the generic Bigarray corresponding to the given zero-dimensional Bigarray.

  • since 4.05
Sourceval genarray_of_array1 : ('a, 'b, 'c) Bigarray.Array1.t -> ('a, 'b, 'c) Bigarray.Genarray.t

Return the generic Bigarray corresponding to the given one-dimensional Bigarray.

Sourceval genarray_of_array2 : ('a, 'b, 'c) Bigarray.Array2.t -> ('a, 'b, 'c) Bigarray.Genarray.t

Return the generic Bigarray corresponding to the given two-dimensional Bigarray.

Sourceval genarray_of_array3 : ('a, 'b, 'c) Bigarray.Array3.t -> ('a, 'b, 'c) Bigarray.Genarray.t

Return the generic Bigarray corresponding to the given three-dimensional Bigarray.

Sourceval array0_of_genarray : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b, 'c) Bigarray.Array0.t

Return the zero-dimensional Bigarray corresponding to the given generic Bigarray.

  • raises Invalid_argument

    if the generic Bigarray does not have exactly zero dimension.

  • since 4.05
Sourceval array1_of_genarray : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b, 'c) Bigarray.Array1.t

Return the one-dimensional Bigarray corresponding to the given generic Bigarray.

  • raises Invalid_argument

    if the generic Bigarray does not have exactly one dimension.

Sourceval array2_of_genarray : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b, 'c) Bigarray.Array2.t

Return the two-dimensional Bigarray corresponding to the given generic Bigarray.

  • raises Invalid_argument

    if the generic Bigarray does not have exactly two dimensions.

Sourceval array3_of_genarray : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b, 'c) Bigarray.Array3.t

Return the three-dimensional Bigarray corresponding to the given generic Bigarray.

  • raises Invalid_argument

    if the generic Bigarray does not have exactly three dimensions.

Re-shaping Bigarrays

Sourceval reshape : ('a, 'b, 'c) Bigarray.Genarray.t -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t

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

Sourceval reshape_0 : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b, 'c) Bigarray.Array0.t

Specialized version of Bigarray.reshape for reshaping to zero-dimensional arrays.

  • since 4.05
Sourceval reshape_1 : ('a, 'b, 'c) Bigarray.Genarray.t -> int -> ('a, 'b, 'c) Bigarray.Array1.t

Specialized version of Bigarray.reshape for reshaping to one-dimensional arrays.

Sourceval reshape_2 : ('a, 'b, 'c) Bigarray.Genarray.t -> int -> int -> ('a, 'b, 'c) Bigarray.Array2.t

Specialized version of Bigarray.reshape for reshaping to two-dimensional arrays.

Sourceval reshape_3 : ('a, 'b, 'c) Bigarray.Genarray.t -> int -> int -> int -> ('a, 'b, 'c) Bigarray.Array3.t

Specialized version of Bigarray.reshape for reshaping to three-dimensional arrays.

Bigarrays and concurrency safety

Care must be taken when concurrently accessing bigarrays from multiple domains: accessing a bigarray will never crash a program, but unsynchronized accesses might yield surprising (non-sequentially-consistent) results.

Atomicity

Every bigarray operation that accesses more than one array element is not atomic. This includes slicing, bliting, and filling bigarrays.

For example, consider the following program:

open Bigarray
let size = 100_000_000
let a = Array1.init Int C_layout size (fun _ -> 1)
let update f a () =
  for i = 0 to size - 1 do a.{i} <- f a.{i} done
let d1 = Domain.spawn (update (fun x -> x + 1) a)
let d2 = Domain.spawn (update (fun x -> 2 * x + 1) a)
let () = Domain.join d1; Domain.join d2

After executing this code, each field of the bigarray a is either 2, 3, 4 or 5. If atomicity is required, then the user must implement their own synchronization (for example, using Mutex.t).

Data races

If two domains only access disjoint parts of the bigarray, then the observed behaviour is the equivalent to some sequential interleaving of the operations from the two domains.

A data race is said to occur when two domains access the same bigarray element without synchronization and at least one of the accesses is a write. In the absence of data races, the observed behaviour is equivalent to some sequential interleaving of the operations from different domains.

Whenever possible, data races should be avoided by using synchronization to mediate the accesses to the bigarray elements.

Indeed, in the presence of data races, programs will not crash but the observed behaviour may not be equivalent to any sequential interleaving of operations from different domains.

Tearing

Bigarrays have a distinct caveat in the presence of data races: concurrent bigarray operations might produce surprising values due to tearing. More precisely, the interleaving of partial writes and reads might create values that would not exist with a sequential execution. For instance, at the end of

let res = Array1.init Complex64 c_layout size (fun _ -> Complex.zero)
let d1 = Domain.spawn (fun () -> Array1.fill res Complex.one)
let d2 = Domain.spawn (fun () -> Array1.fill res Complex.i)
let () = Domain.join d1; Domain.join d2

the res bigarray might contain values that are neither Complex.i nor Complex.one (for instance 1 + i).

Sourcetype bfloat16_elt =
  1. | Bfloat16_elt
Sourcetype bool_elt =
  1. | Bool_elt
Sourcetype int4_signed_elt =
  1. | Int4_signed_elt
Sourcetype int4_unsigned_elt =
  1. | Int4_unsigned_elt
Sourcetype float8_e4m3_elt =
  1. | Float8_e4m3_elt
Sourcetype float8_e5m2_elt =
  1. | Float8_e5m2_elt
Sourcetype complex16_elt =
  1. | Complex16_elt
Sourcetype qint8_elt =
  1. | Qint8_elt
Sourcetype quint8_elt =
  1. | Quint8_elt
Sourcetype ('a, 'b) kind =
  1. | Float32 : (float, float32_elt) kind
  2. | Float64 : (float, float64_elt) kind
  3. | Int8_signed : (int, int8_signed_elt) kind
  4. | Int8_unsigned : (int, int8_unsigned_elt) kind
  5. | Int16_signed : (int, int16_signed_elt) kind
  6. | Int16_unsigned : (int, int16_unsigned_elt) kind
  7. | Int32 : (int32, int32_elt) kind
  8. | Int64 : (int64, int64_elt) kind
  9. | Int : (int, int_elt) kind
  10. | Nativeint : (nativeint, nativeint_elt) kind
  11. | Complex32 : (Complex.t, complex32_elt) kind
  12. | Complex64 : (Complex.t, complex64_elt) kind
  13. | Char : (char, int8_unsigned_elt) kind
  14. | Float16 : (float, float16_elt) kind
  15. | Bfloat16 : (float, bfloat16_elt) kind
  16. | Bool : (bool, bool_elt) kind
  17. | Int4_signed : (int, int4_signed_elt) kind
  18. | Int4_unsigned : (int, int4_unsigned_elt) kind
  19. | Float8_e4m3 : (float, float8_e4m3_elt) kind
  20. | Float8_e5m2 : (float, float8_e5m2_elt) kind
  21. | Complex16 : (Complex.t, complex16_elt) kind
  22. | Qint8 : (int, qint8_elt) kind
  23. | Quint8 : (int, quint8_elt) kind
Sourceval float32 : (float, float32_elt) kind
Sourceval float64 : (float, float64_elt) kind
Sourceval int8_signed : (int, int8_signed_elt) kind
Sourceval int8_unsigned : (int, int8_unsigned_elt) kind
Sourceval int16_signed : (int, int16_signed_elt) kind
Sourceval int16_unsigned : (int, int16_unsigned_elt) kind
Sourceval int32 : (int32, int32_elt) kind
Sourceval int64 : (int64, int64_elt) kind
Sourceval int : (int, int_elt) kind
Sourceval nativeint : (nativeint, nativeint_elt) kind
Sourceval char : (char, int8_unsigned_elt) kind
Sourceval float16 : (float, float16_elt) kind
Sourceval bfloat16 : (float, bfloat16_elt) kind
Sourceval bool : (bool, bool_elt) kind
Sourceval int4_signed : (int, int4_signed_elt) kind
Sourceval int4_unsigned : (int, int4_unsigned_elt) kind
Sourceval float8_e4m3 : (float, float8_e4m3_elt) kind
Sourceval float8_e5m2 : (float, float8_e5m2_elt) kind
Sourceval qint8 : (int, qint8_elt) kind
Sourceval quint8 : (int, quint8_elt) kind
Sourceval kind_size_in_bytes : 'a 'b. ('a, 'b) kind -> int
Sourceval to_stdlib_kind : 'a 'b. ('a, 'b) kind -> ('a, 'b) Bigarray.kind option
Sourceval create_bfloat16_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_bool_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_int4_signed_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_int4_unsigned_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_float8_e4m3_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_float8_e5m2_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_complex16_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_qint8_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval create_quint8_genarray : 'c layout -> int array -> ('a, 'b, 'c) Bigarray.Genarray.t
Sourceval nx_ba_get_generic : ('a, 'b, 'c) Bigarray.Genarray.t -> int array -> 'a
Sourceval nx_ba_set_generic : ('a, 'b, 'c) Bigarray.Genarray.t -> int array -> 'a -> unit
Sourceval nx_ba_kind : ('a, 'b, 'c) Bigarray.Genarray.t -> ('a, 'b) kind
Sourcemodule Genarray : sig ... end
Sourcemodule Array0 : sig ... end
Sourcemodule Array1 : sig ... end
Sourcemodule Array2 : sig ... end
Sourcemodule Array3 : sig ... end