PyDotNet.Torch 1.3.0

PyDotNet.Torch

A typed PyTorch plugin for PyDotNet — autograd, device movement, and zero-copy DLPack interop for torch.Tensor from .NET.

Installation

dotnet add package PyDotNet.Torch

PyTorch must be installed in the active Python environment:

pip install torch

Quick start

using PyDotNet.Torch;
using PyDotNet.Runtime;
using PyDotNet.Types;

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

using var interp = PyRuntime.CreateInterpreter();

// Create tensors
using var a = PyTorchTensor.Ones(interp,  new[] { 3, 4 });
using var b = PyTorchTensor.Zeros(interp, new[] { 3, 4 });

// Arithmetic
using var c = a + b;
using var d = a * 2f + b;

// Shape ops
using var flat = a.Reshape(12);      // 1-D view
using var col  = flat.Unsqueeze(1);  // (12, 1)

// Reductions
using var mean = a.Mean();
using var sum  = a.Sum(dim: 1);

PyRuntime.Shutdown();

Zero-copy interop

FromArray<T> — .NET array → torch tensor

FromArray<T> pins the source array and hands a DLPack capsule to torch.from_dlpack. No data is copied — the tensor shares the same memory as the .NET array. The GC handle is released automatically when the tensor is disposed.

float[] weights = new float[3 * 4];
Random.Shared.NextBytes(MemoryMarshal.AsBytes(weights.AsSpan()));

using var tensor = PyTorchTensor.FromArray(interp, weights, new[] { 3, 4 });
// tensor.Shape → [3, 4], tensor.Device → Cpu, tensor.DataType → Float32

ToDLPack() — tensor → DLPackTensor

Export a CPU tensor back to a DLPackTensor (zero-copy). The tensor must not have requires_grad = true; call Detach() first if needed.

using var dlpack = tensor.ToDLPack();
ReadOnlySpan<float> span = dlpack.AsReadOnlySpan<float>();

AsTensorBuffer() — buffer protocol

AsTensorBuffer() acquires a PyBuffer from the tensor via detach().numpy() (zero-copy for contiguous CPU tensors). Use this when you need Span<T> access to tensor data in-place.

using var buf = tensor.AsTensorBuffer(writable: true);
Span<float> span = buf.AsSpan<float>();
span.Fill(0f);  // writes directly into the tensor's storage

ToArray<T> — managed copy

When you just need a snapshot of the data:

float[] data = tensor.ToArray<float>();

If RequiresGrad is true, the tensor is detached automatically before copying.

Autograd

using var x = PyTorchTensor.Ones(interp, new[] { 3 }, requiresGrad: true);
using var y = x * x;           // y = x²
using var z = y.Sum();         // scalar
z.Backward();                  // ∂z/∂x = 2x

using var grad = x.Grad!;      // grad.Shape == [3]
float[] g = grad.ToArray<float>();
// g == [2, 2, 2]

Backward() propagates gradients from a scalar tensor. Grad returns null until Backward() has been called on a downstream scalar. HasGrad is a cheaper check that avoids constructing the gradient tensor object.

API reference

PyTorchTensor

All methods return a new PyTorchTensor (owned reference, IDisposable) unless stated otherwise.

Metadata

Autograd

Device movement

Arithmetic

Shape

Reductions

Element-wise math

Activations

Data access

Factory methods

All factory methods are static and return a new owned tensor.

TensorDataType

TensorDevice

Python API coverage

~55 of the ~700 methods on torch.Tensor are wrapped.

Notable gaps: index/slice access (tensor[i, j]), in-place (_-suffixed) variants, topk, gather, scatter, color bars, and sparse/complex tensor operations.

Supported frameworks

net8.0 · net9.0 · net10.0