pygsti.baseobjs.label.LabelTup

class LabelTup(iterable=(), /)

Bases: Label, tuple

A label consisting of a string along with a tuple of integers or state-space-names.

These state-space sector names specify which qubits, or more generally, parts of the Hilbert space that is acted upon by the object this label refers to.

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()
count(value, /)	Return number of occurrences of value.
expand_subcircuits()	Expand any sub-circuits within this label.
has_prefix(prefix[, typ])	Whether this label has the given prefix.
index(value[, start, stop])	Return first index of value.
init(name, state_space_labels)	Creates a new Model-item label.
map_state_space_labels(mapper)	Apply a mapping to this Label's state-space (qubit) labels.
replace_name(oldname, newname)	Returns a label with oldname replaced by 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	This label's arguments.
components	The sub-label components of this label, or just (self,) if no sub-labels exist.
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	There is only ever one gate recognized by this label.
name	This label's name (a string).
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	This label's state-space labels, often qubit labels (a tuple).

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)

count(value, /)

Return number of occurrences of value.

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

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

classmethod init(name, state_space_labels)

Creates a new Model-item label.

The created label is comprised of 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) – 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.

Return type:

LabelTup

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

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters:

• oldname (str) – Name to find.

• newname (str) – Name to replace found name with.

Return type:

LabelTup

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 args: tuple

This label’s arguments.

property components: tuple[LabelTup]

The sub-label components of this label, or just (self,) if no sub-labels exist.

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: Literal[True]

There is only ever one gate recognized by this label.

property name: str

This label’s name (a string).

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.

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

This label’s state-space labels, often qubit labels (a tuple).