feat(mps): add successive randomized compression (SRC) apply method

[ultimatile]

Summary

Add ApplyMethod::SuccessiveRandomized, a fifth MPO-MPS apply method implementing successive randomized compression (SRC, arXiv:2504.06475): a single right-to-left randomized-QB sweep that computes the compressed product directly, without materializing the full product MPS, with the output bond chosen adaptively per site from a leave-one-out error estimate (or fixed by the caller). Closes #470.

Changes

• crates/ariadnetor-mps/src/types.rs: SuccessiveRandomizedParams (fixed-rank / adaptive stopping, per-site clamping, seed) and the ApplyMethod::SuccessiveRandomized variant, re-exported from lib.rs
• crates/ariadnetor-mps/src/dispatch.rs: sealed MpsOps::apply_successive_randomized_k; the block-sparse impl panics (a Gaussian sketch mixes symmetry sectors), documented under # Panics
• crates/ariadnetor-mps/src/apply/successive_randomized.rs (new): the kernel — per-column Gaussian environment recursion with prefix caching, per-site thin-QR QB step, adaptive growth with a rank-deficiency guard (singular R means the exact rank is covered) and saturating increments
• crates/ariadnetor-mps/src/apply/mod.rs: the canonicalize + truncate finishing pass is hoisted into a shared finish_dense, reused by streaming-naive and SRC
• Cargo.toml / crates/ariadnetor-mps/Cargo.toml: rand_distr = "0.6" added to the workspace; rand / rand_distr become runtime deps of ariadnetor-mps
• Tests: new tests/mps/apply_successive_randomized.rs suite, an SRC case in tests/authority.rs, and consolidation of shared dense helpers (make_3site_test_mps / make_3site_test_mpo / assert_dense_close / generic densify) into tests/mps/helpers.rs

Impact

Purely additive: no existing behavior changes, and the sole match on ApplyMethod lives in dispatch.rs. The sealed MpsOps trait compile-enforces both storage impls; the Dense/BlockSparse asymmetry is deliberate and documented. ariadnetor-mps gains rand / rand_distr as unconditional runtime dependencies.

Test plan

• Fixed rank at the representable-rank clamp reproduces the lossless streaming-naive product at 1e-10; an interior fixed rank lands exactly on every bond
• Adaptive mode meets 100 * cutoff relative error (the acceptance factor RandomMPOMPS's own check_randomized_apply verification uses) with all bonds within per-site caps
• Output is Mixed { center: 0 } with right-isometric sites; equal seeds give bit-identical output
• Complex chain exercises the cap update's conjugation (invisible for real scalars); unequal adjacent bonds guard the left-leg cap indexing
• Rank-deficient and zero-product inputs exercise the singular-R stop path; forced growth, min_dim floor, max_dim cap, and the TruncateParams finishing pass are each pinned; single-site chains return the exact product
• f32 rejects a finite f64 cutoff that overflows after casting; should_panic covers block-sparse input, a missing stopping rule, and fixed-mode validation of ignored fields
• cargo make gate (fmt-check + clippy -D warnings + workspace tests + doctests) passes; the committed tree also builds and passes in a fresh git worktree

Notes

• Dense-only: the Gaussian sketch does not preserve symmetry sectors, so the block-sparse arm panics; a sector-preserving sketch is tracked as Successive randomized compression (SRC) for MPO-MPS apply #469 P4 (research)
• The QR is recomputed from scratch on each adaptive growth round; incremental QR and batched environment GEMM are Successive randomized compression (SRC) for MPO-MPS apply #469 P2
• cutoff is the per-site randomized QB stopping criterion, not a certified bound on the global relative error (documented on the variant)
• rand / rand_distr are unconditional dependencies; feature-gating the randomized method can be revisited before v0.1

@coderabbitai ignore

Plan-vs-actual delta

Compared against #470's Scope / Out of scope / Acceptance and the implementation-plan comment there:

• Block-sparse arm: the issue scope says the arm "returns an unsupported error"; the landed code panics with a documented message instead, because apply_with_method returns Mps (no Result) and panicking on caller contract violations is the apply surface's existing idiom. Recorded in the plan comment before implementation.
• Final rounding: rides the existing shared params: Option<&TruncateParams> argument of apply_with_method (the StreamingNaive convention) instead of the final_round params field named in the issue scope. Also recorded in the plan comment.
• Scope additions during implementation: the shared finish_dense hoisted out of the streaming-naive path (both apply paths would otherwise duplicate the finalization); dense test helpers consolidated into tests/mps/helpers.rs with mps_to_dense reimplemented on a generic densify; Y assembly through the existing DenseTensorData::stack primitive instead of element-wise loops; saturating sketch growth. From PR review: a memory-order guard in assert_dense_close (Copilot finding, feat(mps): add successive randomized compression (SRC) apply method #471 (comment), fixed in a4e6608).
• Test-plan change: relative errors are measured on densified states rather than from chain norms and overlaps — the inner-product distance form (norm-squared sum minus twice the real overlap) cancels catastrophically and cannot resolve relative errors below roughly the square root of machine epsilon.
• Acceptance: all criteria hold — tolerance-bounded agreement with the exact product, fixed-seed bit-identical reproducibility, and the doc comment names the algorithm and cites arXiv:2504.06475.
• New deferrals discovered: the sibling variational apply path casts its f64 tolerance without a post-cast finiteness check (the same overflow-to-infinity class this PR guards against in SRC) — filed as Guard f64-to-real tolerance casts against overflow to infinity #472; the new rand / rand_distr dependencies are not feature-gated in this PR (see Notes); revisit at v0.1 packaging.

[Copilot]

Pull request overview

Adds a new MPO→MPS apply algorithm, Successive Randomized Compression (SRC), as ApplyMethod::SuccessiveRandomized, including parameterization, dense dispatch wiring, kernel implementation, and a dedicated test suite.

Changes:

• Introduces SuccessiveRandomizedParams and ApplyMethod::SuccessiveRandomized (re-exported from ariadnetor-mps), plus dispatch plumbing in MpsOps.
• Implements the dense SRC kernel (apply_successive_randomized_dense) and factors out a shared dense finishing pass (finish_dense) used by multiple apply methods.
• Adds SRC-focused tests and consolidates shared dense test helpers; adds rand_distr and promotes rand/rand_distr to runtime deps of ariadnetor-mps.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
crates/ariadnetor-mps/tests/mps/helpers.rs	Adds shared 3-site fixtures, densify, and assert_dense_close used across apply tests.
crates/ariadnetor-mps/tests/mps/apply.rs	Switches to the consolidated helpers (removes local copies).
crates/ariadnetor-mps/tests/mps/apply_successive_randomized.rs	New SRC test suite covering exactness, adaptivity, reproducibility, and validation panics.
crates/ariadnetor-mps/tests/mps.rs	Registers the new SRC test module.
crates/ariadnetor-mps/tests/authority.rs	Adds dispatch “authority” coverage for SRC routing through the call-site backend.
crates/ariadnetor-mps/src/types.rs	Defines SuccessiveRandomizedParams and adds ApplyMethod::SuccessiveRandomized with docs/panic contract.
crates/ariadnetor-mps/src/lib.rs	Re-exports SuccessiveRandomizedParams.
crates/ariadnetor-mps/src/dispatch.rs	Adds sealed apply_successive_randomized_k to MpsOps, dense impl, and block-sparse panic arm; wires method into apply_with_method.
crates/ariadnetor-mps/src/apply/successive_randomized.rs	Implements the dense SRC kernel (sketch env recursion, QR-based QB step, adaptive stopping).
crates/ariadnetor-mps/src/apply/mod.rs	Adds SRC module and factors out finish_dense for shared finishing behavior.
crates/ariadnetor-mps/Cargo.toml	Adds rand/rand_distr as runtime dependencies.
Cargo.toml	Adds workspace rand_distr = "0.6".
Cargo.lock	Locks rand_distr 0.6.0 (and updates dependency graph accordingly).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.