NMath User's Guide

TOC | Previous | Next | Index

1.5 NMath Configuration (.NET, C#, CSharp, VB, Visual Basic, F#)

NMath configuration settings govern the loading of the NMath license key and native library.

Property values can be set three ways:

1. by environment variable

2. by configuration setting

3. by programmatically setting properties on class NMathConfiguration

NOTE—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:\temp"

This code uses an application configuration file:



<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="NMathNativeLocation" value="C:\temp" />
  </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:\temp";

The supported environment variables, configuration app setting keys, and property names are show in Table 1.

Table 1 – Configuration Properties

Environment Variable

Configuration Setting

Property or Method

NMATH_LOG_FILENAME

NMathLogFilename

LogFilename

NMATH_LOG_LOCATION

NMathLogLocation

LogLocation

NMATH_LICENSE_KEY

NMathLicenseKey

LicenseKey

NMATH_NATIVE_LOCATION

NMathNativeLocation

NativeLocation

NMATH_MKL_NUM_THREADS

NMathMKLNumThreads

SetMKLNumThreads()

NMATH_REPRODUCIBILITY

NMathReproducibility

Reproducibility

NOTE—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.

Logging

To debug configuration issues, specify a log file location. For example, setting the property programmatically:



NMathConfiguration.LogLocation = @"C:\temp";

NOTE—The specified location must exist.

Setting a log file location turns on logging at that location, using the currently defined log filename (NMathConfiguration.log, unless previously modified).

To turn off logging, set the log location to null.

For verbose logging, such as all native function calls, set NMathConfiguration.LogVerbose to true.

License Key

You can specify your NMath license key using the NMathConfiguration.LicenseKey property, or the equivalent environment variable or app config setting.

Native Location

The NMath native libraries must be found at runtime (Section 1.3). Failure to locate these files is one of the most common configuration issues, especially in deployment. The search order is determined by your PATH. Some standard locations are automatically prepended to your (process-specific) PATH. You can also use the NMathConfiguration.NativeLocation property, or the equivalent environment variable or app config setting, to prepend another location. An architecture-specific /x86 and /x64 subdirectory is also prepended. The appropriate architecture-specific natives are loaded at runtime.

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 rea­sons, 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 applica­tion 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 above).

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.


Top

Top