arrayfire.github.io/docs/configuring_environment.htm at master · arrayfire/arrayfire.github.io

History

242 lines (242 loc) · 15.5 KB

Raw

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

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

window.dataLayer = window.dataLayer || [];

function gtag(){dataLayer.push(arguments);}

gtag('js', new Date());

gtag('config', 'UA-130950618-1');

</script>

<title>ArrayFire: Configuring ArrayFire Environment</title>

MathJax.Hub.Config({

extensions: ["tex2jax.js"],

jax: ["input/TeX","output/HTML-CSS"],

});

</script>

DoxygenAwesomeDarkModeToggle.init()

DoxygenAwesomeInteractiveToc.init()

DoxygenAwesomeFragmentCopyButton.init()

</script>

</head>

<body>

<tbody>

</tr>

<td>

<div id="projectbrief">A high-performance general-purpose compute library</div>

</td>

</tr>

<div>

</td>

</div>

</tr>

<tr>

<td>

</td>

</tr>

</tbody>

</table>

</div>

<li><a href="tutorials.htm"><span>Tutorials</span></a></li>

<li><a href="modules.htm"><span>Functions</span></a></li>

<li><a href="releasenotes.htm"><span>Release Notes</span></a></li>

<li><a href="examples.htm"><span>Examples</span></a></li>

</ul>

</div>

</div>

</div>

<div id="splitbar" style="-moz-user-select:none;"

class="ui-resizable-handle">

</div>

/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */

$(document).ready(function(){initNavTree('configuring_environment.htm',''); initResizable(); });

/* @license-end */

</script>

<div class="headertitle"><div class="title">Configuring ArrayFire Environment </div></div>

</div>

<p >This page lists environment and runtime configurations that will help enhance your experience with ArrayFire.</p>

Environment Variables</h1>

<p >The following are useful environment variable that can be used with ArrayFire.</p>

AF_PATH</h2>

<p >This is the path with ArrayFire gets installed, ie. the includes and libs are present in this directory. You can use this variable to add include paths and libraries to your projects.</p>

AF_PRINT_ERRORS</h2>

<p >When AF_PRINT_ERRORS is set to 1, the exceptions thrown are more verbose and detailed. This helps in locating the exact failure.</p>

<div class="fragment"><div class="line">AF_PRINT_ERRORS=1 ./myprogram</div>

</div><h2><a class="anchor" id="af_cuda_default_device"></a>

AF_CUDA_DEFAULT_DEVICE</h2>

<p >Use this variable to set the default CUDA device. Valid values for this variable are the device identifiers shown when <a class="el" href="group__device__func__info.htm#ga3e22b6ff6e0940bb31577bea2863ca27">af::info</a> is run.</p>

<div class="fragment"><div class="line">AF_CUDA_DEFAULT_DEVICE=1 ./myprogram_cuda</div>

</div><h2><a class="anchor" id="af_oneapi_default_device"></a>

AF_ONEAPI_DEFAULT_DEVICE</h2>

<p >Use this variable to set the default oneAPI device. Valid values for this variable are the device identifiers shown when <a class="el" href="group__device__func__info.htm#ga3e22b6ff6e0940bb31577bea2863ca27">af::info</a> is run.</p>

<div class="fragment"><div class="line">AF_ONEAPI_DEFAULT_DEVICE=1 ./myprogram_oneapi</div>

</div><p >Note: <a class="el" href="group__device__func__set.htm#gad7c36828c21e7efc06a067bbc47d8d3b" title="Sets the current device.">af::setDevice</a> call in the source code will take precedence over this variable.</p>

AF_OPENCL_DEFAULT_DEVICE</h2>

<p >Use this variable to set the default OpenCL device. Valid values for this variable are the device identifiers shown when <a class="el" href="group__device__func__info.htm#ga3e22b6ff6e0940bb31577bea2863ca27">af::info</a> is run.</p>

<div class="fragment"><div class="line">AF_OPENCL_DEFAULT_DEVICE=1 ./myprogram_opencl</div>

AF_OPENCL_DEFAULT_DEVICE_TYPE</h2>

<p >Use this variable to set the default OpenCL device type. Valid values for this variable are: CPU, GPU, ACC (Accelerators).</p>

<p >When set, the first device of the specified type is chosen as default device.</p>

<div class="fragment"><div class="line">AF_OPENCL_DEFAULT_DEVICE_TYPE=CPU ./myprogram_opencl</div>

</div><p >Note: <code>AF_OPENCL_DEFAULT_DEVICE</code> and <a class="el" href="group__device__func__set.htm#gad7c36828c21e7efc06a067bbc47d8d3b" title="Sets the current device.">af::setDevice</a> takes precedence over this variable.</p>

AF_OPENCL_DEVICE_TYPE</h2>

<p >Use this variable to only choose OpenCL devices of specified type. Valid values for this variable are:</p>

<ul>

<li>ALL: All OpenCL devices. (Default behavior).</li>

<li>CPU: CPU devices only.</li>

<li>GPU: GPU devices only.</li>

<li>ACC: Accelerator devices only.</li>

</ul>

<p >When set, the remaining OpenCL device types are ignored by the OpenCL backend.</p>

<div class="fragment"><div class="line">AF_OPENCL_DEVICE_TYPE=CPU ./myprogram_opencl</div>

</div><h2><a class="anchor" id="af_opencl_cpu_offload"></a>

AF_OPENCL_CPU_OFFLOAD</h2>

<p >When ArrayFire runs on devices with unified memory with the host (ie. <code>CL_DEVICE_HOST_UNIFIED_MENORY</code> is true for the device) then certain functions are offloaded to run on the CPU using mapped buffers.</p>

<p >ArrayFire takes advantage of fast libraries such as MKL while spending no time copying memory from device to host. The device memory is mapped to a host pointer which can be used in the offloaded functions.</p>

<p >This functionality can be disabled by using the environment variable <code>AF_OPENCL_CPU_OFFLOAD=0</code>.</p>

<p >The default bevaior of this has changed in version 3.4.</p>

<p >Prior to v3.4, CPU Offload functionality was used only when the user set <code>AF_OPENCL_CPU_OFFLOAD=1</code> and disabled otherwise.</p>

<p >From v3.4 onwards, CPU Offload is enabled by default and is disabled only when <code>AF_OPENCL_CPU_OFFLOAD=0</code> is set.</p>

AF_OPENCL_SHOW_BUILD_INFO</h2>

<p >This variable is useful when debuggin OpenCL kernel compilation failures. When this variable is set to 1, and an error occurs during a OpenCL kernel compilation, then the log and kernel are printed to screen.</p>

AF_DISABLE_GRAPHICS</h2>

<p >Setting this variable to 1 will disable window creation when graphics functions are being called. Disabling window creation will disable all other graphics calls at runtime as well.</p>

<p >This is a useful enviornment variable when running code on servers and systems without displays. When graphics calls are run on such machines, they will print warning about window creation failing. To suppress those calls, set this variable.</p>

AF_SYNCHRONOUS_CALLS</h2>

<p >When this environment variable is set to 1, ArrayFire will execute all functions synchronously.</p>

AF_SHOW_LOAD_PATH</h2>

<p >When using the Unified backend, if this variable is set to 1, it will show the path where the ArrayFire backend libraries are loaded from.</p>

<p >If the libraries are loaded from system paths, such as PATH or LD_LIBRARY_PATH etc, then it will print "system path". If the libraries are loaded from other paths, then those paths are shown in full.</p>

AF_MEM_DEBUG</h2>

<p >When AF_MEM_DEBUG is set to 1 (or anything not equal to 0), the caching mechanism in the memory manager is disabled. The device buffers are allocated using native functions as needed and freed when going out of scope.</p>

<p >When the environment variable is not set, it is treated to be zero.</p>

<div class="fragment"><div class="line">AF_MEM_DEBUG=1 ./myprogram</div>

</div><h2><a class="anchor" id="af_trace"></a>

AF_TRACE</h2>

<p >If ArrayFire was built with logging support, this enviornment variable will enable tracing of various modules within ArrayFire. This is a comma separated list of modules to trace. If enabled, ArrayFire will print relevant information to stdout. Currently the following modules are supported:</p>

<ul>

<li>all: All trace outputs</li>

<li>jit: Logs kernel fetch & respective compile options and any errors.</li>

<li>mem: Memory management allocation, free and garbage collection information</li>

<li>platform: Device management information</li>

<li>unified: Unified backend dynamic loading information</li>

</ul>

<p >Tracing displays the information that could be useful when debugging or optimizing your application. Here is how you would use this variable: </p><pre class="fragment">AF_TRACE=mem,unified ./myprogram

</pre><p> This will print information about memory operations such as allocations, deallocations, and garbage collection.</p>

<p >All trace statements printed to the console have a suffix with the following pattern.</p>

<p ><b>[category][Seconds since Epoch][Thread Id][source file relative path] <Message></b></p>

AF_MAX_BUFFERS</h2>

<p >When AF_MAX_BUFFERS is set, this environment variable specifies the maximum number of buffers allocated before garbage collection kicks in.</p>

<p >Please note that the total number of buffers that can exist simultaneously can be higher than this number. This variable tells the garbage collector that it should free any available buffers immediately if the treshold is reached.</p>

<p >When not set, the default value is 1000.</p>

AF_OPENCL_MAX_JIT_LEN</h2>

<p >When set, this environment variable specifies the maximum height of the OpenCL JIT tree after which evaluation is forced.</p>

<p >The default value, as of v3.4, is 50 on OSX, 100 everywhere else. This value was 20 for older versions.</p>

AF_CUDA_MAX_JIT_LEN</h2>

<p >When set, this environment variable specifies the maximum height of the CUDA JIT tree after which evaluation is forced.</p>

<p >The default value, as of v3.4, 100. This value was 20 for older versions.</p>

AF_CPU_MAX_JIT_LEN</h2>

<p >When set, this environment variable specifies the maximum length of the CPU JIT tree after which evaluation is forced.</p>

<p >The default value, as of v3.4, 100. This value was 20 for older versions.</p>

AF_BUILD_LIB_CUSTOM_PATH</h2>

<p >When set, this environment variable specifies a custom path along which the symbol manager will search for dynamic (shared library) backends to load. This is useful for specialized build configurations that use the unified backend and build shared libraries separately.</p>

<p >By default, no additional path will be searched for an empty value.</p>

AF_JIT_KERNEL_TRACE</h2>

<p >When set, this environment variable has to be set to one of the following three values:</p>

<ul>

<li>stdout : generated kernels will be printed to standard output</li>

<li>stderr : generated kernels will be printed to standard error stream</li>

<li>absolute path to a folder on the disk where generated kernels will be stored</li>

</ul>

<p >CUDA backend kernels are stored in files with cu file extension.</p>

<p >OpenCL backend kernels are stored in files with cl file extension.</p>

AF_JIT_KERNEL_CACHE_DIRECTORY</h2>

<p >This variable sets the path to the ArrayFire cache on the filesystem. If set ArrayFire will write the kernels that are compiled at runtime to this directory. If the path is not writeable, the default path is used.</p>

<p >This path is different from AF_JIT_KERNEL_TRACE which stores strings. These kernels will store binaries and the content will be dependent on the backend and platforms used.</p>

<p >The default path is determined in the following order: Unix:</p><ol type="1">

<li>$HOME/.arrayfire</li>

<li>/tmp/arrayfire Windows:</li>

</ol>

<li>ArrayFire application Temp folder(Usually C:\Users\<user_name>\AppData\Local\Temp\ArrayFire) </li>

</ol>

</div></div>

</div>

</div>

<ul>

<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.5 </li>

</ul>

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

configuring_environment.htm

Latest commit

History

configuring_environment.htm

File metadata and controls