Previous Up Next

Chapter 29  The bigarray library

The bigarray library implements large, multi-dimensional, numerical arrays. These arrays are called “big arrays” to distinguish them from the standard Caml arrays described in Module Array. The main differences between “big arrays” and standard Caml arrays are as follows: Programs that use the bigarray library must be linked as follows:
        ocamlc other options bigarray.cma other files
        ocamlopt other options bigarray.cmxa other files
For interactive use of the bigarray library, do:
        ocamlmktop -o mytop bigarray.cma
or (if dynamic linking of C libraries is supported on your platform), start ocaml and type #load "bigarray.cma";;.

29.1  Module Bigarray: large, multi-dimensional, numerical arrays

Module Bigarray

29.2  Big arrays in the Caml-C interface

C stub code that interface C or Fortran code with Caml code, as described in chapter 18, can exploit big arrays as follows.

29.2.1  Include file

The include file <caml/bigarray.h> must be included in the C stub file. It declares the functions, constants and macros discussed below.

29.2.2  Accessing a Caml bigarray from C or Fortran

If v is a Caml value representing a big array, the expression Data_bigarray_val(v) returns a pointer to the data part of the array. This pointer is of type void * and can be cast to the appropriate C type for the array (e.g. double [], char [][10], etc).

Various characteristics of the Caml big array can be consulted from C as follows:

C expression Returns
Bigarray_val(v)->num_dims number of dimensions
Bigarray_val(v)->dim[i] i-th dimension
Bigarray_val(v)->flags & BIGARRAY_KIND_MASK kind of array elements

The kind of array elements is one of the following constants:

Constant Element kind
BIGARRAY_FLOAT32 32-bit single-precision floats
BIGARRAY_FLOAT64 64-bit double-precision floats
BIGARRAY_SINT8 8-bit signed integers
BIGARRAY_UINT8 8-bit unsigned integers
BIGARRAY_SINT16 16-bit signed integers
BIGARRAY_UINT16 16-bit unsigned integers
BIGARRAY_INT32 32-bit signed integers
BIGARRAY_INT64 64-bit signed integers
BIGARRAY_CAML_INT 31- or 63-bit signed integers
BIGARRAY_NATIVE_INT 32- or 64-bit (platform-native) integers

The following example shows the passing of a two-dimensional big array to a C function and a Fortran function.
    extern void my_c_function(double * data, int dimx, int dimy);
    extern void my_fortran_function_(double * data, int * dimx, int * dimy);

    value caml_stub(value bigarray)
      int dimx = Bigarray_val(bigarray)->dim[0];
      int dimy = Bigarray_val(bigarray)->dim[1];
      /* C passes scalar parameters by value */
      my_c_function(Data_bigarray_val(bigarray), dimx, dimy);
      /* Fortran passes all parameters by reference */
      my_fortran_function_(Data_bigarray_val(bigarray), &dimx, &dimy);
      return Val_unit;

29.2.3  Wrapping a C or Fortran array as a Caml big array

A pointer p to an already-allocated C or Fortran array can be wrapped and returned to Caml as a big array using the alloc_bigarray or alloc_bigarray_dims functions. The following example illustrates how statically-allocated C and Fortran arrays can be made available to Caml.
    extern long my_c_array[100][200];
    extern float my_fortran_array_[300][400];

    value caml_get_c_array(value unit)
      long dims[2];
      dims[0] = 100; dims[1] = 200;
      return alloc_bigarray(BIGARRAY_NATIVE_INT | BIGARRAY_C_LAYOUT,
                            2, my_c_array, dims);

    value caml_get_fortran_array(value unit)
      return alloc_bigarray_dims(BIGARRAY_FLOAT32 | BIGARRAY_FORTRAN_LAYOUT,
                                 2, my_fortran_array_, 300L, 400L);

Previous Up Next