quchip.engine.assembly

Assemble an EngineResult from chip physics, controls, and frame.

Hamiltonians enter in ordinary GHz and are scaled by 2π to rad/ns for d|ψ⟩/dt = -i H |ψ⟩. Carrier and observable-demodulation phases convert frequencies to rad/ns as well, and solver hints convert them back to GHz for display.

Rotating frames subtract Σᵢ ω_frame,ᵢ nᵢ from the static Hamiltonian. Coupling and drive operators split into excitation-change bands with weight w = col - row and carriers exp(-i w·ω t). Exact keeps every band. RWA keeps total-excitation-conserving static bands and matches delivered-signal bands to operator bands. Time dependence is represented by SignalProgram expressions, which backends lower to native coefficients.

References: Scully & Zubairy, Quantum Optics (1997), §5.1; Jaynes & Cummings, Proc. IEEE 51, 89 (1963); Walls & Milburn, Quantum Optics (2008), §10.3; Gambetta et al., PRA 74, 042318 (2006); Magesan & Gambetta, PRA 101, 052308 (2020).

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).
coupling_band_records(chip, resolution, backend)	Return nonzero interaction bands for frame planning.
drive_bands(chip, drive, target, bases, ...)	Yield kept band records, embedded operators, term indices and original signal weights.
instantiate_engine_result(template, ...)	Rebuild signal-program leaves from drive_ops and attach them to the template's operators.
port_band_records(chip, port, resolution, ...)	Return the excitation-change bands of one quantum port's coupling sqrt(kappa) A.

Classes

BandRecord(devices, charges, amplitude, source)	One excitation-change band of an authored operator, with its charge vector.
CompiledCoherentTerm(operation_index, ...)	One S[j, i] beta_i contribution to the canonical source drive.
CompiledDriveTerm(operator, delivered_key, ...)	One projected operator band from an authored drive Hamiltonian term.

class quchip.engine.assembly.BandRecord(devices, charges, amplitude, source, retained=False)

Bases: object

One excitation-change band of an authored operator, with its charge vector.

charges[i] is the photon-number change the band applies to devices[i]. amplitude is the band’s largest concrete matrix element or None when traced.

devices: tuple[str, ...]

charges: tuple[int, ...]

amplitude: float | None

source: str

retained: bool = False

quchip.engine.assembly.coupling_band_records(chip, resolution, backend)

Return nonzero interaction bands for frame planning.

quchip.engine.assembly.port_band_records(chip, port, resolution, backend)

Return the excitation-change bands of one quantum port’s coupling sqrt(kappa) A.

class quchip.engine.assembly.CompiledDriveTerm(operator, delivered_key, hamiltonian_term_index, weight, device_frame_freq, filter_signal_bands, origin='drive', tag=None)

Bases: object

One projected operator band from an authored drive Hamiltonian term.

operator: CanonicalOperator

delivered_key: tuple[str, int]

hamiltonian_term_index: int

weight: int

device_frame_freq: Any

filter_signal_bands: bool

origin: Literal['device', 'coupling', 'drive', 'crosstalk', 'flux', 'port', 'network'] = 'drive'

tag: str | None = None

class quchip.engine.assembly.CompiledCoherentTerm(operation_index, exposure, scattering, lowering, raising, frame_frequency)

Bases: object

One S[j, i] beta_i contribution to the canonical source drive.

operation_index: int

exposure: str

scattering: Any

lowering: CanonicalOperator

raising: CanonicalOperator

frame_frequency: Any

quchip.engine.assembly.drive_bands(chip, drive, target, bases, dims, backend, approximation, *, space=None, embed=True)

Yield kept band records, embedded operators, term indices and original signal weights.

quchip.engine.assembly.compile_hamiltonian_template(chip, drive_ops, *, resolved_frame, approximation=None, _local_resolution=None, _base_result=None, _advisories=None)

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

The template holds everything invariant across a homogeneous sweep: the 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. Envelope parameters, drive frequencies, phases, and frame scalars can therefore sweep through JAX without retracing operator tensors.

quchip.engine.assembly.instantiate_engine_result(template, drive_ops, chip)

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

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

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 you solve 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 ControlOp) – Scheduled classical-drive or coherent-field operations to embed as dynamic terms.

• resolved_frame (ResolvedFrame) – Resolved frame 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:

EngineResult