Beginning with the release of NMath 5.2 and NMath Stats 3.5, NMath includes a new configuration system for controlling the loading of the NMath license key, kernel assembly, and native library. Based on customer feedback, we’ve designed this system to provide greater flexibility and security at deployment, and greater convenience in group development environments. We’ve also added optional logging to help debug configuration issues.
An NMath license file is no longer used.
NMath License Key
NMath license information is stored in a license key which must be found at runtime. The license key governs the properties of your NMath installation. If no license key is found, a default evaluation license key is used which provides a free 30-day evaluation period for NMath on the current machine.
When you purchase one or more developer seats of NMath, you will be issued a license key describing the terms of your license. To enter your license key:
- Open CenterSpace Software | License NMath from your Start menu.
- Enter your name, email, and license key, and click OK.
The license key will be written to the registry. You can also specify your license key using various other mechanisms: by environment variable, by configuration app setting, and programmatically. These mechanisms may be preferable in group development environments, and at deployment. (See below.)
NMath Configuration
NMath configuration settings govern the loading of the NMath license key, kernel assembly, and native library. Property values can be set three ways:
- by environment variable
- by configuration app setting
- by programmatically setting properties on class NMathConfiguration
Settings are applied in that order, and resetting a property takes precedent over any earlier values. For example, here an environment variable is used:
> set NMATH_NATIVE_LOCATION="C:\tmp"
This code uses an app config file:
<?xml version="1.0" encoding="utf-8" ?> <configuration> <appSettings> <add key="NMathNativeLocation" value="C:\tmp" /> </appSettings> </configuration>
And this code accomplishes the same thing programmatically:
NMathConfiguration.NativeLocation = @"C:\tmp";
Also, all paths can be specified relative to the executable. So to place the natives in an existing directory named resources adjacent to the executable one would
write:
NMathConfiguration.NativeLocation = @"..\resources";
The supported environment variables, configuration app setting keys, and property names are show below.
Environment Variable | Configuration Setting | Property |
---|---|---|
NMATH_LOG_LOCATION |
NMathLogLocation |
LogLocation |
NMATH_LICENSE_KEY |
NMathLicenseKey |
LicenseKey |
NMATH_NATIVE_LOCATION |
NMathNativeLocation |
NativeLocation |
NMATH_USE_SEQUENTIAL_THREADING |
NMathUseSequentialThreading |
UseSequentialThreading |
NMATH_USE_EXTERNAL_THREADING |
NMathUseExternalThreading |
UseExternalThreading |
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.
For example, when using Mono on a Mac, to configured NMath with a sequentially threaded library set the environmental variable as follows.
> export NMATH_USE_SEQUENTIAL_THREADING="True"
Logging
To debug configuration issues, specify a log file location. For example, setting the property programmatically to place the NMath log file in the same directory as the executable one would write:
NMathConfiguration.LogLocation = @".";
Or if you prefer to use a global temporary directory you could specify an absolute path.
NMathConfiguration.LogLocation = @"C:\temp\logs";
This creates a file named NMathConfiguration.log
at the specified location containing log output. The specified location must exist. To turn off logging, set the log location to null.
License Key
You can specify your NMath license key using the LicenseKey
property, or the equivalent environment variable or app config setting. If so, any keys in the registry are ignored.
Native Location
The NMath native assembly must be found at runtime. Failure to locate this file is one of the most common configuration issues, especially in deployment. The search order is determined by your PATH
(on Windows systems). Some standard locations are automatically prepended to your (process-specific) PATH
. You can also use the NativeLocation
property, or the equivalent environment variable or app config setting, to prepend another location.
Alternative Kernel and Native Assemblies
The names of the NMath kernel and native assemblies are determined by your platform (x86 or x64), and the values of the UseSequentialThreading
and UseExternalThreading
properties, as shown below:
Standard Kernel NMathKernelx86.dll NMathKernelx64.dll Native nmath_native_x86.dll nmath_native_x64.dll Sequentially-Threaded Kernel NMathKernelx86Sequential.dll NMathKernelx64Sequential.dll Native nmath_native_x86_seq.dll nmath_native_x64_seq.dll Externally-Threaded Kernel NMathKernelx86External.dll NMathKernelx64External.dll Native nmath_native_x86_ext.dll nmath_native_x64_ext.dll
Sequentially-threaded and externally-threaded kernel and native assemblies are available upon request from CenterSpace Software:
- Sequentially-Threaded: MKL contains highly optimized, extensively threaded math routines. In rare cases, these can cause conflicts between the Intel OMP threading library (
libiomp.dll
) and the .NET threading model. If your .NET application is itself highly multi-threaded, you may wish to use the sequentially-threaded version of MKL. - Externally-Threaded: NMath normally statically links in the Intel OMP threading library described above. Sometimes this can cause collisions with libraries from other vendors that also use OMP. The externally-threaded version of
NMath
dynamically-links in OMP.
To trigger loading of these assemblies, use properties UseSequentialThreading
and UseExternalThreading
on class NMathConfiguration, or the equivalent environment variables or app config settings. Both properties default to false
.
UseSequentialThreading
and UseExternalThreading
are mutually exclusive, and UseSequentialThreading
takes precedence; UseExternalThreading
only has an effect if UseSequentialThreading
is false
.
4 thoughts on “NMath Configuration”