perf(layer ops, lazy proxies): implement cashing for supra index and related operations and for nx accessor + add them to benchmarks

Author: L1BOLL

annnet/core/_Layers.py

@@ -193,6 +193,7 @@ def set_aspects(self, aspects, elem_layers: dict[str, list[str]] | None = None):
 
         self._rebuild_all_layers_cache()
         self._drop_unused_placeholder_layers()
+        self._supra_index_cache = None
 
     def set_elementary_layers(self, layers_by_aspect: dict[str, list[str]]):
         """Declare concrete elementary layer values for existing aspects."""
@@ -511,6 +512,27 @@ def iter_vertex_layers(self, u: str):
 
     def _build_supra_index(
         self, restrict_layers: list[tuple[str, ...]] | None = None
+    ) -> tuple[dict, list]:
+        """Return ``(nl_to_row, row_to_nl)`` for the supra layout, cached.
+
+        The index is a full scan + sort of the vertex-entity population, so it is
+        memoised per ``restrict_layers`` key and reused until a structural
+        mutation clears ``_supra_index_cache`` (via ``_mark_matrix_dirty``).
+        The returned dict/list are shared — callers treat them as read-only.
+        """
+        cache = self._supra_index_cache
+        if cache is None:
+            cache = {}
+            self._supra_index_cache = cache
+        key = None if restrict_layers is None else frozenset(tuple(x) for x in restrict_layers)
+        entry = cache.get(key)
+        if entry is None:
+            entry = self._compute_supra_index(restrict_layers)
+            cache[key] = entry
+        return entry
+
+    def _compute_supra_index(
+        self, restrict_layers: list[tuple[str, ...]] | None = None
     ) -> tuple[dict, list]:
         if restrict_layers is not None:
             R = {tuple(x) for x in restrict_layers}

annnet/core/_derive.py

@@ -98,6 +98,7 @@ def invalidate_sparse_caches(g, formats=None) -> None:
     cache_manager = getattr(g, '_cache_manager', None)
     if cache_manager is not None:
         cache_manager.invalidate(list(formats))
+    g._supra_index_cache = None
 
 
 # ---------------------------------------------------------------------------

annnet/core/_state.py

@@ -99,5 +99,6 @@ def init_state(g, *, directed=None, v=0, e=0, aspects=None) -> None:
 
     # Version clock (dirty signal for derived sparse caches).
     g._version = 0
+    g._supra_index_cache = None
 
     g.vertex_aligned = False

annnet/core/backend_accessors/nx_accessor.py

@@ -2,13 +2,24 @@
 
 from typing import TYPE_CHECKING
 import inspect
+from functools import lru_cache
 
 from ._base import _BackendAccessorBase
 
 if TYPE_CHECKING:
     from ..graph import AnnNet
 
 
+@lru_cache(maxsize=4096)
+def _cached_signature(fn):
+    """inspect.signature is expensive; NX callables are stable, so memoise it."""
+    return inspect.signature(fn)
+
+
+# name -> resolved networkx callable (global; the nx module set is static).
+_NX_CALLABLE_CACHE: dict = {}
+
+
 class _NXBackendAccessor(_BackendAccessorBase):
     """NetworkX backend accessor attached to an AnnNet instance."""
 
@@ -108,7 +119,7 @@ def wrapper(*args, **kwargs):
                 args, kwargs = self._replace_owner_graph(args, kwargs, nxG)
 
             try:
-                sig = inspect.signature(nx_callable)
+                sig = _cached_signature(nx_callable)
                 bound = sig.bind_partial(*args, **kwargs)
             except Exception:  # noqa: BLE001
                 bound = None
@@ -151,9 +162,13 @@ def __dir__(self):
         return sorted(set(super().__dir__()) | self._callable_names(*self._nx_candidates()))
 
     def _resolve_nx_callable(self, name: str):
+        cached = _NX_CALLABLE_CACHE.get(name)
+        if cached is not None:
+            return cached
         for mod in self._nx_candidates():
             attr = getattr(mod, name, None)
             if callable(attr):
+                _NX_CALLABLE_CACHE[name] = attr
                 return attr
         raise AttributeError(f"networkx has no callable '{name}'")
 
@@ -185,7 +200,7 @@ def _nx_candidates(self):
     def _needed_edge_attrs(self, target, kwargs) -> set:
         needed = set()
         try:
-            params = inspect.signature(target).parameters
+            params = _cached_signature(target).parameters
         except Exception:  # noqa: BLE001
             params = {}
         if 'weight' in params:
@@ -290,15 +305,17 @@ def _coerce_vertices_in_bound(self, bound, nxG, label_field: str | None):
         )
 
     def _map_output_vertices(self, obj):
-        _id_to_row, row_to_id = self._vertex_row_maps()
-
         def map_id(value):
             # NetworkX returns vertex IDs as the backend graph's node values.
             # Our backend nodes are vertex-ID strings, so strings pass through
             # unchanged. Integers that NX produced from a relabel-to-int pass
-            # are mapped back to their vertex IDs.
-            if isinstance(value, int) and not isinstance(value, bool) and value in row_to_id:
-                return row_to_id[value]
+            # are mapped back to their vertex IDs. Resolve each int in O(1) via
+            # the graph's row->entity index instead of materialising the whole
+            # row->id map on every call.
+            if isinstance(value, int) and not isinstance(value, bool):
+                vid = self._vertex_row_to_id(value)
+                if vid is not None:
+                    return vid
             return value
 
         return self._map_nested_output(obj, map_id)

annnet/core/graph.py

@@ -2031,8 +2031,15 @@ def _matrix(self, value) -> None:
         self._matrix_dirty = False
 
     def _mark_matrix_dirty(self) -> None:
-        """Flag the incidence cache for lazy rebuild from records."""
+        """Flag the incidence cache for lazy rebuild from records.
+
+        Also drops the cached supra (vertex-layer) index: it is derived from the
+        vertex-entity population, which every structural mutation routes through
+        here (add / remove / rekey), so this is the single reliable invalidation
+        point (``_version`` does not bump on removes or ``set_aspects``).
+        """
         self._matrix_dirty = True
+        self._supra_index_cache = None
 
     def X(self):
         """Return the sparse incidence matrix.

benchmarks/report.py

@@ -379,6 +379,20 @@ def render(payload, report_path, plots_dir=None):
         'Algorithms / traversal',
         'Directional neighbor + edge queries and matrix-derived traversals.',
     )
+    lines += _feature_section(
+        records,
+        'layers',
+        'Layers (supra index + supra operations)',
+        'Vertex-layer index and supra-matrix ops; nl_to_row must stay ~O(1) in the '
+        'supra size (cached index).',
+    )
+    lines += _feature_section(
+        records,
+        'backend_proxy',
+        'Backend proxies (G.nx.*)',
+        'Per-call wrapper tax with the converted graph cached; must stay ~O(1) in '
+        'vertex count (O(1) output mapping).',
+    )
     lines += _io_formats(payload)
     lines += _adapters(payload)
     lines += _plots(records, plots_dir)

benchmarks/workloads.py

@@ -480,4 +480,79 @@ def _build_hist():
             note='per-vertex incident edge lists',
         )
     )
+
+    # --- layers: supra (vertex-layer) index + supra operations --------------
+    # Guards the cached supra index: nl_to_row must stay ~O(1) as V_M grows.
+    n_layers = 3
+    n_lv = max(50, min(scale.vertices // 20, 20_000))  # vertices per layer
+    with warnings.catch_warnings():
+        warnings.simplefilter('ignore')
+        Gml = AnnNet(directed=True)
+        Gml.layers.set_aspects(['layer'], {'layer': [f'L{k}' for k in range(n_layers)]})
+        coords = list(Gml.layers.iter_layers())
+        for aa in coords:
+            Gml.add_edges(
+                [
+                    {'source': (f'm{i}', aa), 'target': (f'm{(i + 1) % n_lv}', aa), 'weight': 1.0}
+                    for i in range(n_lv)
+                ]
+            )
+    aa0 = coords[0]
+    v_m = n_lv * n_layers
+    recs.append(
+        rec(
+            'layers',
+            'nl_to_row',
+            time=harness.time_repeat(lambda: Gml.layers.nl_to_row('m0', aa0)),
+            note=f'single vertex-layer lookup (V_M={v_m}); must be ~O(1)',
+        )
+    )
+    recs.append(
+        rec(
+            'layers',
+            'build_supra_index',
+            time=harness.time_repeat(lambda: Gml.layers._build_supra_index()),
+            note='full supra index (cache hit after first build)',
+        )
+    )
+    recs.append(
+        rec(
+            'layers',
+            'supra_adjacency',
+            time=harness.time_oneshot(
+                lambda: Gml.layers.supra_adjacency(), samples=max(3, samples // 2)
+            ),
+            note=f'supra-adjacency over {v_m} vertex-layer nodes',
+        )
+    )
+    recs.append(
+        rec(
+            'layers',
+            'subgraph_from_layer',
+            time=harness.time_oneshot(
+                lambda: Gml.layers.subgraph_from_layer_tuple(aa0), samples=max(3, samples // 2)
+            ),
+            note='single-layer induced subgraph',
+        )
+    )
+
+    # --- backend proxy: G.nx.* per-call wrapper tax on a cache hit ----------
+    # Guards the O(1) output mapping: this must stay flat as V grows.
+    try:
+        import networkx as _nx  # noqa: F401
+
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore')
+            G.nx.number_of_nodes(G)  # prime the conversion cache
+            recs.append(
+                rec(
+                    'backend_proxy',
+                    'nx_call_cache_hit',
+                    time=harness.time_repeat(lambda: G.nx.number_of_nodes(G)),
+                    note='G.nx.* wrapper tax with conversion cached; must be ~O(1) in V',
+                )
+            )
+    except ImportError:
+        pass
+
     return recs