quchip.engine.sectors

Excitation sectors and cutoff classes of a chip’s static model.

A product energy label gives each device one isolated local energy level, and its total excitation is N. When a chip’s static model conserves N, its Hamiltonian is block diagonal in the product energy basis, one block per N. Under an ExcitationCutoff, the retained static model P H P is block diagonal in classes: sets of totals in [0, K] that the static terms’ changes of N connect. SectorModel builds each block from each term’s local operator on its own support. Two product states couple only when they agree outside that support, so no operator on the full product space is formed. Dressed queries diagonalize only the blocks that their labels occupy. The weak-probe VNA route reads its vacuum and one-excitation blocks the same way.

Functions

generated_products(ports, pairs, dims)

Return the Hamiltonian of cascaded port pairs as local terms on joint supports.

Classes

SectorEigensystem(space, eigenvalues, ...)	Labeled eigenpairs of one sector or cutoff class.
SectorModel(chip, *[, resolution, ...])	Static lab-frame model of a chip, built one block of totals at a time.
SectorSpace(dims, totals, levels)	Product energy states whose levels sum to one of a set of totals.

quchip.engine.sectors.generated_products(ports, pairs, dims)

Return the Hamiltonian of cascaded port pairs as local terms on joint supports.

Each pair contributes (L_down^dagger c L_up - h.c.) / 2i, in the units of the port couplings’ product. The product is formed on the joint support of the two ports, so every intermediate level of those devices is kept. Gathering a term onto any set of product labels therefore gives P H_gen P exactly. A support whose elements are all below the round-off threshold of their products contributes no term.

Parameters:

• ports (dict) – Each port’s coupling matrix and support, keyed by port label. All couplings use the same local coordinates.

• pairs (sequence of tuple) – (downstream, upstream, coefficient) of each generated pair.

• dims (sequence of int) – Level count of each device.

class quchip.engine.sectors.SectorSpace(dims, totals, levels)

Bases: object

Product energy states whose levels sum to one of a set of totals.

Variables:

• dims (tuple[int, ...]) – Level count of each device, in chip order.

• totals (tuple[int, ...]) – Total energy-level indices of the states, in increasing order.

• levels (numpy.ndarray) – Levels with shape (size, len(dims)), one state per row, ordered by total and then in C order.

dims: tuple[int, ...]

totals: tuple[int, ...]

levels: ndarray

property size: int

Number of product states in the space.

property labels: tuple[tuple[int, ...], ...]

Bare labels of the states, in row order.

row(label)

Return the row of a bare label in this space.

Parameters:

label (tuple[int, ...]) – Level of each device, in chip order.

class quchip.engine.sectors.SectorEigensystem(space, eigenvalues, eigenvectors, labeling)

Bases: object

Labeled eigenpairs of one sector or cutoff class.

Variables:

• space (SectorSpace) – Product states of the block.

• eigenvalues (array_like) – Ascending eigenvalues in GHz.

• eigenvectors (array_like) – Eigenvectors as columns in the block’s product energy basis. Each column has a real, nonnegative amplitude on its assigned label, as gauge_phases() sets.

• labeling (Labeling) – Assignment of each bare label in space to one eigenvector.

space: SectorSpace

eigenvalues: Any

eigenvectors: Any

labeling: Labeling

energy(label)

Return the dressed energy assigned to a bare label, in GHz.

Parameters:

label (tuple[int, ...]) – Bare label in this block.

class quchip.engine.sectors.SectorModel(chip, *, resolution=None, advisories=None, approximation=None)

Bases: object

Static lab-frame model of a chip, built one block of totals at a time.

Without a cutoff, the chip’s static model must conserve the total energy-level index, as conserves states, and each block is one sector. Under an active ExcitationCutoff, the model is P H P on the labels with N <= K, and each block is one class of excitation_classes(). A block holds the device energies, each coupling band that the chip’s approximation keeps, each retained term, and the Hamiltonian that cascaded ports generate.

Parameters:

• chip (Chip) – Chip whose static model is built.

• resolution (optional) – Resolved local bases to reuse instead of resolving the devices again.

• advisories (list of str, optional) – List that receives approximation advisories instead of warnings.

• approximation (Approximation, optional) – Approximation that selects the static terms. None uses the chip’s.

cutoff: int | None

property traced: bool

Return whether the device energies, static terms or port couplings hold JAX tracers.

property contributions: tuple[tuple[Any, ...], ...]

Collapse contributions of the chip, with retained coordinate maps applied.

class_of(total)

Return the totals of the block that holds total.

Parameters:

total (int) – Total energy-level index.

space(totals)

Return the product states whose levels sum to totals.

Parameters:

totals (int or sequence of int) – One total energy-level index, or the totals of a class.

local_operator(operator, support)

Return an operator on support as a matrix in that support’s product energy basis.

Parameters:

• operator (PhysicsExpr or backend operator) – Operator in the authored coordinates of support.

• support (tuple[int, ...]) – Device indices in the operator’s tensor order. An empty support denotes an operator on the whole chip.

channel_operator(operator, rate, support, phase=None)

Return a channel coupling exp(i phase) sqrt(rate) A in its support’s energy basis.

Parameters:

• operator (PhysicsExpr or backend operator) – Channel operator A on support.

• rate (scalar or PhysicsExpr) – Channel rate.

• support (tuple[int, ...]) – Device indices of A. An empty support denotes the whole chip.

• phase (scalar or None, default=None) – Port phase in radians.

port_couplings()

Return each port’s coupling and support, keyed by port label.

block(operator, support, row_totals, column_totals)

Return the block of an operator from one set of totals to another.

Parameters:

• operator (array_like) – Matrix on support in its product energy basis.

• support (tuple[int, ...]) – Device indices in the matrix’s tensor order. An empty support denotes the whole chip.

• row_totals (int or sequence of int) – Total energy-level indices of the rows and of the columns.

• column_totals (int or sequence of int) – Total energy-level indices of the rows and of the columns.

hamiltonian(totals)

Return the static lab-frame Hamiltonian block on totals, in GHz.

Parameters:

totals (int or sequence of int) – One total energy-level index, or the totals of a class.

eigensystem(total)

Diagonalize the block that holds total and assign its bare labels.

Each block is diagonalized once per model, and a result that holds tracers is reused only inside its trace. A concrete block is diagonalized on the host, and a traced block uses one eigh.

Parameters:

total (int) – Total energy-level index in the block.

embed(totals, vector)

Return a vector of one block as a product-space vector in solver coordinates.

Parameters:

• totals (int or sequence of int) – Total energy-level indices of the block.

• vector (array_like) – Amplitudes in the block’s product energy basis.

labeled_subspace(labels)

Return the eigenpairs of the blocks that labels occupy and the labels’ positions.

The returned eigenvalues and block-diagonal eigenvector matrix hold the occupied blocks in increasing total. The list gives each label’s row, and the array gives the column of its assigned eigenvector.

Parameters:

labels (sequence of tuple[int, ...]) – Bare labels, each with one level per device.