quchip.sweep¶

Declarative parameter sweeps for chip studies.

Sweep axes compose as Cartesian products or zipped correlated scans. Spectrum sweeps dress the chip at each point, keeping eigenvalues and bare→dressed label assignments.

Sweep values keep their native physical units (GHz for frequencies, ns for times, mK for temperatures). Sweep keeps JAX arrays verbatim, so downstream code can differentiate through swept values. Sweep promotes all other values to np.ndarray, so len and indexing behave predictably.

The dressed-spectrum machinery here computes the eigenvalues and overlaps of the lab-frame chip Hamiltonian. For a general reference on the dressed-state picture of coupled circuit qubits, see Blais, Grimsmo, Girvin & Wallraff, Circuit quantum electrodynamics, Rev. Mod. Phys. 93, 025005 (2021).

Classes

`SpectrumSweep`(chip, axes, *[, evals_count, ...])	Calculate dressed spectra over a parameter grid.
`SpectrumSweepResult`(device_labels, ...[, ...])	Dressed-spectrum data collected across a `SpectrumSweep` grid.
`Sweep`(values, *[, name])	Declare a one-dimensional parameter axis.
`ZippedSweep`(sweeps)	Pair sweep axes element by element.

class quchip.sweep.ZippedSweep(sweeps)[source]¶

Bases: object

Pair sweep axes element by element.

Use Sweep.zip() to validate lengths before you construct this bundle.

Parameters:

sweeps (tuple of Sweep) – Nonempty axes with equal lengths and distinct names.

Variables:

sweeps (tuple of Sweep) – Axes advanced together.
size (int) – Length of the first axis.

class quchip.sweep.Sweep(values, *, name=None)[source]¶

Bases: object

Declare a one-dimensional parameter axis.

Parameters:

values (array_like, shape (n,)) – Values in the parameter’s units. JAX arrays are kept and other inputs are converted to NumPy arrays. Scalar inputs are unsupported.
name (str or None, default None) – Parameter path, e.g. "q.freq". Defaults to "unnamed". Names must be unique when axes are combined.

Variables:

values (array_like) – Stored axis values.
name (str) – Parameter path or axis name.
size (int) – Number of values.

static zip(*sweeps)[source]¶

Pair axes for element-wise iteration.

Requires at least two sweeps of equal size, and raises ValueError otherwise.

Parameters:: *sweeps (Sweep) – Two or more Sweep axes. Their name attributes must all be distinct. A ZippedSweep with repeated axis names raises ValueError when it is enumerated later (expand(), SpectrumSweep).
Returns:: Bundle iterated element-wise instead of taken in Cartesian product with other axes.
Return type:: ZippedSweep

static expand(axes)[source]¶

Expand independent axes as a Cartesian product and zipped axes pairwise.

Parameters:: axes (sequence of Sweep or ZippedSweep) – Axes in output order. Names must be unique across all groups.
Returns:: Parameter mappings in C order (last axis fastest). No axes gives one empty mapping, and an empty axis gives no points.
Return type:: list of dict

class quchip.sweep.SpectrumSweepResult(device_labels, bare_labels, eigenvalues, dressed_indices, assignment_overlaps, overlap_threshold, params, eigenvector_matrices=None, eigenstates=None)[source]¶

Bases: object

Dressed-spectrum data collected across a SpectrumSweep grid.

Variables:

device_labels (tuple[str, ...]) – Device labels of the underlying chip, in the chip’s tensor-product order (devices).
bare_labels (tuple[tuple[int, ...], ...]) – Bare-state labels tracked by the sweep (one tuple of occupation numbers per device).
eigenvalues (numpy.ndarray) – (*grid_shape, n_evals) array of eigenvalues in GHz, one row per sweep point.
dressed_indices (numpy.ndarray) – (*grid_shape, n_bare) array giving the dressed-state index assigned to each bare label at each sweep point, or NaN when no confident assignment is found.
assignment_overlaps (numpy.ndarray) – (*grid_shape, n_bare) overlap weights accompanying dressed_indices.
overlap_threshold (float) – Minimum overlap below which an assignment is unreliable and returned as NaN.
params (numpy.ndarray) – Object array of parameter dicts, one per grid point.
eigenvector_matrices (numpy.ndarray | None) – Optional object array of dressed eigenvector matrices (one per grid point), produced when store_eigenstates=True.
eigenstates (numpy.ndarray | None) – Optional object array of dressed eigenstates aligned with eigenvector_matrices.

device_labels: tuple[str, ...]¶

bare_labels: tuple[tuple[int, ...], ...]¶

eigenvalues: ndarray¶

dressed_indices: ndarray¶

assignment_overlaps: ndarray¶

overlap_threshold: float¶

params: ndarray¶

eigenvector_matrices: ndarray | None = None¶

eigenstates: ndarray | None = None¶

property shape: tuple[int, ...]¶: Sweep-grid shape (excludes the trailing eigenvalue axis).

dressed_index(device_states=None, /, **device_state_kwargs)[source]¶

Dressed-state indices across the sweep for one bare label.

Entries where the assignment overlap falls below overlap_threshold (or was never found) are returned as NaN.

Parameters:

device_states (Mapping[str, int] | None) – Mapping from device (label or object) to occupation number, resolved through bare_label_from_mapping(). Unspecified devices default to Fock index 0. Do not use with device_state_kwargs.
**device_state_kwargs (int) – Keyword form of device_states (device label as keyword).

Returns:

Floating-point array of shape shape (the sweep grid, excluding the bare-label axis). A floating dtype is needed to represent unreliable or missing assignments as NaN. An unreliable assignment is a grid point whose overlap with this bare label falls below overlap_threshold. A missing assignment is a grid point where no dressed state was assigned to this bare label.

Return type:

numpy.ndarray

Examples

>>> # Track the bare |1, 0> state across a sweep
>>> # result.dressed_index({qubit_a: 1, qubit_b: 0})

energy_by_bare_label(device_states=None, /, **device_state_kwargs)[source]¶

Dressed energies (GHz) traced out for one bare label across the sweep.

Invalid points inherit the NaN mask from dressed_index().

Parameters:

device_states (Mapping[str, int] | None) – Mapping from device (label or object) to occupation number. See dressed_index(). Do not use with device_state_kwargs.
**device_state_kwargs (int) – Keyword form of device_states (device label as keyword).

Returns:

Floating-point array of shape shape, in GHz. Entries where dressed_index() returns NaN (overlap below overlap_threshold, or no assignment found) are NaN.

Return type:

numpy.ndarray

state_components_at(point, state=None, /, *, n_components=5, **device_state_kwargs)[source]¶

Return the largest bare-state probabilities of one dressed state.

Requires running the sweep with store_eigenstates=True.

Parameters:

point (int, tuple of int, or None) – Grid coordinate. An integer selects a one-dimensional sweep. None is valid only for a result with no sweep axes.
state (int, mapping, or None, default None) – Dressed index, or a mapping from device object or label to bare level. A mapping is resolved through the stored overlap assignment. Omitted devices have level zero.
n_components (int, default 5) – Positive maximum number of components returned.
**device_state_kwargs (int) – Bare levels keyed by device label, as an alternative to a mapping. Do not combine with a nonempty mapping.

Returns:

Bare occupation tuples mapped to squared amplitudes, in descending order.

Return type:

dict

Raises:

ValueError – Eigenvectors were not saved, a coordinate is invalid, the requested count is nonpositive, or the bare label has no confident assignment.