PyDotNet.NumPy 1.0.0

PyDotNet.NumPy

A typed NumPy plugin for PyDotNet — zero-copy interop between .NET memory and NumPy arrays via DLPack, with async reducers that exploit NumPy's GIL-free computation.

Installation

dotnet add package PyDotNet.NumPy

NumPy must be installed in the active Python environment:

pip install numpy

Quick start

using PyDotNet.NumPy;
using PyDotNet.Runtime;

PyRuntime.Initialize(new PyRuntimeOptions { ReleaseGilAfterInit = true });

using var interp = PyRuntime.CreateInterpreter();
using var np     = NumpyModule.Import(interp);

// Create arrays
using var zeros = np.Zeros<float>(3, 4);        // 3×4 float32 zeros
using var ones  = np.Ones<double>(100);          // 100-element float64 ones

// Arithmetic operators
using var a = np.Arange<float>(0f, 6f, 1f);
using var b = np.Full<float>(new long[] { 6 }, 2f);
using var c = a * b + 1f;

// Reducers
double mean = ones.Mean();
double std  = ones.Std();

PyRuntime.Shutdown();

Zero-copy interop

FromMemory<T> exports a .NET Memory<T> to NumPy via DLPack — no data is copied. The C# memory is pinned by the DLPack deleter and unpinned automatically when NumPy's array is garbage-collected.

float[] prices = { 100f, 102f, 98f, 105f, 110f };
using var arr = np.FromMemory<float>(prices.AsMemory());

// Write-through: modifying the span updates the C# array
arr.AsSpan<float>()[0] = 99f;
Console.WriteLine(prices[0]);   // 99

// Changes to the C# array are immediately visible in NumPy
prices[4] = 115f;
Console.WriteLine(arr.Sum());   // 99 + 102 + 98 + 105 + 115 = 519

For read-only scenarios where the source is a temporary span, use FromSpan<T> (copies once):

using var copy = np.FromSpan<double>(stackalloc double[] { 1.0, 2.0, 3.0 });

Async reducers

NumPy releases the GIL during BLAS-accelerated computation. The async reducer methods run reductions on the .NET thread pool, enabling true concurrency across multiple arrays:

using var a = np.Random.Normal(new long[] { 1_000_000 });
using var b = np.Random.Normal(new long[] { 1_000_000 });
using var c = np.Random.Normal(new long[] { 1_000_000 });

// All three reductions proceed in parallel at the native level
var (meanA, meanB, meanC) = await (a.MeanAsync(), b.MeanAsync(), c.MeanAsync())
    .WhenAll();   // helper pattern — or use Task.WhenAll directly

API reference

NumpyModule

NdArray

NumpyRandom

Accessed via NumpyModule.Random.

Real-world examples

Portfolio statistics

double[] dailyReturns = GetDailyReturns();
using var ret = np.FromMemory<double>(dailyReturns.AsMemory());

var annReturn = ret.Mean() * 252.0;
var annVol    = ret.Std()  * Math.Sqrt(252.0);
var sharpe    = annReturn / annVol;

Matrix chain (A @ B + bias)

using var A    = np.Random.Normal(new long[] { 128, 256 });
using var B    = np.Random.Normal(new long[] { 256, 64 });
using var bias = np.Zeros<double>(128, 64);

using var AB = np.MatMul(A, B);
using var C  = AB + bias;

Z-score normalisation

using var data = np.Random.Normal(new long[] { 100_000 }, loc: 50.0, scale: 15.0);
using var z    = (data - data.Mean()) / data.Std();
// z is now standardised: mean ≈ 0, std ≈ 1

Parallel async reductions

using var batches = Enumerable.Range(0, 8)
    .Select(_ => np.Random.Normal(new long[] { 500_000 }))
    .ToArray();

var means = await Task.WhenAll(batches.Select(b => b.MeanAsync()));
foreach (var b in batches) { b.Dispose(); }

Lifetime and disposal

All NdArray objects returned by NumpyModule and arithmetic operators are owned by the caller and must be disposed:

using var a = np.Zeros<float>(1000);   // ✅ owned, will be disposed
var b = np.Ones<float>(1000);          // ⚠ must call b.Dispose() manually

For zero-copy arrays created with FromMemory<T>, the C# backing memory must remain valid until the NdArray is disposed AND the Python GC has collected the internal capsule. In practice, this means keep the backing array alive as long as the NdArray is in scope.

Notes

• Requires NumPy ≥ 1.22 (DLPack protocol support).
• GPU arrays (CuPy, JAX) are supported for Python-level operations; AsSpan<T> requires CPU arrays.
• Transpose() returns a non-contiguous view; call Copy() or Flatten() before AsSpan<T>.