quchip.engine.assembly

Assemble an EngineResult from chip, drive operations, 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,

  • _resolve_coupling_terms() — full interaction band-decomposed, each band handled by the chip’s approximation strategy 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 observable-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

Assembly 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). Exact retains them all. RWA retains total-excitation-conserving static bands and matches delivered-signal bands to operator bands (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_engine_result(chip, drive_ops, *, ...)

Compile the template and instantiate one engine-result variant.

compile_hamiltonian_template(chip, ...[, ...])

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

instantiate_engine_result(template, ...)

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

Classes

CompiledDriveTerm(operator, delivered_index, ...)

One projected operator band from an authored drive Hamiltonian term.
class quchip.engine.assembly.CompiledDriveTerm(operator, delivered_index, hamiltonian_term_index, weight, device_frame_freq, filter_signal_bands, origin='drive', tag=None)[source]

Bases: object

One projected operator band from an authored drive Hamiltonian term.

Parameters:

  • operator (CanonicalOperator)

  • delivered_index (int)

  • hamiltonian_term_index (int)

  • weight (int)

  • device_frame_freq (Any)

  • filter_signal_bands (bool)

  • origin (Literal['device', 'coupling', 'drive', 'crosstalk', 'flux'])

  • tag (str | None)

operator: CanonicalOperator
delivered_index: int
hamiltonian_term_index: int
weight: int
device_frame_freq: Any
filter_signal_bands: bool
origin: Literal['device', 'coupling', 'drive', 'crosstalk', 'flux'] = 'drive'
tag: str | None = None
quchip.engine.assembly.compile_hamiltonian_template(chip, drive_ops, *, resolved_frame, approximation=None, _local_resolution=None, _base_result=None)[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_engine_result()) 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.assembly.instantiate_engine_result(template, drive_ops, chip)[source]

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

Parameters:
Return type:

EngineResult

quchip.engine.assembly.build_engine_result(chip, drive_ops, *, resolved_frame, approximation=None, _local_resolution=None, _base_result=None)[source]

Compile the template and instantiate one engine-result variant.

Equivalent to compile_hamiltonian_template() followed by instantiate_engine_result() 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) – Resolved frame carrying the per-device frame frequencies, demodulation frequencies, and frame mode.

  • approximation (Approximation | None)

  • _local_resolution (_LocalResolution | None)

  • _base_result (EngineResult | None)

Returns:

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

Return type:

EngineResult