ILNumerics Accelerator - Configuration
It is one key feature of the ILNumerics Accelerator compiler to release the programmer from as many decisions as possible. In most cases it will be more efficient (i.e.: bring faster results) if the compiler is left at its default values. However, compilation at the various stages can be controlled to some degree. Configuration is split into two parts: configuration controlling the compilation at development time and configuration of runtime behavior.
Development Time Configuration
This controls how ILNumerics Accelerator handles your code. Settings are made by simple control instructions, embedded into your code as comments. The general syntax of a control instruction is:
ILN(name = value [, name = value, ... ])
Names are not case sensitive.
| Name | Description | Allowed Values | Default |
|---|---|---|---|
| enabled | enables / disables code acceleration | true, false | depends on project configuration: <ILNAcceleratorEnabled> and <ILNALocalEnabled> |
| settingprefix | reconfigures the prefix identifying configuration expressions | [a-zA-Z]+ (any string of 1 or more non-control, non-whitespace ASCII characters) | ILN |
| saturateIntegerOps | whether or not the result of integer operations are clamped to the limits of the corresponding element data type. (Introduced in v7.0-beta02) |
auto: depends on Settings.ArrayStyle (true for ILNumericsV4/Matlab style, false for numpy style), true: integer operations are always clamped, preventing potential overflow - regardless of the currently active array style, false: integer operations are never clamped, potentially causing integer overflow. |
auto |
| BinLoggingEnabled |
Enables / disables the creation of binary logs. This affects the creation of segments code only. Is does not enable / disable the writing of a log! |
true: during execution ILNumerics Accelerator creates a log (if configured). Segments contain all instructions for generating and logging all required information, false: segments save some (small) overhead for logging. Binary logs created nevertheless may not contain enough information for debugging. |
true |
Compiler settings have file scope and are read from each code file individually; from the first character at the start of the file to the last character at file end. A control setting is valid for any array instruction found after the control settings location. Note, that program flow due to jump or loop instructions is not considered here. The value set remains valid until another control setting in the file changes the value again or the end of the file is reached.
The 'settingprefix' setting allows to substitute the 'ILN' default identifier marking the begin of a control setting. This can be useful for code generators and testing scenarios.
Settings within disabled code regions '#if' or '#else' are not considered by the compiler. This allows for testing and profiling in more demanding scenarios.
Project-wide Configuration
The following parameters can be applied to the project (csproj, msbuild XML) file. They control the general behavior of the ILNumerics Accelerator compiler:
| Name | Description | Allowed Values | Default Value |
|---|---|---|---|
| <ILNAServiceURI> | Locates the ILNumerics Accelerator compiler service to be used during build. | Valid uri of the Accelerator compiler service. Example: <ILNAServiceURI> http://localhost:5000 </ILNAServiceURI> | (not specified: cloud service on https://ilnumerics.net) |
| <ILNAcceleratorEnabled> | Enable / disable the ILNumerics Accelerator compiler for the project. | True: include the ILNumerics Accelerator in Build steps. False: do not use ILNumerics Accelerator for building. (same effect as removing the package) | Unspecified: Depends on configuration. (Debug: false, Release: true) |
| <ILNALocalEnabled> | Initial setting for the 'enabled' property in each code file. | True: all array instructions are optimized unless explicitly otherwise configured. False: optimizations must be explicitly enabled via configuration comments (see above) for selected regions in each code file. | False |
Runtime Configuration
At runtime and before a segment is executed ILNumerics Accelerator prepares the segment for execution. Therefore, many information is considered from the data and hardware context. This process is configurable to a large extent.
However, the Accelerator is designed to perform unguided optimization. Hence, the configuration of these parameters commonly decrease compatibility, potentially hurt performance and should be left for experts and rare situations only.
Having said that, in the beta phase and until all optimizations are implemented it might pay off to make use of some of the configuration options. Keep in mind that in a later version you may remove this configuration and give control back to ILNumerics Accelerator.
In order to configure a runtime setting, use the members of the static instance of ILNumerics.Segment.Default:
Configuration Scope
Runtime settings are configured as part of the regular program flow. The scope of such configurations is not limited. Settings to the Default instance remain valid until another setting changes the value or until the program exits. Most settings can be cleared to have the compiler determine the best value automatically (value null) or Default.
A runtime configuration is valid for the current thread only.
|
Name (Segment.Default.[..?]) |
Description | Allowed Values | Default |
|---|---|---|---|
| DevideID |
The device id to execute the next segment(s). The list of devices can be obtained from: ILNumerics.Core.DeviceManagement.GetDevices(). Device id 0 is reserved to the host device (CLR) and is always available. |
0, [existing device ID] | null (auto) Beta: 0 (CLR) |
| SpecializeFlags | Level of specialization for compiling low-level kernel codes. More specializied parameters may lead to longer kernel compile times at the first run but may increase performance for non-varying inputs. | Default, BSDsAll | Default |