Deployment Guide

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

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.

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.