quchip.chip.sw

Schrieffer-Wolff reduction kernels (2nd order) on bare chip blocks.

All functions are pure, jax.numpy-only on the value path, and traced-safe: no float(), no Python branch on a traced value. H is the chip’s bare Hamiltonian in the C-order product basis, ordinary GHz; block masks are static NumPy booleans (dims are static). The caller (the elimination handlers in quchip.chip.transformations) owns cloning, folding, and control-plane concerns.

The partition eliminates one mode: P = the mode in its ground state, Q = everything else. The generator solves the Sylvester condition [S, H₀] = -V_offdiag on the P↔Q blocks, giving the standard 2nd-order effective Hamiltonian H_eff = P (H + ½[S, V]) P.

References: Bravyi, DiVincenzo & Loss, Ann. Phys. 326, 2793 (2011) (Schrieffer-Wolff); F. Yan et al., Phys. Rev. Applied 10, 054062 (2018) (tunable-coupler exchange J); Koch et al., PRA 76, 042319 (2007), §IV (dispersive shift); Krantz et al., Appl. Phys. Rev. 6, 021318 (2019), §V (Purcell decay, dispersive readout).

Functions

bare_hamiltonian(chip, *[, approximation])

Full bare Hamiltonian as a dense jnp array in GHz, with labels and dims.

bare_index(labels, dims[, excited_label])

Full bare product-basis index for the ground state, or one label's n=1 occupation.

basis_row(p_index, labels, dims[, excited_label])

Row within the P-block ordering for the ground state, or one label's n=1 occupation.

exact_reduction(chip, mode_label, ...)

Exact-from-dressing reduction of the complete authored static model.

exact_transform_collapse(c_full, evecs, ...)

c_eff = P U† c U P with U the labeled eigenvector matrix (dense).

extract_pair_parameters(h_eff, p_index, ...)

Read survivor parameters from the P-block matrix.

h_effective_second_order(h, s, p_mask)

H_eff = P (H + ½[S, V]) P restricted to the P block (dense, GHz).

mode_blocks(dims, labels, mode_label)

(p_mask, q_mask) boolean arrays over the product basis.

pathway_attribution(h, s, p_mask, i_idx, j_idx)

Virtual-state attribution for one H_eff matrix element.

purcell_rate_from(...)

rate = |amplitude|² · κ — the mediated decay a survivor inherits.

sylvester_generator(h, p_mask)

Generator S solving the P↔Q Sylvester condition, plus the block-gap diagnostic.

transform_collapse(c_full, s, p_mask)

c_eff = P (c + [S, c]) P — the 2nd-order jump-operator transform (dense).
quchip.chip.sw.bare_hamiltonian(chip, *, approximation=None)[source]

Full bare Hamiltonian as a dense jnp array in GHz, with labels and dims.

This analysis-only path applies the chip’s approximation strategy while leaving the authored Hamiltonian unchanged. It intentionally materializes a dense matrix.

Parameters:
Return type:

tuple[Any, list[str], tuple[int, …]]

quchip.chip.sw.mode_blocks(dims, labels, mode_label)[source]

(p_mask, q_mask) boolean arrays over the product basis.

P is the eliminated mode in its ground state, Q everything else. The masks are static NumPy arrays (dims are static), so they can index and slice without touching the trace.

Parameters:
Return type:

tuple[Any, Any]

quchip.chip.sw.sylvester_generator(h, p_mask)[source]

Generator S solving the P↔Q Sylvester condition, plus the block-gap diagnostic.

E = diag(H) are the bare energies and V = H − diag(E); S_ij = V_ij / (E_i − E_j) on the cross blocks only. The division is double-where guarded so an exactly degenerate cross pair with no matrix element between it contributes zero — with a finite gradient, not a NaN propagated backward through the unselected branch.

Returns:

(s, min_gap): the (anti-Hermitian) generator, and the smallest |E_i − E_j| over cross entries carrying a nonzero V at working precision — a traced scalar, diagnostics only (jnp.inf when no cross entry couples).

Return type:

tuple

Parameters:
quchip.chip.sw.h_effective_second_order(h, s, p_mask)[source]

H_eff = P (H + ½[S, V]) P restricted to the P block (dense, GHz).

Parameters:
Return type:

Any

quchip.chip.sw.basis_row(p_index, labels, dims, excited_label=None)[source]

Row within the P-block ordering for the ground state, or one label’s n=1 occupation.

Shared basis bookkeeping between extract_pair_parameters() and any caller reading out a matching row of a separately transformed P-block operator (e.g. a collapse operator carried through transform_collapse()).

Parameters:
Return type:

int

quchip.chip.sw.bare_index(labels, dims, excited_label=None)[source]

Full bare product-basis index for the ground state, or one label’s n=1 occupation.

Parameters:
Return type:

int

quchip.chip.sw.extract_pair_parameters(h_eff, p_index, labels, dims, mode_label)[source]

Read survivor parameters from the P-block matrix. Pure indexing, no physics choices.

Returns {survivor: {"freq_after": E(1_s) − E(0)}} for every survivor, plus ("J", a, b): h_eff[<1_a|, |1_b>] for every survivor pair — the effective exchange between the two single-excitation states.

Parameters:
Return type:

dict

quchip.chip.sw.transform_collapse(c_full, s, p_mask)[source]

c_eff = P (c + [S, c]) P — the 2nd-order jump-operator transform (dense).

The same rotation that block-diagonalizes H carries the jump operators into the reduced frame; truncating at first order in S matches the Hamiltonian’s 2nd-order accuracy. The projection is exact for the spectrum but approximate for dissipation; the caller records this approximation in the result notes. Pass the unit jump operator and fold the rate back in via purcell_rate_from().

Parameters:
Return type:

Any

quchip.chip.sw.purcell_rate_from(c_eff_survivor_lowering_amplitude, kappa)[source]

rate = |amplitude|² · κ — the mediated decay a survivor inherits.

amplitude is the survivor-lowering matrix element of the transformed unit jump operator (dimensionless, ≈ g/Δ in the dispersive case); κ is the eliminated mode’s own rate in 1/ns, so the result is Lindblad-ready without any further unit conversion.

Parameters:

  • c_eff_survivor_lowering_amplitude (Any)

  • kappa (Any)

Return type:

Any

quchip.chip.sw.exact_reduction(chip, mode_label, survivor_labels)[source]

Exact-from-dressing reduction of the complete authored static model.

Diagonalizes the lab-frame Hamiltonian without term removal, independent of the chip’s solve approximation. Kept-block energies are exact to all orders — which is what ZZ needs. This is the des-Cloizeaux caveat in reverse: energies are exact, but the effective basis is the overlap-projected one, not the canonical SW rotation, so off-diagonal reads (J) agree with the perturbative route only through 2nd order.

Returns the same parameter shape as the perturbative extraction — {survivor: {"freq_after": E(1_s) − E(0)}} and ("J", a, b) — plus ("zz", a, b) = E₁₁ − E₁₀ − E₀₁ + E₀₀ per survivor pair (identical convention to Chip.dispersive_shift()).

Raises:

ValueError – When two kept computational labels are assigned the same dressed state (concrete path only; under tracing the guard is skipped — labeling indices are best-effort diagnostics there, never a traced branch).

Parameters:
Return type:

dict

quchip.chip.sw.exact_transform_collapse(c_full, evecs, kept_dressed_indices)[source]

c_eff = P U† c U P with U the labeled eigenvector matrix (dense).

Rotates the jump operator into the dressed basis and keeps the rows and columns of the kept block’s assigned dressed states. This is the exact counterpart of transform_collapse(); the caller records the selected dissipation treatment in the result notes.

Parameters:

  • c_full (Any)

  • evecs (Any)

  • kept_dressed_indices (Any)

Return type:

Any

quchip.chip.sw.pathway_attribution(h, s, p_mask, i_idx, j_idx)[source]

Virtual-state attribution for one H_eff matrix element.

The contribution of intermediate |k⟩ to (½[S, V])_ij is ½ V_ik V_kj (1/(E_i − E_k) + 1/(E_j − E_k)), with the same double-where guard as the generator. Returns (k, amount) pairs for the Q-block states carrying a nonzero path at working precision; under tracing the nonzero filter cannot run, so every Q state is returned (diagnostics remain complete either way — extra entries are exact zeros).

Parameters:
Return type:

list[tuple[int, Any]]