quchip.chip ¶

set_frame(frame)[source]¶

Set the frame used when assembling simulation inputs.

Supported values:

"lab" — all reference frequencies are 0.0 GHz.
"rotating" — per-device references use dressed drive frequencies.
scalar-like — shared reference frequency for all devices.
dict — per-device references keyed by label or device.

Frame changes never alter dressed-state data — dressing is always computed from the lab-frame static Hamiltonian.

Parameters:: frame (FrameSpec)
Return type:: None

property analysis: ChipAnalysis¶

Dressed-state analysis namespace — the chip’s ChipAnalysis.

Canonical entry point for the full dressed-analysis surface (power users, less-common methods). The common quantities are also exposed as flat chip.* forwarders — energy(), freq(), dress(), dispersive_shift(), … — which delegate here; reach for chip.analysis for everything else.

dress(*, overlap_threshold=0.5, force=False, labeling='DE')[source]¶

Compute (or retrieve) the dressed-state decomposition. See ChipAnalysis.dress().

Parameters:

overlap_threshold (float)
force (bool)
labeling (str)

Return type:

DressedResult

property is_dressed: bool¶: Whether a valid dressed-state result is cached. See ChipAnalysis.is_dressed.

energy(device_states=None, /, **device_state_kwargs)[source]¶

Dressed eigenenergy (GHz) for a bare-state label. See ChipAnalysis.energy().

Parameters:

device_states (Mapping[str | BaseDevice, int] | None)
device_state_kwargs (int)

Return type:

dressed_spectrum()[source]¶

Raw dressed eigenvalue array without Python scalar coercion. See ChipAnalysis.dressed_spectrum().

Return type:: Any

dressed_index(device_states=None, /, **device_state_kwargs)[source]¶

Dressed-state index matching a bare-state label, or None. See ChipAnalysis.dressed_index().

Parameters:

device_states (Mapping[str | BaseDevice, int] | None)
device_state_kwargs (int)

Return type:

int | None

bare_label(dressed_index)[source]¶

Bare-state label assigned to a dressed-state index. See ChipAnalysis.bare_label().

Parameters:: dressed_index (int)
Return type:: tuple[int, …]

operator_in_dressed_basis(device, op, *, truncate=None)[source]¶

Embedded device operator transformed to the dressed eigenbasis.

See ChipAnalysis.operator_in_dressed_basis().

Parameters:

device (str | BaseDevice)
op (str | Any)
truncate (int | None)

Return type:

drive_matrix_elements(transition, *, drives=None)[source]¶

Return <final~|D_j|initial~> for wired drive lines.

The final dressed state is the row index and the initial dressed state is the column index. In the weak-drive projection these matrix elements set the effective driven-Hamiltonian coefficients. See E. Magesan and J. M. Gambetta, Phys. Rev. A 101, 052308 (2020), DOI 10.1103/PhysRevA.101.052308, and ChipAnalysis.drive_matrix_elements() for the transition shorthand, parameters, return type, and error conditions.

Parameters:

transition (str | BaseDevice | tuple[Mapping[str | BaseDevice, int], Mapping[str | BaseDevice, int]])
drives (Sequence[str | BaseDrive] | None)

Return type:

LabelKeyedDict

state_components(state=None, /, *, n_components=5, **device_state_kwargs)[source]¶

Leading bare-basis probabilities for a dressed eigenstate. See ChipAnalysis.state_components().

Parameters:

state (int | Mapping[str | BaseDevice, int] | None)
n_components (int)
device_state_kwargs (int)

Return type:

dict[tuple[int, …], float]

dispersive_shift(device_a, device_b)[source]¶

Dressed cross-Kerr shift (GHz): E(1,1) − E(1,0) − E(0,1) + E(0,0).

See ChipAnalysis.dispersive_shift().

Parameters:

device_a (str | BaseDevice)
device_b (str | BaseDevice)

Return type:

static_zz(device_a, device_b)¶

Dressed cross-Kerr shift (GHz): E(1,1) − E(1,0) − E(0,1) + E(0,0).

See ChipAnalysis.dispersive_shift().

Parameters:

device_a (str | BaseDevice)
device_b (str | BaseDevice)

Return type:

zz(device_a, device_b)¶

Dressed cross-Kerr shift (GHz): E(1,1) − E(1,0) − E(0,1) + E(0,0).

See ChipAnalysis.dispersive_shift().

Parameters:

device_a (str | BaseDevice)
device_b (str | BaseDevice)

Return type:

kerr_matrix()[source]¶

Return the labeled dressed self-Kerr and cross-Kerr matrix in GHz.

See ChipAnalysis.kerr_matrix().

Return type:: KerrMatrix

dressed_anharmonicity(device)[source]¶

Dressed anharmonicity of one device with others grounded (GHz).

See ChipAnalysis.dressed_anharmonicity().

Parameters:: device (str | BaseDevice)
Return type:: float

transition_frequency(target, lower, upper, when=None)[source]¶

Return a dressed transition in GHz with optional spectator levels.

Unspecified spectators are in their ground state. target and entries in when accept either device objects or labels.

Parameters:

target (str | BaseDevice)
lower (int)
upper (int)
when (dict[str | BaseDevice, int] | None)

Return type:

effective_subspace_hamiltonian(states)[source]¶

Dressed effective Hamiltonian in a labeled bare subspace.

See ChipAnalysis.effective_subspace_hamiltonian().

Parameters:: states (list[Mapping[str | BaseDevice, int] | tuple[int, ...]] | tuple[Mapping[str | BaseDevice, int] | tuple[int, ...], ...])
Return type:: Any

freq(target: None = None, when: dict[str | BaseDevice, int] | None = None) → dict[str, float][source]¶

freq(target: str | BaseDevice, when: dict[str | BaseDevice, int] | None = None) → float

All dressed 0→1 frequencies (GHz), or one conditional transition. See ChipAnalysis.freq().

Overloaded: no target returns the full {label: freq} dict; a single target (label or device) returns one scalar 0→1 frequency. Under jax.jit the scalar is a traced 0-d array; the overload is type-only and preserves traceability.

Parameters:

target (str | BaseDevice | None)
when (dict[str | BaseDevice, int] | None)

Return type:

dict[str, float] | float

frame_info()[source]¶

Per-device frame reference frequency ω_ref,i (GHz). See ChipAnalysis.frame_info().

Return type:: dict[str, Any]

physics_notes()[source]¶

Aggregate physics_notes() across every component.

Returns a dict keyed "chip" for the chip-level entry, and "<kind>:<label>" — kind one of "device", "coupling", "drive", "bath", "port" — for every component, mapping to that component’s declared approximations: Hilbert truncation, model regime, RWA status, noise-channel selection, and any other non-obvious assumption the component explicitly declares. Keys are kind-qualified rather than bare labels because the label namespaces are not globally disjoint — a device, coupling, drive, and bath may share a label — and this is an audit surface, so one component’s entry silently overwriting another’s is unacceptable. Drives are enumerated from control_equipment’s wiring rather than per-device connected_drives, so an edge-target ParametricDrive (pumping a coupling, not a device) is included too. The chip-level entry keyed "chip" states the local-Lindblad approximation every collapse operator this chip assembles is built under (see collapse_contributions()) — present even with no baths, since it applies regardless. Intended for inspection/audit rather than for runtime dispatch.

Return type:: dict[str, list[str]]

to_dict()[source]¶

Serialize chip topology into a JSON-safe dictionary.

Return type:: dict[str, Any]

classmethod from_dict(d)[source]¶

Reconstruct a chip from to_dict() output.

Parameters:: d (dict[str, Any])
Return type:: Chip

clone()[source]¶

Isolated structural clone suitable for sweep evaluation.

Return type:: Chip

property parameters: Mapping[str, Any]¶: Bindable numerical values keyed by stable component paths.

property settings: Mapping[str, Any]¶: Read-only structural choices that are not numerical fit parameters.

with_params(bindings)[source]¶

Return an isolated structural copy with component-owned values rebound.

Parameters:: bindings (Mapping[str, Any])
Return type:: Chip

partition()[source]¶

Split into independent sub-chips along the independence graph.

Couplings, non-separable bath target sets, and drive-crosstalk pairs all count as connections. Exact — the joint solve factorizes as the tensor product of the component solves. simulate/seq.simulate consult this automatically; call it directly to orchestrate solves yourself.

Return type:: PartitionResult

status()[source]¶

Print a lightweight diagnostic dashboard for the chip.

Return type:: None

from_array(data, device=None)[source]¶

Build a backend operator from a raw NumPy array.

With device, the array is interpreted as a local operator on that device’s subspace and embedded into the full tensor-product space. With device=None the array must already span the full chip Hilbert space.

Parameters:

data (Any)
device (str | BaseDevice | None)

Return type:

observable(device, op)[source]¶

Embed a device operator onto the full chip Hilbert space.

Accepts either an operator name ("X", "Y", "Z", "n", "a", "a_dag", "I") or an already-built local-space operator, and returns it embedded on the chip’s tensor-product space.

This is for manual full-space operator construction and analysis; it is not a solver e_op. For solver expectation values use e_ops(), which keeps operators local so the demodulation pipeline can band-decompose and embed them correctly.

Parameters:

device (str | BaseDevice)
op (str | Any)

Return type:

e_ops(*, correlators=None, **specs)[source]¶

Build a dict-form e_ops mapping for the solver pipeline.

Each keyword maps a device label to an operator specification: a name string, a list of names, a raw local-space operator, or a mixed list of strings and operators. Two-device correlators (e.g. ⟨Z₁⊗Z₂⟩) are specified via correlators as device-label pairs → operator pairs. Returns local-space operators (not embedded) — the demodulation pipeline embeds as needed.

Examples

>>> from quchip import DuffingTransmon, Capacitive, Chip
>>> q1 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q1")
>>> q2 = DuffingTransmon(freq=5.2, anharmonicity=-0.22, levels=3, label="q2")
>>> chip = Chip([q1, q2], couplings=[Capacitive(q1, q2, g=0.02)])
>>> e = chip.e_ops(
...     q1=["X", "Y", "Z"], q2=["X", "Y", "Z"],
...     correlators={("q1", "q2"): ("Z", "Z")},
... )

Parameters:

correlators (dict[tuple[str | BaseDevice, str | BaseDevice], tuple[str | Any, str | Any]] | None)
specs (str | list | Any)

Return type:

dict[str | tuple[str, str], Any]

set_state_order(*devices, levels=None)[source]¶

Declare the device order used to parse string-state shorthands.

After this is called, bare_state(), state(), and superposition() accept single-string specifications where each character is one level per device in devices order. Level symbols default to g=0, e=1, f=2, h=3; digits 0..9 are always accepted as energy-level indices.

Every chip device must be named exactly once.

Examples

>>> from quchip import DuffingTransmon, Resonator, Chip
>>> qb = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="qb")
>>> tc = DuffingTransmon(freq=5.5, anharmonicity=-0.20, levels=3, label="tc")
>>> cr = Resonator(freq=7.0, levels=4, label="cr")
>>> chip = Chip([qb, tc, cr])
>>> chip.set_state_order(qb, tc, cr)
>>> _ = chip.bare_state("eg1")  # {qb: 1, tc: 0, cr: 1}

Parameters:

devices (str | BaseDevice)
levels (Mapping[str, int] | None)

Return type:

None

superposition(*components)[source]¶

Normalized bare-basis superposition of tensor-product states.

Each component is either a bare-state spec (dict keyed by device or label, or a string when set_state_order() has been called) or an (amplitude, spec) tuple for weighted mixing. Uniform weights by default; results are normalized to unit norm.

Unlike state(), this stays in the bare product basis — no dressed diagonalization — so the probe basis is explicit.

Examples

>>> import numpy as np
>>> from quchip import DuffingTransmon, Resonator, Chip
>>> qb = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="qb")
>>> cr = Resonator(freq=7.0, levels=4, label="cr")
>>> chip = Chip([qb, cr])
>>> _ = chip.superposition({qb: 0}, {qb: 1})  # equal |00> + |10>
>>> _ = chip.superposition(                   # weighted mix
...     (np.sqrt(0.3), {qb: 1, cr: 0}),
...     (np.sqrt(0.7), {qb: 1, cr: 1}),
... )

Parameters:: components (Mapping[str | BaseDevice, int] | str | tuple[Any, Any])
Return type:: Any

state(device_states=None, /, **device_state_kwargs)[source]¶

Dressed eigenstate assigned from the given product-state level labels.

Accepts a string shorthand (e.g. "eg1") when set_state_order() has been called.

Safe inside jax.jit/grad/vmap: under tracing the assigned eigenvector column is selected through the label_eigensystem() array kernel, so dressed initial states are differentiable end-to-end. The global phase is gauge-dependent (eigh column convention) — populations and |overlap| figures of merit are unaffected.

Parameters:

device_states (Mapping[str | BaseDevice, int] | str | None)
device_state_kwargs (int)

Return type:

bare_state(device_states=None, /, **device_state_kwargs)[source]¶

Product state from per-device energy levels or authored local kets.

Each device may be specified as either an energy-level index (int) or a ket vector in that device’s authored local space. Devices not mentioned default to the ground state (level 0). Unlike state() this does not diagonalize the coupled system.

Accepts a string shorthand (e.g. "eg1") when set_state_order() has been called.

Parameters:

device_states (Mapping[str | BaseDevice, int | Any] | str | None)
device_state_kwargs (int | Any)

Return type:

wire(*lines, signal_chain=None)[source]¶

Attach or replace classical control wiring.

Preferred user-facing API for attaching control to a chip. If lines is omitted, the existing connected lines are reused and only the signal chain is replaced.

Examples

>>> # chip.wire(drive_q, drive_r, signal_chain=[Crosstalk(drive_q, drive_r, c=0.05)])

Parameters:

lines (BaseDrive)
signal_chain (Sequence[SignalTransform] | None)

Return type:

ControlEquipment

unwire(line)[source]¶

Remove one control line and every signal-chain transform referencing it.

The inverse of wire() for a single line. Accepts the drive object or its label. Returns the removed drive so it can be rewired later. Removing the last line detaches the equipment entirely (control_equipment becomes None).

Parameters:: line (BaseDrive | str)
Return type:: BaseDrive

connect(control_equipment)[source]¶

Attach control equipment to this chip (low-level API).

Validates every drive target and rejects duplicate drive labels, then reconnects each drive to this chip’s canonical device or coupling instance. User-facing code should prefer wire().

Parameters:: control_equipment (ControlEquipment)
Return type:: None

disconnect()[source]¶

Detach control equipment entirely (low-level API).

The inverse of connect()/wire(): removes all lines and the signal chain at once (control_equipment becomes None). Returns the detached equipment so it can be reconnected later.

Returns:: The equipment that was attached before detachment.
Return type:: ControlEquipment

solve(problem, *, check_truncation=True, truncation_threshold=0.001)[source]¶

Solve a typed SolveProblem through this chip’s backend.

Routes through the common solve_problem() chokepoint, so the Hilbert-truncation safety net applies by default; pass check_truncation=False to opt out or retune truncation_threshold.

Parameters:

problem (SolveProblem)
check_truncation (bool)
truncation_threshold (float)

Return type:

SimulationResult

solve_many(batch_or_problems, *, progress=True)[source]¶

Solve a SolveBatch or list of problems.

Chip-level validation only enforces what needs self (every input was built for this chip); the input-shape dispatch and batching are delegated to quchip.engine.solve_many(), which owns the single SolveBatch / list dispatch.

Parameters:

batch_or_problems (Any)
progress (bool)

Return type:

SimulationBatchResult

steadystate(*, e_ops=None, options=None, frame=None, approximation=None)[source]¶

Solve this chip’s unique static Lindblad steady state.

Parameters:

e_ops (dict | None)
options (dict | None)
frame (FrameSpec | None)
approximation (Approximation | None)

Return type:

SteadyStateResult

steadystate_batch(*axes, e_ops=None, options=None, frame=None, approximation=None, progress=True)[source]¶

Solve static Lindblad steady states over parameter sweep axes.

Parameters:

axes (Any)
e_ops (dict | None)
options (dict | None)
frame (FrameSpec | None)
approximation (Approximation | None)
progress (bool)

Return type:

Any

describe()[source]¶

Sectioned plain-text report of everything on the chip.

Devices with their declared parameters (units included), noise settings, couplings, control wiring, and baths — the “what did I just build?” view. Returns a string; print(chip.describe()). Traced parameters render as <traced> and are never concretized.

Return type:: str

class quchip.chip.DressedResult(eigenvalues, state_map, dressed_eigenvalues, assignment_overlaps, hybridized_labels, bare_labels, bare_labels_by_dressed_index, eigenvector_matrix=None, overlap_threshold=0.5, labeling='DE', _eigensystem=None)[source]¶

Bases: object

Store a frozen snapshot of a dressed-state diagonalization.

Parameters:

eigenvalues (Any)
state_map (dict[tuple[int, ...], int])
dressed_eigenvalues (dict[tuple[int, ...], Any])
assignment_overlaps (dict[tuple[int, ...], float])
hybridized_labels (tuple[tuple[int, ...], ...])
bare_labels (tuple[tuple[int, ...], ...])
bare_labels_by_dressed_index (dict[int, tuple[int, ...]])
eigenvector_matrix (Any)
overlap_threshold (float)
labeling (str)
_eigensystem (EigensystemData | None)

eigenvalues¶

Sorted dressed eigenvalues in GHz.

Type:: array-like

eigenstates¶

Backend eigenstate objects in the same order as eigenvalues. Materialized lazily on first access from the underlying EigensystemData — the dressing / sweep hot path never touches them, so the per-column backend kets are only built when a caller actually asks for states.

Type:: array-like

state_map¶

Assignment from bare product-basis label (one int per device) to the dressed eigenstate index it overlaps most with.

Type:: dict[tuple[int, …], int]

dressed_eigenvalues¶

Dressed eigenvalue for each assigned bare label — direct lookup path for Chip.energy().

Type:: dict[tuple[int, …], Any]

assignment_overlaps¶

|⟨bare|dressed⟩|² of each assignment; values below overlap_threshold flag hybridization.

Type:: dict[tuple[int, …], float]

hybridized_labels¶

Bare labels whose assignment quality is below overlap_threshold. A non-empty tuple triggers a user warning at dress time.

Type:: tuple[tuple[int, …], …]

bare_labels¶

Product energy-level labels exposed by the chip’s resolved local dimensions, in chip order.

Type:: tuple[tuple[int, …], …]

bare_labels_by_dressed_index¶

Inverse of state_map — dressed index → assigned bare label.

Type:: dict[int, tuple[int, …]]

eigenvector_matrix¶

Columns = dressed eigenvectors in the bare product basis. Used for ChipAnalysis.operator_in_dressed_basis() and ChipAnalysis.state_components().

Type:: array-like or None

overlap_threshold¶

Minimum overlap for a confident assignment.

Type:: float

labeling¶

Algorithm id (currently only "DE"), resolved to the confidence-ordered row-greedy overlap-matching policy actually run by ChipAnalysis.dress() (assign_rowwise_greedy()).

Type:: str

eigenvalues: Any¶

state_map: dict[tuple[int, ...], int]¶

dressed_eigenvalues: dict[tuple[int, ...], Any]¶

assignment_overlaps: dict[tuple[int, ...], float]¶

hybridized_labels: tuple[tuple[int, ...], ...]¶

bare_labels: tuple[tuple[int, ...], ...]¶

bare_labels_by_dressed_index: dict[int, tuple[int, ...]]¶

eigenvector_matrix: Any = None¶

overlap_threshold: float = 0.5¶

labeling: str = 'DE'¶

property eigenstates: Any¶: Backend eigenstate kets, materialized lazily from the eigensystem.

class quchip.chip.KerrMatrix(labels, values)[source]¶

Bases: object

Labeled dressed self-Kerr and cross-Kerr coefficients in GHz.

labels follows chip device order. values is a real symmetric square array: diagonal entries are dressed anharmonicities and off-diagonal entries are full-pull cross-Kerr shifts.

Parameters:

labels (tuple[str, ...])
values (Any)

labels: tuple[str, ...]¶

values: Any¶

class quchip.chip.Bath(recipe, targets=None, *, temperature=None, rate=None, correlated=False, label=None)[source]¶

Bases: object

A shared environment coupling a set of devices to a common bath.

Attach at construction (Chip(..., baths=[...])) or at any time after via add_bath() — the next simulate/solve collects the bath’s collapse operators automatically.

Parameters:

recipe (str) – Built-in collapse-channel model. One of "thermal", "collective_decay", or "correlated_dephasing". The argument name is retained for API and serialization compatibility.
targets (list[BaseDevice | str] | None) – Devices the bath couples to (objects or labels). None (default) means every device in the chip — natural for a global thermal bath.
temperature (float | None) – Bath temperature in mK (required for "thermal"). May be a JAX tracer for sweeps / gradients.
rate (float | None) – Bath–device coupling rate γ in 1/ns. For "thermal" it is the environmental coupling rate (explicit — never silently borrowed from a device T1, so it cannot double-count device-level noise). For the collective models it is the overall jump rate. None defaults to 1.0 (user controls the absolute scale elsewhere).
correlated (bool) – "thermal" only: False (default) emits independent per-device channels sharing one temperature. True is unsupported and raises NotImplementedError. The collective models always emit a single correlated operator regardless of this flag.
label (str | None) – Auto-generated "bath_{n}" when omitted.

Examples

>>> from quchip import DuffingTransmon, Chip, Bath
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> chip = Chip([q])
>>> _ = chip.add_bath(Bath("thermal", temperature=20.0))  # global 20 mK bath
>>> _ = chip.add_bath(Bath("collective_decay", targets=[q], rate=0.01))

resolve_targets(chip)[source]¶

Return the ordered target device labels (defaults to all devices).

Parameters:: chip (Chip)
Return type:: list[str]

property separable: bool¶

Whether this bath factorizes into independent per-target channels.

True for models that emit one collapse operator per target ("thermal" with independent channels); False for models that emit a single jump operator summed over targets ("collective_decay", "correlated_dephasing"). Partitioning treats a non-separable bath’s target set as one inseparable block.

to_dict()[source]¶

Serialize the bath; targets are stored as label strings.

Return type:: dict[str, Any]

classmethod from_dict(d)[source]¶

Reconstruct a bath from serialized state (targets as label strings).

Parameters:: d (dict[str, Any])
Return type:: Bath

physics_notes()[source]¶

Return human-readable declarations of this bath’s model and scope.

Mirrors physics_notes(): one entry naming the model and its targets, plus a model-specific assumption a user of this bath should be aware of.

Return type:: list[str]

copy()[source]¶

Independent copy of this bath (targets normalize to label strings).

Used by Chip.clone and eliminate so a transformed chip never shares live Bath objects with its source — mutating one chip’s bath must not silently change another chip’s physics. Parameter values (temperature, rate) are carried by reference, so traced values stay traced.

Return type:: Bath

parameter_values()[source]¶

Return active bath values by local field name.

Return type:: dict[str, Any]

set_parameter_value(name, value)[source]¶

Apply one bath value on an isolated bath copy.

Parameters:

name (str)
value (Any)

Return type:

None

dissipation(chip, bases=None)[source]¶

Return authored full-chip collapse channels.

"thermal" emits independent per-target relaxation/absorption pairs sharing one bath temperature (_bose()). The two collective models instead each emit a single jump operator summed over the resolved targets:

"collective_decay": L = sum_i a_i at rate gamma — an equal-phase, equal-weight rank-one collective channel, not general collective (super/subradiant) decay, which requires per-pair phase and weight factors set by the target geometry (Lehmberg, Phys. Rev. A 2, 883 (1970), for the general collective-radiative-decay construction).
"correlated_dephasing": L = sum_i n_i at rate gamma — maximally correlated common-mode dephasing (every target shares the identical dephasing fluctuation), not general correlated dephasing with a target-dependent correlation structure (Breuer & Petruccione, The Theory of Open Quantum Systems, Oxford, 2002, Ch. 3, for the general Lindblad construction).

Contributions remain backend-neutral; the engine projects and lowers them with the same basis records used for Hamiltonian terms.

Parameters:

chip (Chip)
bases (Mapping[str, Any] | None)

Return type:

tuple[CollapseChannel, …]

collapse_channels(chip, bases=None)[source]¶

Return normalized full-chip bath channels.

Parameters:

chip (Chip)
bases (Mapping[str, Any] | None)

Return type:

tuple[CollapseChannel, …]

class quchip.chip.Port(target, *, rate=None, external_quality_factor=None, operator=None, phase=0.0, label=None)[source]¶

Bases: object

One accessible Markovian channel with a dimensionless coupling operator.

Parameters:

target (Any | Sequence[Any])
rate (Any)
external_quality_factor (Any)
operator (Any)
phase (Any)
label (str | None)

resolve_targets(chip)[source]¶

Return target labels after checking that they belong to chip.

Parameters:: chip (Chip)
Return type:: tuple[str, …]

rate_value(chip)[source]¶

Return the external coupling rate in 1/ns.

Parameters:: chip (Chip)
Return type:: Any

parameter_values()[source]¶

Return active sweepable port values.

Return type:: dict[str, Any]

set_parameter_value(name, value)[source]¶

Set one port parameter on an isolated chip copy.

Parameters:

name (str)
value (Any)

Return type:

None

copy()[source]¶

Return an independent port retaining label-based targets.

Return type:: Port

physics_notes()[source]¶

Return the input-output convention owned by this port.

Return type:: list[str]

to_dict()[source]¶

Serialize port targets and scalar coupling data.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]¶

Reconstruct a port from label-based serialized data.

Parameters:: data (dict[str, Any])
Return type:: Port

class quchip.chip.Capacitive(device_a, device_b, g=unbound, *, label=None)[source]¶

Bases: CouplingModel

Capacitive (charge-charge) coupling between two devices.

The capacitive interaction between two electromagnetic modes takes the canonical dipole-dipole form in the raising/lowering basis:

Full form: H_int = g · (a + a†)(b + b†)
Band-RWA form: H_int = g · (a†b + a b†) (derived, not authored)

The coupling authors only the full form; RWA retaining the Δa + Δb == 0 bands of it, which is exactly g · (a†b + a b†). The RWA drops the counter-rotating terms a b and a† b†, valid when ω_a + ω_b ≫ g — the sum-frequency condition that makes those terms fast-rotating and hence negligible. This is distinct from the dispersive condition |ω_a − ω_b| ≫ g, which instead governs whether the retained exchange term g · (a†b + a b†) can be treated perturbatively (see TunableCapacitive / eliminate() for the dispersive reduction). Approximation is selected on the chip or for one solve, never on the coupling.

Parameters:

device_a (BaseDevice or str) – The two coupled devices, given as objects or label strings. Label-string references are late-bound via Chip.
device_b (BaseDevice or str) – The two coupled devices, given as objects or label strings. Label-string references are late-bound via Chip.
g (float) – Coupling strength in GHz. May be a traced JAX scalar for sweeps / autodiff.
label (str, optional) – Human-readable label; defaults to "cap_{n}".

References

Blais et al., PRA 69, 062320 (2004), Eq. 11. Krantz et al., Appl. Phys. Rev. 6, 021318 (2019), §V.B. Blais et al., Rev. Mod. Phys. 93, 025005 (2021), §II.B.

Examples

>>> from quchip import DuffingTransmon, Resonator, Capacitive
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> r = Resonator(freq=7.0, levels=5, label="r")
>>> coupling = Capacitive(q, r, g=0.05)

folds_exchange: ClassVar[bool] = True¶

reduces_to_crosskerr: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

g: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='g', noise=False, kw_only=False, required=False)¶

default_dressed_target()[source]¶

Use exchange rate for an edge between non-computational modes.

Return type:: tuple[str, Any]

interaction(a, b, p)[source]¶

Return the full capacitive interaction g * (a + a†)(b + b†).

Parameters:

Return type:

physics_notes()[source]¶

Return the declared capacitive interaction.

Return type:: list[str]

classmethod from_dict(d, device_a, device_b)[source]¶

Reconstruct a capacitive coupling from serialized state.

Parameters:

d (dict[str, Any])
device_a (BaseDevice)
device_b (BaseDevice)

Return type:

Capacitive

class quchip.chip.Coupling(device_a, device_b, g, *, op_a=None, op_b=None, interaction=None, label=None)[source]¶

Bases: BaseCoupling

Generic two-body coupling with a user-supplied interaction.

Use this escape hatch when no concrete coupling class models the desired physics (inductive, longitudinal, cross-Kerr test forms, synthetic spin-spin couplings, photonics-style beam-splitters, …). The user supplies the operator structure; this class only provides the g scaling, RWA pass-through, and bookkeeping.

Two mutually exclusive modes:

Product form — H_int = g · op_a(device_a) ⊗ op_b(device_b):

Coupling(q, r, g=0.02,
    op_a=lambda d: d.number_operator(),
    op_b=lambda d: d.number_operator())

Callable form — H_int = g · interaction(device_a, device_b, backend):

Coupling(q, r, g=0.02,
    interaction=lambda a, b, bk: (
        bk.tensor(bk.dag(a.lowering_operator()), b.lowering_operator())
        + bk.tensor(a.lowering_operator(), bk.dag(b.lowering_operator()))
    ))

The selected chip approximation is applied to the complete user-supplied operator after authored physics is assembled.

Parameters:

device_a (BaseDevice | str)
device_b (BaseDevice | str)
g (float)
op_a (Callable[[BaseDevice], Operator] | None)
op_b (Callable[[BaseDevice], Operator] | None)
interaction (Callable[[BaseDevice, BaseDevice, 'Backend'], Operator] | None)
label (str | None)

property coupling_strength: float¶: Scalar prefactor g supplied by the user.

interaction_hamiltonian()[source]¶

User-defined interaction on H_a ⊗ H_b, scaled by g.

Return type:: Any

physics_notes()[source]¶

Return notes describing the user-supplied interaction mode.

Return type:: list[str]

to_dict()[source]¶

Reject serialization because callables cannot be made persistent.

Return type:: dict[str, Any]

classmethod from_dict(d, device_a, device_b)[source]¶

Reject deserialization because callables cannot be reconstructed.

Parameters:

d (dict[str, Any])
device_a (BaseDevice)
device_b (BaseDevice)

Return type:

Coupling

class quchip.chip.CrossKerr(device_a, device_b, chi=unbound, *, label=None)[source]¶

Bases: CouplingModel

Cross-Kerr (dispersive) coupling H_int = χ · n̂_a n̂_b.

The effective diagonal interaction left when an exchange coupling is reduced in the dispersive regime — the natural coupling for effective readout chips (qubit + resonator + CrossKerr probed by an ordinary charge line) and static-ZZ modelling. Diagonal in both endpoints, so the RWA and full forms coincide and the term is frame-trivial.

Declared approximation: this is a uniform-pull model — one χ per edge, the same shift per endpoint excitation; per-level χ differences, dispersive breakdown at the critical photon number, and Purcell decay are not represented (fold Purcell into endpoint T1 via eliminate() when it matters).

Parameters:

device_a (BaseDevice or str) – The two coupled devices, as objects or label strings.
device_b (BaseDevice or str) – The two coupled devices, as objects or label strings.
chi (float) – Cross-Kerr shift in GHz per excitation pair, sign included (convention: full pull E₁₁ − E₁₀ − E₀₁ + E₀₀). May be a JAX tracer.
label (str, optional) – Defaults to "crosskerr_{n}".

is_effective: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

chi: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\chi', noise=False, kw_only=False, required=False)¶

interaction(a, b, p)[source]¶

Full form χ · n̂_a n̂_b (diagonal; identical under RWA).

Parameters:

Return type:

parametric_interaction(a, b, p)[source]¶

Modulable structure n̂_a n̂_b — δχ(t) pumps ride this.

Parameters:

Return type:

physics_notes()[source]¶

Return the declared dispersive-approximation provenance.

Return type:: list[str]

class quchip.chip.TunableCapacitive(device_a, device_b, g_0=unbound, *, label=None)[source]¶

Bases: CouplingModel

Capacitive coupling with a scheduled parametric pump.

Effective two-body interaction with a static mean coupling strength:

\[H_{\text{int}} \;=\; g_0\,\hat Q_a\hat Q_b\]

where \(\hat Q\) is each endpoint’s physical charge-like coupling operator (the position quadrature for a Fock model). The engine applies any requested RWA after local-basis materialization. \(g_0\) is the static coupling strength in GHz; it may be a JAX tracer and flows through jax.grad() without concretization.

Time-dependence is not a construction-time parameter: a ParametricDrive wired onto this coupling schedules a pump δ(t) via pump(), multiplying the same operator structure the static term uses (parametric_interaction()).

Parameters:

device_a (BaseDevice) – The two coupled devices.
device_b (BaseDevice) – The two coupled devices.
g_0 (float) – Static (mean) coupling strength in GHz. May be a JAX tracer.
label (str, optional) – Human-readable label; defaults to "tunable_cap_{n}".

Notes

The pump multiplies parametric_interaction(); frame and RWA logic stay in the engine. A pump tone at the qubits’ difference frequency |ω_a − ω_b| activates the parametric beam-splitter / iSWAP exchange, while a tone at the sum frequency ω_a + ω_b instead activates two-mode-squeezing (a†b†) terms. Either is expressed via the drive’s freq argument, not a coupling-side carrier.

References

McKay, Filipp, Mezzacapo, Magesan, Chow & Gambetta, Universal Gate for Fixed-Frequency Qubits via a Tunable Bus, Phys. Rev. Applied 6, 064007 (2016) — parametric two-qubit gates via coupler flux modulation.

Krantz et al., A quantum engineer’s guide to superconducting qubits, Appl. Phys. Rev. 6, 021318 (2019), §V.D — tunable couplers.

Examples

>>> from quchip import Chip, ControlEquipment, DuffingTransmon, ParametricDrive, TunableCapacitive
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.22, levels=3, label="q1")
>>> tc = TunableCapacitive(q0, q1, g_0=0.0, label="tc")
>>> pump = ParametricDrive(tc, label="pump")
>>> chip = Chip([q0, q1], couplings=[tc], control_equipment=ControlEquipment([pump]))
>>> # seq.pump(tc, envelope=..., freq=...) schedules δg(t); see QuantumSequence.pump.

is_effective: ClassVar[bool] = True¶

folds_exchange: ClassVar[bool] = True¶

reduces_to_crosskerr: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

g_0: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='g_0', noise=False, kw_only=False, required=False)¶

interaction(a, b, p)[source]¶

Static contribution g_0 · (a + a†)(b + b†).

Parameters:

Return type:

parametric_interaction(a, b, p)[source]¶

Modulable charge-charge structure a scheduled pump multiplies.

Parameters:

Return type: