ParallelGpu 0.3.0

ParallelGpu

Synchronous C# loops on CUDA or OpenCL, powered by ILGPU. Write a lambda over captured collections; the library compiles it for the selected device, transfers the data, and copies results back before the call returns.

Installation

dotnet add package ParallelGpu

Quick start

using ParallelGpu;

using var gpu = new Gpu();
int[] input = { 1, 2, 3 };
int[] output = new int[input.Length];

gpu.For(0, input.Length, i => output[i] = input[i] * 2);
// output: 2, 4, 6

Reuse a Gpu instance to retain the accelerator and compiled kernels. GpuParallel.For(...) also provides a static API.

Backend selection

The default backend is Auto. It tries CUDA first, then OpenCL. CPU fallback is disabled by default; enable it explicitly when an application should also run without a compatible GPU:

using var gpu = new Gpu(new GpuOptions
{
    Backend = GpuBackend.Auto,
    AllowCpuFallback = true
});

Explicit Cuda and OpenCL selections never fall back to CPU. Use GpuOptions.DeviceIndex to select a device, and inspect gpu.Backend, gpu.DeviceName, and gpu.IsGpu after initialization.

Capabilities

• Automatic transfers for arrays of any rank, jagged arrays, fixed-size lists, and supported memory views, with shared storage preserved.
• Automatic value mappings for numeric types, bool, char, enums, supported structures, and nullable values.
• Device buffers via Upload<T> and Allocate<T> to retain data between kernels, with partial CopyFrom/CopyTo transfers using array offsets/counts or spans.
• Explicit value kernels through IGpuForKernel and IGpuForEachKernel<T>.
• Reductions, atomic operations, and bounded append buffers for variable output.
• Host collection adapters support inherited and renamed indexers, including List<T>-derived collections; snapshots preserve slices, read-only access, shared identities and one host commit per identity. Explicit object-graph adapters support custom data models.
• Floating-point % and supported Math/MathF operations, including CopySign, Sin, Cos, Pow and both Log overloads (natural logarithm or a specified base).

Execution requirements and limitations

The automatic lambda API requires runtime code generation (Reflection.Emit) and access to method IL. It is not supported in Native AOT applications.

Loop iterations are unordered. Use independent writes, atomics, or reductions to avoid races. Scalars captured by a lambda are read-only; collection elements may be writable, but collection sizes and array topology cannot change during execution.

Loop bodies and their helpers must be device-compatible. Arbitrary .NET methods, managed allocation, boxing, reflection, exception handlers, and checked integer arithmetic are unsupported. Automatic structure mappings cannot contain managed references, native pointers, or explicit layout. Inline arrays and fixed buffers are unsupported, including in nested structures. Direct device buffers and explicit value kernels require public unmanaged ILGPU-compatible types.

Automatic loops transfer captured collections on every call. For repeated operations, keep data in device buffers and download results when needed. Transfers and kernel compilation can outweigh the benefit of GPU execution for small or inexpensive workloads.

Bounds, null access, read-only writes and guarded arithmetic errors become host exceptions before automatic collection copyback, including ref access in value constructors. ArraySegment<T> constructor validation follows CLR behavior. Large loops may use several launches with shared device storage; copyback requires every launch to succeed. Owned device buffers and callback side effects are not rolled back.

Calls on one Gpu instance are serialized. Avoid modifying transferred host collections concurrently, and dispose the executor and its buffers when finished. Transcendental functions are approximate; compare with a numerical tolerance. Floating-point reduction results may differ from sequential CPU results and between devices.

Documentation and examples

See the ParallelGpu repository for the full API guide, supported math operations, collection and object-graph examples, and sample applications.

License

Licensed under MIT.