quchip.chip.effective

Captured effective Hamiltonian and Lindblad terms on a retained product space.

Functions

lineage(projections)	Return the maps of projections and of their parents, each without parents, in the order they apply.
lineage_labels(projection)	Return the source devices of every map in a projection's lineage.
retained_operator(chip, operator, labels, ...)	Return a surviving component's operator in the retained coordinates of chip.
retained_support(chip, labels[, owner_key])	Return, in device order, the devices that a surviving operator on labels acts on in retained coordinates.
transport_retained_operator(chip, operator, ...)	Carry a dense operator through every captured map that it meets.

Classes

EffectiveTerms(labels, dims, hamiltonian[, ...])	Retained matrix terms in the named devices' authored coordinates.
OperatorProjection(source_labels, ...[, ...])	Captured authored coordinates for operators of surviving components.

class quchip.chip.effective.OperatorProjection(source_labels, source_dims, target_labels, target_dims, embedding, overrides=(), parents=(), unchanged_labels=())

Bases: object

Captured authored coordinates for operators of surviving components.

The rectangular embedding maps target authored coordinates into the source product space. parents are earlier maps in the order they apply. An operator passes through each map whose source devices it acts on, and its other devices keep their coordinates. A chain of local reductions therefore never forms a full-space embedding. Rates and local operators remain owned by the components. This record carries only their change of coordinates. unchanged_labels identifies tensor factors on which this map is the identity, proved by the reduction’s generator support.

source_labels: tuple[str, ...]

source_dims: tuple[int, ...]

target_labels: tuple[str, ...]

target_dims: tuple[int, ...]

embedding: Any

overrides: tuple[tuple[str, OperatorProjection], ...] = ()

parents: tuple[OperatorProjection, ...] = ()

unchanged_labels: tuple[str, ...] = ()

classmethod capture(chip, target_labels, target_dims, embedding, *, unchanged_labels=())

Compose a reduction with the source’s already captured operator coordinates.

embedding maps the targets into the product space of all of chip’s devices. One earlier map over all of them is multiplied in. Otherwise the earlier maps become parents, in the order they apply, and keep their own embeddings. unchanged_labels names targets on which this reduction is the identity. A multiplied-in map keeps only the labels that both maps leave unchanged.

with_current_operators(owner_keys)

Mark operators already authored in this retained space, preserving their lineage.

override_keys()

Return the owners whose operators a map in this chain already holds in retained coordinates.

transport(operator, labels, dims, owner_key=None)

Carry a dense operator into the target coordinates through every map of the lineage.

labels and dims give the operator’s tensor order in authored coordinates. Each map acts when the operator acts on one of its source devices. Other labels are spectators. They keep their coordinates and follow the map’s targets in the returned order. An operator whose owner a map holds in retained coordinates starts at that map’s override.

apply(operator, labels, owner_key=None, *, excitation_changes=None, dims=None)

Project a live local array without allocating its full-space identity embedding.

excitation_changes declares the source operator’s total energy-level changes. Pass it only when the captured map conserves the total level index, so that the projected operator carries the same changes. dims is needed only for spectator labels outside this map.

fingerprint()

to_dict()

classmethod from_dict(data)

quchip.chip.effective.lineage(projections)

Return the maps of projections and of their parents, each without parents, in the order they apply.

quchip.chip.effective.lineage_labels(projection)

Return the source devices of every map in a projection’s lineage.

quchip.chip.effective.retained_support(chip, labels, owner_key=None)

Return, in device order, the devices that a surviving operator on labels acts on in retained coordinates.

Parameters:

• chip (Chip) – Chip whose captured maps the operator follows.

• labels (tuple[str, ...]) – Devices the operator acts on in authored coordinates.

• owner_key (str or None, default=None) – Owner whose operator a map can already hold in retained coordinates.

quchip.chip.effective.transport_retained_operator(chip, operator, labels, dims, owner_key=None)

Carry a dense operator through every captured map that it meets.

Returns the operator, labels and dimensions in chip’s device order, or None when no captured map acts on labels. Each map applies in its lineage order, and the maps of different effective terms in chip order.

quchip.chip.effective.retained_operator(chip, operator, labels, backend, owner_key=None, *, bases=None, local_bases=None)

Return a surviving component’s operator in the retained coordinates of chip.

The operator acts on labels in their authored coordinates. The result acts on the targets of every captured map it meets and on its other devices, in device order. It is None when no captured map acts on the operator. The result keeps the operator’s declared level changes when every map it crosses conserves the total level index.

class quchip.chip.effective.EffectiveTerms(labels, dims, hamiltonian, channels=(), label='effective', projection=None, notes=(), excitation_changes=None, omitted_responses=<factory>)

Bases: object

Retained matrix terms in the named devices’ authored coordinates.

hamiltonian is in GHz. Channels carry unscaled operators and rates in 1/ns. These terms already express the reduction’s selected approximation, so assembly changes their frame without dropping further operator bands. Values are captured at construction. If you edit a surviving device, its authored terms change, but this captured correction is not recalculated. projection carries the source coordinates of surviving operators. Channels already stored here are in retained coordinates and bypass projection.

Parameters:

• labels (tuple[str, ...]) – Device labels defining the retained tensor-product order.

• dims (tuple[int, ...]) – Authored dimensions aligned with labels.

• hamiltonian (array-like) – Hermitian retained Hamiltonian in GHz.

• channels (tuple[CollapseChannel, ...], default=()) – Retained jump operators and Lindblad rates in 1/ns.

• label (str, default="effective") – Name used for diagnostics and the generated expression.

• projection (OperatorProjection or None, default=None) – Captured source-to-retained operator coordinates.

• notes (tuple[str, ...], default=()) – Approximations stated by the producer of these terms, reported by physics_notes() after the notes derived from the terms.

• excitation_changes (mapping of str to iterable of int, or None, default=None) – Structure declared by the producer. A mapping states that the Hamiltonian and projection conserve the retained devices’ total energy-level index. It also gives the total level changes, column minus row, that each named channel can carry. Band decomposition then treats every other change as zero, even for traced values. None declares no structure.

• omitted_responses (mapping of str to iterable of str, default={}) – Labels of the removed modes whose kept response, a multiport pole or a one-port section, the time-domain field of each named channel omits. A reduction declares them for the channels that it carries from such a mode. A solve rejects diffusive monitoring of these channels with a nonzero efficiency, also when the port network no longer holds the response.

labels: tuple[str, ...]

dims: tuple[int, ...]

hamiltonian: Any

channels: tuple[CollapseChannel, ...] = ()

label: str = 'effective'

projection: OperatorProjection | None = None

notes: tuple[str, ...] = ()

excitation_changes: Mapping[str, frozenset[int]] | None = None

omitted_responses: Mapping[str, tuple[str, ...]]

expression(matrix=None)

Return a captured matrix through the authored-expression path.

Parameters:

matrix (array-like or None, default=None) – Matrix in GHz. None uses hamiltonian.

channel_expression(channel)

Return one retained jump operator with its declared level changes.

Parameters:

channel (CollapseChannel) – One of channels.

physics_notes()

Return the terms’ support, assembly rule, channels and coordinate map, then the producer’s notes.

validate_for(chip)

Validate retained labels and dimensions against a chip.

Parameters:

chip (Chip) – Chip that will receive these terms.

fingerprint()

to_dict()

Persist concrete retained terms without serializing a live calculation.

classmethod from_dict(data)

Recreate validated retained terms from their numerical payload.

Parameters:

data (dict[str, Any]) – Payload produced by to_dict().