quchip.analysis.effective_hamiltonian¶

Static-ZZ pathways and des-Cloizeaux effective Hamiltonians.

analyze_static_zz() reports the exact dressed ZZ and a second-order Schrieffer-Wolff attribution to virtual transitions. The pathway estimates are diagnostics, and the reported ZZ comes from the dressed spectrum.

effective_hamiltonian() returns a dense GHz matrix on a selected computational subspace, whose eigenvalues equal its labeled dressed energies. Differentiation requires backend support for the eigensolver and a fixed assignment.

References: Bravyi, DiVincenzo & Loss, Schrieffer-Wolff transformation for quantum many-body systems, Ann. Phys. 326, 2793 (2011); Blais et al., Circuit quantum electrodynamics, RMP 93, 025005 (2021), §IV.C.

class quchip.analysis.effective_hamiltonian.StaticZZResult(zz, pathways, device_a, device_b, device_labels)[source]¶

Bases: object

Store the exact static ZZ between two devices and its 2nd-order SW pathway attribution.

Variables:

zz (Any) – E(1,1) - E(1,0) - E(0,1) + E(0,0), identical to dispersive_shift(device_a, device_b)(). This value is exact, not perturbative.
pathways (list[tuple[tuple[int, ...], Any]]) – (bare_occupation, amount) pairs. Each pair gives one virtual intermediate state’s contribution to the 2nd-order SW correction of the (1_a, 1_b) diagonal matrix element. The contribution is amount = 1/2 * V_ik*V_ki*(1/(E_i - E_k) + 1/(E_i - E_k)), where i is the (1_a, 1_b) bare index. This decomposes that one energy correction, not zz itself, which combines four dressed energies exactly. bare_occupation is a full chip-length Fock tuple, in device order.
device_b (device_a,) – Resolved device labels.
device_labels (tuple[str, ...]) – Chip device labels in tensor-product order, for reading the occupation tuples of pathways.
JAX (Amounts stay in the array namespace of the chip's parameters (JAX in,)
every (out) — traceable and differentiable. The concrete path lists)
correction (nonzero contribution, so the amounts sum to the second-order)

:ivar (pathway_attribution()).:

zz: Any¶

pathways: list[tuple[tuple[int, ...], Any]]¶

device_a: str¶

device_b: str¶

device_labels: tuple[str, ...]¶

describe()[source]¶

Print and return the exact ZZ and the leading virtual pathways.

Concrete values only. Call it outside jax.jit/grad regions. Traced amounts show as <traced>.

quchip.analysis.effective_hamiltonian.analyze_static_zz(chip, device_a, device_b)[source]¶

Calculate the exact static ZZ between two devices and its 2nd-order SW pathway attribution.

zz is dispersive_shift(), unchanged: the exact, all-orders residual coupling. pathways decomposes the 2nd-order SW correction to the (1_a, 1_b) diagonal energy into virtual intermediate-state contributions (pathway_attribution()). The pathways come from a partition that keeps only the four computational states of (a, b), with all other devices grounded.

This is the natural loss primitive for a calibration sweep that holds zz near zero while a different exchange, e.g. a eliminate()-mediated J, stays on target.

Parameters:

chip (Chip) – Chip whose dressed spectrum and couplings define the static model.
device_a (str or BaseDevice) – The two devices to analyze.
device_b (str or BaseDevice) – The two devices to analyze.

Return type:

StaticZZResult

Examples

>>> from quchip import Capacitive, Chip, DuffingTransmon
>>> from quchip.analysis import analyze_static_zz
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.24, levels=3, label="q1")
>>> chip = Chip([q0, q1], couplings=[Capacitive(q0, q1, g=0.01)])
>>> result = analyze_static_zz(chip, "q0", "q1")
>>> zz = result.zz  # exact residual ZZ, GHz

class quchip.analysis.effective_hamiltonian.EffectiveHamiltonianResult(h_eff, basis, device_labels)[source]¶

Bases: object

Store the des-Cloizeaux effective Hamiltonian on a labeled computational subspace.

The function builds h_eff as S^-1/2 (W E W^dagger) S^-1/2. Here W is the overlap block between the requested bare states and their assigned dressed states, and E is the labeled dressed energies. S = W W^dagger is the overlap Gram matrix, which in general is not orthonormal. Exact mode reductions use the same symmetric (Löwdin) orthonormalization.

S^-1/2 W is unitary by construction, so h_eff is unitarily similar to diag(E). Its eigenvalues are therefore exactly the labeled dressed energies, to numerical precision, for any hybridization strength between the kept states and the rest of the chip. The off-diagonal entries hold the effective couplings between kept states. When couplings mix the kept states, a diagonal entry in general does not equal one specific dressed energy.

Variables:

h_eff (Any) – Dense Hermitian matrix, GHz, ordered as basis.
basis (tuple[tuple[int, ...], ...]) – Full chip-length bare-occupation tuples that span the subspace, in the row/column order of h_eff.
device_labels (tuple[str, ...]) – Chip device labels in tensor-product order, for reading the basis tuples.

h_eff: Any¶

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

device_labels: tuple[str, ...]¶

describe()[source]¶

Print and return the matrix with labeled row/column kets.

Concrete values only. Call it outside jax.jit/grad regions. A traced matrix shows as <traced>.

quchip.analysis.effective_hamiltonian.effective_hamiltonian(chip, subspace)[source]¶

Calculate the des-Cloizeaux effective Hamiltonian on a user-selected computational subspace.

See EffectiveHamiltonianResult for the construction and its exactness guarantee.

Parameters:

chip (Chip) – Chip whose dressed spectrum defines the effective subspace.
subspace (mapping or sequence) – {device: levels} keeps range(levels) of each named device. A bare sequence of devices keeps each device’s full qubit (Fock 0/1) subspace. In both forms spectators are grounded, and a device can be a label string or the device object.

Return type:

EffectiveHamiltonianResult

Examples

>>> from quchip import Capacitive, Chip, DuffingTransmon
>>> from quchip.analysis import effective_hamiltonian
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.24, levels=3, label="q1")
>>> chip = Chip([q0, q1], couplings=[Capacitive(q0, q1, g=0.01)])
>>> result = effective_hamiltonian(chip, ["q0", "q1"])
>>> result.h_eff.shape
(4, 4)

quchip.analysis.effective_hamiltonian.effective_hamiltonian_between_states(chip, state_a, state_b)[source]¶

Calculate the 2x2 Löwdin-orthonormalized effective Hamiltonian between two explicit bare states.

This function uses the des-Cloizeaux construction of effective_hamiltonian() (see EffectiveHamiltonianResult), but on exactly the two-state subspace that state_a and state_b span. It does not use the four-state product subspace that a ["a", "b"] bare-sequence spec to effective_hamiltonian() builds from each device’s full qubit subspace. It is the natural primitive for a static exchange rate between the single-excitation bare states \(|1_a, 0_b\rangle\) and \(|0_a, 1_b\rangle\). The returned matrix’s off-diagonal entry is that exchange rate, in GHz.

Parameters:

chip (Chip) – Chip whose dressed spectrum defines the effective Hamiltonian.
state_a (tuple[int, ...]) – Full chip-length bare-occupation tuples (one entry for each device, in devices order).
state_b (tuple[int, ...]) – Full chip-length bare-occupation tuples (one entry for each device, in devices order).

Returns:

(2, 2) Hermitian matrix, GHz, in the array namespace of the chip’s backend. Its eigenvalues are exactly the labeled dressed energies of state_a and state_b, to numerical precision.

Return type:

Any

Examples

>>> from quchip import Capacitive, Chip, DuffingTransmon
>>> from quchip.analysis import effective_hamiltonian_between_states
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.24, levels=3, label="q1")
>>> chip = Chip([q0, q1], couplings=[Capacitive(q0, q1, g=0.01)])
>>> h_eff = effective_hamiltonian_between_states(chip, (1, 0), (0, 1))
>>> h_eff.shape
(2, 2)