Add hardware pinning for QEC decoders

[kvmto]

Summary

Allows any registered QEC decoder to be assigned to specific hardware via decoder kwargs and the realtime YAML configuration:

• cuda_device_id — pins GPU decoders to a specific device
• numa_node_id — binds CPU decoder allocations to a NUMA node

Affinity is owned entirely by the base decoder class — no plugin code required. Private RAII guards (CudaDeviceGuard, NumaGuard) in decoder.cpp apply automatically at construction (decoder::get), batch decode (decode_batch), and async decode (decode_async). Raw Linux syscalls, no libnuma. Negative/absent ids are a no-op; out-of-range ids throw at construction.

device_affinity.h is now a CUDA-free param-reader header only (read_cuda_device_id, read_numa_node_id). scoped_cuda_device.h is removed — it was in the wrong location (public include tree). The public decoder.h interface remains free of CUDA and NUMA dependencies.

Design notes

Why the base class owns hardware affinity

The v1 approach put ScopedCudaDevice in the public include tree and required
each decoder plugin to opt in manually. That has two problems. First, a
third-party plugin author who forgets to add the guard gets silent wrong-device
behaviour with no error. Second, scoped_cuda_device.h pulled <cuda_runtime.h>
into the public API, which breaks the rule that decoder.h must be CUDA-free.

The v2 approach puts both RAII guards (CudaDeviceGuard and NumaGuard) in an
anonymous namespace inside decoder.cpp. They are invisible outside that
translation unit. The factory decoder::get() applies the guards during
construction and stores the ids in two protected members (cuda_device_id_,
numa_node_id_). Every decoder that goes through the factory gets correct
hardware affinity for free, including third-party plugins.

Where guards are applied and why

Call site	Guard applied	Reason
decoder::get()	Both guards	GPU allocations and NUMA first-touch happen here
decoder::decode_batch()	Both guards	One syscall for the whole batch, not per syndrome
decoder::decode_async()	Both guards, value-captured	Async thread starts with no inherited affinity
decoder::decode()	None	Sync callers in realtime loops manage their own thread state

The single-syndrome decode() has no guard by design. Adding a CUDA API call
per syndrome in a tight realtime loop would add syscall overhead on every call.
Callers that need affinity on the sync path set it themselves before entering
the loop.

The trt_decoder override

trt_decoder overrides decode_batch() entirely, which means the base class
version with its guard is never reached through virtual dispatch. A small inline
RAII struct at the top of trt_decoder::decode_batch() handles this. It reads
cuda_device_id_ from the protected base-class member and uses
cudaGetDevice/cudaSetDevice directly, since the private CudaDeviceGuard
type is not visible outside decoder.cpp.

No libnuma

NUMA binding uses raw Linux syscalls (SYS_set_mempolicy, sched_setaffinity)
behind #if defined(__linux__) with a one-time stderr warning on other
platforms. This avoids a new link dependency. The CPU affinity restore is
conditional on whether sched_getaffinity succeeded first, which avoids
permanently pinning a thread in containers with locked cpusets.

What this does not cover

Decode-time affinity for the sync decode() path is left to the caller.
The nv-qldpc-decoder and realtime-session NUMA IPC pinning are out of scope
and tracked separately.

The single-syndrome decode() has no guard by design, adding a CUDA API call
and a NUMA syscall per syndrome in a realtime loop would add per-call overhead.
Callers on that path are expected to set affinity once before entering the loop.
All other paths (decode_batch, decode_async, construction) are fully covered.

Tests

• device_affinity param readers (absent, int, size_t, negative-throws)
• decoder::get() rejects out-of-range cuda_device_id for any decoder
• decode_async does not corrupt the calling thread's current device
• trt_decoder rejects invalid device ids and correctly runs decode_async on the assigned GPU end-to-end

Out of scope

Does not address nv-qldpc-decoder runtime device handling or realtime-session NUMA IPC pinning.

[tlshannon]

I think this works, but I'm thinking we might have to do it differently for the realtime api. I think we either need to assume that the thread that creates the decoder is the thread to set affinity on (and just set it persistently during construction) or allow the user to set it outside of the decode/enqueue calls. Perhaps we could set some flags to at least notify the user that they forgot to set the affinity, instead of silently ignoring it. I'm not quite sure what all the user interfaces should be. It seems like, in a realtime system, we should launch a thread that has the decoder on it and just set the affinity once for that thread.

[kvmto]

I will split the PR in two or three.
Still finishing some things, but I should have tackled the majority of the use cases and comments now.
@bmhowe23 @tlshannon

[kvmto]

We will need to wait for new CI :) @bmhowe23 @anjbur

[tlshannon]

LGTM

[bmhowe23]

Thanks, Kevin ... this looks really thorough. As we discussed offline, there may be some use cases that we have not fully thought through for the theading and NUMA pinning. Therefore, I think it would be best to break this down into smaller PRs.

1. Decoder-specific changes to support "cuda_device_id". This one is the near-term priority and is likely the only one needed for this release. While the main goal is YAML support and C++ use cases, I think that this should likely automagically work for Python if we just implement the decoder-specific kwargs like all of our other kwargs.
2. Handle NUMA memory pinning and better threading understanding/support. It would be great to capture what you have in this PR into another draft PR. But it may be next release before we work through all the use cases there.
3. Python interfaces for 2