autoarray 2026.9.26.1__tar.gz → 2026.9.27.2__tar.gz

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/AGENTS.md

@@ -138,3 +138,17 @@ outlives the turn to wait for CI, a review or a merge: no `send_later`, no
 armed hourly check-ins on 2026-08-31, and a mobile `/prm` re-armed a 60-minute
 `send_later` hourly all night on 2026-09-03 with no task active, draining usage.
 <!-- repos_sync:deliverable:end -->
+
+<!-- repos_sync:filing:begin -->
+## Where to file
+
+Questions, help with code or an analysis, ideas, bug reports and results from a
+user or collaborator — or an agent acting for one — go to
+<https://github.com/orgs/PyAutoLabs/discussions> in the matching category
+(Help & Questions, Ideas & Proposals, Bugs & Errors, Show and tell;
+Announcements is maintainers-only), never to this repo's Issues. An agent never
+runs `gh issue create` for such a report: it drafts the title, category and
+body and hands them to the human (sessions cannot create Discussions). Only the
+development flow — Mind prompt → `/start_dev` → `/create_issue` → one issue per
+task → PR — opens issues here. Why: `PyAutoMind/policy/community_surface.md`.
+<!-- repos_sync:filing:end -->

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autoarray
-Version: 2026.9.26.1
+Version: 2026.9.27.2
 Summary: PyAuto Data Structures
 Author-email: James Nightingale <James.Nightingale@newcastle.ac.uk>, Richard Hayes <richard@rghsoftware.co.uk>
 License: MIT

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/__init__.py

@@ -111,7 +111,7 @@ conf.instance.register(__file__)
 # Last manual sync of the source stamp. Release wheels are stamped at build
 # time and the git tag is the release truth — deliberately never bumped per
 # release (PyAutoBuild#118/#120).
-__version__ = "2026.9.26.1"
+__version__ = "2026.9.27.2"
 
 # ---------------------------------------------------------------------------
 # Public re-export of the autonerves configuration / serialization surface.

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/inversion/inversion/dataset_interface.py

@@ -8,6 +8,7 @@ class DatasetInterface:
         transformer=None,
         sparse_operator=None,
         noise_covariance_matrix=None,
+        sparse_dirty_image=None,
     ):
         """
         Generic class which acts as an interface between a dataset and an inversion.
@@ -49,6 +50,13 @@ class DatasetInterface:
         noise_covariance_matrix
             A noise-map covariance matrix representing the covariance between noise in every `data` value, which
             can be used via a bespoke fit to account for correlated noise in the data.
+        sparse_dirty_image
+            The noise-weighted dirty image `Re(Fᴴ W d)` of this interface's `data`, used by the sparse (w-tilde)
+            interferometer inversion to form its data vector. The `sparse_operator` caches the dirty image of the
+            visibilities it was built from, so this is only needed when `data` differs from them (e.g. when the
+            visibilities of ordinary light profiles have been subtracted). If `None`, the operator's cached dirty
+            image is used. This is distinct from `Interferometer.dirty_image`, the unweighted dirty image of the
+            data used for visualization.
         """
         self.data = data
         self.noise_map = noise_map
@@ -57,6 +65,7 @@ class DatasetInterface:
         self.transformer = transformer
         self.sparse_operator = sparse_operator
         self.noise_covariance_matrix = noise_covariance_matrix
+        self.sparse_dirty_image = sparse_dirty_image
 
     @property
     def mask(self):

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/inversion/inversion/factory.py

@@ -125,6 +125,10 @@ def inversion_imaging_from(
     An `Inversion` whose type is determined by the input `dataset` and `settings`.
     """
 
+    # Unlike `inversion_interferometer_from`, imaging keeps func-list-only inversions (e.g. an MGE with no
+    # pixelization) on the mapping formalism. A func-list-only imaging mapping inversion is cheap (one PSF
+    # convolution per basis function), and the imaging sparse data vector's handling of profile-subtracted
+    # data is tracked separately, so the interferometer routing change is deliberately not mirrored here.
     use_sparse_operator = True
 
     if all(
@@ -199,15 +203,12 @@ def inversion_interferometer_from(
     -------
     An `Inversion` whose type is determined by the input `dataset` and `settings`.
     """
-    use_sparse_operator = True
-
-    if all(
-        isinstance(linear_obj, AbstractLinearObjFuncList)
-        for linear_obj in linear_obj_list
-    ):
-        use_sparse_operator = False
-
-    if dataset.sparse_operator is not None and use_sparse_operator:
+    # A sparse operator selects the w-tilde formalism for every linear object list, including func-list-only
+    # ones (e.g. an MGE with no pixelization). For interferometer data this avoids the dense
+    # `transform_mapping_matrix` of shape (N_vis, S), which dominates run time and memory at large N_vis, and
+    # `InversionInterferometerSparse` handles zero mappers (the func-func curvature blocks and the data vector
+    # need no mapper). `_use_interferometer_numba` returns False whenever a func-list is present.
+    if dataset.sparse_operator is not None:
 
         if _use_interferometer_numba(
             linear_obj_list=linear_obj_list,

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/inversion/inversion/interferometer/mapping.py

@@ -1,6 +1,8 @@
 import numpy as np
 from typing import Dict, List, Union
 
+from autonerves import cached_property
+
 from autoarray.dataset.interferometer.dataset import Interferometer
 from autoarray.inversion.inversion.dataset_interface import DatasetInterface
 from autoarray.inversion.inversion.interferometer.abstract import (
@@ -50,7 +52,7 @@ class InversionInterferometerMapping(AbstractInversionInterferometer):
             dataset=dataset, linear_obj_list=linear_obj_list, settings=settings, xp=xp
         )
 
-    @property
+    @cached_property
     def data_vector(self) -> np.ndarray:
         """
         The `data_vector` is a 1D vector whose values are solved for by the simultaneous linear equations constructed
@@ -71,7 +73,7 @@ class InversionInterferometerMapping(AbstractInversionInterferometer):
             noise_map=self.noise_map,
         )
 
-    @property
+    @cached_property
     def curvature_matrix(self) -> np.ndarray:
         """
         The `curvature_matrix` is a 2D matrix which uses the mappings between the data and the linear objects to

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/inversion/inversion/interferometer/sparse.py

@@ -1,6 +1,8 @@
 import numpy as np
 from typing import Dict, List, Optional, Union
 
+from autonerves import cached_property
+
 from autoarray import exc
 from autoarray.dataset.interferometer.dataset import Interferometer
 from autoarray.inversion.inversion.dataset_interface import DatasetInterface
@@ -67,7 +69,7 @@ class InversionInterferometerSparse(AbstractInversionInterferometer):
             preloads=preloads,
         )
 
-    @property
+    @cached_property
     def data_vector(self) -> np.ndarray:
         """
         The `data_vector` is a 1D vector whose values are solved for by the simultaneous linear equations constructed
@@ -88,10 +90,18 @@ class InversionInterferometerSparse(AbstractInversionInterferometer):
           which is exactly the entry the mapping (dense) formalism computes via the linear
           function's transformed mapping matrix. Linear function lists therefore require no
           separate branch here.
+
+        The cached dirty image is that of the visibilities the `sparse_operator` was built from. When
+        the inversion's data differs from them (e.g. a `DatasetInterface` whose data has the visibilities
+        of ordinary light profiles subtracted), the dataset's `sparse_dirty_image` of that data is used
+        instead, so that `D` is consistent with the data the chi-squared is computed from.
         """
-        return self._xp.dot(
-            self.mapping_matrix.T, self.dataset.sparse_operator.dirty_image
-        )
+        dirty_image = getattr(self.dataset, "sparse_dirty_image", None)
+
+        if dirty_image is None:
+            dirty_image = self.dataset.sparse_operator.dirty_image
+
+        return self._xp.dot(self.mapping_matrix.T, dirty_image)
 
     def _sparse_triplets_curvature_from(self, mapper: Mapper):
         """
@@ -121,7 +131,7 @@ class InversionInterferometerSparse(AbstractInversionInterferometer):
             xp=self._xp,
         )
 
-    @property
+    @cached_property
     def curvature_matrix(self) -> np.ndarray:
         """
         The `curvature_matrix` is a 2D matrix which uses the mappings between the data and the linear objects to
@@ -179,7 +189,7 @@ class InversionInterferometerSparse(AbstractInversionInterferometer):
 
         return curvature_matrix
 
-    @property
+    @cached_property
     def curvature_matrix_diag(self) -> np.ndarray:
         """
         The `curvature_matrix` is a 2D matrix which uses the mappings between the data and the linear objects to

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/inversion/inversion/interferometer_numba/sparse.py

@@ -181,7 +181,7 @@ class InversionInterferometerSparseNumba(InversionInterferometerSparse):
 
         return inputs
 
-    @property
+    @cached_property
     def curvature_matrix_diag(self) -> np.ndarray:
         """
         `F = Aᵀ W~ A` for the inversion's single mapper, from the `direct_conv` numba

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/operators/transformer.py

@@ -199,9 +199,12 @@ class TransformerDFT:
         mask as this transformer's `real_space_mask`.
         """
         image_slim = transformer_util.image_direct_from(
-            visibilities=visibilities.in_array,
+            visibilities=xp.stack(
+                (xp.real(visibilities.array), xp.imag(visibilities.array)), axis=-1
+            ),
             grid_radians=self.grid.array,
             uv_wavelengths=self.uv_wavelengths,
+            xp=xp,
         )
 
         image_native = array_2d_util.array_2d_native_from(
@@ -522,14 +525,15 @@ class TransformerNUFFT:
         if xp.__name__.startswith("jax"):
             import jax.numpy as jnp
 
-            mm_T = jnp.asarray(mapping_matrix).T.astype(jnp.complex128)
-            source_images = jnp.zeros((n_src, n_y, n_x), dtype=jnp.complex128)
+            # Real scatter, then cast: GPU complex128 scatter floor (autolens_profiling#308).
+            mm_T = jnp.asarray(mapping_matrix).T
+            source_images = jnp.zeros((n_src, n_y, n_x), dtype=mm_T.dtype)
             source_images = source_images.at[
                 jnp.arange(n_src)[:, None],
                 jnp.asarray(rows)[None, :],
                 jnp.asarray(cols)[None, :],
             ].set(mm_T)
-            flipped = source_images[:, ::-1, :]
+            flipped = source_images[:, ::-1, :].astype(jnp.complex128)
             x = jnp.asarray(self._x)
             y = jnp.asarray(self._y)
             shift = jnp.asarray(self._shift)
@@ -539,10 +543,11 @@ class TransformerNUFFT:
             )
             return vis_batched.T
 
-        mm_T = np.asarray(mapping_matrix).T.astype(np.complex128)
-        source_images = np.zeros((n_src, n_y, n_x), dtype=np.complex128)
+        # Real scatter, then cast: GPU complex128 scatter floor (autolens_profiling#308).
+        mm_T = np.asarray(mapping_matrix).T
+        source_images = np.zeros((n_src, n_y, n_x), dtype=mm_T.dtype)
         source_images[np.arange(n_src)[:, None], rows[None, :], cols[None, :]] = mm_T
-        flipped = source_images[:, ::-1, :]
+        flipped = source_images[:, ::-1, :].astype(np.complex128)
         vis_batched = (
             _nufftax.nufft2d2(self._x, self._y, flipped, self.eps, -1)
             * self._shift[None, :]

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/operators/transformer_util.py

@@ -50,7 +50,10 @@ def visibilities_from(
 
 
 def image_direct_from(
-    visibilities: np.ndarray, grid_radians: np.ndarray, uv_wavelengths: np.ndarray
+    visibilities: np.ndarray,
+    grid_radians: np.ndarray,
+    uv_wavelengths: np.ndarray,
+    xp=np,
 ) -> np.ndarray:
     """
     Reconstruct a real-valued sky image from complex interferometric visibilities
@@ -69,6 +72,8 @@ def image_direct_from(
 
     uv_wavelengths
         The (u, v) spatial frequencies in units of wavelengths for each baseline.
+    xp
+        The array module (`numpy` or `jax.numpy`) the transform is computed with.
 
     Returns
     -------
@@ -78,15 +83,15 @@ def image_direct_from(
     # Compute the phase term for each (pixel, visibility) pair
     phase = (
         2.0
-        * np.pi
+        * xp.pi
         * (
-            np.outer(grid_radians[:, 1], uv_wavelengths[:, 0])
-            + np.outer(grid_radians[:, 0], uv_wavelengths[:, 1])
+            xp.outer(grid_radians[:, 1], uv_wavelengths[:, 0])
+            + xp.outer(grid_radians[:, 0], uv_wavelengths[:, 1])
         )
     )
 
-    real_part = np.dot(np.cos(phase), visibilities[:, 0])
-    imag_part = np.dot(np.sin(phase), visibilities[:, 1])
+    real_part = xp.dot(xp.cos(phase), visibilities[:, 0])
+    imag_part = xp.dot(xp.sin(phase), visibilities[:, 1])
 
     image_1d = real_part - imag_part
 

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/structures/triangles/array.py

@@ -1,11 +1,60 @@
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
 import numpy as np
 
 from autoarray.structures.triangles.abstract import HEIGHT_FACTOR
 
 from autoarray.structures.triangles.abstract import AbstractTriangles
+from autoarray.structures.triangles.shape import Point
 from autoarray.structures.triangles.shape import Shape
+from autoarray.structures.triangles.shape import _barycentric_contains
+
+MAX_CONTAINING_SIZE = 20
+
+# Private A/B switch for the step-0 containment route (point-source CPU phase 4b,
+# PyAutoArray#579). It only affects `ArrayTriangles` built by
+# `CoordinateArrayTriangles.with_vertices` on the static initial lattice (those carrying a
+# `Step0Layout`) and tested against a `Point`; every other containment keeps the general
+# `shape.mask(self.triangles)` path. All routes return bit-identical kept indices:
+#
+# - "gather":     the general path -- pad, ``(N, 3, 2)`` gather, no-op NaN ``where``.
+# - "nopad":      the ``(N, 3, 2)`` gather without the pad / NaN ``where`` (no index is -1).
+# - "components": six ``(N,)`` 1-D gathers, one per vertex component; no ``(N, 3, 2)`` array.
+# - "structured": strided slices of the traced vertex table reshaped to its lattice rows; no
+#                 gather at all, the boolean mask is interleaved back to triangle order.
+#
+# The switch is read at trace time: a jitted function must be re-traced (fresh closure plus
+# ``jax.clear_caches()``) after changing it.
+_STEP0_CONTAINMENT = "structured"
+
+
+@dataclass(frozen=True)
+class Step0Layout:
+    """
+    The closed-form layout of the static initial lattice's vertex table (see
+    `autoarray.structures.triangles.coordinate_array.static_lattice_layout`).
+
+    Every value is a Python int, so a layout is hashable and can sit in pytree aux data: under
+    ``jit`` / ``vmap`` it is a trace-time constant.
+
+    Attributes
+    ----------
+    n_rows, n_cols
+        The triangle lattice is ``n_rows x n_cols`` triangles, stored row-major.
+    grid
+        ``None`` when the vertex table does not follow the closed-form pattern (only the
+        "gather" / "nopad" / "components" routes then apply), else
+        ``(n_pairs, pair_width, pad, corners)``: the ``(V, 2)`` table padded by ``pad`` rows is a
+        ``(n_pairs, pair_width, 2)`` grid, and ``corners[p][k] = (p0, c0, na, nb)`` says that for
+        the parity class ``p = 2 * (i % 2) + (j % 2)`` of triangle row ``i`` and column ``j``,
+        vertex ``k`` of the class's triangle ``(a, b)`` (``i = 2a + i % 2``, ``j = 2b + j % 2``)
+        is grid entry ``(p0 + a, c0 + b)``.
+    """
 
-MAX_CONTAINING_SIZE = 15
+    n_rows: int
+    n_cols: int
+    grid: Optional[Tuple] = None
 
 
 class ArrayTriangles(AbstractTriangles):
@@ -14,6 +63,7 @@ class ArrayTriangles(AbstractTriangles):
         indices,
         vertices,
         max_containing_size=MAX_CONTAINING_SIZE,
+        step0_layout: Optional[Step0Layout] = None,
         **kwargs,
     ):
         """
@@ -26,10 +76,16 @@ class ArrayTriangles(AbstractTriangles):
             with the three indices of the vertices.
         vertices
             The vertices of the triangles.
+        step0_layout
+            Set only by `CoordinateArrayTriangles.with_vertices` on the static initial lattice:
+            the static layout of ``indices`` into ``vertices``, which lets `containing_indices`
+            test a `Point` without materialising the ``(N, 3, 2)`` triangle array (see
+            `_STEP0_CONTAINMENT`). A plain Python constant (pytree aux data), never traced.
         """
         self._indices = indices
         self._vertices = vertices
         self.max_containing_size = max_containing_size
+        self.step0_layout = step0_layout
 
     def __len__(self):
         return len(self.triangles)
@@ -159,7 +215,13 @@ class ArrayTriangles(AbstractTriangles):
         """
         import jax.numpy as jnp
 
-        inside = shape.mask(self.triangles)
+        inside = None
+        # Exactly `Point`: `Circle`, `Triangle`, `Polygon` and `Square` subclass `Point` but
+        # override `mask`, so they must keep the general path.
+        if self.step0_layout is not None and type(shape) is Point:
+            inside = self._step0_point_mask(shape)
+        if inside is None:
+            inside = shape.mask(self.triangles)
 
         return jnp.where(
             inside,
@@ -167,6 +229,70 @@ class ArrayTriangles(AbstractTriangles):
             fill_value=-1,
         )[0]
 
+    def _step0_point_mask(self, point: "Point"):
+        """
+        `Point.mask` of the static initial lattice without the general ``(N, 3, 2)`` gather, by
+        the route `_STEP0_CONTAINMENT` names; ``None`` selects the general path.
+
+        Every route feeds `_barycentric_contains` the same six component values the general path
+        takes from ``self.triangles`` (at step 0 no index is -1, so its NaN ``where`` is a no-op),
+        in the same operation order, so the mask -- and the kept indices -- are bit-identical.
+        """
+        import jax.numpy as jnp
+
+        route = _STEP0_CONTAINMENT
+        vertices = self.vertices
+        indices = self.indices
+
+        if route == "nopad":
+            return point.mask(vertices[indices])
+
+        if route == "components":
+            v0 = vertices[:, 0]
+            v1 = vertices[:, 1]
+            i0 = indices[:, 0]
+            i1 = indices[:, 1]
+            i2 = indices[:, 2]
+            return _barycentric_contains(
+                v0[i0], v1[i0], v0[i1], v1[i1], v0[i2], v1[i2], point.x, point.y
+            )
+
+        if route == "structured" and self.step0_layout.grid is not None:
+            n_rows = self.step0_layout.n_rows
+            n_cols = self.step0_layout.n_cols
+            n_pairs, pair_width, pad, corners = self.step0_layout.grid
+            if pad:
+                vertices = jnp.pad(vertices, ((0, pad), (0, 0)))
+            grid = vertices.reshape(n_pairs, pair_width, 2)
+
+            half_rows = (n_rows + 1) // 2
+            half_cols = (n_cols + 1) // 2
+
+            classes = []
+            for corner in corners:
+                components = []
+                for p0, c0, na, nb in corner:
+                    block = grid[p0 : p0 + na, c0 : c0 + nb]
+                    components += [block[..., 0], block[..., 1]]
+                na, nb = corner[0][2], corner[0][3]
+                mask = _barycentric_contains(*components, point.x, point.y)
+                classes.append(
+                    jnp.pad(mask, ((0, half_rows - na), (0, half_cols - nb)))
+                )
+
+            # classes[2 * pi + pj][a, b] is triangle (2a + pi, 2b + pj): interleave to row-major.
+            interleaved = jnp.stack(
+                (
+                    jnp.stack((classes[0], classes[1]), axis=-1),
+                    jnp.stack((classes[2], classes[3]), axis=-1),
+                ),
+                axis=1,
+            ).reshape(2 * half_rows, 2 * half_cols)
+
+            return interleaved[:n_rows, :n_cols].reshape(-1)
+
+        return None
+
     def for_indexes(self, indexes: np.ndarray) -> "ArrayTriangles":
         """
         Create a new ArrayTriangles containing indices and vertices corresponding to the given indexes
@@ -311,6 +437,7 @@ class ArrayTriangles(AbstractTriangles):
             indices=self.indices,
             vertices=vertices,
             max_containing_size=self.max_containing_size,
+            step0_layout=self.step0_layout,
         )
 
     def tree_flatten(self):
@@ -320,7 +447,7 @@ class ArrayTriangles(AbstractTriangles):
         return (
             self.indices,
             self.vertices,
-        ), (self.max_containing_size,)
+        ), (self.max_containing_size, self.step0_layout)
 
     @classmethod
     def tree_unflatten(cls, aux_data, children):
@@ -331,6 +458,7 @@ class ArrayTriangles(AbstractTriangles):
             indices=children[0],
             vertices=children[1],
             max_containing_size=aux_data[0],
+            step0_layout=aux_data[1],
         )
 
 

{autoarray-2026.9.26.1 → autoarray-2026.9.27.2}/autoarray/structures/triangles/coordinate_array.py

@@ -7,6 +7,7 @@ import numpy as np
 from autoarray.structures.triangles.abstract import HEIGHT_FACTOR
 from autoarray.structures.triangles.abstract import AbstractTriangles
 from autoarray.structures.triangles.array import ArrayTriangles
+from autoarray.structures.triangles.array import Step0Layout
 
 
 def _lattice_coordinates(
@@ -83,8 +84,27 @@ def static_vertex_table(
         axis=1,
     )
 
+    keys = _vertex_keys(coordinates)
+
+    _, first, inverse = np.unique(keys, axis=0, return_index=True, return_inverse=True)
+
+    vertices = np.ascontiguousarray(triangles.reshape(-1, 2)[first], dtype=np.float64)
+    indices = np.ascontiguousarray(inverse.reshape(-1, 3))
+
+    vertices.setflags(write=False)
+    indices.setflags(write=False)
+
+    return vertices, indices
+
+
+def _vertex_keys(coordinates: np.ndarray) -> np.ndarray:
+    """
+    The exact integer lattice key of every ``(3N)`` vertex slot, ordered as
+    `static_vertex_table` orders them (see its docstring).
+    """
+    flip = np.where((coordinates[:, 0] + coordinates[:, 1]) % 2 != 0, -1, 1)[:, None]
     offsets = np.array([[0, 1], [1, -1], [-1, -1]])
-    keys = np.stack(
+    return np.stack(
         (
             coordinates[:, None, 0] + flip * offsets[None, :, 0],
             2 * coordinates[:, None, 1] + flip * offsets[None, :, 1],
@@ -92,15 +112,90 @@ def static_vertex_table(
         axis=-1,
     ).reshape(-1, 2)
 
-    _, first, inverse = np.unique(keys, axis=0, return_index=True, return_inverse=True)
 
-    vertices = np.ascontiguousarray(triangles.reshape(-1, 2)[first], dtype=np.float64)
-    indices = np.ascontiguousarray(inverse.reshape(-1, 3))
+@lru_cache(maxsize=32)
+def static_lattice_layout(
+    y_min: float, y_max: float, x_min: float, x_max: float, scale: float
+) -> Step0Layout:
+    """
+    The closed-form layout of `static_vertex_table`'s index map, so the step-0 containment can
+    read each triangle's vertices by strided slicing instead of a gather (PyAutoArray#579).
+
+    The lattice's triangles are row-major, ``n_rows x n_cols``. The vertex table is sorted on the
+    integer key ``(ky, kx)``; key rows alternate between two widths ``W0, W1`` (equal when the
+    lattice has an odd number of columns), so the ``(V, 2)`` table -- padded by one row when the
+    number of key rows is odd -- is a ``(n_pairs, W0 + W1, 2)`` grid of row pairs. Splitting the
+    triangles into the four parity classes of their (row, column) index fixes each class's flip
+    and the parity of every vertex's key row, so vertex ``k`` of the class's triangle ``(a, b)``
+    is grid entry ``(p0 + a, c0 + b)``: one contiguous 2-D slice per class and vertex.
+
+    The layout is derived from, and checked element-wise against, the actual index map in NumPy:
+    if any class did not follow the strided pattern, ``grid`` is ``None`` and the structured
+    route is not used for this geometry. Built once per geometry (cached) and made only of Python
+    ints, so it is hashable pytree aux data.
+    """
+    vertices, indices = static_vertex_table(y_min, y_max, x_min, x_max, scale)
+    coordinates = _lattice_coordinates(y_min, y_max, x_min, x_max, scale)
 
-    vertices.setflags(write=False)
-    indices.setflags(write=False)
+    ys = np.unique(coordinates[:, 0])
+    xs = np.unique(coordinates[:, 1])
+    n_rows, n_cols = ys.shape[0], xs.shape[0]
 
-    return vertices, indices
+    grid_coordinates = np.stack(np.meshgrid(ys, xs, indexing="ij"), axis=-1)
+    if coordinates.shape[0] != n_rows * n_cols or not np.array_equal(
+        coordinates, grid_coordinates.reshape(-1, 2)
+    ):
+        return Step0Layout(n_rows=0, n_cols=0, grid=None)
+
+    unique_keys = np.unique(_vertex_keys(coordinates), axis=0)
+    _, row_counts = np.unique(unique_keys[:, 0], return_counts=True)
+    R = row_counts.shape[0]
+    W0 = int(row_counts[0])
+    W1 = int(row_counts[1]) if R > 1 else W0
+    if (
+        unique_keys.shape[0] != vertices.shape[0]
+        or np.any(row_counts[0::2] != W0)
+        or np.any(row_counts[1::2] != W1)
+    ):
+        return Step0Layout(n_rows=n_rows, n_cols=n_cols, grid=None)
+
+    # Key rows come in pairs of widths (W0, W1). Viewing the table as (n_pairs, W0 + W1, 2) --
+    # padded by one row when R is odd -- puts vertex (row r, column c) at
+    # (r // 2, (r % 2) * W0 + c).
+    pair_width = W0 + W1
+    n_pairs = (R + 1) // 2
+    row_start = np.concatenate(([0], np.cumsum(row_counts)[:-1]))
+    vertex_key_row = np.repeat(np.arange(R), row_counts)
+    vertex_key_col = np.arange(vertices.shape[0]) - row_start[vertex_key_row]
+    vertex_pair = (vertex_key_row // 2)[indices].reshape(n_rows, n_cols, 3)
+    vertex_offset = ((vertex_key_row % 2) * W0 + vertex_key_col)[indices].reshape(
+        n_rows, n_cols, 3
+    )
+
+    corners = []
+    for pi in (0, 1):
+        for pj in (0, 1):
+            corner = []
+            for k in range(3):
+                class_pair = vertex_pair[pi::2, pj::2, k]
+                class_offset = vertex_offset[pi::2, pj::2, k]
+                na, nb = class_pair.shape
+                p0, c0 = int(class_pair[0, 0]), int(class_offset[0, 0])
+                expected_pair = p0 + np.arange(na)[:, None] + 0 * class_pair
+                expected_offset = c0 + np.arange(nb)[None, :] + 0 * class_offset
+                if not (
+                    np.array_equal(class_pair, expected_pair)
+                    and np.array_equal(class_offset, expected_offset)
+                ):
+                    return Step0Layout(n_rows=n_rows, n_cols=n_cols, grid=None)
+                corner.append((p0, c0, int(na), int(nb)))
+            corners.append(tuple(corner))
+
+    return Step0Layout(
+        n_rows=n_rows,
+        n_cols=n_cols,
+        grid=(n_pairs, pair_width, int(n_pairs * pair_width - vertices.shape[0]), tuple(corners)),
+    )
 
 
 class CoordinateArrayTriangles(AbstractTriangles, ABC):
@@ -113,6 +208,7 @@ class CoordinateArrayTriangles(AbstractTriangles, ABC):
         y_offset: float = 0.0,
         flipped: bool = False,
         vertex_table: Optional[Tuple[np.ndarray, np.ndarray]] = None,
+        step0_layout: Optional[Step0Layout] = None,
     ):
         """
         Represents a set of triangles by integer coordinates.
@@ -134,11 +230,17 @@ class CoordinateArrayTriangles(AbstractTriangles, ABC):
             sets it. Derived lattices (`for_indexes`, `up_sample`, `neighborhood`) do not inherit
             it, and it is not part of the pytree (`tree_flatten`), so an unflattened copy falls
             back to the flat table -- which is still correct, only unshared.
+        step0_layout
+            The `static_lattice_layout` of ``vertex_table``, set with it by
+            `for_limits_and_scale(..., static_vertices=True)` and passed by `with_vertices` to the
+            `ArrayTriangles` it returns, whose `containing_indices` then avoids the ``(N, 3, 2)``
+            gather. Dropped exactly where ``vertex_table`` is.
         """
         import jax.numpy as jnp
 
         self.coordinates = coordinates
         self.vertex_table = vertex_table
+        self.step0_layout = step0_layout if vertex_table is not None else None
         self.side_length = side_length
         self.flipped = flipped
 
@@ -191,10 +293,17 @@ class CoordinateArrayTriangles(AbstractTriangles, ABC):
         import jax.numpy as jnp
 
         vertex_table = None
+        step0_layout = None
         if static_vertices:
-            vertex_table = static_vertex_table(
-                float(y_min), float(y_max), float(x_min), float(x_max), float(scale)
+            geometry = (
+                float(y_min),
+                float(y_max),
+                float(x_min),
+                float(x_max),
+                float(scale),
             )
+            vertex_table = static_vertex_table(*geometry)
+            step0_layout = static_lattice_layout(*geometry)
 
         return cls(
             coordinates=jnp.array(
@@ -202,6 +311,7 @@ class CoordinateArrayTriangles(AbstractTriangles, ABC):
             ),
             side_length=scale,
             vertex_table=vertex_table,
+            step0_layout=step0_layout,
         )
 
     def tree_flatten(self):
@@ -437,6 +547,7 @@ class CoordinateArrayTriangles(AbstractTriangles, ABC):
         return ArrayTriangles(
             indices=self.indices,
             vertices=vertices,
+            step0_layout=self.step0_layout,
         )
 
     def for_indexes(self, indexes: np.ndarray) -> "CoordinateArrayTriangles":