quchip.engine.frames

Resolve integration frames and observable-demodulation frequencies.

Supported FrameSpec values:

• "lab": zero integration frequencies.

• "rotating": each device’s reference_freq, defaulting to its dressed drive frequency. An off-transition reference leaves idle Ramsey detuning.

• "auto": plan_frame() satisfies cascade constraints, then selects tones and exchange bands by integrated strength. Free frequencies use device references in declaration order. Other coupling bands cannot override these choices. Unsatisfied constraints remain time dependent and become residuals.

• A scalar: one common frequency for all devices.

• A device-or-label mapping: per-device frequencies, with missing entries zero.

Assembly subtracts Σᵢ ω_frame,ᵢ nᵢ from the Hamiltonian and decides which coupling bands become static. Stored states stay in the integration frame. Transverse observables are demodulated by ω_ref - ω_frame into the readout reference frame; this phase vanishes when the two frames coincide.

See Gambetta et al., PRA 74, 042318 (2006), and Krantz et al., Appl. Phys. Rev. 6, 021318 (2019), for rotating-frame descriptions of driven qubits.

Functions

frame_tones(chip, operations, *, ...[, ...])	Build weighted frame constraints from scheduled drive and coherent-input signals.
plan_for_operations(chip, frame_spec, ...[, ...])	Build an operation-aware FramePlan for "auto".
plan_frame(chip, tones, *, approximation, strict)	Choose one frame frequency per device from charge-vector constraints.
planning_resolution(chip)	Resolve local solver bases during JAX compile-time evaluation.
resolve_for_operations(chip, operations, *)	Resolve chip with an operation-aware "auto" frame when requested.
resolve_frame(chip, frame_spec, *[, ...])	Resolve frame_spec into a ResolvedFrame.
resolve_reference_frequencies(chip, *[, ...])	Resolve explicit overrides or dressed references in one chip context.
same_frequency(first, second)	Return whether two frequencies are provably identical without concretizing tracers.
stationary_tones(chip, port_frequencies, *, ...)	Build unweighted frame constraints for stationary port tones.

Classes

FrameMap(frequencies, energies, dims, transforms)	Map states and observables between the lab frame and an integration frame.
FramePlan(frequencies, clusters, pins, residuals)	Record the frequencies and constraints chosen by plan_frame().
FrameResidual(source, devices, frequency, weight)	Describe a rejected constraint that remains time dependent.
FrameTone(coefficients, freq, weight, source)	Describe a tone constraint Σ_d k_d ω_d = freq and its weight.

Exceptions

FrameConflict(source, devices, *, kind, cluster)

Report a mandatory tone that conflicts with earlier strict constraints.

quchip.engine.frames.same_frequency(first, second)

Return whether two frequencies are provably identical without concretizing tracers.

Identical objects compare equal. Distinct objects compare equal only when both values are concrete and exactly equal; no tolerance is applied.

class quchip.engine.frames.FrameTone(coefficients, freq, weight, source)

Bases: object

Describe a tone constraint Σ_d k_d ω_d = freq and its weight.

coefficients pairs each device label with its energy-index weight k_d = column - row. Lowering has positive weight, opposite to the level change. weight is |h_band|² ∫|envelope|² dt when available.

Variables:

• coefficients (tuple of (str, int)) – Device labels and energy-index weights column - row.

• freq (scalar) – Constraint frequency in GHz.

• weight (float or None) – Integrated constraint weight, when available.

• source (str) – Description of the originating term or tone.

coefficients: tuple[tuple[str, int], ...]

freq: Any

weight: float | None

source: str

class quchip.engine.frames.FrameResidual(source, devices, frequency, weight)

Bases: object

Describe a rejected constraint that remains time dependent.

frequency is its residual oscillation frequency, Σ_d k_d ω_d for a static coupling or Σ_d k_d ω_d - freq for a tone. source and devices identify its origin, and weight records its integrated strength when available.

Variables:

• source (str) – Description of the rejected constraint.

• devices (tuple of str) – Devices participating in the constraint.

• frequency (scalar) – Residual frequency in GHz.

• weight (float or None) – Integrated constraint weight, when available.

source: str

devices: tuple[str, ...]

frequency: Any

weight: float | None

class quchip.engine.frames.FramePlan(frequencies, clusters, pins, residuals, tones=())

Bases: object

Record the frequencies and constraints chosen by plan_frame().

frequencies maps every device to its frame frequency. clusters groups devices linked by accepted constraints. pins records the reference frequencies used to set free variables. residuals lists rejected constraints that remain time dependent. tones contains the accepted tone constraints that fixed driven clusters, including each tone’s source, charge coefficients, frequency, and weight.

Variables:

• frequencies (mapping) – Frame frequency in GHz for each device label.

• clusters (tuple of tuple of str) – Device groups linked by accepted constraints.

• pins (tuple of (str, scalar)) – Reference frequencies in GHz used for free variables.

• residuals (tuple of FrameResidual) – Rejected constraints that remain time dependent.

• tones (tuple of FrameTone) – Accepted driven constraints.

frequencies: Mapping[str, Any]

clusters: tuple[tuple[str, ...], ...]

pins: tuple[tuple[str, Any], ...]

residuals: tuple[FrameResidual, ...]

tones: tuple[FrameTone, ...] = ()

concrete_key()

Return a hashable key for concrete frame content.

Raises:

ValueError – If a frame, pin, residual, or tone frequency is traced.

exception quchip.engine.frames.FrameConflict(source, devices, *, kind, cluster)

Bases: ValueError

Report a mandatory tone that conflicts with earlier strict constraints.

kind is "port" when an accepted tone already addresses the same devices and "exchange" otherwise. cluster lists the devices linked by accepted constraints.

quchip.engine.frames.resolve_reference_frequencies(chip, *, local_resolution=None)

Resolve explicit overrides or dressed references in one chip context.

quchip.engine.frames.plan_frame(chip, tones, *, approximation, strict, solve_duration=None, reference_frequencies=None, local_resolution=None)

Choose one frame frequency per device from charge-vector constraints.

A retained static coupling band imposes Σ_d k_d ω_d = 0. Each entry in tones imposes Σ_d k_d ω_d = freq. Cascade-generated network couplings add equality constraints between their device frequencies. The non-strict planner keeps the consistent subset of tones and exchange bands with the largest total integrated strength. Declaration order breaks ties. Free variables are pinned to device references in declaration order. Coupling bands whose integer weights sum to a nonzero value cannot override these choices. Rejected constraints become residual oscillations.

Parameters:

• chip (Chip) – The chip whose devices receive frame frequencies.

• tones (sequence of FrameTone) – Charge-vector constraints requested by scheduled or stationary tones.

• approximation (Approximation) – Decides which coupling bands are retained.

• strict (bool) – Apply stationary ordering when true: the planner must satisfy, in order, cascade constraints, exchange coupling bands with nonzero charge vectors summing to zero, and tones. Raise FrameConflict when a tone conflicts. Only non-exchange coupling bands can remain as residuals.

• solve_duration (float, optional) – Integration-window duration used for the static-coupling weight |h_band|² solve_duration. If omitted or traced, static-coupling weights remain unknown.

• reference_frequencies (mapping, optional) – Per-device reference frequencies for pins; defaults to the devices’.

• local_resolution (optional) – Resolved local bases from assembly, reused when already calculated.

Returns:

Frequencies, clusters, pins, and residuals.

Return type:

FramePlan

Raises:

FrameConflict – In strict mode, when a tone cannot be made static.

quchip.engine.frames.frame_tones(chip, operations, *, approximation, resolution, solve_window=None)

Build weighted frame constraints from scheduled drive and coherent-input signals.

Drive signals are read after control equipment applies gain, attenuation, delay, and crosstalk. Each nonzero carrier band constrains every retained operator band of its destination drive; a zero-frequency band adds no constraint. A crosstalk destination therefore receives its own tone, and gain changes the tone’s weight. Coherent inputs use their complete scheduled signal, including its pulse window, start time, phase, and carrier, while network scattering scales the port amplitude. Both paths use the same carrier decomposition. Each signal’s energy is integrated over its own support intersected with solve_window; when omitted, that outer window is [0, last pulse end]. Traced values leave the corresponding weight unknown.

quchip.engine.frames.stationary_tones(chip, port_frequencies, *, resolution)

Build unweighted frame constraints for stationary port tones.

Strict stationary planning uses these constraints to reject tone sets that no single time-independent frame can satisfy.

quchip.engine.frames.planning_resolution(chip)

Resolve local solver bases during JAX compile-time evaluation.

Bases from constant device matrices stay concrete inside jit, while bases that depend on traced inputs remain traced.

quchip.engine.frames.resolve_for_operations(chip, operations, *, frame=None, approximation=None, solve_window=None)

Resolve chip with an operation-aware "auto" frame when requested.

approximation selects the retained bands. solve_window supplies the solve’s (start, stop) bounds for signal-energy weights; when omitted, the bounds are (0, last pulse end).

quchip.engine.frames.plan_for_operations(chip, frame_spec, operations, *, approximation, solve_window=None, _resolution=None)

Build an operation-aware FramePlan for "auto".

Return any other frame_spec unchanged. approximation selects the retained bands. solve_window bounds each signal-energy integral, and its length sets the static-coupling weight.

quchip.engine.frames.resolve_frame(chip, frame_spec, *, reference_frequencies=None, local_resolution=None, approximation=None)

Resolve frame_spec into a ResolvedFrame.

Dispatches on frame_spec shape (str / scalar-like / dict / plan), fills a per-device frequencies dict, and calculates the demodulation frequencies reference_freq − ω_frame. See the module docstring for the physical meaning of each mode. A bare "auto" spec plans from coupling and network constraints only. Operation-aware callers pass a FramePlan that also contains their tone constraints.

Missing references resolve from this chip’s dressed transitions. Explicit references bypass that calculation; reading a device setting does no work.

class quchip.engine.frames.FrameMap(frequencies, energies, dims, transforms)

Bases: object

Map states and observables between the lab frame and an integration frame.

The integration frame removes Σᵢ fᵢ nᵢ from the Hamiltonian, where fᵢ is the frame frequency of device i in GHz and nᵢ its energy-level index. With U(t) = exp(−i 2π t Σᵢ fᵢ nᵢ) at absolute time t in ns, a lab-frame ket ψ is U(t)† ψ in the integration frame, and a density matrix or an observable X is U(t)† X U(t). U(t) is diagonal in energy coordinates. In a solver basis that differs from them, each device applies its energy-to-solver map. A Hamiltonian also gains −2π Σᵢ fᵢ nᵢ; assembly adds that term.

Variables:

• frequencies (tuple) – Frame frequency of each device, in GHz.

• energies (array_like, shape (N,)) – Frame energy Σᵢ fᵢ nᵢ of each coordinate, in GHz.

• dims (tuple of int) – Tensor factors of the coordinates.

• transforms (tuple) – Energy-to-solver map of each factor, or None where the factor uses energy coordinates.

frequencies: tuple[Any, ...]

energies: Any

dims: tuple[int, ...]

transforms: tuple[Any, ...]

classmethod create(frame, labels, bases, xp, *, space=None)

Return the map of product solver coordinates, or of the energy rows of an excitation space.

Parameters:

• frame (ResolvedFrame) – Integration frame of the solve.

• labels (sequence of str) – Device labels in tensor order.

• bases (mapping) – Resolved basis record of each device.

• xp (module) – Array module of the states.

• space (PulseSpace or None, optional) – Excitation space whose rows are energy levels. None selects product solver coordinates.

label_energy(levels)

Return the frame energy Σᵢ fᵢ kᵢ of a product label k, in GHz.

Parameters:

levels (sequence of int) – Energy level of each device.

phases(t)

Return the diagonal exp(i 2π t E) of U(t)†, with shape (N,) or (T, N).

Parameters:

t (scalar or array_like, shape (T,)) – Absolute time or times in ns.

kets(values, t, *, to_lab=False)

Map kets on the last axis from the lab frame into the integration frame, or back.

A ket of shape (N,) and a time array of shape (T,) give one ket per time.

Parameters:

• values (array_like, shape (..., N)) – Kets in the coordinates of this map.

• t (scalar or array_like) – Absolute time or times in ns.

• to_lab (bool, default=False) – Map from the integration frame into the lab frame.

operators(values, t, *, to_lab=False)

Map density matrices or observables on the last two axes: U† X U, or U X U† back.

Parameters:

• values (array_like, shape (..., N, N)) – Operators in the coordinates of this map.

• t (scalar or array_like) – Absolute time or times in ns.

• to_lab (bool, default=False) – Map from the integration frame into the lab frame.