1Bigarray(3)                      OCaml library                     Bigarray(3)
2
3
4

NAME

6       Bigarray - Large, multi-dimensional, numerical arrays.
7

Module

9       Module   Bigarray
10

Documentation

12       Module Bigarray
13        : sig end
14
15
16       Large, multi-dimensional, numerical arrays.
17
18       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
22       The  implementation  allows efficient sharing of large numerical arrays
23       between OCaml code and C or Fortran numerical libraries.
24
25       The main differences between 'Bigarrays' and standard OCaml arrays  are
26       as follows:
27
28       -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
32       -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
36       -Bigarrays  can only contain integers and floating-point numbers, while
37       OCaml arrays can contain arbitrary OCaml data types.
38
39       -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
45       -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
50       -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
55       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
59       Bigarrays support all the OCaml ad-hoc polymorphic operations:
60
61       -comparisons ( = , <> , <= , etc, as well as compare );
62
63       -hashing (module Hash );
64
65       -and structured input-output (the functions from the Marshal module, as
66       well as output_value and input_value ).
67
68
69
70
71
72
73
74
75   Element kinds
76       Bigarrays can contain elements of the following kinds:
77
78       -IEEE  single  precision  (32  bits)  floating-point  numbers  ( Bigar‐
79       ray.float32_elt ),
80
81       -IEEE double  precision  (64  bits)  floating-point  numbers  (  Bigar‐
82       ray.float64_elt ),
83
84       -IEEE  single  precision (2 * 32 bits) floating-point complex numbers (
85       Bigarray.complex32_elt ),
86
87       -IEEE double precision (2 * 64 bits) floating-point complex  numbers  (
88       Bigarray.complex64_elt ),
89
90       -8-bit  integers  (signed  or  unsigned)  ( Bigarray.int8_signed_elt or
91       Bigarray.int8_unsigned_elt ),
92
93       -16-bit integers (signed or unsigned)  (  Bigarray.int16_signed_elt  or
94       Bigarray.int16_unsigned_elt ),
95
96       -OCaml  integers  (signed,  31 bits on 32-bit architectures, 63 bits on
97       64-bit architectures) ( Bigarray.int_elt ),
98
99       -32-bit signed integers ( Bigarray.int32_elt ),
100
101       -64-bit signed integers ( Bigarray.int64_elt ),
102
103       -platform-native signed integers (32 bits on 32-bit  architectures,  64
104       bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
105
106       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
110       type float32_elt =
111        | Float32_elt
112
113
114
115
116       type float64_elt =
117        | Float64_elt
118
119
120
121
122       type int8_signed_elt =
123        | Int8_signed_elt
124
125
126
127
128       type int8_unsigned_elt =
129        | Int8_unsigned_elt
130
131
132
133
134       type int16_signed_elt =
135        | Int16_signed_elt
136
137
138
139
140       type int16_unsigned_elt =
141        | Int16_unsigned_elt
142
143
144
145
146       type int32_elt =
147        | Int32_elt
148
149
150
151
152       type int64_elt =
153        | Int64_elt
154
155
156
157
158       type int_elt =
159        | Int_elt
160
161
162
163
164       type nativeint_elt =
165        | Nativeint_elt
166
167
168
169
170       type complex32_elt =
171        | Complex32_elt
172
173
174
175
176       type complex64_elt =
177        | Complex64_elt
178
179
180
181
182       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
197
198       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
206       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
212       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
216
217       let  zero  :  type  a b. (a, b) kind -> a = function | Float32 -> 0.0 |
218       Complex32 -> Complex.zero | Float64 -> 0.0 | Complex64 ->  Complex.zero
219       |  Int8_signed  ->  0  |  Int8_unsigned  ->  0  |  Int16_signed  -> 0 |
220       Int16_unsigned -> 0 | Int32 -> 0l | Int64 -> 0L | Int -> 0 |  Nativeint
221       -> 0n | Char -> '\000'
222
223
224
225
226       val float32 : (float, float32_elt) kind
227
228       See Bigarray.char .
229
230
231
232       val float64 : (float, float64_elt) kind
233
234       See Bigarray.char .
235
236
237
238       val complex32 : (Complex.t, complex32_elt) kind
239
240       See Bigarray.char .
241
242
243
244       val complex64 : (Complex.t, complex64_elt) kind
245
246       See Bigarray.char .
247
248
249
250       val int8_signed : (int, int8_signed_elt) kind
251
252       See Bigarray.char .
253
254
255
256       val int8_unsigned : (int, int8_unsigned_elt) kind
257
258       See Bigarray.char .
259
260
261
262       val int16_signed : (int, int16_signed_elt) kind
263
264       See Bigarray.char .
265
266
267
268       val int16_unsigned : (int, int16_unsigned_elt) kind
269
270       See Bigarray.char .
271
272
273
274       val int : (int, int_elt) kind
275
276       See Bigarray.char .
277
278
279
280       val int32 : (int32, int32_elt) kind
281
282       See Bigarray.char .
283
284
285
286       val int64 : (int64, int64_elt) kind
287
288       See Bigarray.char .
289
290
291
292       val nativeint : (nativeint, nativeint_elt) kind
293
294       See Bigarray.char .
295
296
297
298       val char : (char, int8_unsigned_elt) kind
299
300       As  shown  by  the  types  of  the  values  above,  Bigarrays  of  kind
301       float32_elt and float64_elt are accessed using the OCaml type  float  .
302       Bigarrays  of  complex kinds complex32_elt , complex64_elt are accessed
303       with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
304       using  the  smallest  OCaml  integer type large enough to represent the
305       array elements: int for 8- and 16-bit integer  Bigarrays,  as  well  as
306       OCaml-integer  Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
307       64-bit integer Bigarrays; and  nativeint  for  platform-native  integer
308       Bigarrays.   Finally,  Bigarrays  of kind int8_unsigned_elt can also be
309       accessed as arrays of characters instead of arrays of  small  integers,
310       by using the kind value char instead of int8_unsigned .
311
312
313
314       val kind_size_in_bytes : ('a, 'b) kind -> int
315
316
317       kind_size_in_bytes k is the number of bytes used to store an element of
318       type k .
319
320
321       Since 4.03.0
322
323
324
325
326   Array layouts
327       type c_layout =
328        | C_layout_typ
329
330
331       See Bigarray.fortran_layout .
332
333
334       type fortran_layout =
335        | Fortran_layout_typ
336
337
338       To facilitate interoperability with existing C and Fortran  code,  this
339       library  supports  two different memory layouts for Bigarrays, one com‐
340       patible with the C conventions, the other compatible with  the  Fortran
341       conventions.
342
343       In  the C-style layout, array indices start at 0, and multi-dimensional
344       arrays are laid out in row-major format.  That  is,  for  a  two-dimen‐
345       sional  array, all elements of row 0 are contiguous in memory, followed
346       by all elements of row 1, etc.  In other terms, the array  elements  at
347       (x,y) and (x, y+1) are adjacent in memory.
348
349       In the Fortran-style layout, array indices start at 1, and multi-dimen‐
350       sional arrays are laid out in column-major  format.   That  is,  for  a
351       two-dimensional  array, all elements of column 0 are contiguous in mem‐
352       ory, followed by all elements of column 1, etc.  In  other  terms,  the
353       array elements at (x,y) and (x+1, y) are adjacent in memory.
354
355       Each  layout style is identified at the type level by the phantom types
356       Bigarray.c_layout and Bigarray.fortran_layout respectively.
357
358
359
360
361   Supported layouts
362       The GADT type 'a layout represents one of the two supported memory lay‐
363       outs:  C-style  or  Fortran-style.  Its constructors are re-exported as
364       values below for backward-compatibility reasons.
365
366       type 'a layout =
367        | C_layout : c_layout layout
368        | Fortran_layout : fortran_layout layout
369
370
371
372
373
374       val c_layout : c_layout layout
375
376
377
378
379       val fortran_layout : fortran_layout layout
380
381
382
383
384
385   Generic arrays (of arbitrarily many dimensions)
386       module Genarray : sig end
387
388
389
390
391
392
393   Zero-dimensional arrays
394       module Array0 : sig end
395
396
397       Zero-dimensional arrays. The Array0 structure provides operations simi‐
398       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
399       zero-dimensional arrays that only contain a single scalar value.  Stat‐
400       ically  knowing  the  number  of  dimensions of the array allows faster
401       operations, and more precise static type-checking.
402
403
404       Since 4.05.0
405
406
407
408
409   One-dimensional arrays
410       module Array1 : sig end
411
412
413       One-dimensional arrays. The Array1 structure provides operations  simi‐
414       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
415       one-dimensional  arrays.   (The  Bigarray.Array2  and   Bigarray.Array3
416       structures   below   provide   operations   specialized  for  two-  and
417       three-dimensional arrays.)  Statically knowing the number of dimensions
418       of  the  array  allows  faster  operations,  and  more  precise  static
419       type-checking.
420
421
422
423
424   Two-dimensional arrays
425       module Array2 : sig end
426
427
428       Two-dimensional arrays. The Array2 structure provides operations  simi‐
429       lar  to  those  of  Bigarray.Genarray  , but specialized to the case of
430       two-dimensional arrays.
431
432
433
434
435   Three-dimensional arrays
436       module Array3 : sig end
437
438
439       Three-dimensional arrays. The Array3 structure provides operations sim‐
440       ilar  to  those  of  Bigarray.Genarray , but specialized to the case of
441       three-dimensional arrays.
442
443
444
445
446   Coercions between generic Bigarrays and fixed-dimension Bigarrays
447       val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b,  'c)  Genar‐
448       ray.t
449
450       Return the generic Bigarray corresponding to the given zero-dimensional
451       Bigarray.
452
453
454       Since 4.05.0
455
456
457
458       val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b,  'c)  Genar‐
459       ray.t
460
461       Return  the generic Bigarray corresponding to the given one-dimensional
462       Bigarray.
463
464
465
466       val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b,  'c)  Genar‐
467       ray.t
468
469       Return  the generic Bigarray corresponding to the given two-dimensional
470       Bigarray.
471
472
473
474       val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b,  'c)  Genar‐
475       ray.t
476
477       Return  the  generic  Bigarray  corresponding to the given three-dimen‐
478       sional Bigarray.
479
480
481
482       val array0_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
483       Array0.t
484
485       Return the zero-dimensional Bigarray corresponding to the given generic
486       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
487       exactly zero dimension.
488
489
490       Since 4.05.0
491
492
493
494       val  array1_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
495       Array1.t
496
497       Return the one-dimensional Bigarray corresponding to the given  generic
498       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
499       exactly one dimension.
500
501
502
503       val array2_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
504       Array2.t
505
506       Return  the two-dimensional Bigarray corresponding to the given generic
507       Bigarray.  Raise Invalid_argument if the generic Bigarray does not have
508       exactly two dimensions.
509
510
511
512       val  array3_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
513       Array3.t
514
515       Return  the  three-dimensional  Bigarray  corresponding  to  the  given
516       generic  Bigarray.  Raise Invalid_argument if the generic Bigarray does
517       not have exactly three dimensions.
518
519
520
521
522   Re-shaping Bigarrays
523       val reshape : ('a, 'b, 'c) Genarray.t -> int  array  ->  ('a,  'b,  'c)
524       Genarray.t
525
526
527       reshape  b  [|d1;...;dN|]  converts  the Bigarray b to a N -dimensional
528       array of dimensions d1 ...  dN .  The returned array and  the  original
529       array  b  share  their  data  and  have the same layout.  For instance,
530       assuming that b is a one-dimensional array of dimension 12,  reshape  b
531       [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4.  If b
532       has C layout, the element (x,y) of b' corresponds to the element x *  3
533       +  y  of  b  .  If b has Fortran layout, the element (x,y) of b' corre‐
534       sponds to the element x + (y - 1) * 4 of b  .   The  returned  Bigarray
535       must  have exactly the same number of elements as the original Bigarray
536       b .  That is, the product of the dimensions of b must be equal to i1  *
537       ... * iN .  Otherwise, Invalid_argument is raised.
538
539
540
541       val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
542
543       Specialized  version  of  Bigarray.reshape for reshaping to zero-dimen‐
544       sional arrays.
545
546
547       Since 4.05.0
548
549
550
551       val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
552
553       Specialized version of Bigarray.reshape  for  reshaping  to  one-dimen‐
554       sional arrays.
555
556
557
558       val  reshape_2  : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
559       Array2.t
560
561       Specialized version of Bigarray.reshape  for  reshaping  to  two-dimen‐
562       sional arrays.
563
564
565
566       val  reshape_3  :  ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
567       'b, 'c) Array3.t
568
569       Specialized version of Bigarray.reshape for reshaping  to  three-dimen‐
570       sional arrays.
571
572
573
574
575
576OCamldoc                          2019-07-30                       Bigarray(3)
Impressum