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
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
226
227
228
229       val float32 : (float, float32_elt) kind
230
231       See Bigarray.char .
232
233
234
235       val float64 : (float, float64_elt) kind
236
237       See Bigarray.char .
238
239
240
241       val complex32 : (Complex.t, complex32_elt) kind
242
243       See Bigarray.char .
244
245
246
247       val complex64 : (Complex.t, complex64_elt) kind
248
249       See Bigarray.char .
250
251
252
253       val int8_signed : (int, int8_signed_elt) kind
254
255       See Bigarray.char .
256
257
258
259       val int8_unsigned : (int, int8_unsigned_elt) kind
260
261       See Bigarray.char .
262
263
264
265       val int16_signed : (int, int16_signed_elt) kind
266
267       See Bigarray.char .
268
269
270
271       val int16_unsigned : (int, int16_unsigned_elt) kind
272
273       See Bigarray.char .
274
275
276
277       val int : (int, int_elt) kind
278
279       See Bigarray.char .
280
281
282
283       val int32 : (int32, int32_elt) kind
284
285       See Bigarray.char .
286
287
288
289       val int64 : (int64, int64_elt) kind
290
291       See Bigarray.char .
292
293
294
295       val nativeint : (nativeint, nativeint_elt) kind
296
297       See Bigarray.char .
298
299
300
301       val char : (char, int8_unsigned_elt) kind
302
303       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
315
316
317       val kind_size_in_bytes : ('a, 'b) kind -> int
318
319
320       kind_size_in_bytes k is the number of bytes used to store an element of
321       type k .
322
323
324       Since 4.03.0
325
326
327
328
329   Array layouts
330       type c_layout =
331        | C_layout_typ
332
333
334       See Bigarray.fortran_layout .
335
336
337       type fortran_layout =
338        | Fortran_layout_typ
339
340
341       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
346       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
352       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
358       Each  layout style is identified at the type level by the phantom types
359       Bigarray.c_layout and Bigarray.fortran_layout respectively.
360
361
362
363
364   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
369       type 'a layout =
370        | C_layout : c_layout layout
371        | Fortran_layout : fortran_layout layout
372
373
374
375
376
377       val c_layout : c_layout layout
378
379
380
381
382       val fortran_layout : fortran_layout layout
383
384
385
386
387
388   Generic arrays (of arbitrarily many dimensions)
389       module Genarray : sig end
390
391
392
393
394
395
396   Zero-dimensional arrays
397       module Array0 : sig end
398
399
400       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
406
407       Since 4.05.0
408
409
410
411
412   One-dimensional arrays
413       module Array1 : sig end
414
415
416       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
424
425
426
427   Two-dimensional arrays
428       module Array2 : sig end
429
430
431       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
435
436
437
438   Three-dimensional arrays
439       module Array3 : sig end
440
441
442       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
446
447
448
449   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
453       Return the generic Bigarray corresponding to the given zero-dimensional
454       Bigarray.
455
456
457       Since 4.05.0
458
459
460
461       val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b,  'c)  Genar‐
462       ray.t
463
464       Return  the generic Bigarray corresponding to the given one-dimensional
465       Bigarray.
466
467
468
469       val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b,  'c)  Genar‐
470       ray.t
471
472       Return  the generic Bigarray corresponding to the given two-dimensional
473       Bigarray.
474
475
476
477       val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b,  'c)  Genar‐
478       ray.t
479
480       Return  the  generic  Bigarray  corresponding to the given three-dimen‐
481       sional Bigarray.
482
483
484
485       val array0_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
486       Array0.t
487
488       Return the zero-dimensional Bigarray corresponding to the given generic
489       Bigarray.
490
491
492       Since 4.05.0
493
494
495       Raises Invalid_argument if the generic Bigarray does not  have  exactly
496       zero dimension.
497
498
499
500       val  array1_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
501       Array1.t
502
503       Return the one-dimensional Bigarray corresponding to the given  generic
504       Bigarray.
505
506
507       Raises  Invalid_argument  if the generic Bigarray does not have exactly
508       one dimension.
509
510
511
512       val array2_of_genarray : ('a,  'b,  'c)  Genarray.t  ->  ('a,  'b,  'c)
513       Array2.t
514
515       Return  the two-dimensional Bigarray corresponding to the given generic
516       Bigarray.
517
518
519       Raises Invalid_argument if the generic Bigarray does not  have  exactly
520       two dimensions.
521
522
523
524       val  array3_of_genarray  :  ('a,  'b,  'c)  Genarray.t  -> ('a, 'b, 'c)
525       Array3.t
526
527       Return  the  three-dimensional  Bigarray  corresponding  to  the  given
528       generic Bigarray.
529
530
531       Raises  Invalid_argument  if the generic Bigarray does not have exactly
532       three dimensions.
533
534
535
536
537   Re-shaping Bigarrays
538       val reshape : ('a, 'b, 'c) Genarray.t -> int  array  ->  ('a,  'b,  'c)
539       Genarray.t
540
541
542       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
554
555
556       val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
557
558       Specialized  version  of  Bigarray.reshape for reshaping to zero-dimen‐
559       sional arrays.
560
561
562       Since 4.05.0
563
564
565
566       val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
567
568       Specialized version of Bigarray.reshape  for  reshaping  to  one-dimen‐
569       sional arrays.
570
571
572
573       val  reshape_2  : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
574       Array2.t
575
576       Specialized version of Bigarray.reshape  for  reshaping  to  two-dimen‐
577       sional arrays.
578
579
580
581       val  reshape_3  :  ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
582       'b, 'c) Array3.t
583
584       Specialized version of Bigarray.reshape for reshaping  to  three-dimen‐
585       sional arrays.
586
587
588
589
590
591OCamldoc                          2020-09-01                       Bigarray(3)
Impressum