pygsti.baseobjs.label.CircuitLabel

class CircuitLabel(name, tup_of_layers, state_space_labels, reps=1, time=None)

Bases: LabelTupTupWithTime, tuple

A (sub-)circuit label.

This class encapsulates a complete circuit as a single layer. It lacks some of the methods and metadata of a true Circuit object, but contains the essentials: the tuple of layer labels (held as the label’s components) and line labels (held as the label’s state-space labels)

Creates a new Model-item label, which defines a set of other labels as a sub-circuit and allows that sub-circuit to be repeated some integer number of times. A CircuitLabel can be visualized as placing a (named) box around some set of labels and optionally exponentiating that box.

Internally, a circuit labels look very similar to LabelTupTup objects, holding a tuple of tuples defining the component labels (circuit layers).

Parameters:

• name (str) – The name of the sub-circuit (box). Cannot be None, but can be empty.

• tup_of_layers (tuple) – The item data - a tuple of tuples which label the components (layers) within this label.

• 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.

• reps (int, optional) – The “exponent” - the number of times the tup_of_layers labels are repeated.

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

Return type:

CircuitLabel

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(tup_of_tups[, time])	Creates a new Model-item tuple-of-tuples 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 version of self with all arguments removed
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	Whether the internal labels are sorted in increasing qubit order.
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).
time	The time value associated with this label.

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(tup_of_tups, time=None)

Creates a new Model-item tuple-of-tuples label.

This is a tuple of tuples of simple string labels and tuples specifying the part of the Hilbert space upon which that item acts (often just qubit indices).

Parameters:

• tup_of_tups (tuple) – The item data - a tuple of (string, state-space-labels) tuples which labels a parallel layer/level of a circuit.

• time (float, optional) – A time value associated with this label. Often this is the duration of the object or operation labeled.

Return type:

LabelTupTupWithTime

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:

CircuitLabel

strip_args()

Return version of self with all arguments removed

Return type:

None

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 | LabelTupWithArgs | LabelTupWithTime | LabelTupTup | LabelTupTupWithArgs | LabelTupTupWithTime | LabelStr | CircuitLabel, ...]

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: bool

Whether the internal labels are sorted in increasing qubit order.

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).

property time: float

The time value associated with this label.