Class NMathConfiguration provides properties for controlling the loading of the NMath kernel assembly and
native library, and specifying license keys.
Setting Properties
Property values can be set three ways: by environment variable, configuration setting, and programmatically.
Settings are applied in that order, and resetting a property takes precedent over any earlier values.
For example, here an environment variable is used:
NMATH_NATIVE_LOCATION="C:\tmp"
This code uses an application configuration file:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<appSettings>
<add key="NMathNativeLocation" value="C:\tmp" />
</appSettings>
</configuration>
Configuration settings may also be placed in a DLL configuration file placed next to the main NMath assembly
(NMath.DLL.config, for example). If a setting is specified in both a DLL and an application configuration file,
the application configuration takes precedence.
This code accomplishes the same thing programmatically:
NMathConfiguration.NativeLocation = @"C:\tmp";
The supported property names, configuration app setting keys, and environment variables
are show below.
Property or Method | Configuration App Setting | Environment Variable |
---|
LicenseKey | NMathLicenseKey | NMATH_LICENSE_KEY |
NativeLocation | NMathNativeLocation | NMATH_NATIVE_LOCATION |
LogFilename | NMathLogFilename | NMATH_LOG_FILENAME |
LogLocation | NMathLogLocation | NMATH_LOG_LOCATION |
LogVerbose | NMathLogVerbose | NMATH_LOG_VERBOSE |
SetMKLNumThreads() | NMathMKLNumThreads | NMATH_MKL_NUM_THREADS |
Reproducibility | NMathReproducibility | NMATH_REPRODUCIBILITY |
Logging
To debug configuration issues, specify a log file location. For example, setting the property programmatically:
NMathConfiguration.LogLocation = @"C:\tmp";
Setting a log file location turns on logging at that location, using the currently defined
log filename (
NMathConfiguration.log, unless previously modified).
For verbose logging, such as all native function calls, set
NMathConfiguration.LogVerbose = true.
Initialization
Assembly loading and license checking is normally performed the first time you make an NMath call. If you wish
to explicitly control when these operations occur--at application start-up, for example--use the static
NMathConfiguration.Init() method.
Licenses
You can specify your NMath license key using the
LicenseKey property. If so, any keys in the registry
are ignored.
Kernel Loading
The name of the NMath kernel assembly is determined by your platform (x86 or x64). The search order is the same as for
the common language runtime: first the GAC is searched, then the directory containing the currently executing
assembly, and so on. Check the log file for details of the search path.
Native Loading
The name of the NMath kernel assembly is determined by your platform (x86 or x64). The search order is determined from
your PATH. Some standard locations are automatically prepended to your (process-specific) PATH. You can
also use the
NativeLocation property to prepend another location.
MKL Threading Control
MKL contains highly optimized, extensively threaded math routines. In rare cases, these can cause conflicts
between the Intel OMP threading library (libiomp5md.dll) and the .NET threading model.
If your .NET application is itself highly multi-threaded, you may wish to use MKL in single-threaded
mode. Set the suggested number of threads to 1 using the SetMKLNumThreads() method, or use the equivalent
environment variable or app config setting.
Note: MKL does not always have a choice on the number of threads for certain reasons, such as system
resources. Although Intel MKL may actually use a different number of threads from the number
suggested, this method enables you to instruct the library to try using the suggested number when
the number used in the calling application is unavailable.
MKL Conditional Numerical Reproducibility (CNR)
For general single and double precision IEEE floating-point math, the order of computation matters. For example,
in infinite precision arithmetic, the associative property holds, (a+b)+c = a+(b+c), but on a computer
using double precision floating-point numbers, rounding error is introduced, and the equality is not guaranteed.
The order of floating-point operations within a single executable program is affected by code-path
selection based on a variety of factors: run-time processor dispatching, data array alignment, variation in number
of threads, threaded algorithms, and so forth.
If strict reproducibility is a requirement, set the Reproducibility property equal to true,
or use the equivalent environment variable or app config setting. You must also
set the suggested number of MKL threads to a constant value--see SetMKLNumThreads().
For more information, see
https://software.intel.com/en-us/articles/introduction-to-the-conditional-numerical-reproducibility-cnr
NOTE: Using MKL Conditional Numerical Reproducibility can significantly degrade performance, and is
only recommended for use during testing or debugging, such as comparison to previous ‘gold’ results.