feat(frames): system-agnostic frame-transformation layer + TransmonSystem.lab_frame carrier fix

[aarontrowbridge]

Summary

Adds a public Frames submodule (src/quantum/frames/): a system-agnostic
frame-transformation layer that converts a rotating-frame QuantumSystem into the
physically correct lab frame (carrier-modulated, time-dependent) and back under
the RWA. Also fixes the incomplete TransmonSystem.lab_frame, whose drives were
static rotating-frame quadratures with no carrier.

Motivation: the calibration ablative study v2 (transmon arm) needs a real device
that evolves in the lab frame under a fast carrier with counter-rotating terms and
|2⟩ leakage — the transmon analogue of the atoms finite-blockade out-of-model error.

What's here

• RotatingFrame(ωs) / LabFrame() — frame descriptors (H_f = Σ ωᵢ nᵢ).
• FrameSpec(number_ops, drive_map, drive_ops) — the subsystem/drive metadata the
  transforms read (operators are input data, never guessed); auto-derivable from
  a CompositeQuantumSystem or a matrix-drive QuantumSystem.
• to_lab_frame(sys_rot, frame, spec) — adds the frame generator back into the drift
  and reconstructs each quadrature pair (u_x, u_y) as Ω cos(ω_d t + φ)(a+a†),
  Ω=√(u_x²+u_y²), φ=atan2(−u_y, u_x). Returns a time_dependent=true function
  system rolled via the Rollouts ODE path (KetTrajectory/UnitaryTrajectory
  • SciML MagnusAdapt4()) — not SplineIntegrator (which rejects function-based
    H and has interval-local t).
• to_rotating_frame(sys_lab, frame, spec; rwa=true) — the RWA inverse.
• TransmonSystem(lab_frame=true) now routes through the layer → a correct
  carrier-modulated, time-dependent system.

Guarantees (tests) — verified locally: frames 64/64 green

1. Round-trip: to_rotating_frame(to_lab_frame(s)) ≈ s (RWA) to < 1e-8.
2. Validity limit: lab-frame gate fidelity → RWA fidelity as Ω_max/ω_d → 0
   (monotone, < 1e-3 at large ω_d), driving both quadratures so the carrier
   physics (φ, y-sign, field factor) is actually pinned.
3. Drive-carrier regression: TransmonSystem(lab_frame=true) applies a
   carrier-modulated drive (guards against reverting to static quadratures).
4. Cross-template: composes on a multi-transmon (CompositeQuantumSystem,
   distinct per-subsystem ω_d) with the same invariants.

Verification (main env, --startup-file=no):

• run_tests(filter="frame") → 64 pass / 0 fail.
• broad sweep (frame/transmon/kettrajectory/unitarytrajectory/composite) → all green
  except 3 pulse_plots.jl tests that error on CairoMakie not found (a test-env-
  only dep; they error identically on main and are unrelated to this change).

Reviewer-critical deviations / decisions

• Operator provenance (design decision): a function-based lab QuantumSystem
  stores no H_drives, so FrameSpec carries drive_ops and both transforms
  read operators from the spec — never from a system's drive list. This is what makes
  the round-trip a clean structural inverse.
• φ-sign convention: the ½-factor/sign were pinned by the round-trip + validity
  tests, not derived in prose. The converged convention is φ = atan2(−u_y, u_x)
  with field = 2·(½-quadrature op); a lone :real drive is modulated directly (no
  2×). The rwa=false inverse branch is completeness-only (not round-trip-guarded).
• A4 metric: the validity-limit test asserts a monotone shrinking gap vs ω_d
  (not just a threshold), and drives both quadratures — otherwise the round-trip
  (a structural inverse) would not exercise the carrier math.
• FrameSpec(comp) auto-derivation skips coupling drives (no single-subsystem
  carrier) and reads per-subsystem quadrature operators from comp.H_drives.

Notes

• Public core; no IP concern — frame transforms are generically useful.
• Review only — please do not merge yet (part of a staged v2 rollout; the demo
  consumer follows after this API is reviewed).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.54140% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/quantum/frames/frame_transforms.jl	94.89%	5 Missing ⚠️
src/quantum/frames/frame_types.jl	94.73%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!