pygsti.models.modelnoise

Objects for specifying the noise to be added to models when they are created.

Module Contents

Classes

ModelNoise

A base class for objects specifying noise (errors) that should be added to a quantum processor model.

OpModelNoise

Noise on a model containing individual gate/SPAM operations, e.g. an OpModel object.

OpModelPerOpNoise

Model noise that is stored on a per-operation basis.

ComposedOpModelNoise

Op-model noise that is specified simply as the composition of other op-model noise specifications.

OpNoise

Specification for a single noise operation.

DepolarizationNoise

Depolarization noise.

StochasticNoise

Pauli stochastic noise.

LindbladNoise

Noise generated by exponentiating a Lindbladian error generator.

class pygsti.models.modelnoise.ModelNoise

Bases: object

A base class for objects specifying noise (errors) that should be added to a quantum processor model.

ModelNoise objects serve as a lightweight and flexible way to specify the noise that should be included in a model prior to its creation. Typically these objects, which can contain complex prescriptions for model noise, are constructed and then passed as input to a model construction routine.

class pygsti.models.modelnoise.OpModelNoise

Bases: ModelNoise

Noise on a model containing individual gate/SPAM operations, e.g. an OpModel object.

This class is a base class that should not be instantiated directly.

classmethod cast(cls, obj)

Convert an object to an OpModelNoise object if it isn’t already.

If a dictionary is given, it is assumed to contain per-operation error specifications. If a list/tuple is given, it is assumed to contain multiple sub-specifications that should be composed together (by constructing a ComposedOpModelNoise object).

Parameters

obj (object) – The object to convert.

Returns

OpModelNoise

abstract keys(self)

The operation labels for which this object specifies noise.

abstract __contains__(self, key)
abstract create_errorgen_stencil(self, opkey, evotype, state_space, num_target_labels=None)

Create an “error generator stencil” for the noise corresponding to an operation label.

A stencil is one or more operator objects that have yet to be embedded on their final qubits and then composed. The embedding and composing step is done later so that, if desired, the same errors can be used on multiple sets of target qubits (often this is done when a “independent” argument to a model-creation function is False). An “error generator stencil” is a stencil whose operators are error generators, rather than error maps.

Parameters
  • opkey (Label or StencilLabel) – The operation label to create the stencil for.

  • evotype (str or Evotype) – The evolution type of to use when creating the stencil operators.

  • state_space (StateSpace) – The state space to use when creating the stencil operators. This can be a local state space, disparate from the actual processor’s state space, or the entire state space that the stencil operations will ultimately be embedded into. In the former case, num_target_labels should be left as None, indicating that state_space is the exact space being acted upon. In the latter case, num_target_labels should specify the number of target labels within state_space that this stencil will be given when it is applied (embedded) into state_space. This requires that all the labels in state_space correspond to the same type and dimension space (e.g. all are qubit spaces).

  • num_target_labels (int or None) – The number of labels within state_space that the op_key operation acts upon (this assumes that all the labels in state_space are similar, e.g., all qubits). If None then it acts on the entire space given by state_space.

Returns

stencil (OrderedDict) – A dictionary with keys that are Label or StencilLabel objects and values that are LinearOperator objects. The stencil is applied by embedding each operator according to its key and then composing the results.

abstract apply_errorgen_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

Apply an error-generator stencil created by this object to a specific set of target labels.

A stencil is applied by embedding each operator in the stencil according to its target state space labels (which may include stencil-label expansions) and then composing the results.

Parameters
  • stencil (OrderedDict) – The stencil to apply, usually created by :method:`create_errorgen_stencil`.

  • evotype (str or Evotype) – The evolution type of to use when creating the embedded and composed operators, which should match that of the stencil operators (the evotype used to create the stencil).

  • state_space (StateSpace) – The state space to use when creating the composed and embedded operators. This should be the total state space of the model that these noise operations will be inserted into.

  • target_labels (tuple or None, optional) – The target labels that determine where on the qubit graph this stencil will be placed. When a tuple, it should have length equal to the num_target_labels argument passed to :method:`create_errorgen_stencil`. None indicates that the entire space is the “target” space of the stencil (e.g. a global idle, preparation, or measurement).

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph, usually from a processor specification, that contains adjacency and direction information used to resolve stencil state space labels into absolute labels within state_space. If None, then an error will be raised if any direction or connectivity information is needed to resolve the state space labels.

  • copy (bool, optional) – Whether the stencil operations should be copied before embedding and composing them to apply the stencil. True can be used to make different applications of the stencil independent operations.

Returns

LinearOperator

create_errorgen(self, opkey, evotype, state_space, target_labels=None, qubit_graph=None)

Create an error generator object to implement the noise on a given model operation.

Parameters
  • opkey (Label or StencilLabel) – The operation label to create the error generator for.

  • evotype (str or Evotype) – The evolution type to use when creating the error generator.

  • state_space (StateSpace) – The state space to use when creating the error generator.

  • target_labels (tuple or None, optional) – The target state space labels for this operation. Sometimes this is also contained in opkey, but not always, so it must be supplied as a separate argument.

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph, usually from a processor specification, that contains adjacency and direction information used to create more complex types of errors. If None, then an error will be raised if graph information is needed.

Returns

LinearOperator

abstract create_errormap_stencil(self, opkey, evotype, state_space, num_target_labels=None)

Create an “error map stencil” for the noise corresponding to an operation label.

A stencil is one or more operator objects that have yet to be embedded on their final qubits and then composed. The embedding and composing step is done later so that, if desired, the same errors can be used on multiple sets of target qubits (often this is done when a “independent” argument to a model-creation function is False). An “error map stencil” is a stencil whose operators are error maps

rather than error generators.

Parameters
  • opkey (Label or StencilLabel) – The operation label to create the stencil for.

  • evotype (str or Evotype) – The evolution type of to use when creating the stencil operators.

  • state_space (StateSpace) – The state space to use when creating the stencil operators. This can be a local state space, disparate from the actual processor’s state space, or the entire state space that the stencil operations will ultimately be embedded into. In the former case, num_target_labels should be left as None, indicating that state_space is the exact space being acted upon. In the latter case, num_target_labels should specify the number of target labels within state_space that this stencil will be given when it is applied (embedded) into state_space. This requires that all the labels in state_space correspond to the same type and dimension space (e.g. all are qubit spaces).

  • num_target_labels (int or None) – The number of labels within state_space that the op_key operation acts upon (this assumes that all the labels in state_space are similar, e.g., all qubits). If None then it acts on the entire space given by state_space.

Returns

stencil (OrderedDict) – A dictionary with keys that are Label or StencilLabel objects and values that are LinearOperator objects. The stencil is applied by embedding each operator according to its key and then composing the results.

abstract apply_errormap_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

Apply an error-map stencil created by this object to a specific set of target labels.

A stencil is applied by embedding each operator in the stencil according to its target state space labels (which may include stencil-label expansions) and then composing the results.

Parameters
  • stencil (OrderedDict) – The stencil to apply, usually created by :method:`create_errormap_stencil`.

  • evotype (str or Evotype) – The evolution type of to use when creating the embedded and composed operators, which should match that of the stencil operators (the evotype used to create the stencil).

  • state_space (StateSpace) – The state space to use when creating the composed and embedded operators. This should be the total state space of the model that these noise operations will be inserted into.

  • target_labels (tuple or None, optional) – The target labels that determine where on the qubit graph this stencil will be placed. When a tuple, it should have length equal to the num_target_labels argument passed to :method:`create_errormap_stencil`. None indicates that the entire space is the “target” space of the stencil (e.g. a global idle, preparation, or measurement).

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph, usually from a processor specification, that contains adjacency and direction information used to resolve stencil state space labels into absolute labels within state_space. If None, then an error will be raised if any direction or connectivity information is needed to resolve the state space labels.

  • copy (bool, optional) – Whether the stencil operations should be copied before embedding and composing them to apply the stencil. True can be used to make different applications of the stencil independent operations.

Returns

LinearOperator

create_errormap(self, opkey, evotype, state_space, target_labels=None, qubit_graph=None)

Create an error map object to implement the noise on a given model operation.

Parameters
  • opkey (Label or StencilLabel) – The operation label to create the error map for.

  • evotype (str or Evotype) – The evolution type to use when creating the error map.

  • state_space (StateSpace) – The state space to use when creating the error map.

  • target_labels (tuple or None, optional) – The target state space labels for this operation. Sometimes this is also contained in opkey, but not always, so it must be supplied as a separate argument.

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph, usually from a processor specification, that contains adjacency and direction information used to create more complex types of errors. If None, then an error will be raised if graph information is needed.

Returns

LinearOperator

reset_access_counters(self)

Resets the internal key-access counters to zero.

These counters tally the number of times each operation key is accessed, and are used to identify model noise specification that are supplied by the user but never used. See :method:`warn_about_zero_counters`.

Returns

None

_increment_touch_count(self, opkey)
warn_about_zero_counters(self)

Issue a warning if any of the internal key-access counters are zero

Used to catch noise specifications that are never utilized and that the caller/user should be warned about.

Returns

None

abstract compute_stencil_absolute_sslbls(self, stencil, state_space, target_labels=None, qubit_graph=None)

Computes the set of state space labels that would be utilized when applying a stencil.

This function computes which state space labels are non-trivially acted upon by the operation that results from applying stencil to target_labels.

Parameters
  • stencil (OrderedDict) – The stencil. A dictionary with keys that are target state space labels (perhaps stencil labels) and values that are operations. This function only cares about the keys of this dictionary.

  • state_space (StateSpace) – The state space that would be given if/when applying stencil. This should be the total state space of the model that the applied stencil would be inserted into.

  • target_labels (tuple or None, optional) – The target labels that determine where on the qubit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph that contains adjacency and direction information used to resolve stencil state space labels into absolute labels within state_space. If None, then an error will be raised if any direction or connectivity information is needed to resolve the state space labels.

Returns

set – A set (i.e. without any duplicates) of the state space labels that would be acted upon.

class pygsti.models.modelnoise.OpModelPerOpNoise(per_op_noise)

Bases: OpModelNoise

Model noise that is stored on a per-operation basis.

Parameters

per_op_noise (dict) – A dictionary mapping operation labels (which will become the keys of this OpModelNoise object) to either OpNoise objects or to a nexted dictionary mapping absolute or stencil state space labels to OpNoise objects. In the former case, the OpNoise object is assumed to apply to all the target labels of the operation.

keys(self)

The operation labels for which this object specifies noise.

__contains__(self, key)
create_errorgen_stencil(self, opkey, evotype, state_space, num_target_labels=None)

See :method:`OpModelNoise.create_errorgen_stencil`.

apply_errorgen_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

See :method:`OpModelNoise.apply_errorgen_stencil`.

create_errormap_stencil(self, opkey, evotype, state_space, num_target_labels=None)

See :method:`OpModelNoise.create_errormap_stencil`.

apply_errormap_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

See :method:`OpModelNoise.apply_errormap_stencil`.

_map_stencil_sslbls(self, stencil_sslbls, qubit_graph, state_space, target_lbls)
compute_stencil_absolute_sslbls(self, stencil, state_space, target_labels=None, qubit_graph=None)

Computes the set of state space labels that would be utilized when applying a stencil.

This function computes which state space labels are non-trivially acted upon by the operation that results from applying stencil to target_labels.

Parameters
  • stencil (OrderedDict) – The stencil. A dictionary with keys that are target state space labels (perhaps stencil labels) and values that are operations. This function only cares about the keys of this dictionary.

  • state_space (StateSpace) – The state space that would be given if/when applying stencil. This should be the total state space of the model that the applied stencil would be inserted into.

  • target_labels (tuple or None, optional) – The target labels that determine where on the qubit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph that contains adjacency and direction information used to resolve stencil state space labels into absolute labels within state_space. If None, then an error will be raised if any direction or connectivity information is needed to resolve the state space labels.

Returns

set – A set (i.e. without any duplicates) of the state space labels that would be acted upon.

_key_to_str(self, key, prefix='')
__str__(self)

Return str(self).

class pygsti.models.modelnoise.ComposedOpModelNoise(opmodelnoises)

Bases: OpModelNoise

Op-model noise that is specified simply as the composition of other op-model noise specifications.

Parameters

opmodelnoises (iterable) – The sub- OpModelNoise objects.

ensure_no_duplicates(self)

Raise an AssertionError if there are any duplicates among the composed noise specifications.

Returns

None

keys(self)

The operation labels for which this object specifies noise.

__contains__(self, key)
create_errorgen_stencil(self, opkey, evotype, state_space, num_target_labels=None)

See :method:`OpModelNoise.create_errorgen_stencil`.

apply_errorgen_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

See :method:`OpModelNoise.apply_errorgen_stencil`.

create_errormap_stencil(self, opkey, evotype, state_space, num_target_labels=None)

See :method:`OpModelNoise.create_errormap_stencil`.

apply_errormap_stencil(self, stencil, evotype, state_space, target_labels=None, qubit_graph=None, copy=False)

See :method:`OpModelNoise.apply_errormap_stencil`.

compute_stencil_absolute_sslbls(self, stencil, state_space, target_labels=None, qubit_graph=None)

Computes the set of state space labels that would be utilized when applying a stencil.

This function computes which state space labels are non-trivially acted upon by the operation that results from applying stencil to target_labels.

Parameters
  • stencil (OrderedDict) – The stencil. A dictionary with keys that are target state space labels (perhaps stencil labels) and values that are operations. This function only cares about the keys of this dictionary.

  • state_space (StateSpace) – The state space that would be given if/when applying stencil. This should be the total state space of the model that the applied stencil would be inserted into.

  • target_labels (tuple or None, optional) – The target labels that determine where on the qubit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.

  • qubit_graph (QubitGraph, optional) – The relevant qubit graph that contains adjacency and direction information used to resolve stencil state space labels into absolute labels within state_space. If None, then an error will be raised if any direction or connectivity information is needed to resolve the state space labels.

Returns

set – A set (i.e. without any duplicates) of the state space labels that would be acted upon.

_key_to_str(self, key, prefix='')
__str__(self)

Return str(self).

class pygsti.models.modelnoise.OpNoise

Bases: object

Specification for a single noise operation.

An OpNoise object specifies a single noisy operation that acts on some state space (e.g. number of qubits). This specification doesn’t contain any information about embedding this noise operation somewhere within a larger space – it just specifies a noise operation on a local space. This removes significant complexity from OpNoise objects, and provides upstream objects like OpModelNoise a common interface for working with all types of noisy operations.

__str__(self)

Return str(self).

class pygsti.models.modelnoise.DepolarizationNoise(depolarization_rate, parameterization='depolarize')

Bases: OpNoise

Depolarization noise.

Parameters
  • depolarization_rate (float) – The uniform depolarization strength.

  • parameterization ({"depolarize", "stochastic", or "lindblad"}) – Determines whether a DepolarizeOp, StochasticNoiseOp, or LindbladErrorgen is used to represent the depolarization noise, respectively. When “depolarize” (the default), a DepolarizeOp is created with the strength given in depolarization_strengths. When “stochastic”, the depolarization strength is split evenly among the stochastic channels of a StochasticOp. When “lindblad”, the depolarization strength is split evenly among the coefficients of the stochastic error generators (which are exponentiated to form a LindbladErrorgen with the “depol” parameterization).

create_errorgen(self, evotype, state_space)

Create an error generator for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator

create_errormap(self, evotype, state_space)

Create an error map (operator or superoperator) for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator

class pygsti.models.modelnoise.StochasticNoise(error_probs, parameterization='stochastic')

Bases: OpNoise

Pauli stochastic noise.

Parameters
  • error_probs (tuple) – The Pauli-stochastic rates for each of the non-trivial Paulis (a 3-tuple is expected for a 1Q gate and a 15-tuple for a 2Q gate).

  • parameterization ({"stochastic", or "lindblad"}) – Determines whether a StochasticNoiseOp or LindbladErrorgen is used to represent the stochastic noise, respectively. When “stochastic”, elements of error_probs are used as coefficients in a linear combination of stochastic channels (the default). When “lindblad”, the elements of error_probs are coefficients of stochastic error generators (which are exponentiated to form a LindbladErrorgen with “cptp” non-Hammiltonian parameterization).

create_errorgen(self, evotype, state_space)

Create an error generator for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator

create_errormap(self, evotype, state_space)

Create an error map (operator or superoperator) for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator

class pygsti.models.modelnoise.LindbladNoise(error_coeffs, parameterization='auto')

Bases: OpNoise

Noise generated by exponentiating a Lindbladian error generator.

The error generator is a Lindblad-form sum of elementary error generators corresponding to Hamiltonian and other (stochastic, correlation, etc.) type of errors.

Parameters
  • error_coeffs (dict) – A dictionary of Lindblad-term coefficients. Keys are (termType, basisLabel1, <basisLabel2>) tuples, where termType can be “H” (Hamiltonian), “S” (Stochastic/other), or “A” (Affine). Hamiltonian and Affine terms always have a single basis label (so key is a 2-tuple) whereas Stochastic/other tuples can have 1 or 2 basis labels depending on the parameterization type. Tuples with 1 basis label indicate a stochastic (diagonal Lindblad) term, and are the only type of terms allowed when a parmeterization with nonham_mode != “all” is selected. “S” terms with 2 basis specify “off-diagonal” non-Hamiltonian Lindblad terms. Basis labels can be strings or integers. Values are complex coefficients.

  • parameterization (str or LindbladParameterization) – Determines the parameterization of the LindbladErrorgen objects used to represent this noise. When “auto” (the default), the parameterization is inferred from the types of error generators specified in the error_coeffs dictionary. When not “auto”, the parameterization type is passed through to created LindbladErrorgen objects.

classmethod from_basis_coefficients(cls, parameterization, lindblad_basis, state_space, ham_coefficients=None, nonham_coefficients=None)

Create a LindbladNoise object containing a complete basis of elementary terms.

This method provides a convenient way to create a lindblad noise specification containing the complete set of terms in a Lindbladian based on a given “Lindblad basis” (often just a Pauli product basis). This routine by default creates all the terms with zero coefficients, but coefficient vectors or matrices (usually obtained by projecting an arbitrary error generator onto the lindblad basis) can be specified via the ham_coefficients and nonham_coefficients arguments.

Parameters
  • parameterization (str or LindbladParameterization) – The Lindblad parameterization, specifying what constitutes the “complete” set of Lindblad terms. For example, “H” means that just Hamiltonian terms are included whereas “CPTP” includes all the terms in a standard Lindblad decomposition.

  • lindblad_basis (str or Basis) – The basis used to construct the Lindblad terms.

  • state_space (StateSpace) – The state space, used only to convert string-valued lindblad_basis names into a Basis object. If lindblad_basis is given as a Basis, then this can be set to None.

  • ham_coefficients (numpy.ndarray or None, optional) – A 1-dimensional array of coefficients giving the initial values of the Hamiltonian-term coefficients. The length of this arrays should be one less than the size of lindblad_basis (since there’s no Lindblad term for the identity element).

  • nonham_coefficients (numpy.ndarray or None, optional) – A 1- or 2-dimensional array of coefficients for the “other” (non-Hamiltonian) terms. The shape of this array should be (d,), (2,d), or (d,d) depending on parameterization (e.g. for S, S+A, and CPTP parameterizations).

Returns

LindbladNoise

create_errorgen(self, evotype, state_space)

Create an error generator for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator

create_errormap(self, evotype, state_space)

Create an error map (operator or superoperator) for this noise operation.

Parameters
  • evotype (str or Evotype) – The evolution type for the returned operator.

  • state_space (StateSpace) – The state space for the returned operator.

Returns

LinearOperator