pygsti.modelmembers.instruments
¶
Subpackage holding model instrument objects.
Submodules¶
Package Contents¶
Classes¶
A generalized quantum instrument. 

A tracepreservng quantum instrument. 

An element of a 
Functions¶

Decode an op type into an appropriate instrument type. 

Convert intrument to a new type of parameterization. 
 class pygsti.modelmembers.instruments.Instrument(member_ops, evotype=None, state_space=None, items=[])¶
Bases:
pygsti.modelmembers.modelmember.ModelMember
,collections.OrderedDict
A generalized quantum instrument.
Meant to correspond to a quantum instrument in theory, this class generalizes that notion slightly to include a collection of gates that may or may not have all of the properties associated by a mathematical quantum instrument.
 Parameters
member_ops (dict of LinearOperator objects) – A dict (or list of key,value pairs) of the gates.
evotype (Evotype or str, optional) – The evolution type. If None, the evotype is inferred from the first instrument member. If len(member_ops) == 0 in this case, an error is raised.
state_space (StateSpace, optional) – The state space for this POVM. If None, the space is inferred from the first instrument member. If len(member_ops) == 0 in this case, an error is raised.
items (list or dict, optional) – Initial values. This should only be used internally in deserialization.
 submembers(self)¶
Get the ModelMemberderived objects contained in this one.
 Returns
list
 to_memoized_dict(self, mmg_memo)¶
Create a serializable dict with references to other objects in the memo.
 Parameters
mmg_memo (dict) – Memo dict from a ModelMemberGraph, i.e. keys are object ids and values are ModelMemberGraphNodes (which contain the serialize_id). This is NOT the same as other memos in ModelMember (e.g. copy, allocate_gpindices, etc.).
 Returns
mm_dict (dict) – A dict representation of this ModelMember ready for serialization This must have at least the following fields:
module, class, submembers, params, state_space, evotype
Additional fields may be added by derived classes.
 classmethod _from_memoized_dict(cls, mm_dict, serial_memo)¶
For subclasses to implement. Submemberexistence checks are performed, and the gpindices of the return value is set, by the nonunderscored :method:`from_memoized_dict` implemented in this class.
 _is_similar(self, other, rtol, atol)¶
Returns True if other model member (which it guaranteed to be the same type as self) has the same local structure, i.e., not considering parameter values or submembers
 __setitem__(self, key, value)¶
Set self[key] to value.
 __reduce__(self)¶
Needed for OrderedDictderived classes (to set dict items)
 __pygsti_reduce__(self)¶
 simplify_operations(self, prefix='')¶
Creates a dictionary of simplified instrument operations.
Returns a dictionary of operations that belong to the Instrument’s parent Model  that is, whose gpindices are set to all or a subset of this instruments’s gpindices. These are used internally within computations involving the parent Model.
 Parameters
prefix (str) – A string, usually identitying this instrument, which may be used to prefix the simplified gate keys.
 Returns
OrderedDict of Gates
 property parameter_labels(self)¶
An array of labels (usually strings) describing this model member’s parameters.
 property num_elements(self)¶
Return the number of total gate elements in this instrument.
This is in general different from the number of parameters, which are the number of free variables used to generate all of the matrix elements.
 Returns
int
 property num_params(self)¶
Get the number of independent parameters which specify this Instrument.
 Returns
int – the number of independent parameters.
 to_vector(self)¶
Extract a vector of the underlying gate parameters from this Instrument.
 Returns
numpy array – a 1D numpy array with length == num_params().
 from_vector(self, v, close=False, dirty_value=True)¶
Initialize the Instrument using a vector of its parameters.
 Parameters
v (numpy array) – The 1D vector of gate parameters. Length must == num_params().
close (bool, optional) – Whether v is close to this Instrument’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.
dirty_value (bool, optional) – The value to set this object’s “dirty flag” to before exiting this call. This is passed as an argument so it can be updated recursively. Leave this set to True unless you know what you’re doing.
 Returns
None
 transform_inplace(self, s)¶
Update each Instrument element matrix O with inv(s) * O * s.
 Parameters
s (GaugeGroupElement) – A gauge group element which specifies the “s” matrix (and it’s inverse) used in the above similarity transform.
 Returns
None
 depolarize(self, amount)¶
Depolarize this Instrument by the given amount.
 Parameters
amount (float or tuple) – The amount to depolarize by. If a tuple, it must have length equal to one less than the dimension of the gate. All but the first element of each spam vector (often corresponding to the identity element) are multiplied by amount (if a float) or the corresponding amount[i] (if a tuple).
 Returns
None
 rotate(self, amount, mx_basis='gm')¶
Rotate this instrument by the given amount.
 Parameters
amount (tuple of floats, optional) – Specifies the rotation “coefficients” along each of the nonidentity Pauliproduct axes. The gate’s matrix G is composed with a rotation operation R (so G > dot(R, G) ) where R is the unitary superoperator corresponding to the unitary operator U = exp( sum_k( i * rotate[k] / 2.0 * Pauli_k ) ). Here Pauli_k ranges over all of the nonidentity unnormalized Pauli operators.
mx_basis ({'std', 'gm', 'pp', 'qt'} or Basis object) – The source and destination basis, respectively. Allowed values are Matrixunit (std), GellMann (gm), Pauliproduct (pp), and Qutrit (qt) (or a custom basis object).
 Returns
None
 acton(self, state)¶
Act with this instrument upon state
 Parameters
state (State) – The state to act on
 Returns
OrderedDict – A dictionary whose keys are the outcome labels (strings) and whose values are (prob, normalized_state) tuples giving the probability of seeing the given outcome and the resulting state that would be obtained if and when that outcome is observed.
 __str__(self)¶
Return str(self).
 class pygsti.modelmembers.instruments.TPInstrument(op_matrices, evotype='default', state_space=None, items=[])¶
Bases:
pygsti.modelmembers.modelmember.ModelMember
,collections.OrderedDict
A tracepreservng quantum instrument.
This is essentially a collection of operations whose sum is a tracepreserving map. The instrument’s elements may or may not have all of the properties associated by a mathematical quantum instrument.
If M1,M2,…Mn are the elements of the instrument, then we parameterize 1. MT = (M1+M2+…Mn) as a TPParmeterizedGate 2. Di = Mi  MT for i = 1..(n1) as FullyParameterizedGates
So to recover M1…Mn we compute: Mi = Di + MT for i = 1…(n1)
= (n2)*MTsum(Di) = (n2)*MT[(MTMi)n*MT] for i == (n1)
 Parameters
op_matrices (dict of numpy arrays) – A dict (or list of key,value pairs) of the operation matrices whose sum must be a tracepreserving (TP) map.
evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.
state_space (StateSpace, optional) – The state space for this Instrument. If None, the space is inferred from the first effect vector. If len(effects) == 0 in this case, an error is raised.
items (list or dict, optional) – Initial values. This should only be used internally in deserialization.
 submembers(self)¶
Get the ModelMemberderived objects contained in this one.
 Returns
list
 to_memoized_dict(self, mmg_memo)¶
Create a serializable dict with references to other objects in the memo.
 Parameters
mmg_memo (dict) – Memo dict from a ModelMemberGraph, i.e. keys are object ids and values are ModelMemberGraphNodes (which contain the serialize_id). This is NOT the same as other memos in ModelMember (e.g. copy, allocate_gpindices, etc.).
 Returns
mm_dict (dict) – A dict representation of this ModelMember ready for serialization This must have at least the following fields:
module, class, submembers, params, state_space, evotype
Additional fields may be added by derived classes.
 classmethod _from_memoized_dict(cls, mm_dict, serial_memo)¶
For subclasses to implement. Submemberexistence checks are performed, and the gpindices of the return value is set, by the nonunderscored :method:`from_memoized_dict` implemented in this class.
 _is_similar(self, other, rtol, atol)¶
Returns True if other model member (which it guaranteed to be the same type as self) has the same local structure, i.e., not considering parameter values or submembers
 __setitem__(self, key, value)¶
Set self[key] to value.
 __reduce__(self)¶
Needed for OrderedDictderived classes (to set dict items)
 __setstate__(self, state)¶
 __pygsti_reduce__(self)¶
 simplify_operations(self, prefix='')¶
Creates a dictionary of simplified instrument operations.
Returns a dictionary of operations that belong to the Instrument’s parent Model  that is, whose gpindices are set to all or a subset of this instruments’s gpindices. These are used internally within computations involving the parent Model.
 Parameters
prefix (str) – A string, usually identitying this instrument, which may be used to prefix the simplified gate keys.
 Returns
OrderedDict of Gates
 property parameter_labels(self)¶
An array of labels (usually strings) describing this model member’s parameters.
 property num_elements(self)¶
Return the number of total gate elements in this instrument.
This is in general different from the number of parameters, which are the number of free variables used to generate all of the matrix elements.
 Returns
int
 property num_params(self)¶
Get the number of independent parameters which specify this Instrument.
 Returns
int – the number of independent parameters.
 to_vector(self)¶
Extract a vector of the underlying gate parameters from this Instrument.
 Returns
numpy array – a 1D numpy array with length == num_params().
 from_vector(self, v, close=False, dirty_value=True)¶
Initialize the Instrument using a vector of its parameters.
 Parameters
v (numpy array) – The 1D vector of gate parameters. Length must == num_params().
close (bool, optional) – Whether v is close to this Instrument’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.
dirty_value (bool, optional) – The value to set this object’s “dirty flag” to before exiting this call. This is passed as an argument so it can be updated recursively. Leave this set to True unless you know what you’re doing.
 Returns
None
 transform_inplace(self, s)¶
Update each Instrument element matrix O with inv(s) * O * s.
 Parameters
s (GaugeGroupElement) – A gauge group element which specifies the “s” matrix (and it’s inverse) used in the above similarity transform.
 Returns
None
 depolarize(self, amount)¶
Depolarize this Instrument by the given amount.
 Parameters
amount (float or tuple) – The amount to depolarize by. If a tuple, it must have length equal to one less than the dimension of the gate. All but the first element of each spam vector (often corresponding to the identity element) are multiplied by amount (if a float) or the corresponding amount[i] (if a tuple).
 Returns
None
 rotate(self, amount, mx_basis='gm')¶
Rotate this instrument by the given amount.
 Parameters
amount (tuple of floats, optional) – Specifies the rotation “coefficients” along each of the nonidentity Pauliproduct axes. The gate’s matrix G is composed with a rotation operation R (so G > dot(R, G) ) where R is the unitary superoperator corresponding to the unitary operator U = exp( sum_k( i * rotate[k] / 2.0 * Pauli_k ) ). Here Pauli_k ranges over all of the nonidentity unnormalized Pauli operators.
mx_basis ({'std', 'gm', 'pp', 'qt'} or Basis object) – The source and destination basis, respectively. Allowed values are Matrixunit (std), GellMann (gm), Pauliproduct (pp), and Qutrit (qt) (or a custom basis object).
 Returns
None
 __str__(self)¶
Return str(self).
 class pygsti.modelmembers.instruments.TPInstrumentOp(param_ops, index)¶
Bases:
pygsti.modelmembers.operations.DenseOperator
An element of a
TPInstrument
.A partial implementation of
LinearOperator
which encapsulates an element of aTPInstrument
. Instances rely on their parent being a TPInstrument. Parameters
param_ops (list of LinearOperator objects) – A list of the underlying operation objects which constitute a simple parameterization of a
TPInstrument
. Namely, this is the list of [MT,D1,D2,…Dn] operations which parameterize all of the TPInstrument’s elements.index (int) – The index indicating which element of the TPInstrument the constructed object is. Must be in the range [0,len(param_ops)1].
 submembers(self)¶
Get the ModelMemberderived objects contained in this one.
 Returns
list
 to_memoized_dict(self, mmg_memo)¶
Create a serializable dict with references to other objects in the memo.
 Parameters
mmg_memo (dict) – Memo dict from a ModelMemberGraph, i.e. keys are object ids and values are ModelMemberGraphNodes (which contain the serialize_id). This is NOT the same as other memos in ModelMember (e.g. copy, allocate_gpindices, etc.).
 Returns
mm_dict (dict) – A dict representation of this ModelMember ready for serialization This must have at least the following fields:
module, class, submembers, params, state_space, evotype
Additional fields may be added by derived classes.
 classmethod _from_memoized_dict(cls, mm_dict, serial_memo)¶
For subclasses to implement. Submemberexistence checks are performed, and the gpindices of the return value is set, by the nonunderscored :method:`from_memoized_dict` implemented in this class.
 _is_similar(self, other, rtol, atol)¶
Returns True if other model member (which it guaranteed to be the same type as self) has the same local structure, i.e., not considering parameter values or submembers
 _construct_matrix(self)¶
 Mi = Di + MT for i = 1…(n1)
= (n2)*MTsum(Di) = (n2)*MT[(MTMi)n*MT] for i == (n1)
 deriv_wrt_params(self, wrt_filter=None)¶
The elementwise derivative this operation.
Construct a matrix whose columns are the vectorized derivatives of the flattened operation matrix with respect to a single operation parameter. Thus, each column is of length op_dim^2 and there is one column per operation parameter. An empty 2D array in the StaticArbitraryOp case (num_params == 0).
 Parameters
wrt_filter (list or numpy.ndarray) – List of parameter indices to take derivative with respect to. (None means to use all the this operation’s parameters.)
 Returns
numpy array – Array of derivatives with shape (dimension^2, num_params)
 has_nonzero_hessian(self)¶
Whether this operation has a nonzero Hessian with respect to its parameters.
(i.e. whether it only depends linearly on its parameters or not)
 Returns
bool
 property num_params(self)¶
Get the number of independent parameters which specify this operation.
 Returns
int – the number of independent parameters.
 to_vector(self)¶
Get the operation parameters as an array of values.
 Returns
numpy array – The operation parameters as a 1D array with length num_params().
 from_vector(self, v, close=False, dirty_value=True)¶
Initialize the operation using a vector of parameters.
 Parameters
v (numpy array) – The 1D vector of operation parameters. Length must == num_params()
close (bool, optional) – Whether v is close to this operation’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.
dirty_value (bool, optional) – The value to set this object’s “dirty flag” to before exiting this call. This is passed as an argument so it can be updated recursively. Leave this set to True unless you know what you’re doing.
 Returns
None
 pygsti.modelmembers.instruments.instrument_type_from_op_type(op_type)¶
Decode an op type into an appropriate instrument type.
 pygsti.modelmembers.instruments.convert(instrument, to_type, basis, extra=None)¶
Convert intrument to a new type of parameterization.
This potentially creates a new object. Raises ValueError for invalid conversions.
 Parameters
instrument (Instrument) – Instrument to convert
to_type ({"full","TP","static","static unitary"}) – The type of parameterizaton to convert to. See :method:`Model.set_all_parameterizations` for more details.
basis ({'std', 'gm', 'pp', 'qt'} or Basis object) – The basis for povm. Allowed values are Matrixunit (std), GellMann (gm), Pauliproduct (pp), and Qutrit (qt) (or a custom basis object).
extra (object, optional) – Additional information for conversion.
 Returns
Instrument – The converted instrument, usually a distinct object from the object passed as input.