quchip.chip.states

Bare states, dressed eigenstates, and normalized superpositions for chips.

String shorthand such as "eg1" uses the device order and level symbols that set_state_order() sets. Dressed-state selection uses the assigned eigenvector column and stays JAX-traceable on a fixed assignment.

Functions

bare_state(chip, *components, ...)	Product state, or normalized superposition of product states, from energy levels or local kets.
copy_state_configuration(source, target)	Keep the relative string-state order and symbols on surviving devices.
normalize_device_state_mapping(chip, ...)	Normalize a mapping or string state specification to device-label keys.
parse_state_string(chip, s)	Parse chip.bare_state("eg1") style strings into {label: index}.
set_state_order(chip, *devices[, levels])	Declare the device order that parses string-state shorthands.
superposition(chip, *components)	Normalized superposition of the dressed states of level labels.

quchip.chip.states.set_state_order(chip, *devices, levels=None)

Declare the device order that parses string-state shorthands.

After this call, Chip.bare_state(), Chip.state(), and Chip.superposition() accept single-string specifications. In these strings, each character is one level per device, in devices order. Level symbols default to g=0, e=1, f=2, h=3. The digits 0..9 are always accepted as energy-level indices.

Every chip device must be named exactly once.

Examples

>>> from quchip import DuffingTransmon, Resonator, Chip
>>> qb = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="qb")
>>> tc = DuffingTransmon(freq=5.5, anharmonicity=-0.20, levels=3, label="tc")
>>> cr = Resonator(freq=7.0, levels=4, label="cr")
>>> chip = Chip([qb, tc, cr])
>>> chip.set_state_order(qb, tc, cr)
>>> _ = chip.bare_state("eg1")  # {qb: 1, tc: 0, cr: 1}

quchip.chip.states.copy_state_configuration(source, target)

Keep the relative string-state order and symbols on surviving devices.

quchip.chip.states.parse_state_string(chip, s)

Parse chip.bare_state("eg1") style strings into {label: index}.

quchip.chip.states.normalize_device_state_mapping(chip, device_states, keyword_states)

Normalize a mapping or string state specification to device-label keys.

Parse strings with the chip’s declared state order. Reject unsupported input types and duplicate device specifications across the mapping and keywords.

quchip.chip.states.superposition(chip, *components)

Normalized superposition of the dressed states of level labels.

Each component is a level label or an (amplitude, label) pair. A label is a dict keyed by device or label, or a string after you call set_state_order(), and names the dressed state that state() returns. The weights are uniform by default, and the result is normalized to unit norm. bare_state() takes the same components for a superposition of bare products.

Examples

>>> import numpy as np
>>> from quchip import DuffingTransmon, Resonator, Chip
>>> qb = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="qb")
>>> cr = Resonator(freq=7.0, levels=4, label="cr")
>>> chip = Chip([qb, cr])
>>> _ = chip.superposition({qb: 0}, {qb: 1})  # equal |00> + |10>
>>> _ = chip.superposition(                   # weighted mix
...     (np.sqrt(0.3), {qb: 1, cr: 0}),
...     (np.sqrt(0.7), {qb: 1, cr: 1}),
... )

quchip.chip.states.bare_state(chip, *components, **device_state_kwargs)

Product state, or normalized superposition of product states, from energy levels or local kets.

You can specify each device as an energy-level index (int) or as a ket vector in that device’s authored local space. Unmentioned devices default to the ground state (level 0). Unlike state(), this function does not diagonalize the coupled system.

One mapping or string, keywords, or both give one product state. Several components, or (amplitude, specification) pairs, give the normalized superposition of their products, as superposition() combines dressed states. Accepts a string shorthand (for example "eg1") after you call set_state_order().

Inside jax.jit, a state that depends on no traced value stays a constant, so a solve can read its excitation support.