Change Summary and Core Architecture Notes

This note captures the recent changes and clarifies how the core module, metadata helpers, and shape planning fit together. It is meant to be a quick orientation for contributors who want the rationale behind the latest updates.

Recent Changes

  • Expanded measurement docstrings (vector/matrix, JIT wrappers, POVM/PNR, expectations) with shapes, key handling, noise models, and meta routing described explicitly.

  • Improved Kraus application paths to validate operator shapes, use consistent contractions, and restore standalone state ordering after applying operators.

  • Documented adapters/kernels interactions, including JIT entry points and how contraction flags affect execution.

  • Enabled Markdown support in docs via myst_parser and cleaned heading/code-block formatting across the docs set.

  • Added tests for adapters, jitted paths, metadata planning, RNG decorrelation, and measurement utilities to guard the new behavior.

Core Module Overview

  • photon_weave.core.adapters: Reshapes/reorders tensors so targets lead the axis order, invokes ordered kernels, applies optional opt_einsum contraction, then restores the original layout. Provides *_jit and *_jit_meta helpers for static-shape call sites.

  • photon_weave.core.kernels: Stateless tensor primitives that assume targets are already front-most; implement apply/measure/trace for vectors and matrices plus Kraus and POVM paths.

  • photon_weave.core.linear and photon_weave.core.ops: Thin dispatch layers that expose array-focused APIs and forward to adapters/kernels.

  • photon_weave.core.jitted: Convenience wrappers that bind metadata for JIT-friendly invocation.

  • photon_weave.core.rng: Utilities for key borrowing/splitting used by stochastic measurement flows.

  • photon_weave.core.meta: Metadata structures that capture dimensions and target ordering to avoid recomputation.

Meta and Shape Planning

  • DimsMeta (from photon_weave.core.meta) stores static dimensions, target indices, and non-target indices. By reusing an instance, call sites keep shapes stable and skip repeated index lookups—important for JIT and vmap.

  • ShapePlan (from photon_weave.state.utils.shape_planning) pairs DimsMeta with the source/target ordering of state objects. Compiled kernels use the plan to reorder once and reuse metadata across repeated operations.

  • Typical flow: build a ShapePlan (or DimsMeta) once, then call the *_jit_meta adapters or jitted helpers. Adapters move targets forward, kernels operate in that ordered frame, and adapters reshape back—optionally contracting along the way when configured.

Suggested Next Steps

  • Re-enable excluded example pages in the Sphinx build once their formatting is cleaned.

  • Extend autosummary coverage to the new core and state utility modules to surface these APIs in the HTML docs.

  • Keep metadata-aware call sites using ShapePlan/DimsMeta for any new operations or measurements to preserve static shapes under JIT.