quchip.engine.stage2_assembly

Stage 2: assemble a HamiltonianDescription from chip, drive ops, and frame.

Responsibilities

This module owns the 2π boundary of the engine: inputs are ordinary GHz (ν), outputs are operators scaled by ω = 2π·ν so backends can solve Schrödinger’s equation with d|ψ⟩/dt = -i H |ψ⟩ in ns/rad units. The operator angular-scaling boundary lives entirely here, in:

  • _build_static_h0() — frame-subtracted bare Hamiltonian,

  • _collect_coupling_terms() — full interaction band-decomposed, each band filtered by the coupling’s RWA policy and folded into H₀ or carried, per band,

  • _apply_2pi_canonical() — the single point that scales every embedded dynamic operator (drive, crosstalk, coupling-dynamic, device-dynamic).

The same 2π convention also expresses signal-AST carrier and rotating-frame-phase frequencies in rad/ns (_single_tone_coefficient(), _direct_real_coefficient()) and the stage-3 demodulation phase; those are frequencies inside the time-dependence / observable bookkeeping, not a second Hamiltonian boundary. quchip.engine.solver_hints divides by 2π only to report advisory hints back in ordinary GHz.

Physics

Stage 2 performs three physically distinct operations on top of the 2π scaling:

  1. Rotating-frame transformation. Each device’s number operator is shifted by its frame reference ω_ref so that the static Hamiltonian becomes H₀ − Σᵢ ω_ref,ᵢ nᵢ (see any standard cQED reference, e.g. Scully & Zubairy, Quantum Optics, CUP 1997, §5.1).

  2. Band decomposition / rotating-wave approximation (RWA). Coupling and drive operators are split into excitation-change bands of weight w = col − row and attached to carriers exp(−i w·ω t). When rwa=True, counter-rotating coupling bands are dropped structurally by the coupling’s rwa_keeps_band predicate and counter-rotating drive bands by the modulation policies (Jaynes & Cummings, Proc. IEEE 51, 89 (1963); Walls & Milburn, Quantum Optics, Springer 2008, §10.3; for dispersive/structured cases see Gambetta et al., PRA 74, 042318 (2006), and the cross-resonance treatment in Magesan & Gambetta, PRA 101, 052308 (2020)).

  3. Signal-program construction. Time dependence is emitted as a SignalProgram AST — a pure, JAX-traceable description that backends lower into their native coefficient form.

Functions

build_hamiltonian_description(chip, ...)

One-shot stage 2: compile the template then instantiate a single variant.

compile_hamiltonian_template(chip, ...)

Compile the invariant Hamiltonian skeleton (H₀, couplings, pre-embedded drive bands).

instantiate_hamiltonian_description(...)

Rebuild signal-program leaves from drive_ops and attach them to the template's operators.

Classes

BandContext(weight, device_frame_freq, ...)

Per-Fourier-band context for the stage-2 modulation dispatch.

CompiledDriveTerm(operator, drive_index, ...)

One pre-embedded, 2π-scaled drive band plus its reinstantiation metadata.
class quchip.engine.stage2_assembly.BandContext(weight, device_frame_freq, drive_freq, rwa)[source]

Bases: object

Per-Fourier-band context for the stage-2 modulation dispatch.

Parameters:

  • weight (int) – Fourier band index (e.g. -1, 0, +1 for a single-mode device; arbitrary integer for higher bands).

  • device_frame_freq (float) – Device-frame oscillation frequency for this band, GHz.

  • drive_freq (float | None) – Carrier frequency for microwave drives, GHz; None for baseband (flux-like) drives.

  • rwa (bool) – Whether the engine is assembling in the rotating-wave approximation.

weight: int
device_frame_freq: Any
drive_freq: Any | None
rwa: bool
class quchip.engine.stage2_assembly.CompiledDriveTerm(operator, drive_index, modulation, weight, device_frame_freq, rwa, origin='drive', tag=None)[source]

Bases: object

One pre-embedded, 2π-scaled drive band plus its reinstantiation metadata.

Template-internal (stored on drive_terms, never handed to backends). During sweep instantiation, stage 2 combines weight, device_frame_freq, the variant’s drive frequency, and rwa into a BandContext, then dispatches on the channel’s DriveModulation tag to emit the variant-specific ScalarModulation for operator. device_frame_freq is in GHz (may be a traced scalar; see ResolvedFrame).

Parameters:
operator: CanonicalOperator
drive_index: int
modulation: DriveModulation
weight: int
device_frame_freq: Any
rwa: bool
origin: Literal['device', 'coupling', 'drive', 'crosstalk', 'flux'] = 'drive'
tag: str | None = None
quchip.engine.stage2_assembly.compile_hamiltonian_template(chip, drive_ops, *, resolved_frame)[source]

Compile the invariant Hamiltonian skeleton (H₀, couplings, pre-embedded drive bands).

Everything that does not change across a homogeneous sweep lives in the template: static Hamiltonian, static-coupling folds, invariant dynamic couplings, and band-decomposed drive operators pre-embedded and pre-scaled by 2π. Per-sweep instantiation (instantiate_hamiltonian_description()) rebuilds only the SignalProgram leaves, so envelope parameters, drive frequencies, phases, and frame scalars can sweep through JAX without retracing operator tensors.

Parameters:
Return type:

HamiltonianTemplate

quchip.engine.stage2_assembly.instantiate_hamiltonian_description(template, drive_ops, chip)[source]

Rebuild signal-program leaves from drive_ops and attach them to the template’s operators.

Parameters:
Return type:

HamiltonianDescription

quchip.engine.stage2_assembly.build_hamiltonian_description(chip, drive_ops, *, resolved_frame)[source]

One-shot stage 2: compile the template then instantiate a single variant.

Equivalent to compile_hamiltonian_template() followed by instantiate_hamiltonian_description() with the same drive_ops. Prefer the two-step form when solving many variants that share the same chip topology.

Parameters:

  • chip (Chip) – The chip whose device, coupling, and drive Hamiltonians are assembled (2π applied at this boundary).

  • drive_ops (list of DriveOp) – Scheduled drive operations to embed as dynamic terms.

  • resolved_frame (ResolvedFrame) – Stage-1 frame result carrying the per-device frame frequencies, demodulation frequencies, and frame mode.

Returns:

Static terms, dynamic terms, and dropped-term records for the single variant.

Return type:

HamiltonianDescription