/build/arrayfire/src/arrayfire-full-3.6.1/docs/pages/configuring_arrayfire_environment.md
Go to the documentation of this file.
1 Configuring ArrayFire Environment {#configuring_environment}
2 ===============================================================================
3 
4 This page lists environment and runtime configurations that will help enhance
5 your experience with ArrayFire.
6 
7 [TOC]
8 
9 Environment Variables{#environment_variables}
10 ===============================================================================
11 
12 The following are useful environment variable that can be used with ArrayFire.
13 
14 AF_PATH {#af_path}
15 -------------------------------------------------------------------------------
16 
17 This is the path with ArrayFire gets installed, ie. the includes and libs are
18 present in this directory. You can use this variable to add include paths and
19 libraries to your projects.
20 
21 AF_PRINT_ERRORS {#af_print_errors}
22 -------------------------------------------------------------------------------
23 
24 When AF_PRINT_ERRORS is set to 1, the exceptions thrown are more verbose and
25 detailed. This helps in locating the exact failure.
26 
27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28 AF_PRINT_ERRORS=1 ./myprogram
29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30 
31 AF_CUDA_DEFAULT_DEVICE {#af_cuda_default_device}
32 -------------------------------------------------------------------------------
33 
34 Use this variable to set the default CUDA device. Valid values for this
35 variable are the device identifiers shown when af::info is run.
36 
37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38 AF_CUDA_DEFAULT_DEVICE=1 ./myprogram_cuda
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 
41 Note: af::setDevice call in the source code will take precedence over this
42 variable.
43 
44 AF_OPENCL_DEFAULT_DEVICE {#af_opencl_default_device}
45 -------------------------------------------------------------------------------
46 
47 Use this variable to set the default OpenCL device. Valid values for this
48 variable are the device identifiers shown when af::info is run.
49 
50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51 AF_OPENCL_DEFAULT_DEVICE=1 ./myprogram_opencl
52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53 
54 Note: af::setDevice call in the source code will take precedence over this
55 variable.
56 
57 AF_OPENCL_DEFAULT_DEVICE_TYPE {#af_opencl_default_device_type}
58 -------------------------------------------------------------------------------
59 
60 Use this variable to set the default OpenCL device type. Valid values for this
61 variable are: CPU, GPU, ACC (Accelerators).
62 
63 When set, the first device of the specified type is chosen as default device.
64 
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 AF_OPENCL_DEFAULT_DEVICE_TYPE=CPU ./myprogram_opencl
67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68 
69 Note: `AF_OPENCL_DEFAULT_DEVICE` and af::setDevice takes precedence over this variable.
70 
71 AF_OPENCL_DEVICE_TYPE {#af_opencl_device_type}
72 -------------------------------------------------------------------------------
73 
74 Use this variable to only choose OpenCL devices of specified type. Valid values for this
75 variable are:
76 
77 - ALL: All OpenCL devices. (Default behavior).
78 - CPU: CPU devices only.
79 - GPU: GPU devices only.
80 - ACC: Accelerator devices only.
81 
82 When set, the remaining OpenCL device types are ignored by the OpenCL backend.
83 
84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 AF_OPENCL_DEVICE_TYPE=CPU ./myprogram_opencl
86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87 
88 AF_OPENCL_CPU_OFFLOAD {#af_opencl_cpu_offload}
89 -------------------------------------------------------------------------------
90 
91 When ArrayFire runs on devices with unified memory with the host (ie.
92 `CL_DEVICE_HOST_UNIFIED_MENORY` is true for the device) then certain functions
93 are offloaded to run on the CPU using mapped buffers.
94 
95 ArrayFire takes advantage of fast libraries such as MKL while spending no time
96 copying memory from device to host. The device memory is mapped to a host
97 pointer which can be used in the offloaded functions.
98 
99 This functionality can be disabled by using the environment variable
100 `AF_OPENCL_CPU_OFFLOAD=0`.
101 
102 The default bevaior of this has changed in version 3.4.
103 
104 Prior to v3.4, CPU Offload functionality was used only when the user set
105 `AF_OPENCL_CPU_OFFLOAD=1` and disabled otherwise.
106 
107 From v3.4 onwards, CPU Offload is enabled by default and is disabled only when
108 `AF_OPENCL_CPU_OFFLOAD=0` is set.
109 
110 AF_OPENCL_SHOW_BUILD_INFO {#af_opencl_show_build_info}
111 -------------------------------------------------------------------------------
112 
113 This variable is useful when debuggin OpenCL kernel compilation failures. When
114 this variable is set to 1, and an error occurs during a OpenCL kernel
115 compilation, then the log and kernel are printed to screen.
116 
117 AF_DISABLE_GRAPHICS {#af_disable_graphics}
118 -------------------------------------------------------------------------------
119 
120 Setting this variable to 1 will disable window creation when graphics
121 functions are being called. Disabling window creation will disable all other
122 graphics calls at runtime as well.
123 
124 This is a useful enviornment variable when running code on servers and systems
125 without displays. When graphics calls are run on such machines, they will
126 print warning about window creation failing. To suppress those calls, set this
127 variable.
128 
129 AF_SYNCHRONOUS_CALLS {#af_synchronous_calls}
130 -------------------------------------------------------------------------------
131 
132 When this environment variable is set to 1, ArrayFire will execute all
133 functions synchronously.
134 
135 AF_SHOW_LOAD_PATH {#af_show_load_path}
136 -------------------------------------------------------------------------------
137 
138 When using the Unified backend, if this variable is set to 1, it will show the
139 path where the ArrayFire backend libraries are loaded from.
140 
141 If the libraries are loaded from system paths, such as PATH or LD_LIBRARY_PATH
142 etc, then it will print "system path". If the libraries are loaded from other
143 paths, then those paths are shown in full.
144 
145 AF_MEM_DEBUG {#af_mem_debug}
146 -------------------------------------------------------------------------------
147 
148 When AF_MEM_DEBUG is set to 1 (or anything not equal to 0), the caching
149 mechanism in the memory manager is disabled. The device buffers are allocated
150 using native functions as needed and freed when going out of scope.
151 
152 When the environment variable is not set, it is treated to be zero.
153 
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155 AF_MEM_DEBUG=1 ./myprogram
156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157 
158 AF_TRACE {#af_trace}
159 -------------------------------------------------------------------------------
160 
161 If ArrayFire was built with logging support, this enviornment variable will
162 enable tracing of various modules within ArrayFire. This is a comma separated
163 list of modules to trace. If enabled, ArrayFire will print relevant information
164 to stdout. Currently the following modules are supported:
165 
166 - all: All trace outputs
167 - mem: Memory management allocation, free and garbage collection information
168 - unified: Unified backend dynamic loading information
169 
170 Tracing displays the information that could be useful when debugging or
171 optimizing your application. Here is how you would use this variable:
172 
173  AF_TRACE=mem:unified ./myprogram
174 
175 This will print information about memory operations such as allocations,
176 deallocations, and garbage collection.
177 
178 
179 AF_MAX_BUFFERS {#af_max_buffers}
180 -------------------------------------------------------------------------
181 
182 When AF_MAX_BUFFERS is set, this environment variable specifies the maximum
183 number of buffers allocated before garbage collection kicks in.
184 
185 Please note that the total number of buffers that can exist simultaneously can
186 be higher than this number. This variable tells the garbage collector that it
187 should free any available buffers immediately if the treshold is reached.
188 
189 When not set, the default value is 1000.
190 
191 AF_OPENCL_MAX_JIT_LEN {#af_opencl_max_jit_len}
192 -------------------------------------------------------------------------------
193 
194 When set, this environment variable specifies the maximum height of the OpenCL
195 JIT tree after which evaluation is forced.
196 
197 The default value, as of v3.4, is 50 on OSX, 100 everywhere else. This value was
198 20 for older versions.
199 
200 AF_CUDA_MAX_JIT_LEN {#af_cuda_max_jit_len}
201 -------------------------------------------------------------------------------
202 
203 When set, this environment variable specifies the maximum height of the CUDA JIT
204 tree after which evaluation is forced.
205 
206 The default value, as of v3.4, 100. This value was 20 for older versions.
207 
208 AF_CPU_MAX_JIT_LEN {#af_cpu_max_jit_len}
209 -------------------------------------------------------------------------------
210 
211 When set, this environment variable specifies the maximum length of the CPU JIT
212 tree after which evaluation is forced.
213 
214 The default value, as of v3.4, 100. This value was 20 for older versions.