[Tensor] Support shape-axis layouts for vector and matrix tensors by hughperkins · Pull Request #991 · Genesis-Embodied-AI/quadrants

hughperkins · 2026-10-26T12:31:31Z

Builds on the helper renames in #994 and test organization in #996, both merged into main. This PR targets main, adds compound layouts, fuses NumPy import helpers, and removes obsolete layout-rejection and factory-hint tests.

Vector and matrix tensors now accept shape-axis layout= permutations through all three factories: qd.tensor, qd.Vector.tensor, and qd.Matrix.tensor. Both FIELD and NDARRAY backends keep component axes innermost and user-facing indexing canonical.

For example, qd.Vector.tensor(3, qd.f32, shape=(4, 5), layout=(1, 0)) uses physical storage order (5, 4, 3) while exporting canonical shape (4, 5, 3).

Delegate the vector/matrix convenience factories to the generic factory so layout validation and allocation are shared.
Extend ndarray DLPack permutations with unchanged component axes, and use canonical shapes for NumPy/Torch imports and exports.
Add _total_canonical_shape() and unify scalar, vector, and matrix NumPy imports in _copy_from_numpy(), sharing validation and synchronization while retaining the existing copy kernels.
Preserve layout through vector/matrix pickle reconstruction and deepcopy, retaining compatibility with older pickles.
Document the semantics and cover indexing, iteration, copied and zero-copy interop, copying across layouts, serialization, gradients, validation, and kernel specialization.

Validation:

Representative cases at 4722e3f3d: 87 CPU/CUDA tests passed across compound layouts and convenience factories. Each general compound-layout test has one parameterization covering all four backend/type pairs. Dtype constants were subsequently inlined into the cases; formatting and lint checks passed.
At 5a3479a9b, general compound-layout tests run on all enabled architectures. The available CPU/CUDA environment passed 179 cases with python tests/run_tests.py -v -t 2 test_tensor_compound_layout test_tensor_factory_vec_mat. NumPy zero-copy remains CPU-only; Torch/DLPack excludes Vulkan and skips Metal FIELD sharing on unsupported PyTorch versions. Metal, AMDGPU, and Vulkan were unavailable in this validation environment.
After stacking on [Tensor] Move test_tensor_pr560_fixes.py tests into other test files #996, all 16 relocated regressions passed on CPU at abc6cf109, including the updated factory-hint tests. The unchanged 16 tests also passed independently on the [Tensor] Move test_tensor_pr560_fixes.py tests into other test files #996 base.
_total_physical_layout() extraction at bfa0e9148: 227 CPU/CUDA compound-layout and interop cases passed, with 2 skips. The subsequent variable rename and merge of main passed formatting, lint, and non-ASCII checks; the merge leaves branch file contents unchanged.
Stacked branch at ed7b8ffda: 589 CPU/CUDA cases passed across ndarray, factories, compound layouts, error handling, gradients, wrapper surface, and layouts. The subsequent base-branch ASCII punctuation fix leaves this branch's file contents unchanged.
At 22c0cceca: 412 CPU/CUDA ndarray and layout cases passed after unifying NumPy imports. The subsequent _copy_to_torch() rename passed formatting and lint checks.
At 3062f762c: 122 compound-layout CPU/CUDA cases passed after adding _total_canonical_shape(), including copied and zero-copy Torch interop.
At 9d5be3558: C++ rebuild succeeded; 412 ndarray and layout CPU/CUDA cases passed after the physical-shape rename.
At b09c32bd577085dd5ad9249680e3d6083d510b59: 383 CPU/CUDA cases passed after removing the private factory helpers. These cover factories, compound layouts, error messages, gradients, wrappers, and layouts.
The earlier run at eeb56dca6282854e2fdef67783b3ba1b897e2be4 also passed 589 existing regression cases, with 2 skips.
Pre-commit checks passed. Pyright: 0 errors, 8 warnings.

Reproduce the shape-helper validation with:

python tests/run_tests.py --arch cpu,cuda -v -t 2 test_ndarray test_tensor_compound_layout test_tensor_layout

Reproduce the factory validation with:

python tests/run_tests.py --arch cpu,cuda -v -t 2 \
  test_tensor_factory_vec_mat test_tensor_compound_layout \
  test_tensor_grad test_tensor_wrapper_surface test_tensor_layout

The earlier regression run also exercised:

python tests/run_tests.py --arch cpu,cuda -v -t 2 \
  test_tensor_layout test_tensor_factory_vec_mat test_tensor_factory_layout_ndarray \
  test_tensor_wrapper_surface test_tensor_layout_host_indexing test_tensor_layout_interop \
  test_tensor_layout_grad test_ndarray test_pickle

Fixes #936.

chatgpt-codex-connector · 2026-10-26T12:31:47Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	🔄 Running since 2026-10-28T19:05:56.449446Z	`881016c`	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

github-actions · 2026-10-26T13:02:48Z

Total: 5 file(s) changed, +202 -31 code lines.

hughperkins · 2026-10-26T13:40:35Z

this file seems ok-ish

github-actions · 2026-10-26T13:41:00Z

Diff coverage: 79% · 197 lines, 42 missing

hughperkins · 2026-10-26T13:47:09Z

this file okish

hughperkins · 2026-10-26T14:04:21Z

    return t


 def _rebuild_matrix_tensor(


_rebuild_matrix_tensor function ok

hughperkins · 2026-10-26T14:04:31Z

    return t  # type: ignore[reportReturnType]


 def _rebuild_vector_tensor(


_rebuild_vector_tensor function ok

hughperkins · 2026-10-26T14:05:43Z

    def element_shape(self) -> typing.Tuple[int, ...]:
        return _element_shape_of(self._impl)

    def __reduce__(self) -> typing.Tuple[typing.Any, typing.Tuple[typing.Any, ...]]:


reduce function ok

hughperkins · 2026-10-26T14:06:24Z

this file changs ok

hughperkins · 2026-10-26T14:14:12Z

 # work on one backend and raise cryptic errors deep in the other. Users who need backend-specific knobs (e.g.
 # ``offset=`` for field offset indexing, ``order=`` for SoA layouts) should call ``qd.field`` / ``qd.ndarray`` directly
 # — they have explicitly opted out of the unified tensor API.
-#


this change ok

hughperkins · 2026-10-26T14:14:58Z

+_TENSOR_ACCEPTED_KWARGS = frozenset({"backend", "needs_grad", "layout"})


 def _validate_kwargs(kwargs, *, factory_name, accepted):


changes in _validate_kwargs function ok

hughperkins · 2026-10-26T14:17:21Z

    return "".join(chr(ord("i") + axis) for axis in layout)


 def tensor(dtype, shape, *, backend=Backend.NDARRAY, layout=None, **kwargs):


tensor function ok

github-actions · 2026-10-26T14:46:16Z

Total: 8 file(s) changed, +242 -65 code lines.

github-actions · 2026-10-26T15:43:46Z

Diff coverage: 82% · 237 lines, 42 missing

hughperkins · 2026-10-26T17:05:26Z

this file ok

github-actions · 2026-10-26T17:27:44Z

Total: 8 file(s) changed, +241 -70 code lines.

hughperkins · 2026-10-28T12:53:29Z

this file ok (reviwed earelir, before the rename/mege)

hughperkins · 2026-10-28T13:09:45Z

+    reason="Coverage probes change the kernel AST, preventing offline cache hits after reinit",
+)
+@test_utils.test()
+def test_compound_layout_offline_cache(backend: qd.Backend, dtype: MatrixType, tmp_path: Path) -> None:


test_compound_layout_offline_cache ok 🥵

hughperkins · 2026-10-28T13:14:09Z

+    ],
+)
+@test_utils.test()
+def test_compound_layout_fastcache(dtype: MatrixType, tmp_path: Path) -> None:


test_compound_layout_fastcache ok

hughperkins · 2026-10-28T13:14:22Z

this file ok 🙌

hughperkins · 2026-10-28T13:14:58Z

Finally, review ok 🙌

Lets wait for CI green-ish, and recheck Mr Codex review.

hughperkins · 2026-10-28T13:15:09Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5e13254c79

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

github-actions · 2026-10-28T13:47:09Z

Total: 9 file(s) changed, +672 -113 code lines.

github-actions · 2026-10-28T14:53:58Z

Diff coverage: 74% · 413 lines, 106 missing

hughperkins · 2026-10-28T17:58:02Z

+@test_utils.test()
+def test_compound_layout_grad(backend: qd.Backend, dtype: MatrixType, request: pytest.FixtureRequest) -> None:
+    """Check that gradients retain the layout and compute correct values across different input and output layouts."""
+    if sys.platform == "darwin" and qd.lang.impl.current_cfg().arch == qd.vulkan and backend == qd.Backend.NDARRAY:


this xfail seems ok-ish

hughperkins · 2026-10-28T17:58:47Z

Ok, so we'll merged once CI green-ish.

github-actions · 2026-10-28T18:23:01Z

Total: 9 file(s) changed, +681 -113 code lines.

hughperkins · 2026-10-28T18:49:40Z

github-actions · 2026-10-28T18:50:29Z

Diff coverage: 73% · 416 lines, 114 missing

hughperkins · 2026-10-28T19:05:09Z

@codex review

github-actions · 2026-10-28T19:23:16Z

Total: 9 file(s) changed, +681 -113 code lines.

github-actions · 2026-10-28T20:35:26Z

Diff coverage: 76% · 416 lines, 98 missing

github-actions · 2026-10-28T22:27:18Z

Total: 9 file(s) changed, +695 -113 code lines.

github-actions · 2026-10-28T23:32:18Z

Diff coverage: 93% · 430 lines, 31 missing

hughperkins added 2 commits October 26, 2026 05:19

Support shape-axis layouts for compound tensors

dcb34c6

Clarify compound tensor reconstruction return types

eeb56dc

hughperkins changed the title ~~Support shape-axis layouts for vector and matrix tensors~~ [Tensor] Support shape-axis layouts for vector and matrix tensors Oct 26, 2026