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. New routes, such as a higher-order Schrieffer-Wolff method or numeric fit, register with register_reduction_method(), following the rule registry in quchip.chip.retarget.

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. Each hook returns the shape required by the shared fold loop.

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 reduced parameters from an exact diagonalization of the same engine-consumed static model as the SW route: 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, …]