1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="manual.css">
<TITLE>
The bigarray library
</TITLE>
</HEAD>
<BODY >
<A HREF="manual042.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual044.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1 CLASS="chapter"><A NAME="htoc261">Chapter 29</A> The bigarray library</H1>
The <TT>bigarray</TT> library implements large, multi-dimensional, numerical
arrays. These arrays are called “big arrays” to distinguish them
from the standard Caml arrays described in
<A HREF="libref/Array.html">Module <TT>Array</TT></A>.
The main differences between “big arrays” and standard Caml arrays
are as follows:
<UL CLASS="itemize"><LI CLASS="li-itemize">
Big arrays are not limited in size, unlike Caml arrays
(<TT>float array</TT> are limited to 2097151 elements on a 32-bit platform,
other <TT>array</TT> types to 4194303 elements).
<LI CLASS="li-itemize">Big arrays are multi-dimensional. Any number of dimensions
between 1 and 16 is supported. In contrast, Caml arrays are
mono-dimensional and require encoding multi-dimensional arrays as
arrays of arrays.
<LI CLASS="li-itemize">Big arrays can only contain integers and floating-point
numbers, while Caml arrays can contain arbitrary Caml data types.
However, big arrays provide more space-efficient storage of integer
and floating-point elements, in particular because they support
“small” types such as single-precision floats and 8 and 16-bit
integers, in addition to the standard Caml types of double-precision
floats and 32 and 64-bit integers.
<LI CLASS="li-itemize">The memory layout of big arrays is entirely compatible with that
of arrays in C and Fortran, allowing large arrays to be passed back
and forth between Caml code and C / Fortran code with no data copying
at all.
<LI CLASS="li-itemize">Big arrays support interesting high-level operations that normal
arrays do not provide efficiently, such as extracting sub-arrays and
“slicing” a multi-dimensional array along certain dimensions, all
without any copying.
</UL>
Programs that use the <TT>bigarray</TT> library must be linked as follows:
<PRE>
ocamlc <I>other options</I> bigarray.cma <I>other files</I>
ocamlopt <I>other options</I> bigarray.cmxa <I>other files</I>
</PRE>
For interactive use of the <TT>bigarray</TT> library, do:
<PRE>
ocamlmktop -o mytop bigarray.cma
./mytop
</PRE>
or (if dynamic linking of C libraries is supported on your platform),
start <TT>ocaml</TT> and type <TT>#load "bigarray.cma";;</TT>.<BR>
<BR>
<H2 CLASS="section"><A NAME="htoc262">29.1</A> Module <TT>Bigarray</TT>: large, multi-dimensional, numerical arrays</H2>
<br><a HREF="libref/Bigarray.html">Module <tt>Bigarray</tt></a>
<BR>
<BR>
<H2 CLASS="section"><A NAME="htoc263">29.2</A> Big arrays in the Caml-C interface</H2>
C stub code that interface C or Fortran code with Caml code, as
described in chapter <A HREF="manual032.html#c:intf-c">18</A>, can exploit big arrays as
follows.<BR>
<BR>
<H3 CLASS="subsection"><A NAME="htoc264">29.2.1</A> Include file</H3>
The include file <TT><caml/bigarray.h></TT> must be included in the C stub
file. It declares the functions, constants and macros discussed
below.<BR>
<BR>
<H3 CLASS="subsection"><A NAME="htoc265">29.2.2</A> Accessing a Caml bigarray from C or Fortran</H3>
If <I>v</I> is a Caml <TT>value</TT> representing a big array, the expression
<TT>Data_bigarray_val(</TT><I>v</I><TT>)</TT> returns a pointer to the data part of the array.
This pointer is of type <TT>void *</TT> and can be cast to the appropriate C
type for the array (e.g. <TT>double []</TT>, <TT>char [][10]</TT>, etc).<BR>
<BR>
Various characteristics of the Caml big array can be consulted from C
as follows:
<BR>
<BR>
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
<TR><TD ALIGN=center NOWRAP><B>C expression</B></TD>
<TD ALIGN=center NOWRAP><B>Returns</B></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>
<TT>Bigarray_val(</TT><I>v</I><TT>)->num_dims</TT></TD>
<TD ALIGN=left NOWRAP>number of dimensions</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>Bigarray_val(</TT><I>v</I><TT>)->dim[</TT><I>i</I><TT>]</TT></TD>
<TD ALIGN=left NOWRAP><I>i</I>-th dimension</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>Bigarray_val(</TT><I>v</I><TT>)->flags & BIGARRAY_KIND_MASK</TT></TD>
<TD ALIGN=left NOWRAP>kind of array elements</TD>
</TR></TABLE></DIV><BR>
<BR>
The kind of array elements is one of the following constants:
<BR>
<BR>
<DIV CLASS="center"><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
<TR><TD ALIGN=center NOWRAP><B>Constant</B></TD>
<TD ALIGN=center NOWRAP><B>Element kind</B></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>
<TT>BIGARRAY_FLOAT32</TT></TD>
<TD ALIGN=left NOWRAP>32-bit single-precision floats</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_FLOAT64</TT></TD>
<TD ALIGN=left NOWRAP>64-bit double-precision floats</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_SINT8</TT></TD>
<TD ALIGN=left NOWRAP>8-bit signed integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_UINT8</TT></TD>
<TD ALIGN=left NOWRAP>8-bit unsigned integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_SINT16</TT></TD>
<TD ALIGN=left NOWRAP>16-bit signed integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_UINT16</TT></TD>
<TD ALIGN=left NOWRAP>16-bit unsigned integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_INT32</TT></TD>
<TD ALIGN=left NOWRAP>32-bit signed integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_INT64</TT></TD>
<TD ALIGN=left NOWRAP>64-bit signed integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_CAML_INT</TT></TD>
<TD ALIGN=left NOWRAP>31- or 63-bit signed integers</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>BIGARRAY_NATIVE_INT</TT></TD>
<TD ALIGN=left NOWRAP>32- or 64-bit (platform-native) integers</TD>
</TR></TABLE></DIV><BR>
<BR>
The following example shows the passing of a two-dimensional big array
to a C function and a Fortran function.
<PRE CLASS="verbatim">
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;
}
</PRE>
<H3 CLASS="subsection"><A NAME="htoc266">29.2.3</A> Wrapping a C or Fortran array as a Caml big array</H3>
A pointer <I>p</I> to an already-allocated C or Fortran array can be
wrapped and returned to Caml as a big array using the <TT>alloc_bigarray</TT>
or <TT>alloc_bigarray_dims</TT> functions.
<UL CLASS="itemize"><LI CLASS="li-itemize">
<TT>alloc_bigarray(</TT><I>kind</I> <TT>|</TT> <I>layout</I>, <I>numdims</I>, <I>p</I>, <I>dims</I><TT>)</TT><BR>
<BR>
Return a Caml big array wrapping the data pointed to by <I>p</I>.
<I>kind</I> is the kind of array elements (one of the <TT>BIGARRAY_</TT>
kind constants above). <I>layout</I> is <TT>BIGARRAY_C_LAYOUT</TT> for an
array with C layout and <TT>BIGARRAY_FORTRAN_LAYOUT</TT> for an array with
Fortran layout. <I>numdims</I> is the number of dimensions in the
array. <I>dims</I> is an array of <I>numdims</I> long integers, giving
the sizes of the array in each dimension.<BR>
<BR>
<LI CLASS="li-itemize"><TT>alloc_bigarray_dims(</TT><I>kind</I> <TT>|</TT> <I>layout</I>, <I>numdims</I>,
<I>p</I>, <TT>(long) </TT><I>dim</I><SUB>1</SUB>, <TT>(long) </TT><I>dim</I><SUB>2</SUB>, ..., <TT>(long) </TT><I>dim<SUB>numdims</SUB></I><TT>)</TT><BR>
<BR>
Same as <TT>alloc_bigarray</TT>, but the sizes of the array in each dimension
are listed as extra arguments in the function call, rather than being
passed as an array.
</UL>
The following example illustrates how statically-allocated C and
Fortran arrays can be made available to Caml.
<PRE CLASS="verbatim">
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);
}
</PRE>
<HR>
<A HREF="manual042.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual044.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
|
