quchip.chip.transformations.methods

Reduction-method registry for device elimination (extension seam).

eliminate()’s device path is method-agnostic up to a handful of decision points: how the surviving pair parameters are extracted, how the eliminated mode’s jump operator is carried into the reduced frame, whether a residual ZZ and a pathway attribution are available, and what higher-order physics the reduction drops. This module factors those decision points into a ReductionMethod strategy keyed in _REDUCTION_METHODS, so a new route (a higher-order Schrieffer-Wolff, a numeric fit) registers a strategy with register_reduction_method() rather than threading another method == branch through the fold — the same registration pattern as quchip.chip.retarget’s rule registry.

Dispatch keys on the static method string, never a traced value: the two shipped strategies, SchriefferWolffMethod and ExactReduction, are selected once by name and then operate on the DeviceReductionContext the caller computed.

Functions

lookup_reduction_method(name)

Return the strategy registered under name, or None if none is.

reduction_method_names()

The registered method names, in registration order.

register_reduction_method(method)

Register a reduction strategy under its ReductionMethod.name.

Classes

DeviceReductionContext(chip, mode, ...)

Method-agnostic inputs of one device elimination.

ExactReduction()

Exact-from-dressing reduction (method="exact").

ReductionMethod()

One route from a bare chip to its reduced effective parameters.

SchriefferWolffMethod()

2nd-order Schrieffer-Wolff reduction (method="sw").
class quchip.chip.transformations.methods.DeviceReductionContext(chip, mode, mode_label, survivor_labels, labels, dims, h, s, p_mask)[source]

Bases: object

Method-agnostic inputs of one device elimination.

Computed once by the device path of eliminate() and handed to the chosen ReductionMethod. Every field is shared by both shipped routes: the reduction differs only in how it reads this context, not in what the context contains.

Parameters:
chip

The source chip being reduced (never mutated).

Type:

Any

mode

The device being eliminated.

Type:

Any

mode_label

Its label.

Type:

str

survivor_labels

The touching survivors in bare-label order — the same ordering the pair extraction and the fold loop key on, so every ("J", a, b) lookup agrees regardless of coupling-scan order.

Type:

list[str]

labels

Device labels in the bare product-basis order.

Type:

list[str]

dims

Per-device Hilbert-space dimensions, aligned with labels.

Type:

tuple[int, …]

h

The bare chip Hamiltonian as a dense array.

Type:

Any

s

The Sylvester generator rotating the P/Q partition of h.

Type:

Any

p_mask

Boolean mask selecting the kept (P) block of the product basis.

Type:

Any

chip: Any
mode: Any
mode_label: str
survivor_labels: list[str]
labels: list[str]
dims: tuple[int, ...]
h: Any
s: Any
p_mask: Any
class quchip.chip.transformations.methods.ReductionMethod[source]

Bases: object

One route from a bare chip to its reduced effective parameters.

A concrete strategy declares its name (the method string eliminate() dispatches on) and implements the five hooks below. Each receives the DeviceReductionContext the caller assembled; a hook returns the same shape its method == name branch produced before this seam existed, so the fold loop is identical across routes.

Every hook body runs on jax.grad/jit paths and must stay traceable: no float()/int()/bool() or Python branching on a traced value.

name: ClassVar[str]
pair_parameters(ctx)[source]

Reduced per-survivor and per-pair parameters.

Returns a mapping matching extract_pair_parameters() /exact_reduction(): {survivor: {"freq_after": ...}} for each survivor, plus a ("J", a, b) entry per survivor pair (and, for a route that resolves it, a ("zz", a, b) entry).

Parameters:

ctx (DeviceReductionContext)

Return type:

dict

survivor_amplitudes(ctx)[source]

Survivor-lowering amplitude of the mode’s transformed unit jump operator.

One entry per ctx.survivor_labels: the amplitude with which the eliminated mode’s own (unit, dimensionless) lowering operator, carried into the reduced frame with the route’s rotation, drives that survivor. The caller folds each amplitude into a Purcell rate with purcell_rate_from(). Only called when the mode dissipates.

Parameters:

ctx (DeviceReductionContext)

Return type:

dict[str, Any]

residual_zz(ctx, pair_params, a, b)[source]

Residual ZZ between survivor pair (a, b), or None if the route cannot resolve it.

Parameters:
Return type:

Any | None

pathways(ctx, pair_params, a, b)[source]

Top virtual-state attribution of the pair’s mediated exchange, or None.

Parameters:
Return type:

list | None

dropped_suffix()[source]

Trailing clause of the "Dropped: ..." note — the physics this route omits.

Return type:

str

class quchip.chip.transformations.methods.SchriefferWolffMethod[source]

Bases: ReductionMethod

2nd-order Schrieffer-Wolff reduction (method="sw").

Perturbative and differentiable: pair parameters come from the projected 2nd-order effective Hamiltonian, and the mediated exchange carries a virtual-state pathway attribution. Residual ZZ is a higher-order correction this route does not represent (Bravyi, DiVincenzo & Loss, Ann. Phys. 326, 2793 (2011)).

name: ClassVar[str] = 'sw'
pair_parameters(ctx)[source]

Reduced per-survivor and per-pair parameters.

Returns a mapping matching extract_pair_parameters() /exact_reduction(): {survivor: {"freq_after": ...}} for each survivor, plus a ("J", a, b) entry per survivor pair (and, for a route that resolves it, a ("zz", a, b) entry).

Parameters:

ctx (DeviceReductionContext)

Return type:

dict

survivor_amplitudes(ctx)[source]

Survivor-lowering amplitude of the mode’s transformed unit jump operator.

One entry per ctx.survivor_labels: the amplitude with which the eliminated mode’s own (unit, dimensionless) lowering operator, carried into the reduced frame with the route’s rotation, drives that survivor. The caller folds each amplitude into a Purcell rate with purcell_rate_from(). Only called when the mode dissipates.

Parameters:

ctx (DeviceReductionContext)

Return type:

dict[str, Any]

residual_zz(ctx, pair_params, a, b)[source]

Residual ZZ between survivor pair (a, b), or None if the route cannot resolve it.

Parameters:
Return type:

Any | None

pathways(ctx, pair_params, a, b)[source]

Top virtual-state attribution of the pair’s mediated exchange, or None.

Parameters:
Return type:

list | None

dropped_suffix()[source]

Trailing clause of the "Dropped: ..." note — the physics this route omits.

Return type:

str

class quchip.chip.transformations.methods.ExactReduction[source]

Bases: ReductionMethod

Exact-from-dressing reduction (method="exact").

Reads the reduced parameters off the chip’s exact dressed spectrum: exact kept-block energies (what residual ZZ needs) at the cost of a full diagonalization. It has no perturbative generator, so no pathway attribution is available (exact_reduction()).

name: ClassVar[str] = 'exact'
pair_parameters(ctx)[source]

Reduced per-survivor and per-pair parameters.

Returns a mapping matching extract_pair_parameters() /exact_reduction(): {survivor: {"freq_after": ...}} for each survivor, plus a ("J", a, b) entry per survivor pair (and, for a route that resolves it, a ("zz", a, b) entry).

Parameters:

ctx (DeviceReductionContext)

Return type:

dict

survivor_amplitudes(ctx)[source]

Survivor-lowering amplitude of the mode’s transformed unit jump operator.

One entry per ctx.survivor_labels: the amplitude with which the eliminated mode’s own (unit, dimensionless) lowering operator, carried into the reduced frame with the route’s rotation, drives that survivor. The caller folds each amplitude into a Purcell rate with purcell_rate_from(). Only called when the mode dissipates.

Parameters:

ctx (DeviceReductionContext)

Return type:

dict[str, Any]

residual_zz(ctx, pair_params, a, b)[source]

Residual ZZ between survivor pair (a, b), or None if the route cannot resolve it.

Parameters:
Return type:

Any | None

pathways(ctx, pair_params, a, b)[source]

Top virtual-state attribution of the pair’s mediated exchange, or None.

Parameters:
Return type:

list | None

dropped_suffix()[source]

Trailing clause of the "Dropped: ..." note — the physics this route omits.

Return type:

str

quchip.chip.transformations.methods.register_reduction_method(method)[source]

Register a reduction strategy under its ReductionMethod.name.

Parameters:

method (ReductionMethod)

Return type:

None

quchip.chip.transformations.methods.lookup_reduction_method(name)[source]

Return the strategy registered under name, or None if none is.

Parameters:

name (str)

Return type:

ReductionMethod | None

quchip.chip.transformations.methods.reduction_method_names()[source]

The registered method names, in registration order.

Return type:

tuple[str, …]