quchip.analysis.effective_hamiltonian¶

Static-ZZ pathway attribution and des-Cloizeaux effective-Hamiltonian extraction.

Two analysis primitives built on the dressed-state and Schrieffer-Wolff (SW) machinery of quchip.chip.sw and quchip.chip.analysis:

analyze_static_zz: analyze_static_zz() — the exact residual ZZ between two devices (dispersive_shift(), unchanged), plus a 2nd-order SW attribution of the virtual states mediating it. The exact zz value is the “ZZ = 0 while J stays on target” loss primitive of a calibration sweep; pathways is a diagnostic for which virtual transition dominates it.
effective_hamiltonian: effective_hamiltonian() — the des-Cloizeaux effective Hamiltonian on a user-chosen computational subspace: dense, GHz, with eigenvalues that are exactly the labeled dressed energies of the requested bare states.

Both routes are algebra on the chip’s exact dressed spectrum (no perturbative truncation for the reported zz or effective_hamiltonian eigenvalues), so they stay differentiable end-to-end whenever the chip’s backend supports differentiating through its eigensolver.

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 (static ZZ) and the des-Cloizeaux perturbation-theory appendix convention for projecting onto a computational subspace.

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

Bases: object

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

Parameters:

zz (Any)
pathways (list[tuple[tuple[int, ...], Any]])
device_a (str)
device_b (str)
device_labels (tuple[str, ...])

zz¶

E(1,1) - E(1,0) - E(0,1) + E(0,0), identical to dispersive_shift(device_a, device_b)() — exact, not perturbative.

Type:: Any

pathways¶

(bare_occupation, amount) pairs: the contribution of each virtual intermediate state to the 2nd-order SW correction of the (1_a, 1_b) diagonal matrix element, amount = 1/2 * V_ik*V_ki*(1/(E_i - E_k) + 1/(E_i - E_k)) for i the (1_a, 1_b) bare index — a decomposition of that one energy correction, not of zz itself (which combines four dressed energies exactly). bare_occupation is a full chip-length Fock tuple, in device order.

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

device_a, device_b: Resolved device labels.

device_labels¶

Chip device labels in tensor-product order, for reading pathways’ occupation tuples.

Type:: tuple[str, …]

Amounts stay in the array namespace of the chip's parameters (JAX in, JAX

out) — traceable and differentiable, precision-filtered only on the

concrete path (:func:`~quchip.chip.sw.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 plus the leading virtual pathways.

Concrete values only — call outside jax.jit/grad regions; traced amounts render as <traced>.

Return type:: str

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

Compute exact static ZZ between two devices, plus 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 its virtual-intermediate-state contributions (pathway_attribution()), read off a partition that keeps only the four computational states of (a, b) (every other device grounded) — the natural loss primitive for a calibration sweep that holds zz near zero while some other exchange (e.g. a eliminate()-mediated J) stays on target.

Parameters:

chip (Chip)
device_a (str or BaseDevice) – The two devices whose static ZZ is analyzed.
device_b (str or BaseDevice) – The two devices whose static ZZ is analyzed.

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.

h_eff is built as S^-1/2 (W E W^dagger) S^-1/2 with W the overlap block between the requested bare states and their assigned dressed states, E the labeled dressed energies, and S = W W^dagger the (generally non-orthonormal) overlap Gram matrix — the symmetric (Löwdin) orthonormalization of exact_reduction()’s pairwise construction, generalized to an arbitrary number of kept states. S^-1/2 W is unitary by construction, so h_eff is unitarily similar to diag(E): its eigenvalues are exactly the labeled dressed energies, to numerical precision, regardless of how strongly the kept states hybridize with the rest of the chip. Off-diagonal entries carry the effective couplings between kept states; the diagonal is not, in general, individually equal to any one dressed energy once couplings mix the kept states.

Parameters:

h_eff (Any)
basis (tuple[tuple[int, ...], ...])
device_labels (tuple[str, ...])

h_eff¶

Dense Hermitian matrix, GHz, ordered as basis.

Type:: Any

basis¶

Full chip-length bare-occupation tuples spanning the subspace, in h_eff row/column order.

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

device_labels¶

Chip device labels in tensor-product order, for reading basis tuples.

Type:: tuple[str, …]

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 outside jax.jit/grad regions; a traced matrix renders as <traced>.

Return type:: str

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

Compute the des-Cloizeaux effective Hamiltonian on a user-chosen computational subspace.

Reuses the chip’s dressed spectrum (_compute_array_labeled()) rather than re-diagonalizing: one full-chip diagonalization drives both this and dispersive_shift(). See EffectiveHamiltonianResult for the construction and its exactness guarantee.

Parameters:

chip (Chip)
subspace (mapping or sequence) – {device: levels} keeps range(levels) of each named device (spectators grounded); a bare sequence of devices keeps each one’s full qubit (Fock 0/1) subspace (spectators grounded). Both accept a device label string or the object itself.

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]¶

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

The same des-Cloizeaux construction effective_hamiltonian() uses (see EffectiveHamiltonianResult), specialized to exactly the two-state subspace spanned by state_a and state_b — not the four-state product subspace a ["a", "b"] bare-sequence spec to effective_hamiltonian() would build (each device’s full qubit subspace independently), which is a different projection. This is the natural primitive for a static exchange rate between two 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)
state_a (tuple[int, ...]) – Full chip-length bare-occupation tuples (one entry per device, in devices order).
state_b (tuple[int, ...]) – Full chip-length bare-occupation tuples (one entry per device, in devices order).

Returns:

(2, 2) Hermitian matrix, GHz, in the array namespace of the chip’s backend. Eigenvalues are exactly state_a and state_b’s labeled dressed energies, 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)