feat(propagator): ✨ read individual evolved coefficients by term

[JoshCudbyAlgo]

🤖 AI text below 🤖

Summary

evolved_operator decodes the whole evolved operator: it enumerates the index, materialises a key per surviving term, and builds a term dictionary. evolved_operator_coefficients probes the index with the terms the caller names instead, so the decode costs one entry per term requested rather than one per term the operator carries. Reading a few amplitudes out of an evolved state (Schrödinger picture) is the motivating case. The graph contraction is unchanged and still dominant — this removes the per-surviving-term tail, not evolution cost.

Contracts, all pinned by tests: an absent term reads back as 0; there is deliberately no atol, since the caller named its terms and magnitude filtering would silently zero some of them (threshold the result instead); the result is positional, and a repeated term is answered once per occurrence; the empty term agrees with evolved_operator in both pictures — core_term() in Heisenberg, an ordinary index row in Schrödinger; and it is rank-local, exactly as evolved_operator is.

Terms must be canonical, as the constructor's initial_operator keys must be. The engine keys terms by an order-insensitive bitset, so a raw (1, 0) would resolve to the row of (0, 1) and read back its coefficient without the anticommutation sign — which a lookup has no coefficient of its own to carry. Raw sequences are therefore validated through Majorana rather than normalized; use Majorana.from_unsorted and apply the sign it returns.

Changes

• MonomialPropagator::evolved_operator_coefficients(parameters, terms), built on the operator index's group-prefetch find_batch rather than a for_each enumeration. Under partitions each partition probes on its own master thread into its own vector and the merge runs on the facade thread, as every other partition fan-out in the file does.
• Bound as evolved_operator_coefficients(terms, parameters=None), returning a complex NumPy array.
• A _term_slots front-end hook: Majorana indices for MajoranaPropagator (Majorana terms, index tuples or index arrays, with non-canonical ones rejected), symplectic slots for PauliPropagator (Pauli terms). Cross-front-end terms raise TypeError. It is a default rather than an abstract method, so a front-end that does not encode terms still constructs.
• 11 C++ and 17 Python cases oracled against evolved_operator(atol=0.0), covering both pictures crossed with 1/2/4 partitions. Partitioned Schrödinger is the only configuration where the identity is a hash-partitioned index row, so it is what exercises the empty key against the concurrent merge.
• test_evolved_operator_coefficients_is_rank_local: the ranks' answers sum to the serial result, plus a check that the split is real — counted against the terms each rank owns rather than its nonzero coefficients, which would drift if an owned term evolved to exactly zero.
• A "Reading individual terms" section in docs/content/docs/features/evaluation.mdx.

Verification

274/274 C++ ctest and 611 Python tests pass locally, and prek run --all-files is clean over this branch's files. The MPI leg was never executed: the dev environment is a serial build, so test_evolved_operator_coefficients_is_rank_local is reviewed but unrun and CI's [mpi:on] lanes are its first real run. Branched from 7101b33, which main has since moved past, so a rebase before merge would be sensible.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable — N/A, the repository keeps no CHANGELOG

AI/LLM disclosure

• I did not use LLM tooling, or used it only privately for ideation
• I used the following tool to help write this PR description: Claude Code (Claude Opus 5)
• I used the following tool to generate or modify code: Claude Code (Claude Opus 5)

[github-actions]

Docs preview: https://pr-337.monoprop-docs.pages.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.72%. Comparing base (d531dc6) to head (656c7b0).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #337      +/-   ##
==========================================
+ Coverage   97.70%   97.72%   +0.01%     
==========================================
  Files          14       14              
  Lines         742      746       +4     
  Branches       98       98              
==========================================
+ Hits          725      729       +4     
  Misses         12       12              
  Partials        5        5              

Flag	Coverage Δ
cpp	97.72% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
34.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud