quchip.engine.ir

IR types shared by engine responsibilities and backends.

This module is the contract between the engine and its backends. It defines four families of immutable, JAX-pytree-friendly types:

1. Signal Program AST: the subclasses of SignalNode (Constant, EnvelopeRef, Window, Shift, Scale, PolarScale, Add, Multiply, Conjugate, RealPart, Carrier). They describe, purely functionally, a time-dependent scalar coefficient f(t) : ℝ → ℂ. Every sweepable leaf (envelope parameters, amplitudes, phases, and carrier frequencies) is a pytree leaf, so the whole program is differentiable through JAX.

2. CanonicalOperator: backend-free operator storage in dense / CSR / DIA layouts plus subsystem metadata. Backends convert to and from this format.

3. Resolved open-system physics: ResolvedSLH plus solve-applied Hamiltonian terms in EngineResult.

4. Solve requests: SolveProblem and SolveBatch, the frozen hand-offs to backends. The chip owns the backend selection. Do not put backend in options.

A note on 2π: engine assembly scales every operator here by 2π. Carrier frequencies are stored in angular units (rad/ns). IR consumers (backends, analyses) must not re-apply 2π.

Functions

decompose_carrier_bands(signal)	Rewrite signal into Σ_k envelope_k(t) · exp(i · freq_k · t) with carrier-free envelopes.
evaluate_signal_program(signal, t, *[, xp])	Evaluate a signal program at time(s) t (ns); xp defaults to NumPy.
signal_children(node)	Return the SignalProgram child nodes of node.
signal_window_bounds(signal[, shift])	Return absolute window edges, and keep native values and batch axes.
simplify_signal(signal)	Recursively simplify a signal program by canceling exact opposing carrier pairs.

Classes

Add(children)
BoundCoherentInput(exposure, source_label, ...)	One solve-bound incident field, kept outside input-free SLH.
CanonicalOperator(layout, values, shape, ...)	Backend-free operator with explicit dense/CSR/DIA payload and subsystem metadata.
Carrier(freq[, sign])	Oscillating carrier exp(sign · i · freq · t).
CarrierBand(envelope, freq)	One band of a carrier-normalized signal: envelope(t) · exp(i · freq · t).
CoefficientRef(coefficient)	Internal signal leaf backed by a public component-owned coefficient.
CoherenceResponseProblem(frequencies, ...)	Frequency response on adjacent excitation-sector coherences.
CoherentOp(coherent_input, envelope[, freq, ...])	Coherent field operation scheduled on an external SLH exposure.
CollapseTerm(operator, rate, source, channel)	Backend-neutral Lindblad channel, optionally exposed as a port.
Conjugate(child)
Constant(value)
DriveOp(target_label, envelope[, freq, ...])	Drive operation scheduled on a device or a modulable coupling.
DroppedTerm(source, operator, reason[, ...])	Advisory record for a Hamiltonian term elided by an approximation.
DynamicTerm(operator, time_dependence[, ...])	Time-dependent Hamiltonian contribution operator · f(t).
EngineResult(slh[, applied_hamiltonian, ...])	Backend-neutral resolved physics passed to backends.
EnvelopeRef(envelope)	Reference to a pulse envelope evaluated at local time.
HamiltonianProgram([static_terms, dynamic_terms])	Resolved static and time-dependent Hamiltonian contributions.
HamiltonianTemplate(base_result[, ...])	Captured chip physics and pre-embedded bands for homogeneous drive sweeps.
ImagPart(child)	Imaginary quadrature of a complex analytic signal.
LinearResponseProblem(frequencies, ...[, ...])	Passive-linear input-output request handed to a backend.
Multiply(children)
PolarScale(child, amplitude, theta)	Scale child by amplitude * exp(i * theta) (both are pytree leaves).
RealPart(child)
ResolvedFrame(frequencies, demod_freqs, mode)	Resolved per-device frame information.
ResolvedSLH(scattering, hamiltonian[, ...])	Immutable, input-free normal form for resolved Markovian physics.
SLHChannel(key, accessibility, collapse[, ...])	One resolved Markov channel and its boundary accessibility.
ScalarModulation(signal)	Mark a SignalProgram as a scalar modulation.
Scale(child, factor)	Multiply child by a complex scalar factor.
Shift(child, delta_t)	Time-shift child by delta_t: child(t - delta_t).
SignalNode()	Base class for signal-program AST nodes.
SignalPower(child, exponent)	Pointwise power of a scalar signal program.
SignalProgram
SolveBatch(chip, problems[, params, shape, ...])	Explicit solve problems sharing one dispatch owner and sweep shape.
SolveProblem(chip, engine_result, ...[, ...])	Immutable simulation request handed from the chip pipeline to a backend.
StaticTerm(operator[, coefficient, origin, ...])	Time-independent Hamiltonian contribution.
SteadyStateProblem(chip, engine_result[, ...])	Immutable static Lindblad request handed from a chip to its backend.
Window(child, start, stop)	Gate child to [start, stop]; zero outside.

class quchip.engine.ir.SignalNode

Bases: object

Base class for signal-program AST nodes.

A node describes a time-dependent scalar f(t) : ℝ → ℂ. Subclasses:

• are @dataclass(frozen=True). Every dataclass field is a JAX pytree child. Defining a subclass registers it automatically, so any sweepable field is differentiable.

• name the fields that hold child nodes (or tuples of child nodes) in _signal_child_fields. This attribute supplies generic traversal (signal_children()) and rewriting (rebuild_children()).

• implement evaluate(), the pointwise semantics of the node.

• override bands() when (and only when) the node interacts with Carrier leaves. The default treats any carrier-free subtree as a single zero-frequency band, which is exact for every envelope-like node.

signal_children()

Return this node’s child nodes (flattening tuple-valued fields).

rebuild_children(transform)

Reconstruct this node with transform applied to each child.

Non-child fields are preserved; nodes without children pass through unchanged.

Parameters:

transform (callable) – Function applied to every direct signal child.

evaluate(t, *, xp)

Evaluate the node in a selected array namespace.

Parameters:

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

• xp (module) – NumPy-like array namespace.

bands()

Rewrite this subtree into carrier-normalized bands.

By default, a carrier-free subtree is exactly one zero-frequency band whose envelope is the subtree itself. Nodes whose subtrees can contain Carrier leaves must override this with their carrier algebra (see decompose_carrier_bands()).

class quchip.engine.ir.Constant(value: 'complex')

Bases: SignalNode

value: complex

evaluate(t, *, xp)

Return the constant value, broadcast to the shape of t.

bands()

Return the single zero-frequency band carrying this constant.

class quchip.engine.ir.EnvelopeRef(envelope)

Bases: SignalNode

Reference to a pulse envelope evaluated at local time.

envelope: Envelope

evaluate(t, *, xp)

Return the referenced envelope’s complex value(t).

bands()

Return the single zero-frequency band carrying this envelope.

class quchip.engine.ir.CoefficientRef(coefficient)

Bases: SignalNode

Internal signal leaf backed by a public component-owned coefficient.

coefficient: TimeCoefficient

evaluate(t, *, xp)

Evaluate the node in a selected array namespace.

Parameters:

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

• xp (module) – NumPy-like array namespace.

class quchip.engine.ir.Window(child, start, stop)

Bases: SignalNode

Gate child to [start, stop]; zero outside.

child: SignalNode

start: float

stop: float

evaluate(t, *, xp)

Return the child value inside [start, stop] (ns), zero elsewhere.

bands()

Return the child bands with the same time gate applied to each envelope.

class quchip.engine.ir.Shift(child, delta_t)

Bases: SignalNode

Time-shift child by delta_t: child(t - delta_t).

child: SignalNode

delta_t: float

evaluate(t, *, xp)

Return the child evaluated at t - delta_t (ns).

bands()

Return the child bands, each carrying the shift’s carrier phase.

A time shift distributes over bands and contributes the constant carrier phase exp(-i·freq·Δt) per band.

class quchip.engine.ir.Scale(child, factor)

Bases: SignalNode

Multiply child by a complex scalar factor.

child: SignalNode

factor: complex

evaluate(t, *, xp)

Return the child value scaled by factor.

bands()

Return the child bands with factor folded into each envelope.

class quchip.engine.ir.PolarScale(child, amplitude, theta)

Bases: SignalNode

Scale child by amplitude * exp(i * theta) (both are pytree leaves).

child: SignalNode

amplitude: float

theta: float

evaluate(t, *, xp)

Return the child value scaled by amplitude * exp(i * theta).

bands()

Return the child bands with the polar scale folded into each envelope.

class quchip.engine.ir.Add(children: 'tuple[SignalNode, ...]')

Bases: SignalNode

children: tuple[SignalNode, ...]

evaluate(t, *, xp)

Return the sum of the children evaluated at t (ns).

bands()

Return the concatenation of every child’s bands.

class quchip.engine.ir.Multiply(children: 'tuple[SignalNode, ...]')

Bases: SignalNode

children: tuple[SignalNode, ...]

evaluate(t, *, xp)

Return the product of the children evaluated at t (ns).

bands()

Return the frequency convolution: the Cartesian product of child bands.

class quchip.engine.ir.Conjugate(child: 'SignalNode')

Bases: SignalNode

child: SignalNode

evaluate(t, *, xp)

Return the complex conjugate of the child evaluated at t (ns).

bands()

Return the child bands with each envelope conjugated and its frequency negated.

class quchip.engine.ir.RealPart(child: 'SignalNode')

Bases: SignalNode

child: SignalNode

evaluate(t, *, xp)

Return the real part of the child evaluated at t (ns).

bands()

Return each band split into ±freq halves with Re z = (z + z̄) / 2.

class quchip.engine.ir.ImagPart(child)

Bases: SignalNode

Imaginary quadrature of a complex analytic signal.

child: SignalNode

evaluate(t, *, xp)

Return the imaginary part of the child evaluated at t (ns).

bands()

Split bands using Im z = (z - z_bar) / (2i).

class quchip.engine.ir.SignalPower(child, exponent)

Bases: SignalNode

Pointwise power of a scalar signal program.

child: SignalNode

exponent: Any

evaluate(t, *, xp)

Evaluate the node in a selected array namespace.

Parameters:

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

• xp (module) – NumPy-like array namespace.

bands()

Rewrite this subtree into carrier-normalized bands.

By default, a carrier-free subtree is exactly one zero-frequency band whose envelope is the subtree itself. Nodes whose subtrees can contain Carrier leaves must override this with their carrier algebra (see decompose_carrier_bands()).

class quchip.engine.ir.Carrier(freq, sign=-1)

Bases: SignalNode

Oscillating carrier exp(sign · i · freq · t).

freq is in angular units (rad/ns). The default sign = -1 matches the rotating-frame decomposition convention (Scully & Zubairy, Quantum Optics, §5). In this convention, a raising-type band on a +Δ detuning rotates as exp(−iΔt). Both fields are registered as pytree children. freq can be traced, but sign is semantically a static ±1, so do not map over it.

Variables:

• freq (scalar) – Angular carrier frequency in rad/ns.

• sign ({-1, 1}) – Sign in the complex exponential.

freq: float

sign: Literal[-1, 1] = -1

evaluate(t, *, xp)

Return exp(sign · i · freq · t).

Parameters:

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

• xp (module) – NumPy-like array namespace.

bands()

Return the single sign·freq band with a unit-constant envelope.

quchip.engine.ir.SignalProgram

alias of SignalNode

class quchip.engine.ir.ScalarModulation(signal)

Bases: object

Mark a SignalProgram as a scalar modulation.

Variables:

signal (SignalProgram) – Backend-neutral scalar time dependence.

signal: SignalNode

quchip.engine.ir.signal_children(node)

Return the SignalProgram child nodes of node.

Dispatches to SignalNode.signal_children(). A ScalarModulation wrapper contributes its signal. EnvelopeRef.envelope is an Envelope, not a SignalProgram child, and so is not returned here.

quchip.engine.ir.signal_window_bounds(signal, shift=0.0)

Return absolute window edges, and keep native values and batch axes.

Enclosing shifts move every descendant window’s clock. Collecting the structure makes no numerical decisions, so timing stays differentiable.

quchip.engine.ir.evaluate_signal_program(signal, t, *, xp=None)

Evaluate a signal program at time(s) t (ns); xp defaults to NumPy.

quchip.engine.ir.simplify_signal(signal)

Recursively simplify a signal program by canceling exact opposing carrier pairs.

class quchip.engine.ir.CarrierBand(envelope, freq)

Bases: object

One band of a carrier-normalized signal: envelope(t) · exp(i · freq · t).

decompose_carrier_bands() rewrites any SignalProgram into a sum of these bands. Each envelope is carrier-free (no Carrier leaves) and therefore slow. freq is the angular band frequency (rad/ns, sign folded in, JAX-traceable). Backends use this to keep the fast oscillation analytic and sample only the slow envelope. Unlike pre-sampling the whole product, this is exact for every carrier, resonant or not.

envelope: SignalNode

freq: Any

quchip.engine.ir.decompose_carrier_bands(signal)

Rewrite signal into Σ_k envelope_k(t) · exp(i · freq_k · t) with carrier-free envelopes.

It is the scalar-coefficient analogue of the operator band decomposition in quchip.engine.bands. Every Carrier leaf is pulled out into a band frequency, leaving a slow, carrier-free envelope for each band. The rewrite is exact and follows the carrier algebra, implemented node-locally in each SignalNode.bands():

• Carrier(freq, sign) → one band (1, sign·freq).

• Conjugate → conjugate the envelope, flip the band frequency.

• RealPart → split each band into ±freq (Re z = (z+z̄)/2).

• Multiply → frequency convolution (Cartesian product of bands).

• Add → concatenate bands.

• Scale / PolarScale / Window / Shift → distribute over bands (Shift also contributes the constant phase exp(-i·freq·Δt)).

All frequency arithmetic stays in JAX-traceable terms (no float(), no branching on traced values).

class quchip.engine.ir.CanonicalOperator(layout, values, shape, dims, basis, subsystem_labels, indices=None, indptr=None, offsets=None, tag=None)

Bases: object

Backend-free operator with explicit dense/CSR/DIA payload and subsystem metadata.

For dense, the payload is the full 2D matrix. For csr, it is the 1D nonzero value array paired with indices/indptr. For dia, it is a 2D (n_diags, n_cols) array paired with offsets. dims must multiply to shape[0] and subsystem_labels names each subsystem.

Variables:

• layout ({"dense", "csr", "dia"}) – Storage layout of values.

• values (array_like) – Matrix or sparse payload.

• shape (tuple of int) – Square operator shape.

• dims (tuple of int) – Subsystem dimensions.

• basis (str) – Basis convention for the payload.

• subsystem_labels (tuple of str) – Labels matching dims.

• offsets (indices, indptr,) – Sparse CSR/DIA metadata.

• tag (str or None) – Optional diagnostic label.

layout: Literal['dense', 'csr', 'dia']

values: Any

shape: tuple[int, int]

dims: tuple[int, ...]

basis: str

subsystem_labels: tuple[str, ...]

indices: Any | None = None

indptr: Any | None = None

offsets: Any | None = None

tag: str | None = None

property is_sparse: bool

True for the csr / dia layouts, False for dense.

classmethod from_dense(values, *, dims, basis, subsystem_labels, tag=None)

Build a dense canonical operator.

Parameters:

• values (array_like) – Square dense matrix.

• dims (tuple of int) – Subsystem dimensions.

• basis (str) – Basis convention for values.

• subsystem_labels (tuple of str) – Labels matching dims.

• tag (str or None, optional) – Diagnostic label.

classmethod from_csr(values, indices, indptr, *, shape, dims, basis, subsystem_labels, tag=None)

Build a CSR canonical operator.

Parameters:

• values (array_like) – CSR payload arrays.

• indices (array_like) – CSR payload arrays.

• indptr (array_like) – CSR payload arrays.

• shape (tuple of int) – Square matrix shape.

• dims (tuple of int) – Subsystem dimensions.

• basis (str) – Basis convention for the payload.

• subsystem_labels (tuple of str) – Labels matching dims.

• tag (str or None, optional) – Diagnostic label.

classmethod from_dia(values, offsets, *, shape, dims, basis, subsystem_labels, tag=None)

Build a DIA canonical operator.

Parameters:

• values (array_like) – Diagonal payload and integer offsets.

• offsets (array_like) – Diagonal payload and integer offsets.

• shape (tuple of int) – Square matrix shape.

• dims (tuple of int) – Subsystem dimensions.

• basis (str) – Basis convention for the payload.

• subsystem_labels (tuple of str) – Labels matching dims.

• tag (str or None, optional) – Diagnostic label.

with_metadata(*, dims=None, basis=None, subsystem_labels=None, tag=None)

Return a metadata-adjusted copy with unchanged payload.

Parameters:

• dims (tuple of int or None, optional) – Replacement subsystem dimensions.

• basis (str or None, optional) – Replacement basis convention.

• subsystem_labels (tuple of str or None, optional) – Replacement subsystem labels.

• tag (str or None, optional) – Replacement diagnostic label.

scaled(factor, *, tag=None)

Return a scalar multiple without changing the operator layout.

Parameters:

• factor (scalar) – Multiplier applied to the payload.

• tag (str or None, optional) – Replacement diagnostic label.

diagonal()

Return the main diagonal without materializing a sparse matrix.

to_dense()

Materialize the payload as a dense shape-sized matrix.

Vectorized and array-namespace-preserving (JAX-safe). A traced JAX payload yields a JAX array through .at[].set / .add. A concrete NumPy payload yields a NumPy array. Callers that need a guaranteed concrete NumPy matrix must wrap the result in np.asarray(..., dtype=complex) themselves.

fingerprint()

Batching key: value-sensitive, with an automatic tracer-safe fallback.

Two crosstalk-rebuilt operators carrying the same coefficients collapse to the same key so they batch into one solve slot. Under jax.jit, the payload is a tracer, possibly hidden inside a backend qarray wrapper such as a sparse-DIA dynamiqs QArray. contains_tracer() detects this case, and the key falls back to layout + shape/dtype structure only, so tobytes() is never called on a tracer. Two equivalent traced operators in different batch slots still produce identical keys.

class quchip.engine.ir.StaticTerm(operator, coefficient=1.0, origin='device', metadata=<factory>)

Bases: object

Time-independent Hamiltonian contribution.

Engine assembly scales the operator payload by 2π, so backends must not re-apply it. coefficient multiplies operator and can be a concrete scalar or a JAX tracer (for example, sweeps over static couplings or detunings). origin is purely advisory metadata.

Variables:

• operator (CanonicalOperator) – Angular-frequency operator payload.

• coefficient (scalar) – Scalar multiplier, default one.

• origin (str) – Component category that authored the term.

• metadata (dict) – Advisory term metadata.

operator: CanonicalOperator

coefficient: complex = 1.0

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

metadata: dict[str, Any]

class quchip.engine.ir.DynamicTerm(operator, time_dependence, origin='drive', tag=None)

Bases: object

Time-dependent Hamiltonian contribution operator · f(t).

f(t) is wrapped in ScalarModulation, which each backend lowers into its native coefficient representation (for example, a QuTiP callback or a dynamiqs sampled array). The operator is 2π-scaled already (see module docstring). tag is an optional human label that does not participate in physics.

Variables:

• operator (CanonicalOperator) – Angular-frequency operator payload.

• time_dependence (ScalarModulation) – Scalar coefficient evaluated in time.

• origin (str) – Component category that authored the term.

• tag (str or None) – Optional diagnostic label.

operator: CanonicalOperator

time_dependence: ScalarModulation

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

tag: str | None = None

class quchip.engine.ir.CollapseTerm(operator, rate, source, channel, parameter_paths=(), phase=None, frame_frequency=None)

Bases: object

Backend-neutral Lindblad channel, optionally exposed as a port.

Variables:

• operator (CanonicalOperator) – Dimensionless local jump operator before rate scaling.

• rate (scalar) – Lindblad rate in 1/ns.

• channel (source,) – Owning component and local channel labels.

• parameter_paths (tuple of str) – Parameter paths controlling the channel.

• phase (scalar or None) – Coupling phase in radians.

• frame_frequency (scalar or None) – Accessible-channel carrier in GHz; None marks a hidden channel.

operator: CanonicalOperator

rate: Any

source: str

channel: str

parameter_paths: tuple[str, ...] = ()

phase: Any = None

frame_frequency: Any = None

property label: str

Return the input-output label for an accessible channel.

latex()

Render this collapse channel as an opaque named operator.

class quchip.engine.ir.HamiltonianProgram(static_terms=(), dynamic_terms=())

Bases: object

Resolved static and time-dependent Hamiltonian contributions.

Variables:

• static_terms (tuple of StaticTerm) – Time-independent contributions.

• dynamic_terms (tuple of DynamicTerm) – Time-dependent contributions.

static_terms: tuple[StaticTerm, ...] = ()

dynamic_terms: tuple[DynamicTerm, ...] = ()

class quchip.engine.ir.SLHChannel(key, accessibility, collapse, coupling_operator=None, reference=<factory>, input_occupation=None)

Bases: object

One resolved Markov channel and its boundary accessibility.

Variables:

• key (str) – Unique resolved channel key.

• accessibility ({"exposed", "hidden"}) – If the channel reaches the modeled experiment boundary.

• collapse (CollapseTerm) – Component-authored channel record.

• coupling_operator (CanonicalOperator or None) – Resolved physical coupling operator, when already composed.

• reference (ReferencePlane) – External reference-plane transfer.

• input_occupation (scalar or None) – Markov input occupation for a thermal field.

key: str

accessibility: Literal['exposed', 'hidden']

collapse: CollapseTerm

coupling_operator: CanonicalOperator | None = None

reference: ReferencePlane

input_occupation: Any = None

property carrier: Any

Return this channel’s stationary carrier in GHz, zero when unframed.

property coupling: CanonicalOperator

Return the physical coupling operator for this channel.

property collapse_term: CollapseTerm

Return the solver-facing collapse record for this resolved channel.

class quchip.engine.ir.ResolvedSLH(scattering, hamiltonian, channels=(), support=None, output_network=None)

Bases: object

Immutable, input-free normal form for resolved Markovian physics.

Variables:

• scattering (array_like) – Unitary scalar channel matrix S.

• hamiltonian (HamiltonianProgram) – Resolved Hamiltonian H.

• channels (tuple of SLHChannel) – Coupling channels L in scattering order.

• support (array_like or None) – Boolean structural reachability matrix.

• output_network (object or None) – Captured external output processing.

Notes

See Physics reference for the SLH composition and channel conventions.

scattering: Any

hamiltonian: HamiltonianProgram

channels: tuple[SLHChannel, ...] = ()

support: Any = None

output_network: Any = None

property has_network_hamiltonian: bool

Return if connection resolution generated coherent Hamiltonian terms.

classmethod from_terms(*, static_terms, dynamic_terms, collapse_terms)

Build an identity-scattering model from engine terms.

Parameters:

• static_terms (tuple of StaticTerm) – Static Hamiltonian contributions.

• dynamic_terms (tuple of DynamicTerm) – Dynamic Hamiltonian contributions.

• collapse_terms (tuple of CollapseTerm) – Component-authored Lindblad channels.

property S: Any

Return the scalar scattering matrix.

feeds(output_index, input_index)

Return if one input structurally reaches one output.

Parameters:

• output_index (int) – Output row and input column in channel order.

• input_index (int) – Output row and input column in channel order.

property L: tuple[CanonicalOperator, ...]

Return physical coupling operators in channel order.

property H: HamiltonianProgram

Return the resolved Hamiltonian program.

property external_channels: tuple[SLHChannel, ...]

Return the exposed boundary channels.

property hidden_channels: tuple[SLHChannel, ...]

Return channels traced out by the modeled experiment.

property collapse_terms: tuple[CollapseTerm, ...]

Return solver-facing collapse records in resolved channel order.

class quchip.engine.ir.DroppedTerm(source, operator, reason, band_weights=None, amplitude=None, frequency=None, frame_frequency=None)

Bases: object

Advisory record for a Hamiltonian term elided by an approximation.

For static interactions, amplitude and frequency identify the entry with the largest |V|²/|E_col - E_row| in isolated energy coordinates. This perturbative scale is a heuristic, not an error bound. A nonzero entry at zero detuning is resonant. Its scale is infinite. A zero amplitude contributes no shift. Numeric fields use ordinary GHz and can be traced. The selected entry can change as parameters vary.

Parameters:

• source (str) – Label of the owning component (coupling / drive / …) that dropped the term.

• operator (str) – Human-readable operator string (for example "a_q0 · a_q1").

• reason (str) – Short reason (for example "discarded by RWA band selection").

• band_weights (tuple[int, ...] | None) – Energy-index weights column - row, one per supported device in the owner’s declared order (for example (1, 1) for a·b). Lowering has positive weight, opposite to the level change. None when not applicable.

• amplitude (Any | None) – Magnitude of the selected static matrix element in GHz, possibly traced. None for time-dependent terms or unknown amplitudes.

• frequency (Any | None) – Absolute bare-energy detuning of that same entry in GHz, independent of the frame and possibly traced. Zero denotes resonance. None when unknown, including general time-dependent terms.

• frame_frequency (Any | None) – Absolute frame carrier in GHz, possibly traced. For a scheduled drive this includes its dropped signal partner. None when unknown. This carrier is not a physical transition detuning.

source: str

operator: str

reason: str

band_weights: tuple[int, ...] | None = None

amplitude: Any = None

frequency: Any = None

frame_frequency: Any = None

class quchip.engine.ir.BoundCoherentInput(exposure, source_label, beta, reference_beta)

Bases: object

One solve-bound incident field, kept outside input-free SLH.

reference_beta is the signal scheduled at the authored external reference plane. beta is shifted by the total duration of the exposure’s inbound reference run and is the field composed with the Markov boundary.

exposure: str

source_label: str

beta: SignalNode

reference_beta: SignalNode

class quchip.engine.ir.EngineResult(slh, applied_hamiltonian=<factory>, coherent_inputs=(), dims=(), metadata=<factory>, dropped_terms=(), bases=<factory>, authored=None, resolved_frame=None, approximation=None, dynamical_supports=(), dissipation=True, excitation_space=None, _dressing_context=None)

Bases: object

Backend-neutral resolved physics passed to backends.

Represents

\[H(t) \;=\; \sum_s c_s \, O_s \;+\; \sum_d O_d \, f_d(t)\]

slh is the input-free Markov model. applied_hamiltonian holds scheduled controls and solve-bound coherent drives. Operators already include the 2π conversion. Backends can use metadata integration hints but remain responsible for resolving finite-support dynamics. dropped_terms is advisory approximation metadata.

Variables:

• slh (ResolvedSLH) – Input-free resolved scattering, Hamiltonian, and channel description.

• applied_hamiltonian (HamiltonianProgram) – Solve-bound static and dynamic terms added after the input-free model.

• coherent_inputs (tuple) – Captured coherent source bindings used to assemble those terms.

• dims (tuple of int) – Solver dimensions. A compact solve uses one coordinate axis. Physical dimensions remain in excitation_space and in the public result.

• excitation_space (object or None) – Captured exact excitation coordinate map. None denotes product coordinates.

• metadata (dict) – Advisory solver hints, with frequencies in GHz and time scales in ns.

• dropped_terms (tuple of DroppedTerm) – Terms removed by the selected approximation, kept for diagnostics.

• bases (mapping) – Per-device authored-to-solver basis records.

• authored (object or None) – Captured authored physics description.

• resolved_frame (ResolvedFrame) – Frame frequencies and demodulation convention used by assembly.

• approximation (Approximation or None) – Approximation captured by this resolved snapshot.

• dynamical_supports (tuple of tuple of str) – Device groups coupled by kept dynamical terms.

• dissipation (bool) – If collapse_terms exposes the resolved dissipators.

slh: ResolvedSLH

applied_hamiltonian: HamiltonianProgram

coherent_inputs: tuple[BoundCoherentInput, ...] = ()

dims: tuple[int, ...] = ()

metadata: dict[str, Any]

dropped_terms: tuple[DroppedTerm, ...] = ()

bases: Mapping[str, Any]

authored: Any = None

resolved_frame: Any = None

approximation: Any = None

dynamical_supports: tuple[tuple[str, ...], ...] = ()

dissipation: bool = True

excitation_space: Any = None

property static_terms: tuple[StaticTerm, ...]

Return resolved and solve-applied static Hamiltonian terms.

property dynamic_terms: tuple[DynamicTerm, ...]

Return resolved and solve-applied time-dependent Hamiltonian terms.

property collapse_terms: tuple[CollapseTerm, ...]

Return active collapse records in SLH channel order.

dress(*, at_time=None, overlap_threshold=0.5, labeling='DE')

Dress this resolved Hamiltonian, optionally at one instant.

Unlike Chip.dress, this method analyzes the selected frame and approximation stored in this snapshot. A snapshot with dynamic Hamiltonian terms requires at_time. The result is an instantaneous eigensystem, not a Floquet analysis. A compact pulse snapshot analyzes only its retained invariant space. Its eigenstates use those compact solver coordinates.

Parameters:

• at_time (scalar or None, optional) – Instant in ns for dynamic snapshots.

• overlap_threshold (float, default=0.5) – Minimum bare-state overlap accepted for labeling.

• labeling (str, default="DE") – Bare-to-dressed assignment strategy.

with_applied_hamiltonian_terms(*, static_terms=None, dynamic_terms=None)

Return a copy with solve-bound Hamiltonian terms replaced.

Parameters:

• static_terms (tuple of StaticTerm or None, optional) – Replacement static terms. None keeps them.

• dynamic_terms (tuple of DynamicTerm or None, optional) – Replacement dynamic terms. None keeps them.

property port_terms: tuple[CollapseTerm, ...]

Return active collapse channels that cross an accessible port boundary.

hamiltonian()

Return the exact canonical Hamiltonian as an inspectable expression.

This view derives from the same terms backends receive. Matrix leaves remain opaque, while each dynamic coefficient renders as a named function of time.

latex()

Render the canonical Hamiltonian with named time functions.

dropped_terms_summary()

Format dropped_terms as a multi-line human-readable string.

Traced numeric values print as traced and are not concretized.

class quchip.engine.ir.HamiltonianTemplate(base_result, drive_terms=(), coherent_terms=(), reference_drive_ops=(), delivered_keys=frozenset({}))

Bases: object

Captured chip physics and pre-embedded bands for homogeneous drive sweeps.

base_result owns invariant operators, channels, bases and diagnostics. Reference operations and delivered keys guard the routing and pulse topology. Only signal-program leaves are rebuilt for each variant.

base_result: EngineResult

drive_terms: tuple[Any, ...] = ()

coherent_terms: tuple[Any, ...] = ()

reference_drive_ops: tuple[Any, ...] = ()

delivered_keys: frozenset[SignalKey] = frozenset({})

class quchip.engine.ir.ResolvedFrame(frequencies, demod_freqs, mode, plan=None)

Bases: object

Resolved per-device frame information.

Describes the rotating-frame transformation applied uniformly to the chip. The static Hamiltonian gets the counter-term −Σᵢ ω_frame,ᵢ nᵢ, and solves and results keep states in this integration frame.

Variables:

• frequencies (dict) – Integration-frame frequency ω_frame of each device label, in GHz.

• demod_freqs (dict) – reference_freq − ω_frame of each device label, in GHz. After the solve, this frequency rotates expectations back into the user’s control frame. reference_freq is the device attribute (see reference_freq), which defaults to the dressed drive frequency.

• mode (str) – One of "lab", "rotating", "auto", "float" and "dict".

• plan (FramePlan or None) – The FramePlan selected for "auto", or None for an explicit frame.

frequencies: dict[str, Any]

demod_freqs: dict[str, Any]

mode: str

plan: FramePlan | None = None

class quchip.engine.ir.SolveProblem(chip, engine_result, initial_state, tlist, e_ops=None, e_ops_meta=None, resolved_frame=None, solver=None, options=<factory>, *, truncation=None, states=None, run_args=<factory>, monitoring=None, backend=None, device_info=())

Bases: object

Immutable simulation request handed from the chip pipeline to a backend.

Backend selection is captured separately from options. e_ops_meta reconstructs flattened band expectations into public dict-keyed observables.

Variables:

• chip (Chip) – Source chip captured by the request.

• engine_result (EngineResult) – Frozen resolved physics.

• initial_state (state_like) – Initial ket or density matrix in solver coordinates.

• tlist (array_like) – Solver times in ns.

• e_ops (sequence or None) – Backend-ready expectation operators.

• e_ops_meta (object or None) – Metadata used to reconstruct public observables.

• resolved_frame (ResolvedFrame) – Captured integration and demodulation frame.

• solver (str or None) – Explicit solver selection.

• options (dict) – Backend solver options. A "backend" key is rejected.

• run_args (dict) – Native trajectory call keywords, separate from integrator options.

• monitoring (dict or None) – Captured channel-index to (efficiency, phase) selection; prepare with_monitoring().

• truncation (object or None) – Captured boundary-population plan.

• states ({"all", "final", "none"} or None) – None keeps native stochastic defaults. Deterministic requests resolve it to all.

• backend (Backend) – Captured backend owner.

• device_info (tuple) – Device labels and computational flags in subsystem order.

chip: Any

engine_result: Any

initial_state: Any

tlist: Any

e_ops: Any = None

e_ops_meta: Any = None

resolved_frame: Any = None

solver: str | None = None

options: dict[str, Any]

truncation: Any = None

states: Literal['all', 'final', 'none'] | None = None

run_args: dict[str, Any]

monitoring: dict[int, tuple[Any, Any]] | None = None

backend: Any = None

device_info: tuple[tuple[str, bool], ...] = ()

property stochastic: bool

Return if an explicitly selected native solver produces trajectories.

property dissipation: bool

Return if this calculation includes the resolved dissipators.

solver_name(backend)

Return the selected solver name.

An explicit solver takes precedence, but sesolve is rejected for a density matrix. Otherwise, select sesolve only for a ket with no collapse terms, and mesolve for a density matrix or any problem with collapse terms.

Parameters:

backend (Backend) – Backend used to classify the initial state.

class quchip.engine.ir.LinearResponseProblem(frequencies, mode_labels, hamiltonian, couplings, scattering, plane_indices, inbound_transfer, outbound_transfer, field_channels=())

Bases: object

Passive-linear input-output request handed to a backend.

hamiltonian is the number-conserving mode matrix in angular units. For a weak probe of an excitation-conserving chip, it is the chip’s one-excitation block, which can carry a non-Hermitian part from number-conserving channels. couplings stacks the channel rows of L = C a. scattering is the complete instantaneous SLH matrix, including hidden vacuum and loss channels. Frequencies remain ordinary GHz at the public boundary. plane_indices selects the external channels used as matrix rows and columns. inbound_transfer and outbound_transfer contain the per-frequency reference factors for each external channel. Backends return the undecorated Markov response, and the engine applies both factors.

Variables:

• frequencies (array_like) – Probe frequencies in GHz.

• mode_labels (tuple of str) – Linear Fock modes, or the devices whose first excited levels span the one-excitation states, in matrix order.

• hamiltonian (array_like) – Number-conserving mode matrix in rad/ns.

• couplings (array_like) – Channel-to-mode coupling matrix in 1/sqrt(ns).

• scattering (array_like) – Instantaneous SLH scattering matrix.

• plane_indices (tuple of int) – External channel indices used for result rows and columns.

• outbound_transfer (inbound_transfer,) – Frequency-dependent external reference factors.

• field_channels (tuple of FieldChannel) – Captured input field states.

frequencies: Any

mode_labels: tuple[str, ...]

hamiltonian: Any

couplings: Any

scattering: Any

plane_indices: tuple[int, ...]

inbound_transfer: Any

outbound_transfer: Any

field_channels: tuple[FieldChannel, ...] = ()

class quchip.engine.ir.CoherenceResponseProblem(frequencies, hamiltonians, lowering, conserving, sources, scattering, plane_indices, inbound_transfer, outbound_transfer)

Bases: object

Frequency response on adjacent excitation-sector coherences.

Variables:

• frequencies (array_like) – Probe frequencies in GHz.

• hamiltonians (tuple of array_like) – Sector Hamiltonians in rad/ns, ordered by excitation number from zero.

• lowering (tuple of array_like) – Channel blocks from N to N-1, shaped (channels, d[N-1], d[N]). Entry zero is unused and has zero rows.

• conserving (tuple of array_like) – Number-conserving channel blocks, shaped (conserving_channels, d[N], d[N]).

• sources (tuple of array_like) – Negative probe commutators on (N,N-1), shaped (d[N], d[N-1], inputs). Entry zero is unused and has zero columns.

• scattering (array_like) – Complete instantaneous SLH scattering matrix.

• plane_indices (tuple of int) – Selected external channels in input and output order.

• outbound_transfer (inbound_transfer,) – Reference-plane transfer factors, shaped (frequencies, channels).

frequencies: Any

hamiltonians: tuple[Any, ...]

lowering: tuple[Any, ...]

conserving: tuple[Any, ...]

sources: tuple[Any, ...]

scattering: Any

plane_indices: tuple[int, ...]

inbound_transfer: Any

outbound_transfer: Any

class quchip.engine.ir.SteadyStateProblem(chip, engine_result, e_ops=None, e_ops_meta=None, resolved_frame=None, options=<factory>, *, backend=None, device_info=())

Bases: object

Immutable static Lindblad request handed from a chip to its backend.

Variables:

• chip (Chip) – Source chip captured by the request.

• engine_result (EngineResult) – Frozen static resolved physics.

• e_ops (sequence or None) – Backend-ready expectation operators.

• e_ops_meta (object or None) – Metadata used to reconstruct public observables.

• resolved_frame (ResolvedFrame) – Captured stationary frame.

• options (dict) – Backend solver options.

• backend (Backend) – Captured backend owner.

• device_info (tuple) – Device labels and computational flags in subsystem order.

chip: Any

engine_result: EngineResult

e_ops: Any = None

e_ops_meta: Any = None

resolved_frame: Any = None

options: dict[str, Any]

backend: Any = None

device_info: tuple[tuple[str, bool], ...] = ()

class quchip.engine.ir.SolveBatch(chip, problems, params=None, shape=(), axes=(), _failure_context=())

Bases: object

Explicit solve problems sharing one dispatch owner and sweep shape.

Variables:

• chip (Chip) – Source chip for the batch.

• problems (tuple of SolveProblem) – Compatible frozen requests in flat sweep order.

• params (array_like or None) – Bound parameter mappings on the sweep grid.

• shape (tuple of int) – Sweep-grid shape.

• axes (tuple) – Named sweep-axis metadata.

chip: Any

problems: tuple[SolveProblem, ...]

params: Any = None

shape: tuple[int, ...] = ()

axes: tuple[tuple[str, Any], ...] = ()

property has_shared_tlist: bool

Return if every point has the same captured time grid.

property batch_size: int

property initial_states: tuple[Any, ...]

property tlist: Any

signals_for(slot)

Return one dynamic slot across all batch points.

Parameters:

slot (int) – Dynamic-term index.

params_at(point)

Return sweep values at one grid coordinate.

Parameters:

point (int or tuple of int) – Flat index or multidimensional sweep coordinate.

element(index)

Return one solve request by flat batch index.

Parameters:

index (int) – Flat batch index.

class quchip.engine.ir.DriveOp(target_label, envelope, freq=None, start_time=0.0, phase_offset=0.0, drive_label='', frame=None, detuning=None)

Bases: object

Drive operation scheduled on a device or a modulable coupling.

freq is in GHz. None selects flux drive (or baseband edge pump). start_time and phase_offset apply in the control frame. drive_label resolves the drive in the chip’s control equipment (for example "charge_0"). target_label resolves in the chip’s device or coupling label space.

frame names the device whose accumulated virtual-Z phase phase_offset includes, or is None. The phase is already in phase_offset, so the engine does not read frame. detuning is a carrier offset in GHz, referenced to start_time, or None for no offset.

The pulse window keeps its absolute scheduled time. A solve can select a partial interval, and a window wholly outside it or touching only an endpoint contributes no evolution.

target_label: str

envelope: Envelope

freq: float | None = None

start_time: float = 0.0

phase_offset: float = 0.0

drive_label: str = ''

frame: str | None = None

detuning: float | None = None

class quchip.engine.ir.CoherentOp(coherent_input, envelope, freq=None, start_time=0.0, phase_offset=0.0, frame=None, detuning=None)

Bases: object

Coherent field operation scheduled on an external SLH exposure.

The fields follow DriveOp. frame is None unless the schedule names a device frame for this input.

coherent_input: Any

envelope: Envelope

freq: float | None = None

start_time: float = 0.0

phase_offset: float = 0.0

frame: str | None = None

detuning: float | None = None

property exposure: str

Return the external exposure receiving this incident field.

property target_label: str

Alias the exposure for common solve-window diagnostics.

property drive_label: str

Alias the endpoint label for common scheduling diagnostics.