quchip.engine.excitation

Excitation-number structure of resolved chips.

N is the total isolated energy-level index of a product state. This module finds the changes of N that authored operators carry, proves whether the retained static model of a chip conserves N, and indexes product states by N. ExcitationStructure holds these facts for one resolved system and one approximation, and the engine’s routes read them from it.

Functions

authored_excitation_changes(operator, ...)	Return the total energy-level changes an authored operator carries.
concrete_excitation_changes(matrix, dims[, ...])	Return the total level changes carried by a concrete operator.
drive_excitation_changes(chip, drive, ...)	Return the changes of N that a delivered drive keeps under approximation, or None.
excitation_classes(changes, maximum)	Partition the totals 0..maximum into the classes that changes connect.
excitation_sectors(dims)	Total energy-level index of every C-order product state.
excitation_structure(chip, approximation, *)	Return the excitation structure of chip under approximation.
format_changes(changes)	Return changes as text, with each symmetric pair written ±c.
keeps_zero_total_only(approximation)	Return whether approximation keeps only the zero-total bands of ordinary interactions.
largest_changing_entry(operator, labels, ...)	Return the largest magnitude of an entry of operator that changes N.
lowers_by_one(changes)	Return whether changes proves that an operator lowers N by one and does nothing else.
round_off_advisory(structure)	Return a warning when only entries far below the level spacings break conservation.
sector_eigh(h, sectors)	Diagonalize each total-excitation block; return ascending eigenpairs.
sector_levels(dims, total)	Return every level product below dims that sums to total, in C order.
sector_size(dims, total)	Count the product states of dims whose levels sum to total.

Classes

ExcitationStructure(chip, approximation, ...)	Excitation-number structure of one resolved chip under one approximation.
ExcitationTerm(label, kind, changes[, ...])	The changes of the total excitation number N that one term carries.

quchip.engine.excitation.excitation_sectors(dims)

Total energy-level index of every C-order product state.

quchip.engine.excitation.sector_levels(dims, total)

Return every level product below dims that sums to total, in C order.

quchip.engine.excitation.sector_size(dims, total)

Count the product states of dims whose levels sum to total.

Parameters:

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

• total (int) – Total energy-level index.

quchip.engine.excitation.excitation_classes(changes, maximum)

Partition the totals 0..maximum into the classes that changes connect.

A class holds the totals that steps n -> n +- c with every intermediate total in [0, maximum] connect. Unknown changes give one class.

Parameters:

• changes (frozenset of int or None) – Changes of the total energy-level index, or None when unknown.

• maximum (int) – Largest retained total.

quchip.engine.excitation.sector_eigh(h, sectors)

Diagonalize each total-excitation block; return ascending eigenpairs.

Eigenvectors have exact zeros outside their own sector, so round-off can neither mix sectors nor make the result depend on near-degeneracies between them. A concrete Hamiltonian is diagonalized on the host, where the differently sized blocks compile no device programs.

quchip.engine.excitation.concrete_excitation_changes(matrix, dims, energy_vectors=None)

Return the total level changes carried by a concrete operator.

matrix acts on a product basis whose energy-ordered states are the columns of energy_vectors; None means the product basis is already energy ordered. dims counts the energy levels per subsystem. Exact nonzero comparison can add round-off weights but never omits a band. Traced payloads return None: their bands are not statically known.

quchip.engine.excitation.authored_excitation_changes(operator, labels, backend, bases)

Return the total energy-level changes an authored operator carries.

Declarations and factored algebra supply structural support. Scalar coefficients do not change it, including at zero. Constant leaves are checked in the captured energy bases at compile time. Unknown matrix support or traced energy vectors return None. No small-entry threshold supplies a conservation proof. A product on a truncated energy basis is checked as one complete matrix.

Parameters:

• operator (PhysicsExpr or backend operator) – Operator on labels in their authored coordinates.

• labels (tuple[str, ...]) – Ordered device labels supporting operator.

• backend (Backend) – Backend used to materialize operator.

• bases (mapping or None) – Captured basis records keyed by device label.

quchip.engine.excitation.largest_changing_entry(operator, labels, backend, bases)

Return the largest magnitude of an entry of operator that changes N.

The operator is read as one complete matrix in the captured energy bases, in its own units. None means that a basis is missing, that the matrix would not fit in memory, or that the operator, its parameters or the energy vectors are traced.

Parameters:

• operator (PhysicsExpr or backend operator) – Operator on labels in their authored coordinates.

• labels (tuple[str, ...]) – Ordered device labels supporting operator.

• backend (Backend) – Backend used to materialize operator.

• bases (mapping or None) – Captured basis records keyed by device label.

quchip.engine.excitation.format_changes(changes)

Return changes as text, with each symmetric pair written ±c.

Parameters:

changes (frozenset of int or None) – Changes of N, or None when unknown.

quchip.engine.excitation.keeps_zero_total_only(approximation)

Return whether approximation keeps only the zero-total bands of ordinary interactions.

Such an approximation removes every change of N from a coupling or an intrinsic two-device term. Retained terms bypass the filter.

Parameters:

approximation (Approximation) – Approximation the model is resolved with.

quchip.engine.excitation.lowers_by_one(changes)

Return whether changes proves that an operator lowers N by one and does nothing else.

Parameters:

changes (frozenset of int or None) – Changes of N that the operator carries, or None when unknown.

class quchip.engine.excitation.ExcitationTerm(label, kind, changes, largest_entry=None)

Bases: object

The changes of the total excitation number N that one term carries.

A change c maps a product state with total N to total N - c, so a lowering operator has the change 1.

Variables:

• label (str) – Label of the coupling, retained term, port, drive or collapse channel. A port pair is labeled "upstream -> downstream" and a collapse channel "owner.name".

• kind (str) – "coupling", "retained", "cascade" (the Hamiltonian that a port network generates for one port pair), "port", "drive" or "channel".

• changes (frozenset of int or None) – Changes of N that quchip finds for the term under the approximation, or None when it cannot prove them.

• largest_entry (float or None) – For a coupling or retained term that changes N, the largest magnitude in GHz of a static entry that changes N. None for other terms and when the entry is traced.

label: str

kind: str

changes: frozenset[int] | None

largest_entry: float | None = None

class quchip.engine.excitation.ExcitationStructure(chip, approximation, resolution)

Bases: object

Excitation-number structure of one resolved chip under one approximation.

N is the total isolated energy-level index of a product state. The static model conserves N when every coupling, retained term and generated port pair keeps only zero changes of N, and every port of a generated pair lowers N by one. quchip reads these changes from exact operator structure: a nonzero entry that changes N breaks conservation however small it is, and unknown structure is not a proof. A conserving static model is block diagonal with one block for each N, and dressed queries diagonalize only the blocks of their labels. Under an active ExcitationCutoff, each block is one class of totals that the static changes connect.

Chip.excitation_structure() returns a complete record. The engine builds one record for each resolved system and approximation, and reads each fact the first time a route asks for it.

Parameters:

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

• approximation (Approximation) – Approximation that selects the static terms.

• resolution (object) – Resolved local bases of chip.

Variables:

• approximation (Approximation) – Approximation that selects the static terms.

• dims (tuple of int) – Resolved level count of each device, in chip order.

• cutoff (int or None) – Largest total of the chip’s active excitation cutoff, or None.

property changes: frozenset[int] | None

Changes of N of the static model, closed under negation and holding 0, or None when unknown.

property conserves: bool

Whether the static model conserves N.

interaction_changes()

Yield the changes of N of each coupling and retained term, in chip order.

Each term is read once. A coupling under an approximation that keeps only zero-total bands yields {0}.

property terms: tuple[ExcitationTerm, ...]

Changes of N of every coupling, retained term and generated port pair.

property ports: tuple[ExcitationTerm, ...]

Changes of N of each port of a generated pair, in the chip’s retained coordinates.

property breaking: tuple[ExcitationTerm, ...]

Terms and ports that prevent a proof of conservation, empty when the static model conserves N.

property drives: tuple[ExcitationTerm, ...]

Changes of N of each wired control line under the approximation.

property channels: tuple[ExcitationTerm, ...]

Changes of N of each collapse channel, ports included.

property level_span: float | None

Largest spread of one device’s resolved energies in GHz, or None when they are traced.

classes(max_total)

Return the classes of totals 0..max_total that the static changes connect.

Parameters:

max_total (int) – Largest retained total excitation number.

sector_sizes(max_total)

Return the number of product states with each total 0..max_total.

Parameters:

max_total (int) – Largest total excitation number.

largest_block(max_total)

Return the size of the largest block that dressed queries diagonalize for labels up to max_total.

A conserving chip diagonalizes one sector for each total, a chip with an active excitation cutoff one class, and any other chip its complete static model.

Parameters:

max_total (int) – Largest total excitation number of the queried labels.

quchip.engine.excitation.round_off_advisory(structure)

Return a warning when only entries far below the level spacings break conservation.

Every term that breaks conservation must be a coupling or retained term whose largest entry that changes N is below 1e-12 times the largest level span of one device. The heuristic does not change the verdict, and None means that it does not apply. The search stops at the first term that rules it out.

Parameters:

structure (ExcitationStructure) – Record of a chip whose static model does not conserve N.

quchip.engine.excitation.excitation_structure(chip, approximation, *, resolution=None, complete=False)

Return the excitation structure of chip under approximation.

The record is built once for each resolved system and approximation.

Parameters:

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

• approximation (Approximation) – Approximation that selects the static terms.

• resolution (optional) – Resolved local bases to reuse. None resolves the chip.

• complete (bool, default=False) – Evaluate every fact now and keep no reference to chip. Such a record is not cached.

quchip.engine.excitation.drive_excitation_changes(chip, drive, target, bases, approximation)

Return the changes of N that a delivered drive keeps under approximation, or None.

The operator-band filter applies to a coupling drive under every approximation, so an approximation whose retained bands conserve N removes every change of a coupling drive that no captured map retains.

Parameters:

• chip (Chip) – Chip that owns the drive.

• drive (BaseDrive) – Drive whose authored terms are read.

• target (object) – Device or coupling that receives the drive.

• bases (mapping) – Resolved basis records keyed by device label.

• approximation (Approximation) – Approximation the model is resolved with.