quchip.analysis.cross_resonance¶

Cross-resonance Hamiltonian tomography analysis.

Fits target-qubit Bloch-vector trajectories from a CR pulse duration sweep and extracts the six effective Hamiltonian coefficients {IX, IY, IZ, ZX, ZY, ZZ} in GHz (the package units contract).

The CR effective Hamiltonian in the two-qubit subspace is written as:

H_eff = (I ⊗ A + Z ⊗ B) / 2, A, B ∈ span{X, Y, Z}

which expands to six coefficients:

ω_IX, ω_IY, ω_IZ (control-state-independent) ω_ZX, ω_ZY, ω_ZZ (control-state-dependent)

in units of ordinary frequency (GHz).

References

Sheldon, Magesan, Chow, Gambetta, “Procedure for systematically tuning up cross-talk in the cross resonance gate”, PRA 93, 060302(R) (2016).

Unit convention: public durations are in ns and returned coefficients are in GHz. The fit runs internally in Hz/seconds (the conditioning heuristics are tuned for CR-tomography scales, following Sheldon et al.); both conversions happen exactly once at the public boundary. Multiply by 2π to get angular frequency.

Functions

`analyze_cr_susceptibility`(chip, control, ...)	Return the dressed weak-drive CR response of one directed edge.
`analyze_cross_resonance`(durations, ctrl0, ctrl1)	Extract CR effective Hamiltonian coefficients from Bloch tomography data.
`bloch_model`(t, px, py, pz, td, bx, by, bz)	Model Bloch-vector evolution under a constant drive Hamiltonian with a single decay envelope.

Classes

`CRHamiltonianResult`(IX, IY, IZ, ZX, ZY, ZZ, ...)	Store the six CR effective Hamiltonian coefficients in GHz, with uncertainties.
`CRSusceptibilityResult`(m_control_0, ...)	Store weak-drive CR coefficients per unit programmed drive amplitude.

quchip.analysis.cross_resonance.bloch_model(t, px, py, pz, td, bx, by, bz)[source]¶

Model Bloch-vector evolution under a constant drive Hamiltonian with a single decay envelope.

The model assumes a drive Hamiltonian

H = π (px X + py Y + pz Z)

so the Bloch vector precesses at frequency \(f = \sqrt{p_x^2 + p_y^2 + p_z^2}\) Hz about axis \(\hat{n} = (p_x, p_y, p_z)/f\), damped by a single exponential envelope \(\exp(-t / t_d)\) applied uniformly to all three Bloch components. Separate \(T_1\) and \(T_2\) decay processes are not modeled.

Parameters:

t ((N,) ndarray) – Times in seconds.
px (float) – Drive Hamiltonian coefficients in Hz (ordinary frequency).
py (float) – Drive Hamiltonian coefficients in Hz (ordinary frequency).
pz (float) – Drive Hamiltonian coefficients in Hz (ordinary frequency).
td (float) – Decay time constant in seconds.
bx (float) – Bloch vector offset (fixed point, reached asymptotically).
by (float) – Bloch vector offset (fixed point, reached asymptotically).
bz (float) – Bloch vector offset (fixed point, reached asymptotically).

Returns:

Rows are [⟨X(t)⟩, ⟨Y(t)⟩, ⟨Z(t)⟩].

Return type:

(3, N) ndarray

class quchip.analysis.cross_resonance.CRHamiltonianResult(IX, IY, IZ, ZX, ZY, ZZ, IX_err, IY_err, IZ_err, ZX_err, ZY_err, ZZ_err, params_ctrl0=None, params_ctrl1=None, cov_ctrl0=None, cov_ctrl1=None, cost_ctrl0=0.0, cost_ctrl1=0.0)[source]¶

Bases: object

Store the six CR effective Hamiltonian coefficients in GHz, with uncertainties.

All six quantities are ordinary frequency (not angular); multiply by 2π to convert to rad/ns. The convention matches Sheldon et al. (PRA 93, 060302(R), 2016):

H_eff = (I ⊗ A + Z ⊗ B) / 2

where A = ω_IX X + ω_IY Y + ω_IZ Z and B = ω_ZX X + ω_ZY Y + ω_ZZ Z.

params_ctrl0 / params_ctrl1 hold the raw per-control-state fit output [px, py, pz, td, bx, by, bz] and are diagnostics only: they are in the fit’s internal units (px/py/pz in Hz, td in seconds), not converted.

Parameters:

IX (float)
IY (float)
IZ (float)
ZX (float)
ZY (float)
ZZ (float)
IX_err (float)
IY_err (float)
IZ_err (float)
ZX_err (float)
ZY_err (float)
ZZ_err (float)
params_ctrl0 (ndarray | None)
params_ctrl1 (ndarray | None)
cov_ctrl0 (ndarray | None)
cov_ctrl1 (ndarray | None)
cost_ctrl0 (float)
cost_ctrl1 (float)

IX: float¶

IY: float¶

IZ: float¶

ZX: float¶

ZY: float¶

ZZ: float¶

IX_err: float¶

IY_err: float¶

IZ_err: float¶

ZX_err: float¶

ZY_err: float¶

ZZ_err: float¶

params_ctrl0: ndarray | None = None¶

params_ctrl1: ndarray | None = None¶

cov_ctrl0: ndarray | None = None¶

cov_ctrl1: ndarray | None = None¶

cost_ctrl0: float = 0.0¶

cost_ctrl1: float = 0.0¶

coeffs()[source]¶

Return {name: (value_ghz, err_ghz)} for all six coefficients.

Return type:: dict[str, tuple[float, float]]

summary()[source]¶

Print and return a formatted summary of all six coefficients.

Return type:: str

class quchip.analysis.cross_resonance.CRSusceptibilityResult(m_control_0, m_control_1, IX_per_amplitude, ZX_per_amplitude, control, target, drive)[source]¶

Bases: object

Store weak-drive CR coefficients per unit programmed drive amplitude.

For control-state-conditioned target-transition matrix elements

\[m_z = \langle\widetilde{z_c,1_t}|D_c|\widetilde{z_c,0_t}\rangle,\]

the effective-Hamiltonian convention

\[H_\mathrm{eff} = \tfrac{1}{2}(IX\,I\!X + ZX\,Z\!X)\]

gives IX_per_amplitude = m_0 + m_1 and ZX_per_amplitude = m_0 - m_1. Values are backend-native complex scalars and remain JAX-traceable.

Parameters:

m_control_0 (Any)
m_control_1 (Any)
IX_per_amplitude (Any)
ZX_per_amplitude (Any)
control (str)
target (str)
drive (str)

m_control_0, m_control_1: Dressed target-transition matrix elements conditioned on the control occupying |0> and |1>.

IX_per_amplitude, ZX_per_amplitude: Weak-drive Pauli coefficients per unit signal amplitude.

control, target, drive: Resolved labels.

m_control_0: Any¶

m_control_1: Any¶

IX_per_amplitude: Any¶

ZX_per_amplitude: Any¶

control: str¶

target: str¶

drive: str¶

quchip.analysis.cross_resonance.analyze_cr_susceptibility(chip, control, target, *, drive=None)[source]¶

Return the dressed weak-drive CR response of one directed edge.

The analysis projects the physical control-line operator onto the target’s dressed 0 -> 1 transition twice: once with the control in |0> and once in |1>. No pulse, rotating-frame solve, or time evolution is performed.

Parameters:

chip (Chip) – Coupled chip with attached control equipment.
control (str | 'BaseDevice') – Directed CR control and target, supplied as device objects or labels.
target (str | 'BaseDevice') – Directed CR control and target, supplied as device objects or labels.
drive (str | 'BaseDrive' | None) – Control line to project. When omitted, the unique wired device-target line attached to control is selected.

Returns:

Conditional matrix elements and the corresponding IX and ZX coefficients per unit programmed amplitude.

Return type:

CRSusceptibilityResult

Raises:

ValueError – If the edge is a self-edge, control equipment is absent, implicit drive resolution is ambiguous, or the selected line does not target the control.

References

Magesan and Gambetta, Phys. Rev. A 101, 052308 (2020). Malekakhlagh, Magesan, and McKay, Phys. Rev. A 102, 042605 (2020).

quchip.analysis.cross_resonance.analyze_cross_resonance(durations, ctrl0, ctrl1, sigma_ctrl0=None, sigma_ctrl1=None, t_offset=0.0)[source]¶

Extract CR effective Hamiltonian coefficients from Bloch tomography data.

Fits the target-qubit Bloch trajectory under a CR pulse to the analytic model in bloch_model() — once with the control qubit in |0⟩ and once with it in |1⟩ — and combines the two fits to isolate the six coefficients {IX, IY, IZ, ZX, ZY, ZZ}.

The decomposition is:

p_ctrl0 = (I/2) part → ω_IX, ω_IY, ω_IZ
p_ctrl1 = (Z/2) part → ω_ZX, ω_ZY, ω_ZZ

Specifically:

ω_ZQ = (p_ctrl0_Q - p_ctrl1_Q) / 2 ω_IQ = (p_ctrl0_Q + p_ctrl1_Q) / 2

for Q ∈ {X, Y, Z}.

Parameters:

durations ((N,) ndarray) – CR pulse durations in ns (the package convention). Must be monotone; need not be equally spaced. Converted once to seconds at the function boundary for the fit.
ctrl0 (dict or 2D ndarray) – Target-qubit Bloch trajectory with control in |0⟩, as a dict with keys "x", "y", "z" or a 2D array shaped (3, N) or (N, 3) (see _as_xyz()).
ctrl1 (dict or 2D ndarray) – Same with control in |1⟩.
sigma_ctrl0 (dict with keys "x", "y", "z" (optional)) – Per-point standard deviations for the control-|0⟩ data (used as inverse weights in the least-squares fit).
sigma_ctrl1 (dict with keys "x", "y", "z" (optional)) – Same for the control-|1⟩ data.
t_offset (float) – Subtract this offset (in ns) from durations before fitting (useful to exclude a pulse-ramp transient).

Returns:

Six coefficients in GHz (package units contract; durations are taken in ns and the Hz-valued fit internals are converted exactly once at this boundary), each with a one-sigma uncertainty.

Return type:

CRHamiltonianResult

Raises:

RuntimeError – If all initial guesses fail to converge for either control state.

Examples

>>> import numpy as np
>>> from quchip import analyze_cross_resonance
>>> durations = np.linspace(0, 400, 20)  # ns
>>> ctrl0 = {"x": np.sin(0.02 * durations), "y": np.zeros_like(durations),
...          "z": np.cos(0.02 * durations)}
>>> ctrl1 = {"x": np.sin(0.03 * durations), "y": np.zeros_like(durations),
...          "z": np.cos(0.03 * durations)}
>>> result = analyze_cross_resonance(durations, ctrl0, ctrl1)
>>> zx, zx_err = result.coeffs()["ZX"]  # GHz