Referencing NMath

To use NMath types in your application, add a reference to NMath.dll, just as you would with other types of .NET applications. If you are using web projects in Visual Studio, you can simply right-click the References folder and select the Add Reference… command. If you specify Copy Local = true in the reference’s properties, then the assembly will be copied to the /bin directory of the web application, facilitating deployment to a web server.

If you are not using web projects in Visual Studio (e.g. using the “Open Web Site” command in Visual Studio, or using other development tools), then you can alternatively specify the reference in the web.config file, like this:

<configuration>
<system.web>
<compilation>
<assemblies>
<add assembly=”NMath, Version=<Version>, Culture=neutral, PublicKeyToken=<Token>”/>
</assemblies>
</compilation>
</system.web>
</configuration>

We recommend that you do not add references to the kernel assemblies, as the appropriate kernel assembly for your platform is loaded at runtime and the appropriate native DLL is linked to the kernel.  Instead, place the kernel assemblies in the same location as the native DLLs, as described below.

Note: when the web server launches an ASP.NET application for the first time, the assemblies in the /bin directory are loaded into memory. If the /bin directory contains a mixture of 32-bit and 64-bit assemblies (for example, both NMathKernelx86.dll and NMathKernelx64.dll), then depending on the configuration of the web server, the application may fail to start and instead throw an exception like this: “An attempt was made to load a program with an incorrect format.”

Kernel Assemblies and Native DLLs

For ASP.NET applications, Microsoft recommends that the /bin directory contain only .NET assemblies, not native DLLs.

If the deployment web server may not have NMath installed directly, then we recommend that the appropriate kernel assembly (NMathKernelx86.dll or NMathKernelx64.dll) and the appropriate native DLLs (e.g. nmath_native_x86.dll or nmath_native_x64.dll) be placed in a folder within the web application root directory, such as /NativeBin. This folder should then be copied to the deployment web server along with the rest of your application.

NMath Configuration

NMath settings can be configured as described in Chapter 1.5 of the NMath User’s Guide. However, when deploying web applications — especially to a shared hosting environment — it’s quite common not to know the details about the physical structure of the file system, and to have restricted access to the system’s environment variables. The references to resources within web apps are typically relative to the root of the virtual directory for the website, regardless of where they might physically reside on disk.

For this reason, starting in NMath 5.3, the ASP.NET ~ operator can be used to specify the location of the NMath native libraries and the log file, relative to the web application root. That is, these can be specified in the web.config file like this:

<add key=”NMathNativeLocation” value=”~/NativeBin” />
<add key=”NMathLogLocation” value=”~/Logs” />

It is not sufficient to use relative paths (e.g. “bin/”), since the executing assembly is usually the ASP.NET worker process, and depending on the web server configuration, the working directory will usually be a subdirectory of the Windows system directory (e.g. c:\windows\system32).

The ~ operator can only be used in ASP.NET applications; specifying this in a Windows application will cause the path to be resolved incorrectly.

The post Building ASP.NET web applications with NMath appeared first on CenterSpace.

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:

1. Open CenterSpace Software | License NMath from your Start menu.
2. 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.

The post NMath Configuration appeared first on CenterSpace.