quchip.chip.transformations.methods

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

eliminate()’s device path is method-agnostic except at a few decision points. They are how to extract the surviving pair parameters and how to carry the eliminated mode’s jump operator into the reduced frame. They also include whether a residual ZZ and a pathway attribution are available, and what higher-order physics the reduction drops. This module puts those decision points into a ReductionMethod strategy. 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 on a traced value. The two shipped strategies, SchriefferWolffMethod and ExactReduction, are selected once by name and then operate on the DeviceReductionContext that 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 name.

Classes

DeviceReductionContext(mode_label, ...[, ...])	Method-agnostic inputs of one device elimination.
ExactReduction()	Exact-from-dressing reduction (method="exact").
ReductionMethod()	Compute a retained Hamiltonian, embedding and reduction diagnostics.
SchriefferWolffMethod()	2nd-order Schrieffer-Wolff reduction (method="sw").

class quchip.chip.transformations.methods.DeviceReductionContext(mode_label, survivor_labels, labels, dims, h, p_mask, sectors=None)

Bases: object

Method-agnostic inputs of one device elimination.

The device path of eliminate() computes this context once and passes it to the chosen ReductionMethod. The perturbative generator is computed only when a method requests it, and exact reduction does not use it.

Variables:

• mode_label (str) – Its label.

• survivor_labels (list[str]) – The touching survivors in bare-label order. The retained Hamiltonian and the pair diagnostics use the same order, so every ("J", a, b) lookup agrees for all coupling-scan orders.

• labels (list[str]) – Device labels in the bare product-basis order.

• dims (tuple[int, ...]) – Per-device Hilbert-space dimensions, aligned with labels.

• h (Any) – The bare chip Hamiltonian as a dense array.

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

• p_mask (Any) – Boolean mask selecting the kept (P) block of the product basis.

• sectors (numpy.ndarray | None) – Total excitation number of each product state when h conserves it, else None.

mode_label: str

survivor_labels: list[str]

labels: list[str]

dims: tuple[int, ...]

h: Any

p_mask: Any

sectors: ndarray | None = None

property s: Any

Return the SW generator, computed once per reduction on request.

property sw_embedding: Any

property sw_hamiltonian: Any

property eigensystem: Any

Diagonalize and label the captured Hamiltonian once per reduction.

property exact: Any

class quchip.chip.transformations.methods.ReductionMethod

Bases: object

Compute a retained Hamiltonian, embedding and reduction diagnostics.

A concrete strategy declares its name (the method string that eliminate() dispatches on) and implements the hooks below. Each hook receives the DeviceReductionContext the caller assembled and uses its fixed product energy coordinates.

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

name: ClassVar[str]

source_approximation(chip)

Approximation strategy of the static model this route reads.

retained_hamiltonian(ctx)

Return the complete Hamiltonian on the retained product coordinates.

embedding(ctx)

Map retained energy coordinates into the captured full energy basis.

pair_parameters(ctx)

Reduced per-survivor and per-pair parameters.

Returns a mapping that matches extract_pair_parameters() /exact_pair_parameters(), with {survivor: {"freq_after": ...}} for each survivor and a ("J", a, b) entry for each survivor pair. A route that resolves it also adds a ("zz", a, b) entry.

transform_operator(ctx, operator)

Carry a full operator into the kept mode-ground manifold.

dressed_transition(ctx, lowering)

Compute the eliminated mode’s dressed transition and lowering weight.

The default reads the labeled exact eigensystem of ctx.h. A route can override it with its own approximation, as SW does.

Parameters:

• ctx (DeviceReductionContext) – Captured reduction inputs in product energy coordinates.

• lowering (Any) – Mode lowering operator embedded in the full product space.

Returns:

Transition frequency in GHz and dimensionless squared matrix element.

Return type:

tuple

residual_zz(ctx, pair_params, a, b)

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

pathways(ctx, pair_params, a, b)

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

pathway_source(ctx)

Attribution of any retained element to virtual states, or None when the route has none.

The function takes two product-state indices of ctx and returns (index, amount) pairs. The elimination result keeps it, so it holds only the arrays it reads.

label_margins(ctx)

Margins of the route’s dressed-state labeling checks, or None when it has none.

dropped_suffix()

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

class quchip.chip.transformations.methods.SchriefferWolffMethod

Bases: ReductionMethod

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

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

name: ClassVar[str] = 'sw'

retained_hamiltonian(ctx)

Return the complete Hamiltonian on the retained product coordinates.

embedding(ctx)

Map retained energy coordinates into the captured full energy basis.

dressed_transition(ctx, lowering)

Compute second-order energies and a unitary first-order transition weight.

pair_parameters(ctx)

Reduced per-survivor and per-pair parameters.

Returns a mapping that matches extract_pair_parameters() /exact_pair_parameters(), with {survivor: {"freq_after": ...}} for each survivor and a ("J", a, b) entry for each survivor pair. A route that resolves it also adds a ("zz", a, b) entry.

residual_zz(ctx, pair_params, a, b)

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

pathways(ctx, pair_params, a, b)

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

pathway_source(ctx)

Attribution of any retained element to virtual states, or None when the route has none.

The function takes two product-state indices of ctx and returns (index, amount) pairs. The elimination result keeps it, so it holds only the arrays it reads.

dropped_suffix()

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

class quchip.chip.transformations.methods.ExactReduction

Bases: ReductionMethod

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

This reduction reads reduced parameters from an exact diagonalization of the same engine-consumed static model as the SW route. It gives exact kept-block energies (which residual ZZ needs), but requires a full diagonalization. It has no perturbative generator, so no pathway attribution is available (exact_pair_parameters()).

name: ClassVar[str] = 'exact'

retained_hamiltonian(ctx)

Return the complete Hamiltonian on the retained product coordinates.

embedding(ctx)

Map retained energy coordinates into the captured full energy basis.

pair_parameters(ctx)

Reduced per-survivor and per-pair parameters.

Returns a mapping that matches extract_pair_parameters() /exact_pair_parameters(), with {survivor: {"freq_after": ...}} for each survivor and a ("J", a, b) entry for each survivor pair. A route that resolves it also adds a ("zz", a, b) entry.

residual_zz(ctx, pair_params, a, b)

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

pathways(ctx, pair_params, a, b)

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

label_margins(ctx)

Margins of the route’s dressed-state labeling checks, or None when it has none.

dropped_suffix()

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

quchip.chip.transformations.methods.register_reduction_method(method)

Register a reduction strategy under its name.

Parameters:

method (ReductionMethod) – Strategy added under its unique name.

quchip.chip.transformations.methods.lookup_reduction_method(name)

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

quchip.chip.transformations.methods.reduction_method_names()

The registered method names, in registration order.