pygsti.baseobjs.label

Defines the Label class

Module Contents

Classes

Label

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

LabelTup

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

LabelTupWithTime

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

LabelStr

A string-valued label.

LabelTupTup

A label consisting of a tuple of (string, state-space-labels) tuples.

LabelTupTupWithTime

A label consisting of a tuple of (string, state-space-labels) tuples.

CircuitLabel

A (sub-)circuit label.

LabelTupWithArgs

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

LabelTupTupWithArgs

A label consisting of a tuple of (string, state-space-labels) tuples.

class pygsti.baseobjs.label.Label

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

namestr

The item name. E.g., ‘CNOT’ or ‘H’.

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

timefloat

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

argsiterable 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,))

property depth

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

property reps

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

property has_nontrivial_components
collect_args()
strip_args()
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
tuple

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

class pygsti.baseobjs.label.LabelTup

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.

Initialize self. See help(type(self)) for accurate signature.

property time

This label’s name time (always 0)

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

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

property num_qubits

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

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

namestr

The item name. E.g., ‘CNOT’ or ‘H’.

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

Returns

LabelTup

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTup

is_simple()

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

Returns

bool

class pygsti.baseobjs.label.LabelTupWithTime

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.

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

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

property num_qubits

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

classmethod init(name, state_space_labels, time=0.0)

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

namestr

The item name. E.g., ‘CNOT’ or ‘H’.

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

timefloat

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

Returns

LabelTupWithTime

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTupWithTime

is_simple()

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

Returns

bool

class pygsti.baseobjs.label.LabelStr

Bases: Label, str

A string-valued label.

A Label for the special case when only a name is present (no state-space-labels). We create this as a separate class so that we can use the string hash function in a “hardcoded” way - if we put switching logic in __hash__ the hashing gets much slower.

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

An alias for sslbls, since commonly these are just qubit indices.

property num_qubits

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

classmethod init(name, time=0.0)

Creates a new Model-item label, which is just a simple string label.

Parameters

namestr

The item name. E.g., ‘CNOT’ or ‘H’.

timefloat

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

Returns

LabelStr

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

bool

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

str

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelStr

is_simple()

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

Returns

bool

class pygsti.baseobjs.label.LabelTupTup

Bases: Label, tuple

A label consisting of a tuple of (string, state-space-labels) tuples.

This typically labels a layer of a circuit (a parallel level of gates).

Initialize self. See help(type(self)) for accurate signature.

property time

This label’s name time (always 0)

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

An alias for sslbls, since commonly these are just qubit indices.

property num_qubits

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

property depth

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

classmethod init(tup_of_tups)

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_tupstuple

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

Returns

LabelTupTup

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

strip_args()

Return version of self with all arguments removed

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTupTup

is_simple()

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

Returns

bool

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

tuple

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

class pygsti.baseobjs.label.LabelTupTupWithTime

Bases: Label, tuple

A label consisting of a tuple of (string, state-space-labels) tuples.

This typically labels a layer of a circuit (a parallel level of gates).

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

An alias for sslbls, since commonly these are just qubit indices.

property num_qubits

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

property depth

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

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_tupstuple

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

timefloat, optional

A time value associated with this label. Often this is the duration of the object or operation labeled.

Returns

LabelTupTupWithTime

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

strip_args()

Return version of self with all arguments removed

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTupTupWithTime

is_simple()

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

Returns

bool

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

tuple

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

class pygsti.baseobjs.label.CircuitLabel

Bases: Label, 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)

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property reps

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

abstract property args

This label’s arguments.

property components

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

property qubits

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

property num_qubits

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

property depth

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

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

CircuitLabel

abstract strip_args()
to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

CircuitLabel

is_simple()

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

Returns

bool

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

tuple

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

class pygsti.baseobjs.label.LabelTupWithArgs

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. This label type also supports having arguments and a time value.

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

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

property num_qubits

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

classmethod init(name, state_space_labels, time=0.0, args=())

Creates a new Model-item label.

The created is divided into a simple string label, a tuple specifying the part of the Hilbert space upon which the item acts (often just qubit indices), a time, and arguments.

Parameters

namestr

The item name. E.g., ‘CNOT’ or ‘H’.

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

timefloat

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

argsiterable of hashable types

A list of “arguments” for this label.

Returns

LabelTupWithArgs

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

strip_args()
to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replacename(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTupWithArgs

is_simple()

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

Returns

bool

class pygsti.baseobjs.label.LabelTupTupWithArgs

Bases: Label, tuple

A label consisting of a tuple of (string, state-space-labels) tuples.

This typically labels a layer of a circuit (a parallel level of gates). This label type also supports having arguments and a time value.

Initialize self. See help(type(self)) for accurate signature.

property name

This label’s name (a string).

property sslbls

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

property args

This label’s arguments.

property components

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

property qubits

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

property num_qubits

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

property depth

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

classmethod init(tup_of_tups, time=None, args=())

Creates a new Model-item label.

The created label 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_tupstuple

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

timefloat

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

argsiterable of hashable types

A list of “arguments” for this label.

Returns

LabelTupTupWithArgs

has_prefix(prefix, typ='all')

Whether this label has the given prefix.

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

Parameters

prefixstr

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.

Returns

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

mapperdict 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

Label

strip_args()

Return version of self with all arguments removed

to_native()

Returns this label as native python types.

Useful for faster serialization.

Returns

tuple

replace_name(oldname, newname)

Returns a label with oldname replaced by newname.

Parameters

oldnamestr

Name to find.

newnamestr

Name to replace found name with.

Returns

LabelTupTupWithArgs

is_simple()

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

Returns

bool