quchip.chip.analysis

Dressed-state analysis owned by quchip.chip.chip.Chip.

ChipAnalysis diagonalizes the lab-frame static Hamiltonian and assigns bare-state labels to dressed eigenvectors by overlap maximization. It also exposes derived quantities: dressed eigenenergies, transition frequencies, dispersive shifts, and effective subspace Hamiltonians. All results cache against a structural signature and refresh automatically when a device or coupling parameter changes.

Dressing is always computed in the lab frame, so the frame selection never changes dressed data.

References

Gambetta, J., Blais, A., Schuster, D. I., Wallraff, A., Frunzio, L.,

Majer, J., Devoret, M. H., Girvin, S. M., & Schoelkopf, R. J. Qubit-photon interactions in a cavity: Measurement-induced dephasing and number splitting. PRA 74, 042318 (2006).

Koch, J., Yu, T. M., Gambetta, J., Houck, A. A., Schuster, D. I., Majer,

J., Blais, A., Devoret, M. H., Girvin, S. M., & Schoelkopf, R. J. Charge-insensitive qubit design derived from the Cooper pair box. PRA 76, 042319 (2007).

Blais, A., Grimsmo, A. L., Girvin, S. M., & Wallraff, A. Circuit quantum

electrodynamics. Rev. Mod. Phys. 93, 025005 (2021), §IV on dispersive regime and dressed-state labeling.

Functions

kerr_entry(index_a, index_b, *, dims, ...)

Read one self- or cross-Kerr coefficient from a captured labeled spectrum.

Classes

ChipAnalysis(chip)	Dressed-state analysis, caching, and dressed-basis helpers.
KerrMatrix(labels, values)	Labeled dressed self-Kerr and cross-Kerr coefficients in GHz.

class quchip.chip.analysis.KerrMatrix(labels, values)

Bases: object

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

labels follows chip device order, and 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, ...]) – Device labels in chip order.

• values (array-like) – Real symmetric Kerr matrix in GHz.

labels: tuple[str, ...]

values: Any

quchip.chip.analysis.kerr_entry(index_a, index_b, *, dims, eigenvalues, labeling)

Read one self- or cross-Kerr coefficient from a captured labeled spectrum.

class quchip.chip.analysis.ChipAnalysis(chip)

Bases: object

Dressed-state analysis, caching, and dressed-basis helpers.

Every Chip owns one ChipAnalysis, and the chip forwards common dressed quantities. The namespace exposes the frozen static contract via engine_result() and keeps less-common analysis methods grouped.

Caching: dress() keys its cache on a structural signature covering the backend identity and the state_version of every device and coupling. Any change that increments a version invalidates the cache on the next access. The first query that uses a cached static model reports its approximation advisories once.

Parameters:

chip (Chip) – Chip whose static lab-frame Hamiltonian is analyzed under its approximation.

engine_result(*, _local_resolution=None, _advise=True)

Return the resolved static lab-frame contract used by analysis.

dress(*, overlap_threshold=0.5, force=False, labeling='DE')

Diagonalize the lab-frame Hamiltonian and assign bare-state labels.

Dressing keeps network-generated Hamiltonian terms, so the assigned eigenstates match the solver Hamiltonian and degenerate cascaded modes dress into superpositions. The assignment uses the label_eigensystem kernel (quchip.engine.dressing) with assign_rowwise_greedy, i.e. confidence-ordered row-greedy matching as a pure lax.scan. Its cost is O(D**2) in the Hilbert dimension, versus O(D**3) for the global variant.

The result is identical to assign_global_greedy in the dispersive or weak-hybridization regime. It can differ only on strongly hybridized chips, where the assignment is already approximate and the labels are flagged. Bare labels whose best match is below overlap_threshold are flagged in DressedResult.hybridized_labels and trigger a user warning.

DressedResult is the eager, dict-materialized view. Materialization makes the assignment indices concrete and is not traceable. In jax.jit/grad/vmap, call energy(), freq(), dispersive_shift(), or state(), which go directly through the array kernel.

Parameters:

• overlap_threshold (float) – Confidence cutoff for the greedy assignment.

• force (bool) – Force a new calculation even if the signature matches.

• labeling (str) – Currently only "DE" is implemented.

Returns:

Cached result. Callers that modify it do so at their own risk.

Return type:

DressedResult

property is_dressed: bool

True if a cached dressed result is present and consistent.

energy(device_states=None, /, **device_state_kwargs)

Dressed eigenvalue (GHz) for the given bare-state label.

Unspecified devices default to level 0. The method goes through the quchip.engine.dressing.label_eigensystem() array kernel, so it is safe in jax.jit/grad/vmap, and gradients flow through eigenvalues[labeling.indices[bare_idx]] to all traced chip parameters.

Parameters:

• device_states (mapping or None, default=None) – Bare product-state levels. Unspecified devices use level zero.

• **device_state_kwargs (int) – Per-device energy levels keyed by label.

dressed_spectrum()

Raw sorted eigenvalue array of the dressed Hamiltonian (GHz).

dressed_index(device_states=None, /, **device_state_kwargs)

Return the dressed index assigned to a bare label.

Parameters:

• device_states (mapping or None, default=None) – Bare product-state levels. Unspecified devices use level zero.

• **device_state_kwargs (int) – Per-device energy levels keyed by label.

bare_label(dressed_index)

Return the bare label assigned to a dressed index.

Parameters:

dressed_index (int) – Index in ascending order of dressed energy.

operator_in_dressed_basis(device, op, *, truncate=None)

Transform a local operator into the dressed eigenbasis.

Computes U† O_embedded U, where U is the dressed eigenvector matrix in solver coordinates. Each column has a real, nonnegative amplitude on its assigned bare state, as in state(). Optional truncation keeps the lowest truncate dressed levels.

Parameters:

• device (str or BaseDevice) – Device whose local operator is embedded and transformed.

• op (str or Operator) – Operator name resolved from the device (e.g. "n", "a"), or an operator already built in the local solver basis.

• truncate (int, optional) – Keep only the lowest truncate dressed levels of the result.

drive_matrix_elements(transition, *, drives=None)

Return dressed matrix elements of wired drive operators.

The matrix convention is m_j^{fi} = <f~|D_j|i~>, with the final dressed state as row index and the initial dressed state as column index. Each dressed eigenvector is phase-fixed so that its overlap with the assigned bare state is real and nonnegative. Relative matrix elements between different conditioned transitions are therefore independent of the backend’s eigenvector phases.

Passing a device selects its dressed ground-to-first-excitation transition, with every other device in its ground state. Passing (initial, final) mappings selects an arbitrary transition.

Each drive must expose exactly one local Hamiltonian channel. Without applying the signal chain, the method returns the physical matrix element of each control line’s drive operator, for combination with declared signal-chain phasors. This weak-drive projection gives effective driven-Hamiltonian coefficients. See Magesan and Gambetta, Phys. Rev. A 101, 052308 (2020), DOI 10.1103/PhysRevA.101.052308.

Parameters:

• transition (str, BaseDevice, or tuple[mapping, mapping]) – Device shorthand, or (initial, final) bare-state mappings. Unspecified devices in each mapping default to level zero.

• drives (sequence[str or BaseDrive], optional) – Wired control lines to evaluate. None evaluates every line. Original or rebound drive objects resolve by label.

Returns:

Mapping from drive label to backend-native scalar matrix elements, addressable by drive object or label. On a JAX-capable backend, the values stay JAX-traceable.

Return type:

LabelKeyedDict

Raises:

• ValueError – If no control equipment is attached, if a selected line is not a device-target drive, or if a drive exposes zero or multiple channels.

• KeyError – If a requested drive label is not in the attached equipment.

• TypeError – If transition is neither a device reference nor a pair of state mappings.

Examples

>>> from quchip import Chip, ChargeDrive, ControlEquipment, DuffingTransmon
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> drive = ChargeDrive(q, label="xy")
>>> chip = Chip([q], control_equipment=ControlEquipment([drive]))
>>> elements = chip.drive_matrix_elements(q, drives=[drive])
>>> abs(elements["xy"]) > 0
True

rotation_amplitude(transition, line, envelope, angle=3.141592653589793)

Return a first-guess amplitude that rotates a dressed transition by angle.

On resonance under RWA(), in the two-level limit, a pulse whose envelope keeps one phase rotates the transition by θ = 2π |m| |A a|, where m is the dressed matrix element of the line from drive_matrix_elements() and A a the area() of the envelope at amplitude A. The method returns A = θ / (2π |m| |a|). Leakage to other levels, detuning, counter-rotating terms under Exact(), and a phase that changes during the pulse all change the rotation, so the value is a starting point for a calibration, not a calibrated gate.

Parameters:

• transition (str, BaseDevice, or tuple[mapping, mapping]) – Transition as for drive_matrix_elements().

• line (str or BaseDrive) – Wired device-target line that plays the pulse.

• envelope (Envelope) – Pulse shape with an amplitude field. The field’s present value is ignored.

• angle (scalar, default=pi) – Rotation angle in rad.

Raises:

• ValueError – If a signal-chain transform or crosstalk acts on the line, or if the matrix element or the area per unit amplitude is zero.

• TypeError – If the envelope has no amplitude field.

state_components(state=None, /, *, n_components=5, **device_state_kwargs)

Leading bare-basis probabilities |⟨bare|dressed⟩|² of a dressed eigenstate.

state can be an int (direct dressed index) or a mapping of {device: Fock} (dressed index resolved through label matching).

Parameters:

• state (int, mapping, or None, default=None) – Dressed index or bare label. None uses keyword levels.

• n_components (int, default=5) – Maximum number of components returned.

• **device_state_kwargs (int) – Per-device energy levels keyed by label.

dispersive_shift(device_a, device_b)

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

Equivalent to the static ZZ interaction strength between the two devices, with all other devices grounded. See Blais et al., RMP 93, 025005 (2021), §IV.C.

Parameters:

• device_a (str or BaseDevice) – Devices whose cross-Kerr shift is evaluated.

• device_b (str or BaseDevice) – Devices whose cross-Kerr shift is evaluated.

Examples

>>> from quchip import DuffingTransmon, Capacitive, Chip
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.22, levels=3, label="q1")
>>> chip = Chip([q0, q1], couplings=[Capacitive(q0, q1, g=0.02)])
>>> zz = chip.dispersive_shift(q0, q1)  # residual ZZ in GHz

excitation_structure()

Return the excitation-number structure of the chip’s static model.

The record states whether the static model conserves the total excitation number N, the isolated energy-level index summed over devices. It gives the changes of N of each coupling, retained term, generated port pair, port, drive and collapse channel under the chip’s approximation, and the largest entry of each term that breaks conservation. largest_block() gives the largest matrix that dressed queries diagonalize. Each call reads the chip as it is, and the record keeps no reference to it.

Returns:

Complete record for the chip’s approximation.

Return type:

ExcitationStructure

Examples

>>> from quchip import DuffingTransmon, Capacitive, Chip, RWA
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.22, levels=3, label="q1")
>>> chip = Chip([q0, q1], couplings=[Capacitive(q0, q1, g=0.02)], approximation=RWA())
>>> structure = chip.excitation_structure()
>>> structure.conserves, structure.largest_block(2)
(True, 3)

kerr_matrix()

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

Labels and axes follow chip device order. Diagonal entries are dressed anharmonicities, and are NaN when that device has fewer than three resolved levels. Off-diagonal entries use the full-pull E11 - E10 - E01 + E00 convention.

effective_subspace_hamiltonian(states)

Effective Hamiltonian projected onto a labeled bare subspace.

Returns a Hermitian matrix in the user-selected bare-state basis whose eigenvalues are exactly the dressed eigenenergies of the listed bare-label states. The truncated overlap block is Löwdin (S^{-1/2}) orthonormalized, the same des-Cloizeaux construction as quchip.analysis.effective_hamiltonian(). Hybridization with states outside the subspace therefore cannot leak absolute dressed energies into the off-diagonal elements. The method connects full-chip dressed physics to the low-dimensional effective models of dispersive gate design and state-transfer analysis.

Parameters:

states (sequence of mapping or tuple[int, ...]) – Bare-state labels spanning the subspace, each a {device: energy_level} mapping or a full chip-ordered level tuple.

effective_hamiltonian_on_basis(basis)

Return the Löwdin-orthonormalized effective Hamiltonian on explicit bare states.

This is the shared core of quchip.analysis.effective_hamiltonian(), quchip.analysis.effective_hamiltonian_between_states() and effective_subspace_hamiltonian(). See quchip.analysis.EffectiveHamiltonianResult for the construction.

Parameters:

basis (sequence of tuple of int) – Chip-ordered bare-level tuples that span the subspace.

dressed_anharmonicity(device)

Return the dressed anharmonicity in GHz.

Parameters:

device (str or BaseDevice) – Device label or object. All other devices are grounded.

transition_frequency(target, lower, upper, when=None)

Return one optionally conditioned dressed transition in GHz.

Unspecified spectators are grounded. The target cannot appear in when. Traceable under jit/grad/vmap.

Parameters:

• target (str or BaseDevice) – Device whose transition is measured.

• lower (int) – Lower and upper local energy levels.

• upper (int) – Lower and upper local energy levels.

• when (dict or None, default=None) – Conditioning levels for spectator devices.

freq(target=None, when=None)

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

Parameters:

• target (str or BaseDevice, optional) – Device whose 0→1 transition is returned. None returns the full {device_label: frequency} dict for every device.

• when (dict[str | BaseDevice, int], optional) – Spectator Fock indices held fixed while the transition is evaluated. Unlisted devices stay in their ground state.

frame_info()

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

Resolves the chip’s current frame spec and returns a flat {device_label: ω_ref,i} dict. The assembler subtracts these concrete frequencies as -Σ_i ω_ref,i n̂_i. The method thus shows what the solver will solve without running it.

Values are returned as the frame resolver produces them. They are concrete Python floats in "lab", "rotating", or scalar modes, and can be JAX tracers in dict mode when the user wired a traced reference frequency through. Traced values pass through unchanged to preserve differentiability.

state(device_states=None, /, **device_state_kwargs)

Dressed eigenstate for local-energy product-state labels.

Validates the mapping (rejects bool, non-int, and out-of-range indices) and returns the assigned dressed eigenvector. After Chip.set_state_order(), a str shorthand (e.g. "eg1") is parsed via normalize_device_state_mapping(). Use Chip.bare_state() for arbitrary kets.

If the requested label’s assignment overlap is low, the method warns and names Chip.bare_state() as the product-state alternative.

Safe in jax.jit/grad/vmap. Under tracing, the method selects the eigenvector column through the array kernel, so a dressed initial state is differentiable end-to-end. The state’s amplitude on its assigned product state is real and nonnegative (gauge_phases()).

Parameters:

• device_states (mapping, str, or None, default=None) – Bare product-state label used for dressed assignment.

• **device_state_kwargs (int) – Per-device energy levels keyed by label.