[MISC] Add docs for external_metal_command_queue / shared Metal queue

New page metal_shared_queue.md with full setup guide: extracting
PyTorch MPS MTLCommandQueue, init ordering, sync implications,
ownership, and fallback. Cross-referenced from init_options.md
and interop.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hughperkins

docs/source/user_guide/index.md

@@ -31,6 +31,7 @@ parallelization
 :titlesonly:
 
 interop
+metal_shared_queue
 ```
 
 ```{toctree}

docs/source/user_guide/init_options.md

@@ -64,6 +64,14 @@ Forces every adstack in the program to exactly `N` slots and bypasses the launch
 
 Cutoff (in bytes) below which the gate-passing-count sizing path described in [Memory footprint](./autodiff.md#memory-footprint) is skipped in favour of the eager `dispatched_threads * stride` heap. Default `100 MiB`. The sparse path saves memory on kernels of the shape `for i in range(...): if field[i] cmp literal: <adstack work>` but pays a per-launch reducer dispatch; below the threshold that overhead outweighs the savings. Set to `0` to always use the sparse path; lower it if the default still skips kernels you want shrunk. No effect when `ad_stack_experimental_enabled=False` or when the kernel has no such gate.
 
+## Apple Metal
+
+### `external_metal_command_queue`
+
+An `MTLCommandQueue*` pointer (as an integer) to use instead of creating a new Metal command queue. Default `0` (create a new queue). When non-zero, Quadrants dispatches all GPU work on the provided queue, which enables GPU-side ordering with other frameworks that share the same queue (most notably PyTorch MPS).
+
+See [Shared Metal command queue](./metal_shared_queue.md) for the full setup guide, including how to extract the queue pointer from PyTorch and the synchronisation implications.
+
 ## Debugging
 
 See [Debug mode](./debug.md) for runnable examples and a typical develop / benchmark workflow.

docs/source/user_guide/interop.md

@@ -178,6 +178,8 @@ my_kernel(f)                     # now safe
 
 This is intentional: forcing a sync on every Quadrants kernel that touches a previously-zerocopied field would be very expensive in workloads that batch many torch ops and many kernels back-to-back. If you mutate fields from torch and then read them from a Quadrants kernel on Metal, call `torch.mps.synchronize()` once between the torch ops and the kernels.
 
+**Shared command queue.** The synchronisation overhead above can be eliminated entirely by passing PyTorch MPS's `MTLCommandQueue` to Quadrants at init time via `external_metal_command_queue`. When both frameworks share the same queue, Metal guarantees command buffer ordering automatically. See [Shared Metal command queue](./metal_shared_queue.md) for the setup guide.
+
 ### Lifetime caveats
 
 A zero-copy view becomes invalid when the underlying Quadrants storage is freed. This happens on `qd.reset()` and `qd.init()`. Holding a `copy=False` tensor across either is undefined behaviour:

docs/source/user_guide/metal_shared_queue.md

@@ -0,0 +1,114 @@
+# Shared Metal command queue (PyTorch MPS)
+
+On Apple Silicon, Quadrants and PyTorch MPS both dispatch GPU work via Metal. By default each framework creates its own `MTLCommandQueue`, which means there is no GPU-level ordering between them. Every zero-copy interop point therefore requires explicit CPU-side synchronisation (`qd.sync()` and `torch.mps.synchronize()`) to guarantee data visibility.
+
+The `external_metal_command_queue` option lets you pass PyTorch's command queue to Quadrants so that both frameworks share a single queue. Metal processes command buffers in commit order within a queue, so GPU-side ordering is automatic and the per-interop sync overhead is eliminated.
+
+## Quick start
+
+```python
+import quadrants as qd
+
+queue_ptr = get_mps_command_queue()   # see below
+qd.init(arch=qd.metal, external_metal_command_queue=queue_ptr)
+```
+
+Once initialised this way:
+
+- `to_torch(copy=False)` no longer calls `qd.sync()` internally.
+- `to_torch(copy=True)` no longer calls `torch.mps.synchronize()` after the copy.
+- GPU work submitted by Quadrants and by PyTorch executes in the order it was committed — no manual sync needed between the two.
+
+You can still call `qd.sync()` when you need to read results back to the CPU (e.g. `to_numpy()`); what changes is that you no longer need *both* `qd.sync()` and `torch.mps.synchronize()` at every framework boundary.
+
+## Extracting PyTorch's MTLCommandQueue
+
+PyTorch does not expose its MPS command queue through a public Python API. The following helper extracts it at runtime using `ctypes` and the Objective-C runtime, with no build-time PyTorch dependency:
+
+```python
+import ctypes
+import os
+import torch
+
+
+def get_mps_command_queue() -> int:
+    """Return PyTorch MPS's MTLCommandQueue* as a Python int."""
+    # Ensure MPS is initialised
+    torch.zeros(1, device="mps")
+
+    torch_lib = os.path.join(
+        os.path.dirname(torch.__file__), "lib", "libtorch_cpu.dylib"
+    )
+    handle = ctypes.CDLL(torch_lib)._handle
+
+    libdl = ctypes.CDLL(None)
+    dlsym = libdl.dlsym
+    dlsym.restype = ctypes.c_void_p
+    dlsym.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+
+    # at::mps::getDefaultMPSStream() -> MPSStream*
+    func_addr = dlsym(handle, b"_ZN2at3mps19getDefaultMPSStreamEv")
+    assert func_addr, "Cannot find getDefaultMPSStream — check PyTorch version"
+    stream_ptr = ctypes.CFUNCTYPE(ctypes.c_void_p)(func_addr)()
+
+    # MPSStream::commandBuffer() -> id<MTLCommandBuffer>
+    cb_addr = dlsym(handle, b"_ZN2at3mps9MPSStream13commandBufferEv")
+    assert cb_addr, "Cannot find MPSStream::commandBuffer"
+    cb_ptr = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_void_p)(cb_addr)(
+        stream_ptr
+    )
+
+    # [commandBuffer commandQueue] via ObjC runtime
+    objc = ctypes.CDLL("/usr/lib/libobjc.A.dylib")
+    sel_reg = objc.sel_registerName
+    sel_reg.restype = ctypes.c_void_p
+    sel_reg.argtypes = [ctypes.c_char_p]
+    msg_send = objc.objc_msgSend
+    msg_send.restype = ctypes.c_void_p
+    msg_send.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+
+    queue_ptr = msg_send(cb_ptr, sel_reg(b"commandQueue"))
+    assert queue_ptr, "Failed to extract MTLCommandQueue"
+    return queue_ptr
+```
+
+The C++ symbol `_ZN2at3mps19getDefaultMPSStreamEv` has been stable since PyTorch 1.13.
+
+## Init ordering
+
+PyTorch MPS must be initialised **before** `qd.init()` so that the command queue exists when Quadrants starts:
+
+```python
+import torch
+torch.zeros(1, device="mps")        # trigger MPS init
+
+import quadrants as qd
+queue_ptr = get_mps_command_queue()
+qd.init(arch=qd.metal, external_metal_command_queue=queue_ptr)
+```
+
+## What changes with a shared queue
+
+| Scenario | Separate queues (default) | Shared queue |
+|----------|--------------------------|--------------|
+| `f.to_torch(copy=False)` | `qd.sync()` called internally | no sync needed |
+| `f.to_torch(copy=True)` | `qd.sync()` + `torch.mps.synchronize()` | no sync needed |
+| Quadrants kernel after torch write | manual `torch.mps.synchronize()` required | automatic (same queue) |
+| `f.to_numpy()` | `qd.sync()` (always needed for CPU readback) | `qd.sync()` (still needed) |
+
+## Lifetime and ownership
+
+The caller (your application) owns the command queue. Quadrants retains it for the duration of the runtime and does **not** release it on `qd.reset()`. You must keep PyTorch (and its MPS backend) alive for as long as the Quadrants runtime is active.
+
+## Fallback
+
+If extracting the queue fails (e.g. on an older PyTorch version or a non-Apple system), fall back to the default separate-queue path:
+
+```python
+try:
+    queue_ptr = get_mps_command_queue()
+except (AssertionError, OSError):
+    queue_ptr = 0   # 0 means "create a new queue" (the default)
+
+qd.init(arch=qd.metal, external_metal_command_queue=queue_ptr)
+```

quadrants/rhi/metal/metal_device.mm

@@ -1016,17 +1016,18 @@
 MTLCommandBuffer_id MetalCommandList::finalize() { return cmdbuf_; }
 
 MetalStream::MetalStream(const MetalDevice &device,
-                         MTLCommandQueue_id mtl_command_queue,
-                         bool owns_queue)
-    : device_(&device), mtl_command_queue_(mtl_command_queue), owns_queue_(owns_queue) {}
+                         MTLCommandQueue_id mtl_command_queue, bool owns_queue)
+    : device_(&device), mtl_command_queue_(mtl_command_queue),
+      owns_queue_(owns_queue) {}
 MetalStream::~MetalStream() { destroy(); }
 
 MetalStream *MetalStream::create(const MetalDevice &device) {
   MTLCommandQueue_id compute_queue = [device.mtl_device() newCommandQueue];
   return new MetalStream(device, compute_queue, /*owns_queue=*/true);
 }
-MetalStream *MetalStream::create_with_external_queue(const MetalDevice &device,
-                                                     MTLCommandQueue_id external_queue) {
+MetalStream *
+MetalStream::create_with_external_queue(const MetalDevice &device,
+                                        MTLCommandQueue_id external_queue) {
   [external_queue retain];
   return new MetalStream(device, external_queue, /*owns_queue=*/false);
 }
@@ -1224,8 +1225,8 @@ DeviceCapabilityConfig collect_metal_device_caps(MTLDevice_id mtl_device) {
                          MTLCommandQueue_id external_command_queue)
     : mtl_device_(mtl_device) {
   if (external_command_queue != nil) {
-    compute_stream_ =
-        std::unique_ptr<MetalStream>(MetalStream::create_with_external_queue(*this, external_command_queue));
+    compute_stream_ = std::unique_ptr<MetalStream>(
+        MetalStream::create_with_external_queue(*this, external_command_queue));
   } else {
     compute_stream_ = std::unique_ptr<MetalStream>(MetalStream::create(*this));
   }
@@ -1241,7 +1242,8 @@ DeviceCapabilityConfig collect_metal_device_caps(MTLDevice_id mtl_device) {
   MTLDevice_id mtl_device = MTLCreateSystemDefaultDevice();
   return new MetalDevice(mtl_device);
 }
-MetalDevice *MetalDevice::create_with_external_queue(uint64_t external_queue_ptr) {
+MetalDevice *
+MetalDevice::create_with_external_queue(uint64_t external_queue_ptr) {
   MTLDevice_id mtl_device = MTLCreateSystemDefaultDevice();
   auto *queue = reinterpret_cast<MTLCommandQueue_id>(external_queue_ptr);
   return new MetalDevice(mtl_device, queue);

tests/python/test_metal_shared_queue.py

@@ -1,11 +1,10 @@
 """Tests for the external Metal command queue feature (``external_metal_command_queue``)."""
 
-import platform
-
 import numpy as np
 import pytest
 
 import quadrants as qd
+
 from tests import test_utils