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 ar‐
46       rays  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 Bi‐
91       garray.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  ab‐
108       stract 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 ar‐
308       ray 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 Bi‐
311       garrays.   Finally, Bigarrays of kind int8_unsigned_elt can also be ac‐
312       cessed as arrays of characters instead of arrays of small integers,  by
313       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 op‐
404       erations, 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 three-di‐
420       mensional arrays.)  Statically knowing the number of dimensions of  the
421       array allows faster operations, and more precise static type-checking.
422
423
424
425
426   Two-dimensional arrays
427       module Array2 : sig end
428
429
430       Two-dimensional  arrays. The Array2 structure provides operations simi‐
431       lar to those of Bigarray.Genarray , but  specialized  to  the  case  of
432       two-dimensional arrays.
433
434
435
436
437   Three-dimensional arrays
438       module Array3 : sig end
439
440
441       Three-dimensional arrays. The Array3 structure provides operations sim‐
442       ilar to those of Bigarray.Genarray , but specialized  to  the  case  of
443       three-dimensional arrays.
444
445
446
447
448   Coercions between generic Bigarrays and fixed-dimension Bigarrays
449       val  genarray_of_array0  : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
450       ray.t
451
452       Return the generic Bigarray corresponding to the given zero-dimensional
453       Bigarray.
454
455
456       Since 4.05.0
457
458
459
460       val  genarray_of_array1  : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
461       ray.t
462
463       Return the generic Bigarray corresponding to the given  one-dimensional
464       Bigarray.
465
466
467
468       val  genarray_of_array2  : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
469       ray.t
470
471       Return the generic Bigarray corresponding to the given  two-dimensional
472       Bigarray.
473
474
475
476       val  genarray_of_array3  : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
477       ray.t
478
479       Return the generic Bigarray corresponding  to  the  given  three-dimen‐
480       sional Bigarray.
481
482
483
484       val  array0_of_genarray  :  ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
485       ray0.t
486
487       Return the zero-dimensional Bigarray corresponding to the given generic
488       Bigarray.
489
490
491       Since 4.05.0
492
493
494       Raises  Invalid_argument  if the generic Bigarray does not have exactly
495       zero dimension.
496
497
498
499       val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a,  'b,  'c)  Ar‐
500       ray1.t
501
502       Return  the one-dimensional Bigarray corresponding to the given generic
503       Bigarray.
504
505
506       Raises Invalid_argument if the generic Bigarray does not  have  exactly
507       one dimension.
508
509
510
511       val  array2_of_genarray  :  ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
512       ray2.t
513
514       Return the two-dimensional Bigarray corresponding to the given  generic
515       Bigarray.
516
517
518       Raises  Invalid_argument  if the generic Bigarray does not have exactly
519       two dimensions.
520
521
522
523       val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a,  'b,  'c)  Ar‐
524       ray3.t
525
526       Return  the  three-dimensional  Bigarray  corresponding  to  the  given
527       generic Bigarray.
528
529
530       Raises Invalid_argument if the generic Bigarray does not  have  exactly
531       three dimensions.
532
533
534
535
536   Re-shaping Bigarrays
537       val  reshape  :  ('a,  'b,  'c) Genarray.t -> int array -> ('a, 'b, 'c)
538       Genarray.t
539
540
541       reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional ar‐
542       ray of dimensions d1 ...  dN .  The returned array and the original ar‐
543       ray b share their data and have the same layout.  For instance,  assum‐
544       ing  that  b  is  a  one-dimensional  array  of dimension 12, reshape b
545       [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4.  If b
546       has  C layout, the element (x,y) of b' corresponds to the element x * 3
547       + y of b .  If b has Fortran layout, the element  (x,y)  of  b'  corre‐
548       sponds  to  the  element  x + (y - 1) * 4 of b .  The returned Bigarray
549       must have exactly the same number of elements as the original  Bigarray
550       b  .  That is, the product of the dimensions of b must be equal to i1 *
551       ... * iN .  Otherwise, Invalid_argument is raised.
552
553
554
555       val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
556
557       Specialized version of Bigarray.reshape for  reshaping  to  zero-dimen‐
558       sional arrays.
559
560
561       Since 4.05.0
562
563
564
565       val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
566
567       Specialized  version  of  Bigarray.reshape  for reshaping to one-dimen‐
568       sional arrays.
569
570
571
572       val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a,  'b,  'c)
573       Array2.t
574
575       Specialized  version  of  Bigarray.reshape  for reshaping to two-dimen‐
576       sional arrays.
577
578
579
580       val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int ->  int  ->  ('a,
581       'b, 'c) Array3.t
582
583       Specialized  version  of Bigarray.reshape for reshaping to three-dimen‐
584       sional arrays.
585
586
587
588
589
590OCamldoc                          2021-07-22                       Bigarray(3)
Impressum