pygsti.models.stencillabel

Stencil label classes and supporting functions.

Module Contents

Classes

StencilLabel

A generalization of a simple tuple of state space labels.

StencilLabelTuple

A stencil label that is a single state space label tuple.

StencilLabelSet

A stencil label that is explicitly a set of multiple state space label tuples.

StencilLabelAllCombos

A stencil label that expands into all the length-k combinations of a larger set of state space labels.

StencilLabelRadiusCombos

A stencil label specifying all length-k combinations of the labels within a radius of some "base" label(s).

class pygsti.models.stencillabel.StencilLabel(local_state_space=None)

Bases: object

A generalization of a simple tuple of state space labels.

A StencilLabel can be a simple tuple of absolute state space labels, but it can also contain special labels identifying the target labels of a gate (@<int>) and qubit-graph directions relative to target labels, e.g. @0+left. Furthermore, a stencil label can expand into multiple state-space label tuples, e.g. the 2-tuples of all the qubit-graph edges.

Parameters

local_state_space (StateSpace) – A manually supplied local state space for this label, which is returned by :method:`create_local_state_space` instead of generating a local state space.

classmethod cast(cls, obj)

Convert an object into a stencil label if it isn’t already.

Parameters

obj (object) – The object to convert.

Returns

StencilLabel

_resolve_single_sslbls_tuple(self, sslbls, qubit_graph, state_space, target_lbls)
abstract compute_absolute_sslbls(self, qubit_graph, state_space, target_lbls)

Creates a list of all the state space label tuples this stencil label expands into.

To perform the expansion, the qubit graph of the relevant processor is required, along with the target state space labels, which determine where the stencil is placed on the qubit graph. The returned list of tuples contains absolute state space labels, meaning that they are labels in state_space and do not use any special directives.

Parameters
  • qubit_graph (QubitGraph) – The qubit graph of the relevant processor, used to resolve any special stencil labels.

  • state_space (StateSpace) – The state space for the entire processor. This specifies what the state space labels are.

  • target_lbls (tuple) – The target state space labels, specifying where the stencil is placed on the qubit graph before being expanded into absolute state space labels.

Returns

list – The state space label tuples this stencil label expands into, e.g. [(‘Q0’,’Q1’), (‘Q1’,’Q2’)].

create_local_state_space(self, entire_state_space)

Creates a “local” state space for an operator indexed using this stencil label.

When creating operator objects, a stencil label specifies where to place (embed) operators on some subset of the entire space. When these to-be-embedded operations are constructed, they need to be supplied with a state space that just corresponds to the sub-space where they act – a “local” state space. A stencil label expands into one or more state space label tuples, and this function constructs a single local state space that is appropriate for any and all of these tuples (i.e. what is returned by :method:`compute_absolute_sslbls`), and that is therefore appropriate for constructing the to-be-embedded operation. Importantly, this function can be called without knowing where this stencil label will be placed, that is, it doesn’t require a “target labels” argument.

Parameters

entire_state_space (StateSpace) – The entire state space of the relevant processor, specifying the state space labels and information about them.

Returns

StateSpace

abstract _create_local_state_space(self, entire_state_space)

Stub that derived classes implement - same function as :method:`create_local_state_space`

_create_local_state_space_for_sslbls(self, sslbls, entire_state_space)

A helper function for derived class implementations of _create_local_state_space(…)

Constructs a sub-space of a large state space corresponding to a subset (sslbls) of the large state space’s labels. We call this the “local” state space for these labels. It’s possible that sslbls contains special stencil labels, e.g. “@0”, and in this case the entire state space must have labels with similar dimensions so it only matters how many labels (not which ones specifically) a local space is needed for.

class pygsti.models.stencillabel.StencilLabelTuple(stencil_sslbls)

Bases: StencilLabel

A stencil label that is a single state space label tuple.

This is the simplest type of stencil labels, and almost the same as just a tuple of state space labels. It may contain, however, special stencil directives like ‘@<num>’ and direction labels.

Parameters

stencil_sslbls (tuple) – A tuple of state space labels. May contain special stencil directives.

compute_absolute_sslbls(self, qubit_graph, state_space, target_lbls)

Creates a list of all the state space label tuples this stencil label expands into.

See :method:`StencilLabel.compute_absolute_sslbls`

_create_local_state_space(self, entire_state_space)

Stub that derived classes implement - same function as :method:`create_local_state_space`

__str__(self)

Return str(self).

class pygsti.models.stencillabel.StencilLabelSet(stencil_sslbls_set)

Bases: StencilLabel

A stencil label that is explicitly a set of multiple state space label tuples.

A StencilLabelSet stencil label simply expands into the list/set of state space label tuples used to construct it. It may contain special stencil directives, and is essentially just a list or tuple of StencilLabelTuple objects.

Parameters

stencil_sslbls_set (list or tuple or set) – A collection of the individual state space label tuples that this stencil label expands into. May contain special stencil directives.

compute_absolute_sslbls(self, qubit_graph, state_space, target_lbls)

Creates a list of all the state space label tuples this stencil label expands into.

See :method:`StencilLabel.compute_absolute_sslbls`

_create_local_state_space(self, entire_state_space)

Stub that derived classes implement - same function as :method:`create_local_state_space`

__str__(self)

Return str(self).

class pygsti.models.stencillabel.StencilLabelAllCombos(possible_sslbls, num_to_choose, connected=False)

Bases: StencilLabel

A stencil label that expands into all the length-k combinations of a larger set of state space labels.

For example, if num_to_choose = 2 and possible_sslbls = [1,2,3] then this stencil label would expand into the pairs: [(1,2), (2,3), (1,3)]. Optionally, the tuples can be restricted to only those that form a connected sub-graph of the qubit graph (eliminating (1,3) in our example if the qubits were in a 1-2-3 chain).

Parameters
  • possible_sslbls (list or tuple) – The set of possible state space labels to take combinations of.

  • num_to_choose (int) – The number of possible state space labels to choose when forming each state space label tuple.

  • connected (bool, optional) – If True, restrict combinations to those that form a connected subgraph of the qubit graph.

compute_absolute_sslbls(self, qubit_graph, state_space, target_lbls)

Creates a list of all the state space label tuples this stencil label expands into.

See :method:`StencilLabel.compute_absolute_sslbls`

_create_local_state_space(self, entire_state_space)

Stub that derived classes implement - same function as :method:`create_local_state_space`

__str__(self)

Return str(self).

class pygsti.models.stencillabel.StencilLabelRadiusCombos(base_sslbls, radius, num_to_choose, connected=False)

Bases: StencilLabel

A stencil label specifying all length-k combinations of the labels within a radius of some “base” label(s).

This stencil label depends heavily on the qubit graph. It expands to all length-num_to_choose combinations of the qubit graphy nodes (state space labels) that lie within radius edge traversals of any of the node labels in base_sslbls. If connected=True then the combinations are further filtered so that they must form connected subgraphs of the qubit graph.

Parameters

base_sslbls (tuple) – The state space labels that form the “center” of the possible labels

radiusint

The maximum number of edge traversals (along the qubit graph) used to define the “radius” of labels about the base labels.

num_to_chooseint

The number of possible state space labels in each combination of the labels within the radius of possible labels. This stencil label expands into potentially many state space label tuples all of this length.

connectedbool, optional

If True, restrict combinations to those that form a connected subgraph of the qubit graph.

compute_absolute_sslbls(self, qubit_graph, state_space, target_lbls)

Creates a list of all the state space label tuples this stencil label expands into.

See :method:`StencilLabel.compute_absolute_sslbls`

_create_local_state_space(self, entire_state_space)

Stub that derived classes implement - same function as :method:`create_local_state_space`

__str__(self)

Return str(self).