Defines the Instrument class

Module Contents



A generalized quantum instrument.

class pygsti.modelmembers.instruments.instrument.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.

  • 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 de-serialization.


Get the ModelMember-derived objects contained in this one.



to_memoized_dict(self, mmg_memo)

Create a serializable dict with references to other objects in the memo.


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


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. Submember-existence checks are performed, and the gpindices of the return value is set, by the non-underscored :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.


Needed for OrderedDict-derived classes (to set dict items)

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.


prefix (str) – A string, usually identitying this instrument, which may be used to prefix the simplified gate keys.


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.



property num_params(self)

Get the number of independent parameters which specify this Instrument.


int – the number of independent parameters.


Extract a vector of the underlying gate parameters from this Instrument.


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.

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



transform_inplace(self, s)

Update each Instrument element matrix O with inv(s) * O * s.


s (GaugeGroupElement) – A gauge group element which specifies the “s” matrix (and it’s inverse) used in the above similarity transform.



depolarize(self, amount)

Depolarize this Instrument by the given amount.


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



rotate(self, amount, mx_basis='gm')

Rotate this instrument by the given amount.

  • amount (tuple of floats, optional) – Specifies the rotation “coefficients” along each of the non-identity Pauli-product 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 non-identity un-normalized Pauli operators.

  • mx_basis ({'std', 'gm', 'pp', 'qt'} or Basis object) – The source and destination basis, respectively. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).



acton(self, state)

Act with this instrument upon state


state (State) – The state to act on


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.


Return str(self).