[Misc] Forward copy= through qd.Tensor, add copy=None option (#616)

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

Author: hughperkins

docs/source/user_guide/interop.md

@@ -79,12 +79,13 @@ Quadrants' zero-copy interop has been designed with **PyTorch as the first-class
 ```python
 f = qd.field(qd.f32, shape=(1024,))
 
-view  = f.to_torch(copy=False)  # zero-copy view: aliases f's memory
+view  = f.to_torch(copy=False)  # zero-copy view: aliases f's memory, or ValueError
+auto  = f.to_torch(copy=None)   # zero-copy if possible, otherwise copy
 clone = f.to_torch(copy=True)   # independent copy (default)
-auto  = f.to_torch()            # same as copy=True
+plain = f.to_torch()            # same as copy=True
 ```
 
-When using `copy=False`, modifications via the view are visible to subsequent Quadrants kernel reads, and vice-versa. The view stays valid until the underlying storage is reallocated -- typically on `qd.init()` or `qd.reset()`, after which a fresh call to `to_torch(copy=False)` / `to_numpy(copy=False)` returns a new view.
+When using `copy=False` or `copy=None` (when zero-copy succeeds), modifications via the view are visible to subsequent Quadrants kernel reads, and vice-versa. The view stays valid until the underlying storage is reallocated -- typically on `qd.init()` or `qd.reset()`, after which a fresh call to `to_torch(copy=False)` / `to_numpy(copy=False)` returns a new view.
 
 ### When zero-copy is available
 
@@ -105,9 +106,10 @@ On **NumPy >= 2.1**, `to_numpy(copy=False)` returns a **writable** array (via a
 | Value | Behaviour |
 |---|---|
 | `True` (default) | Independent copy via kernel. |
+| `None` | Zero-copy view via DLPack when available, otherwise falls back to a copy silently. |
 | `False` | Zero-copy view via DLPack, or `ValueError` if zero-copy is unsupported for this backend/dtype. |
 
-The default `copy=True` always returns a buffer that is safe to mutate without affecting the field/ndarray.
+The default `copy=True` always returns a buffer that is safe to mutate without affecting the field/ndarray. Use `copy=None` when you want zero-copy as a best-effort optimisation without having to handle exceptions — it gives you a view when possible and a safe copy otherwise.
 
 ### Examples
 
@@ -304,8 +306,9 @@ print(x.grad[0])  # 4.0
 |--------|-------------|-------------------|---------------------|
 | `to_numpy()` / `from_numpy()` (default) | yes | yes | yes |
 | `to_torch()` / `from_torch()` (default) | yes | yes | yes |
+| `to_numpy(copy=None)` / `to_torch(copy=None)` | no when possible, yes otherwise | yes | yes |
 | `to_numpy(copy=False)` / `to_torch(copy=False)` | no (DLPack view) | yes | yes |
 | `to_dlpack()` | no (raw capsule) | yes | yes |
 | Direct pass-through | no | no | yes (as kernel arg) |
 
-The `copy` parameter is supported on `to_numpy()` and `to_torch()` for `ScalarField`, `MatrixField` (and `VectorField`), `StructField`, and all `Ndarray` types. See [Zero-copy interop via DLPack](#zero-copy-interop-via-dlpack) for the support matrix and lifetime rules.
+The `copy` parameter is supported on `to_numpy()` and `to_torch()` for `ScalarField`, `MatrixField` (and `VectorField`), `StructField`, `qd.Tensor`, and all `Ndarray` types. See [Zero-copy interop via DLPack](#zero-copy-interop-via-dlpack) for the support matrix and lifetime rules.

docs/source/user_guide/tensor.md

@@ -151,6 +151,33 @@ a.from_torch(out)
 
 The exact same surface is available on both backends — switching `qd.tensor(..., backend=qd.Backend.FIELD/NDARRAY)` does not require any other code change at the call site.
 
+### Zero-copy with `copy=False`
+
+`to_numpy()` and `to_torch()` accept a keyword-only `copy` argument:
+
+```python
+a = qd.tensor(qd.f32, shape=(1024,))
+a.fill(1.0)
+
+view  = a.to_torch(copy=False)   # zero-copy: aliases a's memory, or ValueError
+auto  = a.to_torch(copy=None)    # zero-copy if possible, otherwise copy
+clone = a.to_torch(copy=True)    # independent copy (default)
+```
+
+| Value | Behaviour |
+|---|---|
+| `True` (default) | Independent copy via kernel. Safe to mutate freely. |
+| `None` | Zero-copy when available, otherwise falls back to a copy silently. |
+| `False` | Zero-copy DLPack view, or `ValueError` if unsupported for this backend/dtype. |
+
+`copy=False` and `copy=None` avoid both the buffer allocation and the copy kernel when zero-copy is available — the returned numpy array or torch tensor points directly at Quadrants' existing memory. For a large tensor this eliminates a potentially expensive memcpy and a device-side kernel launch. Writes through the view are immediately visible to subsequent Quadrants kernels (and vice versa), removing the need for `to_torch` → modify → `from_torch` round-trips.
+
+The difference between `False` and `None`: `copy=False` raises `ValueError` when zero-copy is not supported (e.g. unsupported dtype or GPU-to-numpy), while `copy=None` silently falls back to a kernel copy in those cases. Use `copy=None` when you want zero-copy as a best-effort optimisation without having to handle exceptions.
+
+The tradeoff of zero-copy is lifetime coupling: the view is invalidated on `qd.reset()` or `qd.init()`, and on GPU you must be mindful of stream synchronisation when both frameworks write to the same buffer.
+
+This works identically on both backends. For the full support matrix (which backends/dtypes qualify, lifetime caveats, Metal synchronisation) see [`interop`](interop.md#zero-copy-interop-via-dlpack).
+
 Gradient buffers behave identically: `a.grad.to_numpy()` returns the canonical view of the gradient.
 
 ## Annotating kernel arguments: `qd.Tensor`

python/quadrants/_tensor_wrapper.py

@@ -189,18 +189,20 @@ def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
     # Interop forwards (layout-aware on both impls already)
     # ------------------------------------------------------------------
 
-    def to_numpy(self, dtype: typing.Any = None) -> typing.Any:
-        if dtype is None:
-            return self._impl.to_numpy()
-        return self._impl.to_numpy(dtype=dtype)
+    def to_numpy(self, dtype: typing.Any = None, *, copy: typing.Optional[bool] = True) -> typing.Any:
+        kw: dict[str, typing.Any] = {"copy": copy}
+        if dtype is not None:
+            kw["dtype"] = dtype
+        return self._impl.to_numpy(**kw)
 
     def from_numpy(self, arr: typing.Any) -> None:
         self._impl.from_numpy(arr)
 
-    def to_torch(self, device: typing.Any = None) -> typing.Any:
-        if device is None:
-            return self._impl.to_torch()
-        return self._impl.to_torch(device=device)
+    def to_torch(self, device: typing.Any = None, *, copy: typing.Optional[bool] = True) -> typing.Any:
+        kw: dict[str, typing.Any] = {"copy": copy}
+        if device is not None:
+            kw["device"] = device
+        return self._impl.to_torch(**kw)
 
     def from_torch(self, arr: typing.Any) -> None:
         self._impl.from_torch(arr)

python/quadrants/lang/_ndarray.py

@@ -477,18 +477,22 @@ def to_numpy(self, dtype=None, *, copy=True):
 
         Args:
             dtype: Optional numpy dtype to cast the result to. ``None`` keeps the native ndarray dtype.
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
         """
-        if copy is False:
+        if copy is not True:
             from quadrants.lang.field import (  # pylint: disable=C0415
                 _try_zerocopy_numpy,
             )
 
-            arr = _try_zerocopy_numpy(self, copy=False, is_ndarray=True)
+            arr = _try_zerocopy_numpy(self, copy=copy, is_ndarray=True)
             if arr is not None:
                 if dtype is not None and arr.dtype != dtype:
-                    raise ValueError(f"copy=False is incompatible with dtype conversion ({arr.dtype} -> {dtype})")
-                return arr
+                    if copy is False:
+                        raise ValueError(f"copy=False is incompatible with dtype conversion ({arr.dtype} -> {dtype})")
+                    # copy=None: fall through to the copy path for dtype conversion
+                else:
+                    return arr
 
         arr = self._ndarray_to_numpy()
         if dtype is not None and arr.dtype != dtype:
@@ -508,14 +512,17 @@ def to_torch(self, device=None, *, copy=True):
         view just like ``to_numpy()`` does.
 
         Args:
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
         """
-        if copy is False:
+        if copy is not True:
             from quadrants.lang.field import (  # pylint: disable=C0415
                 _try_zerocopy_torch,
             )
 
-            return _try_zerocopy_torch(self, copy=copy, device=device, is_ndarray=True)
+            result = _try_zerocopy_torch(self, copy=copy, device=device, is_ndarray=True)
+            if result is not None:
+                return result
 
         import torch  # pylint: disable=C0415
 

python/quadrants/lang/field.py

@@ -204,20 +204,25 @@ def _can_zerocopy_field(field: "Field", *, is_scalar: bool = False, is_ndarray:
 def _try_zerocopy_torch(field: "Field", *, copy, device=None, is_scalar: bool = False, is_ndarray: bool = False):
     """Try to return a zero-copy torch tensor via DLPack.
 
-    Only called when ``copy is False``. Returns the tensor on success. Raises ``ValueError`` when zero-copy is not
-    available. Does NOT call ``torch.mps.synchronize()`` -- the caller is expected to handle MPS sync for the copy=True
-    (kernel-copy) path instead.
+    Returns the tensor on success. When ``copy is False``, raises ``ValueError`` if zero-copy is not available. When
+    ``copy is None``, returns ``None`` if zero-copy is not available (allowing the caller to fall back to a copy). Does
+    NOT call ``torch.mps.synchronize()`` -- the caller is expected to handle MPS sync for the copy=True (kernel-copy)
+    path instead.
     """
     if not _can_zerocopy_field(field, is_scalar=is_scalar, is_ndarray=is_ndarray):
-        raise ValueError(f"Zero-copy not available for arch={impl.current_cfg().arch.name}, dtype={field.dtype}")
+        if copy is False:
+            raise ValueError(f"Zero-copy not available for arch={impl.current_cfg().arch.name}, dtype={field.dtype}")
+        return None
 
     import torch  # pylint: disable=C0415
     import torch.utils.dlpack  # pylint: disable=C0415
 
     try:
         tc = torch.utils.dlpack.from_dlpack(field.to_dlpack())
     except RuntimeError as e:
-        raise ValueError(f"Zero-copy not available: {e}") from None
+        if copy is False:
+            raise ValueError(f"Zero-copy not available: {e}") from None
+        return None
     if impl.current_cfg().arch == _ARCH_METAL:
         impl.get_runtime().sync()
 
@@ -228,9 +233,11 @@ def _try_zerocopy_torch(field: "Field", *, copy, device=None, is_scalar: bool =
             requested.index is not None and tc.device.index is not None and tc.device.index != requested.index
         )
         if type_mismatch or index_mismatch:
-            raise ValueError(
-                f"copy=False is incompatible with device transfer (data on {tc.device}, requested {device})"
-            )
+            if copy is False:
+                raise ValueError(
+                    f"copy=False is incompatible with device transfer (data on {tc.device}, requested {device})"
+                )
+            return None
 
     return tc
 
@@ -431,7 +438,8 @@ def to_numpy(self, dtype: DataTypeCxx | None = None, *, copy=True):
         """Converts `self` to a numpy array.
 
         Args:
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
 
         Returns:
             numpy.ndarray: The result numpy array.
@@ -444,7 +452,8 @@ def to_torch(self, device=None, *, copy=True):
 
         Args:
             device (torch.device, optional): The desired device of returned tensor.
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
 
         Returns:
             torch.tensor: The result torch tensor.
@@ -604,14 +613,17 @@ def to_numpy(self, dtype=None, *, copy=True):
 
         Args:
             dtype: Optional target numpy dtype.
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
         """
-        if copy is False:
-            arr = _try_zerocopy_numpy(self, copy=False, is_scalar=True)
+        if copy is not True:
+            arr = _try_zerocopy_numpy(self, copy=copy, is_scalar=True)
             if arr is not None:
                 if dtype is not None and arr.dtype != dtype:
-                    raise ValueError(f"copy=False is incompatible with dtype conversion ({arr.dtype} -> {dtype})")
-                return arr
+                    if copy is False:
+                        raise ValueError(f"copy=False is incompatible with dtype conversion ({arr.dtype} -> {dtype})")
+                else:
+                    return arr
 
         if self.parent()._snode.ptr.type == _qd_core.SNodeType.dynamic:
             warn(
@@ -634,10 +646,13 @@ def to_torch(self, device=None, *, copy=True):
 
         Args:
             device: Optional torch device for the returned tensor.
-            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises.
+            copy: ``True`` (default) returns an independent copy, ``False`` requires zero-copy or raises,
+                ``None`` uses zero-copy when available and falls back to a copy otherwise.
         """
-        if copy is False:
-            return _try_zerocopy_torch(self, copy=copy, device=device, is_scalar=True)
+        if copy is not True:
+            result = _try_zerocopy_torch(self, copy=copy, device=device, is_scalar=True)
+            if result is not None:
+                return result
 
         import torch  # pylint: disable=C0415