/build/arrayfire/src/arrayfire-full-3.6.1/docs/pages/getting_started.md
Go to the documentation of this file.
1 Getting Started {#gettingstarted}
2 ===============
3 
4 [TOC]
5 
6 # Introduction
7 
8 ArrayFire is a high performance software library for parallel computing with
9 an easy-to-use API. ArrayFire abstracts away much of the details of
10 programming parallel architectures by providing a high-level container object,
11 the [array](\ref af::array), that represents data stored on a CPU, GPU, FPGA,
12 or other type of accelerator. This abstraction permits developers to write
13 massively parallel applications in a high-level language where they need
14 not be concerned about low-level optimizations that are frequently required to
15 achieve high throughput on most parallel architectures.
16 
17 # Supported data types {#gettingstarted_datatypes}
18 
19 ArrayFire provides one generic container object, the [array](\ref af::array)
20 on which functions and mathematical operations are performed. The `array`
21 can represent one of many different [basic data types](\ref af::af_dtype):
22 
23 * [f32](\ref f32) real single-precision (`float`)
24 * [c32](\ref c32) complex single-precision (`cfloat`)
25 * [f64](\ref f64) real double-precision (`double`)
26 * [c64](\ref c64) complex double-precision (`cdouble`)
27 * [b8](\ref b8) 8-bit boolean values (`bool`)
28 * [s32](\ref s32) 32-bit signed integer (`int`)
29 * [u32](\ref u32) 32-bit unsigned integer (`unsigned`)
30 * [u8](\ref u8) 8-bit unsigned values (`unsigned char`)
31 * [s64](\ref s64) 64-bit signed integer (`intl`)
32 * [u64](\ref u64) 64-bit unsigned integer (`uintl`)
33 * [s16](\ref s16) 16-bit signed integer (`short`)
34 * [u16](\ref u16) 16-bit unsigned integer (`unsigned short`)
35 
36 Most of these data types are supported on all modern GPUs; however, some
37 older devices may lack support for double precision arrays. In this case,
38 a runtime error will be generated when the array is constructed.
39 
40 If not specified otherwise, `array`s are created as single precision floating
41 point numbers (`f32`).
42 
43 # Creating and populating an ArrayFire array {#getting_started_af_arrays}
44 
45 ArrayFire [array](\ref af::array)s represent memory stored on the device.
46 As such, creation and population of an array will consume memory on the device
47 which cannot freed until the `array` object goes out of scope. As device memory
48 allocation can be expensive, ArrayFire also includes a memory manager which
49 will re-use device memory whenever possible.
50 
51 Arrays can be created using one of the [array constructors](\ref #construct_mat).
52 Below we show how to create 1D, 2D, and 3D arrays with uninitialized values:
53 
54 \snippet test/getting_started.cpp ex_getting_started_constructors
55 
56 However, uninitialized memory is likely not useful in your application.
57 ArrayFire provides several convenient functions for creating arrays that contain
58 pre-populated values including constants, uniform random numbers, uniform
59 normally distributed numbers, and the identity matrix:
60 
61 \snippet test/getting_started.cpp ex_getting_started_gen
62 
63 A complete list of ArrayFire functions that automatically generate data
64 on the device may be found on the [functions to create arrays](\ref data_mat)
65 page. As stated above, the default data type for arrays is [f32](\ref f32) (a
66 32-bit floating point number) unless specified otherwise.
67 
68 ArrayFire `array`s may also be populated from data found on the host.
69 For example:
70 
71 \snippet test/getting_started.cpp ex_getting_started_init
72 
73 ArrayFire also supports array initialization from memory already on the GPU.
74 For example, with CUDA one can populate an `array` directly using a call
75 to `cudaMemcpy`:
76 
77 \snippet test/getting_started.cpp ex_getting_started_dev_ptr
78 
79 Similar functionality exists for OpenCL too. If you wish to intermingle
80 ArrayFire with CUDA or OpenCL code, we suggest you consult the
81 [CUDA interoperability](\ref interop_cuda) or
82 [OpenCL interoperability](\ref interop_opencl) pages for detailed instructions.
83 
84 # ArrayFire array contents, dimensions, and properties {#getting_started_array_properties}
85 
86 ArrayFire provides several functions to determine various aspects of arrays.
87 This includes functions to print the contents, query the dimensions, and
88 determine various other aspects of arrays.
89 
90 The [af_print](\ref af::af_print) function can be used to print arrays that
91 have already been generated or any expression involving arrays:
92 
93 \snippet test/getting_started.cpp ex_getting_started_print
94 
95 The dimensions of an array may be determined using either a
96 [dim4](\ref af::dim4) object or by accessing the dimensions directly using the
97 [dims()](\ref af::array::dims) and [numdims()](\ref af::array::numdims)
98 functions:
99 
100 \snippet test/getting_started.cpp ex_getting_started_dims
101 
102 In addition to dimensions, arrays also carry several properties including
103 methods to determine the underlying type and size (in bytes). You can even
104 determine whether the array is empty, real/complex, a row/column, or a scalar
105 or a vector:
106 
107 \snippet test/getting_started.cpp ex_getting_started_prop
108 
109 For further information on these capabilities, we suggest you consult the
110 full documentation on the [array](\ref af::array).
111 
112 # Writing mathematical expressions in ArrayFire {#getting_started_writing_math}
113 
114 ArrayFire features an intelligent Just-In-Time (JIT) compilation engine that
115 converts expressions using arrays into the smallest number of CUDA/OpenCL
116 kernels. For most operations on arrays, ArrayFire functions like a vector library.
117 That means that an element-wise operation, like `c[i] = a[i] + b[i]` in C,
118 would be written more concisely without indexing, like `c = a + b`.
119 When there are multiple expressions involving arrays, ArrayFire's JIT engine
120 will merge them together. This "kernel fusion" technology not only decreases
121 the number of kernel calls, but, more importantly, avoids extraneous global
122 memory operations.
123 Our JIT functionality extends across C/C++ function boundaries and only ends
124 when a non-JIT function is encountered or a synchronization operation is
125 explicitly called by the code.
126 
127 ArrayFire provides [hundreds of functions](\ref arith_mat) for element-wise
128 operations. All of the standard operators (e.g. +,-,\*,/) are supported
129 as are most transcendental functions (sin, cos, log, sqrt, etc.).
130 Here are a few examples:
131 
132 \snippet test/getting_started.cpp ex_getting_started_arith
133 
134 To see the complete list of functions please consult the documentation on
135 [mathematical](\ref mathfunc_mat), [linear algebra](\ref linalg_mat),
136 [signal processing](\ref signal_mat), and [statistics](\ref stats_mat).
137 
138 # Mathematical constants {#getting_started_constants}
139 
140 ArrayFire contains several platform-independent constants, like
141 [Pi](\ref af::Pi), [NaN](\ref af::NaN), and [Inf](\ref af::Inf).
142 If ArrayFire does not have a constant you need, you can create your own
143 using the [af::constant](\ref af::constant) array constructor.
144 
145 Constants can be used in all of ArrayFire's functions. Below we demonstrate
146 their use in element selection and a mathematical expression:
147 
148 \snippet test/getting_started.cpp ex_getting_started_constants
149 
150 Please note that our constants may, at times, conflict with macro definitions
151 in standard header files. When this occurs, please refer to our constants
152 using the `af::` namespace.
153 
154 # Indexing {#getting_started_indexing}
155 
156 Like all functions in ArrayFire, indexing is also executed in parallel on
157 the OpenCL/CUDA device.
158 Because of this, indexing becomes part of a JIT operation and is accomplished
159 using parentheses instead of square brackets (i.e. as `A(0)` instead of `A[0]`).
160 To index `af::array`s you may use one or a combination of the following functions:
161 
162 * integer scalars
163 * [seq()](\ref af::seq) representing a linear sequence
164 * [end](\ref af::end) representing the last element of a dimension
165 * [span](\ref af::span) representing the entire dimension
166 * [row(i)](\ref af::array::row) or [col(i)](\ref af::array::col) specifying a single row/column
167 * [rows(first,last)](\ref af::array::rows) or [cols(first,last)](\ref af::array::cols)
168  specifying a span of rows or columns
169 
170 Please see the [indexing page](\ref indexing) for several examples of how to
171 use these functions.
172 
173 # Getting access to ArrayFire array memory on the host and device {#getting_started_memory_access}
174 
175 Memory in `af::array`s may be accessed using the [host()](\ref af::array::host)
176 and [device()](\ref af::array::device) functions.
177 The `host` function *copies* the data from the device and makes it available
178 in a C-style array on the host. As such, it is up to the developer to manage
179 any memory returned by `host`.
180 The `device` function returns a pointer/reference to device memory for
181 interoperability with external CUDA/OpenCL kernels. As this memory belongs to
182 ArrayFire, the programmer should not attempt to free/deallocate the pointer.
183 For example, here is how we can interact with both OpenCL and CUDA:
184 
185 \snippet test/getting_started.cpp ex_getting_started_ptr
186 
187 ArrayFire also provides several helper functions for creating `af::array`s from
188 OpenCL `cl_mem` references and `cl::Buffer` objects. See the `include/af/opencl.h`
189 file for further information.
190 
191 Lastly, if you want only the first value from an `af::array` you can use
192 get it using the [scalar()](\ref af::array::scalar) function:
193 
194 \snippet test/getting_started.cpp ex_getting_started_scalar
195 
196 # Bitwise operators {#getting_started_bitwise_operators}
197 
198 In addition to supporting standard mathematical functions, arrays
199 that contain integer data types also support bitwise operators including
200 and, or, and shift:
201 
202 \snippet test/getting_started.cpp ex_getting_started_bit
203 
204 # Using the ArrayFire API in C and C++ {#gettingstarted_api_usage}
205 
206 The ArrayFire API is wrapped into a unified C/C++ header. To use the library
207 simply include the `arrayfire.h` header file and start coding!
208 
209 ## Sample using the C API
210 
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
212  #include <arrayfire.h>
213  // Generate random data and sum and print the result
214  int main(void)
215  {
216  // generate random values
217  int n = 10000;
218  af_array a;
219  af_randu(&a, n);
220 
221  // sum all the values
222  float result;
223  af_sum_all(&result, a, 0);
224 
225  printf("sum: %g\n", sum);
226  return 0;
227  }
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229 
230 ## Sample using the C++ API
231 
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
233  #include <arrayfire.h>
234  // Generate random data, sum and print the result.
235  int main(void)
236  {
237  // Generate 10,000 random values
238  af::array a = af::randu(10000);
239 
240  // Sum the values and copy the result to the CPU:
241  double sum = af::sum<float>(a);
242 
243  printf("sum: %g\n", sum);
244  return 0;
245  }
246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
247 
248 # What to read next? {#getting_started_next_steps}
249 
250 Now that you have a general introduction to ArrayFire, where do you go from
251 here? In particular you might find these documents useful
252 
253 * [Building an ArrayFire program on Linux](\ref using_on_linux)
254 * [Building an Arrayfire program on Windows](\ref using_on_windows)
255 * [Timing ArrayFire code](\ref timing)
256 
257 
258 
259 # Where to go for help? {#getting_started_help}
260 
261 * Google Groups: https://groups.google.com/forum/#!forum/arrayfire-users
262 * ArrayFire Services: [Consulting](http://arrayfire.com/consulting/) | [Support](http://arrayfire.com/support/) | [Training](http://arrayfire.com/training/)
263 * ArrayFire Blogs: http://arrayfire.com/blog/
264 * Email: <mailto:technical@arrayfire.com>