quchip.engine.states

State preparation in the solver basis.

Product states from energy labels or authored local kets, authored states of the full chip, the dressed initial state of a label, and reusable states in captured excitation coordinates. The chip’s state queries and the solve problems call these functions.

Functions

bare_local_kets(chip, resolved, bases)	Resolve each local ket without allocating its tensor product.
bare_state_from_bases(chip, resolved, bases)	Build a product state from the shared local state preparation.
block_model(chip, approximation)	Return the static block model of approximation, or None when dressing needs the full eigensystem.
compact_state(chip, *components[, dressed])	Prepare a normalized state on the excitation totals of its components.
compatible_values(state, labels, dims, ...)	Validate captured coordinates before interpreting a saved energy state.
label_levels(chip, spec, dims, *[, role])	Return the product label of a level mapping or state shorthand, in device order.
label_state(chip, spec, result, start)	Return the dressed state of a label at the start of a solve, in the solve's coordinates and frame.
materialize_compact(chip, spec, space)	Prepare an initial state in the coordinates of an exact pulse space.
materialize_state_spec(chip, state_spec, bases)	Materialize one authored state specification in the engine's solver basis.
sector_label_ket(chip, model, space, levels)	Return the dressed eigenstate assigned to a label in the rows of an excitation space.

Classes

CompactState(values, space)	Keep a ket or density matrix without expanding its product coordinates.
LabelTargets(chip, approximation)	Prepare the label targets of one solve from a snapshot of its chip.

quchip.engine.states.bare_state_from_bases(chip, resolved, bases)

Build a product state from the shared local state preparation.

quchip.engine.states.bare_local_kets(chip, resolved, bases)

Resolve each local ket without allocating its tensor product.

quchip.engine.states.label_levels(chip, spec, dims, *, role='An initial label')

Return the product label of a level mapping or state shorthand, in device order.

Devices without a level are in level 0. A mapping that holds a local ket is not a label, and chip.bare_state takes it.

Parameters:

• chip (Chip) – Chip whose devices and state order read the label.

• spec (mapping or str) – Energy level of each named device, or a state shorthand.

• dims (sequence of int) – Level count of each device.

• role (str, optional) – Name of the label in error messages.

quchip.engine.states.label_state(chip, spec, result, start)

Return the dressed state of a label at the start of a solve, in the solve’s coordinates and frame.

The state is the eigenstate |d_k⟩ assigned to label k of the undriven static lab-frame model that result.approximation keeps, with real, nonnegative overlap on the bare product |k⟩, as chip.state() assigns it. Under an excitation cutoff the model is the truncated P H P. The frame map places the state at start as the label target of overlap(): U(start)†|d_k⟩ exp(−i 2π start Σᵢ fᵢ kᵢ). The labels of an uncoupled chip start in |k⟩ in every frame.

Parameters:

• chip (Chip) – Chip whose static model defines the state.

• spec (mapping, str, or None) – Level label. None is the all-ground label.

• result (EngineResult) – Solve contract with the frame, approximation, bases, and excitation space.

• start (scalar) – Start time of the solve, in ns.

Returns:

Native backend ket in the coordinates of the solve.

Return type:

state

quchip.engine.states.materialize_state_spec(chip, state_spec, bases)

Materialize one authored state specification in the engine’s solver basis.

Labels and an omitted state are dressed states, which label_state() prepares from the solve’s engine result.

class quchip.engine.states.CompactState(values, space)

Bases: object

Keep a ket or density matrix without expanding its product coordinates.

Create this value with chip.compact_state or result.compact_state. Pass it as initial_state to a later simulation of the same device bases. Numerical arrays are JAX pytree leaves.

Parameters:

• values (array_like) – Ket columns or density matrix in the captured excitation space.

• space (object) – Captured coordinate map, supplied by the state factory.

values: Any

space: PulseSpace

tree_flatten()

Return numerical leaves and immutable coordinate metadata for JAX.

classmethod tree_unflatten(metadata, leaves)

Restore a state from JAX’s coordinate metadata and numerical leaves.

Parameters:

• metadata (tuple) – Captured dimensions, labels, totals, and basis kinds.

• leaves (tuple) – State values and numerical basis arrays.

quchip.engine.states.compact_state(chip, *components, dressed=True)

Prepare a normalized state on the excitation totals of its components.

Parameters:

• chip (Chip) – Chip whose resolved energy bases define the coordinates.

• *components (mapping, str, or (amplitude, specification) pairs) – Energy-level labels, as in Chip.compact_state. With dressed=False, a mapping can also give a device a local ket.

• dressed (bool, default=True) – Use the static dressed eigenstate assigned to each label. False uses the bare product of each label.

Returns:

Captured state accepted as a pulse simulation’s initial_state.

Return type:

CompactState

quchip.engine.states.block_model(chip, approximation)

Return the static block model of approximation, or None when dressing needs the full eigensystem.

Under an excitation cutoff, every chip has a block model. Without one, the static model must conserve the total energy-level index.

Parameters:

• chip (Chip) – Chip whose static model is split.

• approximation (Approximation) – Approximation of the static model.

quchip.engine.states.sector_label_ket(chip, model, space, levels)

Return the dressed eigenstate assigned to a label in the rows of an excitation space.

The eigenvector comes from the block of model that holds the label. Rows of the block outside space are dropped, because the states of the solve have no amplitude there.

Parameters:

• chip (Chip) – Chip whose backend sets the array module.

• model (SectorModel) – Static block model of the solve’s approximation.

• space (PulseSpace) – Excitation space of the solve.

• levels (tuple of int) – Product label of local energy levels.

class quchip.engine.states.LabelTargets(chip, approximation)

Bases: object

Prepare the label targets of one solve from a snapshot of its chip.

capture() takes an isolated clone when the solve finishes, so later changes to the source chip do not change the targets. The clone runs its dressed analysis only when a dressed target is requested.

Parameters:

• chip (Chip) – Isolated clone of the solve’s chip.

• approximation (Approximation) – Approximation of the solve’s static model.

chip: Any

approximation: Any

classmethod capture(chip, approximation)

Record an isolated clone of a chip.

Parameters:

• chip (Chip) – Source chip of the solve.

• approximation (Approximation) – Approximation of the solve’s static model.

levels(spec, dims)

Return the product label of a mapping or state shorthand, in device order.

Parameters:

• spec (mapping or str) – Local energy level of each named device. Devices without a level are in level 0.

• dims (sequence of int) – Level count of each device.

bare(levels, bases, space=None)

Return the bare product state of a label, in solver coordinates or in the rows of space.

Parameters:

• levels (tuple of int) – Product label of local energy levels.

• bases (mapping) – Resolved basis record of each device.

• space (PulseSpace or None, optional) – Excitation space of the solve. A label outside it gives a zero vector.

dressed(levels, bases, space=None)

Return the lab-frame dressed eigenstate assigned to a label, as bare() places it.

The static model is the one that the solve’s approximation keeps. None means the all-ground label of a conserving model, whose bare product is the only state with total level 0.

Parameters:

• levels (tuple of int) – Product label of local energy levels.

• bases (mapping) – Resolved basis record of each device.

• space (PulseSpace or None, optional) – Excitation space of the solve.

energy(levels)

Return the energy in GHz of the dressed eigenstate that dressed() assigns to a label.

Parameters:

levels (tuple of int) – Product label of local energy levels.

quchip.engine.states.compatible_values(state, labels, dims, bases, backend)

Validate captured coordinates before interpreting a saved energy state.

quchip.engine.states.materialize_compact(chip, spec, space)

Prepare an initial state in the coordinates of an exact pulse space.

Parameters:

• chip (Chip) – Chip whose resolved energy bases define the state.

• spec (state_like or CompactState) – Initial state. label_state() prepares labels and an omitted state.

• space (PulseSpace) – Exact excitation space of the solve.

Returns:

Native backend ket or density matrix in space coordinates.

Return type:

state