1 Getting Started {#gettingstarted}
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.
17 # Supported data types {#gettingstarted_datatypes}
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):
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`)
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.
40 If not specified otherwise, `array`s are created as single precision floating
41 point numbers (`f32`).
43 # Creating and populating an ArrayFire array {#getting_started_af_arrays}
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.
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:
54 \snippet test/getting_started.cpp ex_getting_started_constructors
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:
61 \snippet test/getting_started.cpp ex_getting_started_gen
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.
68 ArrayFire `array`s may also be populated from data found on the host.
71 \snippet test/getting_started.cpp ex_getting_started_init
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
77 \snippet test/getting_started.cpp ex_getting_started_dev_ptr
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.
84 # ArrayFire array contents, dimensions, and properties {#getting_started_array_properties}
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.
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:
93 \snippet test/getting_started.cpp ex_getting_started_print
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)
100 \snippet test/getting_started.cpp ex_getting_started_dims
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
107 \snippet test/getting_started.cpp ex_getting_started_prop
109 For further information on these capabilities, we suggest you consult the
110 full documentation on the [array](\ref af::array).
112 # Writing mathematical expressions in ArrayFire {#getting_started_writing_math}
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
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.
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:
132 \snippet test/getting_started.cpp ex_getting_started_arith
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).
138 # Mathematical constants {#getting_started_constants}
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.
145 Constants can be used in all of ArrayFire's functions. Below we demonstrate
146 their use in element selection and a mathematical expression:
148 \snippet test/getting_started.cpp ex_getting_started_constants
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.
154 # Indexing {#getting_started_indexing}
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:
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
170 Please see the [indexing page](\ref indexing) for several examples of how to
173 # Getting access to ArrayFire array memory on the host and device {#getting_started_memory_access}
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:
185 \snippet test/getting_started.cpp ex_getting_started_ptr
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.
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:
194 \snippet test/getting_started.cpp ex_getting_started_scalar
196 # Bitwise operators {#getting_started_bitwise_operators}
198 In addition to supporting standard mathematical functions, arrays
199 that contain integer data types also support bitwise operators including
202 \snippet test/getting_started.cpp ex_getting_started_bit
204 # Using the ArrayFire API in C and C++ {#gettingstarted_api_usage}
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!
209 ## Sample using the C API
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
212 #include <arrayfire.h>
213 // Generate random data and sum and print the result
216 // generate random values
221 // sum all the values
223 af_sum_all(&result, a, 0);
225 printf("sum: %g\n", sum);
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230 ## Sample using the C++ API
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
233 #include <arrayfire.h>
234 // Generate random data, sum and print the result.
237 // Generate 10,000 random values
238 af::array a = af::randu(10000);
240 // Sum the values and copy the result to the CPU:
241 double sum = af::sum<float>(a);
243 printf("sum: %g\n", sum);
246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248 # What to read next? {#getting_started_next_steps}
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
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)
259 # Where to go for help? {#getting_started_help}
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>