Deployment Guide

This guide documents the procedures for the deployment and configuration of applications built using Numerics.NET.

Licensing at application startup

Pro applications must have a valid entitlement before their first protected numerical calculation. Community does not require Pro credentials. For Native AOT, either configure the process environment before starting the application or verify credentials explicitly at startup. Keys are secrets: obtain them from your deployment secret store and do not embed them in source control, build arguments or logs.

For automatic startup with a permanent license, set NUMERICSDOTNET_USERNAME, NUMERICSDOTNET_ORGANIZATION and NUMERICSDOTNET_LICENSEKEY to the exact licensed user, organization and key. For a trial, set NUMERICSDOTNET_TRIALKEY instead. These are process environment variables, read by the library. The library still verifies the license before permitting a protected calculation; the following application code does not need an explicit verification call. For example, supply these permanent-license settings through your deployment secret configuration:

NUMERICSDOTNET_USERNAME=<licensed user>
NUMERICSDOTNET_ORGANIZATION=<licensed organization>
NUMERICSDOTNET_LICENSEKEY=<license key>

The following managed-provider example exercises automatic licensing without depending on native provider deployment or managed plugin discovery. This licensing setup does not qualify every library API or provider for Native AOT.

// Environment supplied by your deployment before process startup.
Numerics.NET.NumericsConfiguration.AutoLoadNativeProviders = false;
Numerics.NET.NumericsConfiguration.AutoLoadCustomProviders = false;
Numerics.NET.Vector<double> result = Numerics.NET.Vector.Create(1.0, 2.0) + Numerics.NET.Vector.Create(3.0, 4.0);

Alternatively, call Verify(String, String, String) with your permanent credentials, or Verify(String) with a trial key, before constructing licensed objects. Replace the placeholders below with values read securely at runtime.

bool verified = Numerics.NET.License.Verify("<licensed user>", "<licensed organization>", "<license key>");
if (!verified) throw new System.InvalidOperationException("License verification failed.");

Successful verification is cached for the lifetime of the process. Once licensed, subsequent verification calls return success without validating new arguments; changing environment variables does not revoke the cached entitlement. Unsuccessful attempts are not cached by the licensing subsystem: correct the configuration or verify valid credentials and retry. Configure licensing before using APIs whose own static initializers require a license; the CLR cannot retry a failed type initializer.

Configure and verify licensing at application startup before handing numerical work to other threads. Duplicate concurrent validation with one stable configuration is permitted, but simultaneous verification with different credentials has no guaranteed winner. Concurrent environment-variable or component-model context changes are outside the supported configuration contract. A failed attempt never clears a successfully cached entitlement.

Before a successful entitlement is cached, JIT applications first look for an existing component-model embedded/saved full license. Next, the library tries a valid process permanent key, then an installed machine permanent license when AllowDesignTimeLicenseAtRuntime is enabled, then a process trial key. Machine registry credentials exist only on .NET Framework. A valid earlier source wins even if a later source is invalid. An invalid permanent configuration can fall back to that enabled valid machine source or a valid process trial. If configured process material remains invalid, verification rejects it rather than continuing to saved trials. When no process material is configured and no full license was found, JIT retains its saved-trial and .NET Framework installed-trial discovery. Process configuration is now active without the former design-time-license opt-in. Remove stale invalid process settings when relying on a saved trial, or configure valid credentials explicitly before commencing work.

The component-model license provider uses the same source precedence whether its allowExceptions argument is true or false. After configured material has been rejected, true reports a LicenseException and false returns null; neither continues to a lower-priority saved trial. Absent configuration may continue to trial discovery in either mode, and an earlier saved full license retains its precedence.

An empty design-time context may construct the licensing component using a designer-only compatibility license. That placeholder does not authorize protected numerical calculations or enter the successful-entitlement cache. A calculation still needs a validated permanent or trial entitlement, even inside a designer. Changing to a runtime context does not convert a placeholder into authorization. After rejection, supply valid configuration or explicitly verify valid credentials before retrying. Existing designer code that performed protected calculations without a valid entitlement must now configure licensing first.

Native AOT uses the process permanent key followed by the process trial key. It does not enumerate managed host assemblies or discover component-model embedded, saved or installed licenses. The design-time-license flag does not enable that discovery in a native application. Deploy process configuration or use explicit verification instead. Trial expiration and build eligibility, and permanent-key build/subscription eligibility, are validated by the same rules on JIT and AOT.

Without a usable entitlement, a protected calculation throws LicenseException. Invalid trial verification throws that exception. Permanent-key Verify(String, String, String) returns false for invalid credentials when no successful entitlement is cached, regardless of logging level. Check the return value before commencing work. This corrects earlier behavior where enabling informational logging could instead throw a licensing exception; callers must no longer rely on that logging-dependent exception. An already cached entitlement continues to return success without revalidating later arguments. A platform-discovery exception is not a licensing rejection.

Redistributable files

The following files may be distributed as part of your application: All required binary files (including .dll, .so, and .dylib files) that are copied into your application's bin folder and its subfolders.

What to deploy

Not all redistributable files need to be installed with your application. In fact, most installations will require just the main assembly, plus any additional managed assemblies and native libraries used by the application.

  • All installations require the Numerics.NET.dll assembly.

  • If you use single-precision linear algebra, or any of the classes that are specialized for single-precision floating-point numbers, you also require Numerics.NET.SinglePrecision.dll.

  • If you use linear algebra for elements other than single and double precision numbers, or any of the generic classes, you also require Numerics.NET.Generic.dll.

Numerics.NET supports optimized native providers based on Intel's Math Kernel Library, OpenBLAS, and Apple Accelerate. Automatic native loading prefers MKL on Windows and Linux, and Accelerate on macOS, with OpenBLAS as the fallback.

You only need to deploy the assemblies you actually use. For example, most applications will not use any of the single precision types, and so won’t require the *.SinglePrecision.* assemblies. Native acceleration is optional; its benefit depends on the operation, problem size, and hardware.

P/Invoke based libraries

P/Invoke based libraries are written in native C++ and are called from managed code using Platform Invoke (P/Invoke).

The name of the dynamic link library is hard-coded in the main Numerics.NET assembly. For the library based on Intel's Math Kernel Library, the name is Numerics.NET.Native.Mkl. The extension is platform-dependent.

On macOS 12 or later, install Numerics.NET.Native.Accelerate. It contains separate x64 and ARM64 versions of Numerics.NET.Native.Accelerate.dylib and dynamically uses Apple's system Accelerate framework. The package does not redistribute Apple framework binaries.

The Accelerate provider supplies dense BLAS and LAPACK operations, vDSP-backed real vector arithmetic, and selected contiguous vForce functions. Unsupported strides, overlaps, complex vector operations and sparse operations use managed implementations. Directly supported one-dimensional real and complex FFT lengths use vDSP in both precisions. Other exact FFT lengths can use provider-assisted Bluestein transforms without changing the requested length. Convolution and correlation may select a larger directly supported work length. Two-dimensional FFTs use separable one-dimensional transforms; Rader and direct native 2D transforms are not included. MKL-specific thread and reproducibility settings do not apply to Accelerate.

The single-precision MKL native code is in the Numerics.NET.Native.Mkl.SinglePrecision library. It requires the Numerics.NET.SinglePrecision assembly as well.

On Windows, the MKL packages also include the shared threading library called libiomp5md.dll.

Deploy the native provider libraries and runtime dependencies for the platforms your application targets. The NuGet packages include the required runtime assets. MKL single precision is a separate native package; Accelerate and OpenBLAS each supply both precisions in one native library. OpenBLAS supplies dense BLAS and LAPACK operations, with managed implementations for other functionality.

Provider compatibility and diagnostics

Current native providers report compatibility metadata. Numerics.NET validates identity, ABI, precision, and required capabilities before use. Invalid reported metadata always causes rejection.

Compatible v10 MKL providers without the metadata bootstrap are accepted by default as legacy providers with inferred compatibility version 1.0. Set AllowLegacyProviders to false before loading to require the modern handshake. This legacy exception does not apply to OpenBLAS or Accelerate.

Enumerate providers through RegisteredProviders and inspect Information. Information is an immutable cached snapshot; reading it performs no native calls or filesystem probing.

CompatibilityVersion identifies the Numerics.NET provider contract. ProviderVersion identifies the bridge implementation when known. BackendVersion is diagnostic text and does not determine compatibility. Legacy MKL has unknown reported capabilities and provider version, but exposes known enabled capabilities.

Mixed-mode assemblies

Mixed-mode assemblies are written in C++/CLI and provide the best performance because of the minimal overhead when calling native code. Unfortunately, C++/CLI does not support spans, which are extensively used in the revised core API. As a result, mixed-mode assemblies are no longer supported.