Click or drag to resize

NMathConfiguration Class

Class NMathConfiguration provides properties for controlling the loading of the NMath kernel assembly and native library, and specifying license keys.
Inheritance Hierarchy
SystemObject
  CenterSpace.NMath.CoreNMathConfiguration

Namespace: CenterSpace.NMath.Core
Assembly: NMath (in NMath.dll) Version: 7.4
Syntax
public class NMathConfiguration

The NMathConfiguration type exposes the following members.

Constructors
 NameDescription
Public methodNMathConfigurationInitializes a new instance of the NMathConfiguration class
Top
Properties
 NameDescription
Public propertyStatic memberLicenseKey Gets and sets the NMath license key.
Public propertyStatic memberLogFilename Gets and sets the configuration log filename.
Public propertyStatic memberLogLocation Gets and sets the location of the configuration log file.
Public propertyStatic memberLogVerbose If true, enables verbose logging, such as native functions calls.
Public propertyStatic memberNativeLocation Sets the location used at runtime to locate the NMath native libraries.
Public propertyStatic memberReproducibility Gets and sets the value of the MKL Conditional Numerical Reproducibility (CNR) flag.
Top
Methods
 NameDescription
Public methodStatic memberInit Initializes this NMath configuration.
Public methodStatic memberLog Writes a newline to the log file.
Public methodStatic memberLog(Exception) Writes an exception message and stack trace to the log file.
Public methodStatic memberLog(String) Writes a string to the log file.
Public methodStatic memberLog(String, Object) Writes a string to the log file, replacing string parameters as necessary.
Public methodStatic memberSetMKLNumThreads Sets the suggested number of threads for MKL to use.
Top
Remarks
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:

C#
NMATH_NATIVE_LOCATION="C:\tmp"
This code uses an application configuration file:
C#
<?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:

C#
NMathConfiguration.NativeLocation = @"C:\tmp";
The supported property names, configuration app setting keys, and environment variables are show below.
Property or MethodConfiguration App SettingEnvironment Variable
LicenseKeyNMathLicenseKeyNMATH_LICENSE_KEY
NativeLocationNMathNativeLocationNMATH_NATIVE_LOCATION
LogFilenameNMathLogFilenameNMATH_LOG_FILENAME
LogLocationNMathLogLocationNMATH_LOG_LOCATION
LogVerboseNMathLogVerboseNMATH_LOG_VERBOSE
SetMKLNumThreads()NMathMKLNumThreadsNMATH_MKL_NUM_THREADS
ReproducibilityNMathReproducibilityNMATH_REPRODUCIBILITY
Logging

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

C#
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.

See Also