pygsti.baseobjs.label.Label

class Label(name, state_space_labels=None, time=None, args=None)

Bases: object

A label used to identify a gate, circuit layer, or (sub-)circuit.

A label consisting of a string along with a tuple of integers or sector-names specifying which qubits, or more generally, parts of the Hilbert space that is acted upon by an object so-labeled.

Creates a new Model-item label, which is divided into a simple string label and a tuple specifying the part of the Hilbert space upon which the item acts (often just qubit indices).

Parameters:

• name (str) – The item name. E.g., ‘CNOT’ or ‘H’.

• state_space_labels (list or tuple, optional) – A list or tuple that identifies which sectors/parts of the Hilbert space is acted upon. In many cases, this is a list of integers specifying the qubits on which a gate acts, when the ordering in the list defines the ‘direction’ of the gate. If something other than a list or tuple is passed, a single-element tuple is created containing the passed object.

• time (float) – The time at which this label occurs (can be relative or absolute)

• args (iterable of hashable types, optional) – A list of “arguments” for this label. Having arguments makes the Label even more resemble a function call, and supplies parameters for the object (often a gate or layer operation) being labeled that are fixed at circuit-creation time (i.e. are not optimized over). For example, the angle of a continuously-variable X-rotation gate could be an argument of a gate label, and one might create a label: Label(‘Gx’, (0,), args=(pi/3,))

Return type:

ConcreteLabel

Methods

__init__()
collect_args()	Gather all of the arguments of the components including this Label's arguments.
concat(other)	Combine two labels together so that they are one label which could be a single layer.
copy()
expand_subcircuits()	Expand any sub-circuits within this label.
has_prefix(prefix[, typ])	Whether this label has the given prefix.
map_state_space_labels(mapper)	Apply a mapping to this Label's state-space (qubit) labels.
replace_name(oldname, newname)
strip_args()	Return a Label which does not include the arguments.
to_native()	Returns this label as native python types.
with_sorted_inner_labels()	Returns self if either (1) we aren't a LabelTupTup or (2) we are a LabelTupTup, but one or more inner Label objects have sslbls == None.

Attributes

IS_SIMPLE
args
components
depth	The depth of this label, viewed as a sub-circuit.
has_nontrivial_components	Checks if this Label may be used to store other `Label`s.
is_simple	Whether this is a "simple" (opaque w/a true name, from a circuit perspective) label or not.
is_sorted	Whether the internal labels are sorted in increasing qubit order.
name
num_qubits	The number of qubits this label "acts" on (an integer).
qubits	An alias for sslbls, since commonly these are just qubit indices.
reps	Number of repetitions (of this label's components) that this label represents.
sslbls

collect_args()

Gather all of the arguments of the components including this Label’s arguments.

Return type:

tuple

concat(other)

Combine two labels together so that they are one label which could be a single layer.

Parameters:

other (Label)

expand_subcircuits()

Expand any sub-circuits within this label.

Returns a list of component labels which doesn’t include any CircuitLabel labels. This effectively expands any “boxes” or “exponentiation” within this label.

Returns:

A tuple of component Labels (none of which should be CircuitLabel objects).

Return type:

tuple

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

Usually used to test whether the label names a given type.

Parameters:

• prefix (str) – The prefix to check for.

• typ ({"any","all"}) – Whether, when there are multiple parts to the label, the prefix must occur in any or all of the parts.

Return type:

bool

map_state_space_labels(mapper)

Apply a mapping to this Label’s state-space (qubit) labels.

Return a copy of this Label with all of the state-space labels (often just qubit labels) updated according to a mapping function.

For example, calling this function with mapper = {0: 1, 1: 3} on the Label “Gcnot:0:1” would return “Gcnot:1:3”.

Parameters:

mapper (dict or function) – A dictionary whose keys are the existing state-space-label values and whose value are the new labels, or a function which takes a single (existing state-space-label) argument and returns a new state-space-label.

Returns:

A new label of the same concrete type as self (e.g. a LabelTup returns a LabelTup).

Return type:

Label

strip_args()

Return a Label which does not include the arguments.

to_native()

Returns this label as native python types.

Useful for faster serialization. The returned value is guaranteed to be roundtrippable back through the Label constructor, satisfying: Label(lbl.to_native()) == lbl.

Returns:

The native representation of this label (e.g., a string or a tuple of native types).

Return type:

NativeLabel

with_sorted_inner_labels()

Returns self if either (1) we aren’t a LabelTupTup or (2) we are a LabelTupTup, but one or more inner Label objects have sslbls == None.

In all other situations, we return a LabelTupTup whose inner labels are sorted according to their sslbls. This may raise an error if any of the sslbls are not comparable to one another.

Note that we are sorting in increasing order of the first qubit that the label acts on and respect the order of the sslbls for each label.

Return type:

LabelTup | LabelTupWithArgs | LabelTupWithTime | LabelTupTup | LabelTupTupWithArgs | LabelTupTupWithTime | LabelStr | CircuitLabel

property depth: int

The depth of this label, viewed as a sub-circuit.

property has_nontrivial_components: bool

Checks if this Label may be used to store other `Label`s.

property is_simple: bool

Whether this is a “simple” (opaque w/a true name, from a circuit perspective) label or not.

property is_sorted: bool

Whether the internal labels are sorted in increasing qubit order.

property num_qubits: int | None

The number of qubits this label “acts” on (an integer). None if self.ssbls is None.

property qubits: tuple[str | Integral | int, ...] | None

An alias for sslbls, since commonly these are just qubit indices. (a tuple)

property reps: int

Number of repetitions (of this label’s components) that this label represents.