pygsti.models.modelnoise
Objects for specifying the noise to be added to models when they are created.
Module Contents
Classes
A base class for objects specifying noise (errors) that should be added to a quantum processor model. 

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

Model noise that is stored on a peroperation basis. 

Opmodel noise that is specified simply as the composition of other opmodel noise specifications. 

Specification for a single noise operation. 

Depolarization noise. 

Pauli stochastic noise. 

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(obj)
Convert an object to an
OpModelNoise
object if it isn’t already.If a dictionary is given, it is assumed to contain peroperation error specifications. If a list/tuple is given, it is assumed to contain multiple subspecifications that should be composed together (by constructing a
ComposedOpModelNoise
object).Parameters
 objobject
The object to convert.
Returns
OpModelNoise
 abstract keys()
The operation labels for which this object specifies noise.
 abstract create_errorgen_stencil(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 qudits 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 qudits (often this is done when a “independent” argument to a modelcreation function is False). An “error generator stencil” is a stencil whose operators are error generators, rather than error maps.
Parameters
 opkeyLabel or StencilLabel
The operation label to create the stencil for.
 evotypestr or Evotype
The evolution type of to use when creating the stencil operators.
 state_spaceStateSpace
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_labelsint 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
 stencilOrderedDict
A dictionary with keys that are
Label
orStencilLabel
objects and values that areLinearOperator
objects. The stencil is applied by embedding each operator according to its key and then composing the results.
 abstract apply_errorgen_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
Apply an errorgenerator 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 stencillabel expansions) and then composing the results.
Parameters
 stencilOrderedDict
The stencil to apply, usually created by
create_errorgen_stencil()
. evotypestr 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_spaceStateSpace
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_labelstuple or None, optional
The target labels that determine where on the qudit graph this stencil will be placed. When a tuple, it should have length equal to the num_target_labels argument passed to
create_errorgen_stencil()
. None indicates that the entire space is the “target” space of the stencil (e.g. a global idle, preparation, or measurement). qudit_graphQubitGraph, optional
The relevant qudit 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.
 copybool, 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(opkey, evotype, state_space, target_labels=None, qudit_graph=None)
Create an error generator object to implement the noise on a given model operation.
Parameters
 opkeyLabel or StencilLabel
The operation label to create the error generator for.
 evotypestr or Evotype
The evolution type to use when creating the error generator.
 state_spaceStateSpace
The state space to use when creating the error generator.
 target_labelstuple 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.
 qudit_graphQubitGraph, optional
The relevant qudit 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(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 qudits 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 qudits (often this is done when a “independent” argument to a modelcreation function is False). An “error map stencil” is a stencil whose operators are error maps rather than error generators.
Parameters
 opkeyLabel or StencilLabel
The operation label to create the stencil for.
 evotypestr or Evotype
The evolution type of to use when creating the stencil operators.
 state_spaceStateSpace
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_labelsint 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
 stencilOrderedDict
A dictionary with keys that are
Label
orStencilLabel
objects and values that areLinearOperator
objects. The stencil is applied by embedding each operator according to its key and then composing the results.
 abstract apply_errormap_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
Apply an errormap 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 stencillabel expansions) and then composing the results.
Parameters
 stencilOrderedDict
The stencil to apply, usually created by
create_errormap_stencil()
. evotypestr 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_spaceStateSpace
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_labelstuple or None, optional
The target labels that determine where on the qudit graph this stencil will be placed. When a tuple, it should have length equal to the num_target_labels argument passed to
create_errormap_stencil()
. None indicates that the entire space is the “target” space of the stencil (e.g. a global idle, preparation, or measurement). qudit_graphQubitGraph, optional
The relevant qudit 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.
 copybool, 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(opkey, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
Create an error map object to implement the noise on a given model operation.
Parameters
 opkeyLabel or StencilLabel
The operation label to create the error map for.
 evotypestr or Evotype
The evolution type to use when creating the error map.
 state_spaceStateSpace
The state space to use when creating the error map.
 target_labelstuple 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.
 qudit_graphQubitGraph, optional
The relevant qudit 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.
 copybool, optional
Whether the operations arising from the same stencil 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
 reset_access_counters()
Resets the internal keyaccess 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
warn_about_zero_counters()
.Returns
None
 warn_about_zero_counters()
Issue a warning if any of the internal keyaccess 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(stencil, state_space, target_labels=None, qudit_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 nontrivially acted upon by the operation that results from applying stencil to target_labels.
Parameters
 stencilOrderedDict
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_spaceStateSpace
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_labelstuple or None, optional
The target labels that determine where on the qudit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.
 qudit_graphQubitGraph, optional
The relevant qudit 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 peroperation basis.
Parameters
 per_op_noisedict
A dictionary mapping operation labels (which will become the keys of this
OpModelNoise
object) to eitherOpNoise
objects or to a nexted dictionary mapping absolute or stencil state space labels toOpNoise
objects. In the former case, theOpNoise
object is assumed to apply to all the target labels of the operation.
 keys()
The operation labels for which this object specifies noise.
 create_errorgen_stencil(opkey, evotype, state_space, num_target_labels=None)
 apply_errorgen_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
 create_errormap_stencil(opkey, evotype, state_space, num_target_labels=None)
 apply_errormap_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
 compute_stencil_absolute_sslbls(stencil, state_space, target_labels=None, qudit_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 nontrivially acted upon by the operation that results from applying stencil to target_labels.
Parameters
 stencilOrderedDict
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_spaceStateSpace
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_labelstuple or None, optional
The target labels that determine where on the qudit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.
 qudit_graphQubitGraph, optional
The relevant qudit 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.ComposedOpModelNoise(opmodelnoises)
Bases:
OpModelNoise
Opmodel noise that is specified simply as the composition of other opmodel noise specifications.
Parameters
 opmodelnoisesiterable
The sub
OpModelNoise
objects.
 ensure_no_duplicates()
Raise an AssertionError if there are any duplicates among the composed noise specifications.
Returns
None
 keys()
The operation labels for which this object specifies noise.
 create_errorgen_stencil(opkey, evotype, state_space, num_target_labels=None)
 apply_errorgen_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
 create_errormap_stencil(opkey, evotype, state_space, num_target_labels=None)
 apply_errormap_stencil(stencil, evotype, state_space, target_labels=None, qudit_graph=None, copy=False)
 compute_stencil_absolute_sslbls(stencil, state_space, target_labels=None, qudit_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 nontrivially acted upon by the operation that results from applying stencil to target_labels.
Parameters
 stencilOrderedDict
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_spaceStateSpace
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_labelstuple or None, optional
The target labels that determine where on the qudit graph stencil will be placed. None indicates that the entire space is the “target” space of the stencil.
 qudit_graphQubitGraph, optional
The relevant qudit 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.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 fromOpNoise
objects, and provides upstream objects likeOpModelNoise
a common interface for working with all types of noisy operations.
 class pygsti.models.modelnoise.DepolarizationNoise(depolarization_rate, parameterization='depolarize')
Bases:
OpNoise
Depolarization noise.
Parameters
 depolarization_ratefloat
The uniform depolarization strength.
 parameterization{“depolarize”, “stochastic”, “lindblad”, “exp(lindblad)”, “1+lindblad”}
Determines whether a
DepolarizeOp
,StochasticNoiseOp
, orLindbladErrorgen
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).
 class pygsti.models.modelnoise.StochasticNoise(error_probs, parameterization='stochastic')
Bases:
OpNoise
Pauli stochastic noise.
Parameters
 error_probstuple
The Paulistochastic rates for each of the nontrivial Paulis (a 3tuple is expected for a 1Q gate and a 15tuple for a 2Q gate).
 parameterization{“stochastic”, or “lindblad”}
Determines whether a
StochasticNoiseOp
orLindbladErrorgen
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” nonHammiltonian parameterization).
 class pygsti.models.modelnoise.LindbladNoise(error_coeffs, parameterization='auto')
Bases:
OpNoise
Noise generated by exponentiating a Lindbladian error generator.
The error generator is a Lindbladform sum of elementary error generators corresponding to Hamiltonian and other (stochastic, correlation, etc.) type of errors.
Parameters
 error_coeffsdict
A dictionary of Lindbladterm 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 2tuple) 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 “offdiagonal” nonHamiltonian Lindblad terms. Basis labels can be strings or integers. Values are complex coefficients.
 parameterizationstr 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(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
 parameterizationstr 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_basisstr or Basis
The basis used to construct the Lindblad terms.
 state_spaceStateSpace
The state space, used only to convert stringvalued lindblad_basis names into a
Basis
object. If lindblad_basis is given as aBasis
, then this can be set to None. ham_coefficientsnumpy.ndarray or None, optional
A 1dimensional array of coefficients giving the initial values of the Hamiltonianterm 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_coefficientsnumpy.ndarray or None, optional
A 1 or 2dimensional array of coefficients for the “other” (nonHamiltonian) 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