# Update Notes

This page summarizes the recent changes and briefly explains the new core modules, metadata helpers, and shape planning utilities.

## Highlights
- Expanded measurement docstrings (vector/matrix, JIT wrappers, POVM/PNR, expectations) with explicit shapes, key handling, meta routing, and noise models.
- Added core adapter/kernels modules with Kraus-aware contraction paths and jitted entry points.
- Cleaned documentation structure (headings, code blocks, myst support) and added API/core overview pages.

## Core Modules
- `photon_weave.core.adapters`: Reorder/reshape flat tensors so targets sit at the front, call ordered kernels, optionally use contraction (opt_einsum), and restore original ordering. Provides `*_jit` and `*_jit_meta` for static-shape JIT paths.
- `photon_weave.core.kernels`: Stateless, ordered tensor primitives (assume targets already front-most). Implements apply/measure/trace for vectors and matrices plus Kraus and POVM paths.
- `photon_weave.core.linear` and `photon_weave.core.ops`: Thin dispatch layers to adapters/kernels; keep array-only interfaces.
- `photon_weave.core.meta`: Metadata helpers (dims, target indices) to avoid recomputation and keep shapes static for JIT/vmap.
- `photon_weave.core.rng`: Key handling utilities (borrow/split) used by measurement paths.
- `photon_weave.core.jitted`: Convenience wrappers that bind metas for JIT-friendly call sites.

## Meta and Shape Planning
- `photon_weave.core.meta.DimsMeta`: Captures static dimensions, target indices, and rest indices for a given operation/measurement. Enables reuse and stable shapes under JIT.
- `photon_weave.state.utils.shape_planning.ShapePlan`: Higher-level plan pairing `DimsMeta` with source/target ordering for state objects. Used by compiled kernels to skip per-call shape computation.
- Shape planning flow: build `ShapePlan` (or `DimsMeta`) once, route operations/measurements through `*_jit_meta` adapters/jitted helpers to avoid repeated reshapes/index lookups and to maintain static shapes for compilation.

## Measurement Updates
- RNG splitting now drops the first subkey to decorrelate runs when different base keys are provided.
- POVM/Kraus paths validate operator shapes; envelope post-measure/Kraus paths contract once (and twice when contractions are enabled) to restore standalone representations.
- PNR helpers model efficiency (binomial thinning), dark counts (Poisson), and jitter (Gaussian) with both vector and matrix support.