quchip.engine.stage1_frames

Stage 1: resolve a FrameSpec into a ResolvedFrame.

This stage is purely combinatorial: it decides which rotating frame to work in.

Supported specs

  • "lab" — every reference frequency is zero; stage 2 emits the bare chip Hamiltonian unchanged.

  • "rotating" — each device’s reference is its reference_freq (the device’s readout/LO reference, defaulting to the dressed drive frequency ω_d), so stage 2 builds

    \[H(t) \;=\; H_0 - \sum_i \omega_{\text{ref},i} n_i + V_{\text{drive}}(t) + V_{\text{coupling}}(t),\]

    the standard rotating-frame form used in cQED / driven multi-level systems (e.g. Gambetta et al., PRA 74, 042318 (2006); Krantz et al., Appl. Phys. Rev. 6, 021318 (2019)). Setting a device’s reference_freq off its transition surfaces a residual detuning Δ = ω − ω_ref in H₀ — idle Ramsey precession.

  • Scalar — every device uses the same shared reference frequency.

  • dict[str | BaseDevice, scalar] — per-device references; missing entries default to 0.0.

The demodulation frequencies are ω_ref − ω_frame per device: observables are always reported co-rotating at reference_freq (the readout LO), independent of which frame the solver integrated in. In the default "rotating" mode the integration frame is the reference frame, so the demodulation is a no-op and the raw stored states already sit in the readout frame (result.states and result.expect agree). Transverse observables (<a>, <σ_x>) thus come back as the non-oscillatory demodulated envelope; only an explicitly overridden non-reference integration frame leaves result.states in that other frame.

Whether a coupling band folds into H₀ is decided per band in stage 2, from the concreteness of its frame carrier Δa·ω_a + Δb·ω_b — not here (see _collect_coupling_terms()).

Functions

resolve_frame(chip, frame_spec)

Resolve frame_spec into a ResolvedFrame.
quchip.engine.stage1_frames.resolve_frame(chip, frame_spec)[source]

Resolve frame_spec into a ResolvedFrame.

Dispatches on frame_spec shape (str / scalar-like / dict), fills a per-device frequencies dict, and computes the demodulation frequencies reference_freq − ω_frame. See the module docstring for the physical meaning of each mode.

Dressing happens lazily: reading a device’s reference_freq diagonalizes the chip only when its default (the dressed drive frequency) is actually consulted. A chip whose devices all carry explicit reference_freq overrides resolves any frame spec without ever diagonalizing.

Parameters:
Return type:

ResolvedFrame