quchip.chip.sw

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

Kernels follow their inputs: a concrete chip reduces with NumPy on the host, and a traced chip reduces with jax.numpy. A host check reports coupled singularities, also under tracing. No traced physics is coerced to Python scalars. H is the chip’s bare Hamiltonian in the C-order product basis, in ordinary GHz.

The partition eliminates one mode: P is the mode in its ground state, and Q is everything else. The generator solves the Sylvester condition [S, H₀] = -V_offdiag on the P↔Q blocks, which gives 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 array in GHz, with labels and dims.
bare_index(labels, dims[, excited_label])	Full bare product-basis index for the ground state, or for the n=1 occupation of one label.
basis_row(p_index, labels, dims[, excited_label])	Row in the P-block ordering for the ground state, or for the n=1 occupation of one label.
cross_block_gap(h, p_mask)	Smallest coupled P/Q bare-energy gap at diagnostic working precision.
degeneracy_error(labels, dims)	Return the error of a coupled degeneracy that names its levels in the product basis of labels.
exact_mode_subspace(h, labels, dims, ...[, ...])	Diagonalize one model and validate its computational label assignment.
exact_pair_parameters(subspace, labels, ...)	Report labeled energies and exchange entries from the complete kept model.
exact_subspace(eigenvalues, eigenvectors, ...)	Use one Lowdin map for a complete kept Hamiltonian and every operator.
extract_pair_parameters(h_eff, p_index, ...)	Read survivor parameters from the P-block matrix by pure indexing, with no physics choices.
h_effective_second_order(h, s, p_mask)	H_eff = P (H + ½[S, V]) P restricted to the P block (dense, GHz).
interaction_generator(energies, interaction, *)	First-order anti-Hermitian generator that removes the off-diagonal part of an interaction.
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.
sylvester_generator(h, p_mask, *[, error])	Generator S that solves the P↔Q Sylvester condition, and the block-gap diagnostic.

Classes

ExactSubspace(hamiltonian, embedding, ...[, ...])

One orthonormal kept coordinate map and its exact Hamiltonian.

Exceptions

EliminationError(message, *[, route, check, ...])

A check of eliminate() failed.

exception quchip.chip.sw.EliminationError(message, *, route=None, check=None, devices=(), label=None, weight=None, levels=None, coupling=None, residual=None, threshold=None)

Bases: ValueError

A check of eliminate() failed.

The string form is the message of the check followed by its values. Inside jax.jit the check runs in a host callback, so the caller receives a JAX runtime error with the same text instead of this type.

Parameters:

• message (str) – The message of the check followed by its values.

• route (optional) – Keywords that set the attributes below.

• check (optional) – Keywords that set the attributes below.

• devices (optional) – Keywords that set the attributes below.

• label (optional) – Keywords that set the attributes below.

• weight (optional) – Keywords that set the attributes below.

• levels (optional) – Keywords that set the attributes below.

• coupling (optional) – Keywords that set the attributes below.

• residual (optional) – Keywords that set the attributes below.

• threshold (optional) – Keywords that set the attributes below.

Variables:

• route (str) – "sw" or "exact".

• check (str) – "degeneracy" when two coupled levels have the same bare energy, "labeling" when a diagnostic label has no distinct majority dressed state, or "orthonormalization" when the kept overlap matrix cannot be orthonormalized stably.

• devices (tuple of str) – Device order of the occupations in label and levels.

• label (tuple of int or None) – The diagnostic label that failed the labeling check.

• weight (float or None) – Its largest dressed weight.

• levels (tuple of tuple of int, or None) – The two coupled levels that failed the degeneracy check.

• coupling (complex or None) – Their coupling element in GHz.

• residual (float or None) – The orthonormalization residual.

• threshold (float or None) – The bound of the check: the smallest weight of a label, or the largest residual.

quchip.chip.sw.bare_hamiltonian(chip, *, approximation=None, include_network=True)

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

This path is for analysis only. It applies the chip’s approximation strategy, does not change the authored Hamiltonian, and intentionally materializes a dense matrix. Set include_network=False to omit terms that the network generates from its ports.

quchip.chip.sw.mode_blocks(dims, labels, mode_label)

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

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

quchip.chip.sw.cross_block_gap(h, p_mask)

Smallest coupled P/Q bare-energy gap at diagnostic working precision.

quchip.chip.sw.degeneracy_error(labels, dims)

Return the error of a coupled degeneracy that names its levels in the product basis of labels.

quchip.chip.sw.sylvester_generator(h, p_mask, *, error=None)

Generator S that solves the P↔Q Sylvester condition, and 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 has a double-where guard, so an exactly degenerate cross pair with no matrix element between it contributes zero with a finite gradient. It does not propagate a NaN backward through the unselected branch. A coupled degeneracy raises error(row, column, coupling, energy), by default a ValueError; degeneracy_error() names the levels.

Traced execution checks through a host callback that also survives callers requesting only a gradient, and marks invalid outputs NaN.

Returns:

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

Return type:

tuple

quchip.chip.sw.interaction_generator(energies, interaction, *, error=None)

First-order anti-Hermitian generator that removes the off-diagonal part of an interaction.

A coupled degeneracy raises error(row, column, coupling, energy) for its first pair, by default a ValueError (sylvester_generator()).

quchip.chip.sw.h_effective_second_order(h, s, p_mask)

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

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

Row in the P-block ordering for the ground state, or for the n=1 occupation of one label.

Shared basis bookkeeping between extract_pair_parameters() and any caller that reads a matching row of a separately transformed P-block operator.

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

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

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

Read survivor parameters from the P-block matrix by pure indexing, with no physics choices.

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

class quchip.chip.sw.ExactSubspace(hamiltonian, embedding, energies, kept_indices, gram=None, residual=None, label_margins=None)

Bases: object

One orthonormal kept coordinate map and its exact Hamiltonian.

gram is the overlap matrix of the kept dressed states on the kept bare states, and residual the error of its symmetric orthonormalization. label_margins holds the labeling report of exact_mode_subspace().

hamiltonian: Any

embedding: Any

energies: Any

kept_indices: Any

gram: Any = None

residual: Any = None

label_margins: dict | None = None

transform_operator(operator)

quchip.chip.sw.exact_subspace(eigenvalues, eigenvectors, kept_indices, dressed_indices, *, error=None)

Use one Lowdin map for a complete kept Hamiltonian and every operator.

An unstable orthonormalization raises error(residual), by default a ValueError.

quchip.chip.sw.exact_mode_subspace(h, labels, dims, mode_label, survivor_labels, sectors=None, *, eigensystem=None)

Diagonalize one model and validate its computational label assignment.

With sectors, the Hamiltonian conserves total excitation number and the kept map keeps every sector separate. Reuse eigensystem when the caller already diagonalized and labeled h.

The diagnostic labels are the ground state and the single and pair excitations of the survivors. Each needs a distinct majority dressed state, with a largest weight of at least 0.5 + 1e-6, and the kept overlap matrix needs a stable orthonormalization. A failed check raises EliminationError. label_margins of the result reports, for each diagnostic label in the occupation order of labels, its largest weight, the runner-up and the margin to that threshold, and the smallest eigenvalue of the overlap matrix, the residual and its margin to 1e-9.

quchip.chip.sw.exact_pair_parameters(subspace, labels, dims, mode_label, survivor_labels)

Report labeled energies and exchange entries from the complete kept model.

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

Virtual-state attribution for one H_eff matrix element.

Intermediate |k⟩’s contribution to (½[S, V])_ij is ½ V_ik V_kj (1/(E_i − E_k) + 1/(E_j − E_k)), evaluated from the supplied generator and its commutator. With s=None, the two generator rows come from h. Returns (k, amount) pairs for every Q-block state with a nonzero contribution, so the amounts sum to the second-order part (H_eff − PHP)_ij. Under tracing, the nonzero filter cannot run, so every Q state is returned, and the extra entries are exact zeros.