:py:mod:`pygsti.modelmembers.instruments` ========================================= .. py:module:: pygsti.modelmembers.instruments .. autoapi-nested-parse:: Sub-package holding model instrument objects. Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 instrument/index.rst tpinstrument/index.rst tpinstrumentop/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.modelmembers.instruments.Instrument pygsti.modelmembers.instruments.TPInstrument pygsti.modelmembers.instruments.TPInstrumentOp Functions ~~~~~~~~~ .. autoapisummary:: pygsti.modelmembers.instruments.instrument_type_from_op_type pygsti.modelmembers.instruments.convert .. py:class:: Instrument(member_ops, evotype=None, state_space=None, called_from_reduce=False, items=None) Bases: :py:obj:`pygsti.modelmembers.modelmember.ModelMember`, :py:obj:`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 de-serialization. Initialize a new ModelMember .. py:property:: parameter_labels An array of labels (usually strings) describing this model member's parameters. .. py:property:: num_elements 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 .. py:property:: num_params Get the number of independent parameters which specify this Instrument. Returns ------- int the number of independent parameters. .. py:method:: submembers() Get the ModelMember-derived objects contained in this one. Returns ------- list .. py:method:: to_memoized_dict(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. .. py:method:: simplify_operations(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 .. py:method:: to_vector() Extract a vector of the underlying gate parameters from this Instrument. Returns ------- numpy array a 1D numpy array with length == num_params(). .. py:method:: from_vector(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 .. py:method:: transform_inplace(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 .. py:method:: depolarize(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 .. py:method:: rotate(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 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). Returns ------- None .. py:method:: acton(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. .. py:class:: TPInstrument(op_matrices, evotype='default', state_space=None, called_from_reduce=False, items=None) Bases: :py:obj:`pygsti.modelmembers.modelmember.ModelMember`, :py:obj:`collections.OrderedDict` A trace-preservng quantum instrument. This is essentially a collection of operations whose sum is a trace-preserving 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..(n-1)` as FullyParameterizedGates So to recover `M1...Mn` we compute: Mi = Di + MT for i = `1...(n-1)` = -(n-2)*MT-sum(Di) = -(n-2)*MT-[(MT-Mi)-n*MT] for i == (n-1) Parameters ---------- op_matrices : dict of numpy arrays A dict (or list of key,value pairs) of the operation matrices whose sum must be a trace-preserving (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 de-serialization. Initialize a new ModelMember .. py:property:: parameter_labels An array of labels (usually strings) describing this model member's parameters. .. py:property:: num_elements 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 .. py:property:: num_params Get the number of independent parameters which specify this Instrument. Returns ------- int the number of independent parameters. .. py:attribute:: param_ops :value: '[]' .. py:method:: submembers() Get the ModelMember-derived objects contained in this one. Returns ------- list .. py:method:: to_memoized_dict(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. .. py:method:: simplify_operations(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 .. py:method:: to_vector() Extract a vector of the underlying gate parameters from this Instrument. Returns ------- numpy array a 1D numpy array with length == num_params(). .. py:method:: from_vector(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 .. py:method:: transform_inplace(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 .. py:method:: depolarize(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 .. py:method:: rotate(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 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). Returns ------- None .. py:class:: TPInstrumentOp(param_ops, index, basis=None) Bases: :py:obj:`pygsti.modelmembers.operations.DenseOperator` An element of a :class:`TPInstrument`. A partial implementation of :class:`LinearOperator` which encapsulates an element of a :class:`TPInstrument`. 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 :class:`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]`. basis : Basis or {'pp','gm','std'} or None The basis used to construct the Hilbert-Schmidt space representation of this state as a super-operator. If None, certain functionality, such as access to Kraus operators, will be unavailable. Initialize a new LinearOperator .. py:property:: num_params Get the number of independent parameters which specify this operation. Returns ------- int the number of independent parameters. .. py:attribute:: index .. py:attribute:: num_instrument_elements .. py:attribute:: relevant_param_ops .. py:method:: submembers() Get the ModelMember-derived objects contained in this one. Returns ------- list .. py:method:: to_memoized_dict(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. .. py:method:: deriv_wrt_params(wrt_filter=None) The element-wise 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) .. py:method:: has_nonzero_hessian() Whether this operation has a non-zero Hessian with respect to its parameters. (i.e. whether it only depends linearly on its parameters or not) Returns ------- bool .. py:method:: to_vector() Get the operation parameters as an array of values. Returns ------- numpy array The operation parameters as a 1D array with length num_params(). .. py:method:: from_vector(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 .. py:function:: instrument_type_from_op_type(op_type) Decode an op type into an appropriate instrument type. Parameters: ----------- op_type: str or list of str Operation parameterization type (or list of preferences) Returns ------- instr_type_preferences: tuple of str POVM parameterization types .. py:function:: convert(instrument, to_type, basis, ideal_instrument=None, flatten_structure=False) TODO: update docstring 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 :meth:`Model.set_all_parameterizations` for more details. basis : {'std', 'gm', 'pp', 'qt'} or Basis object The basis for `povm`. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object). ideal_instrument : Instrument, optional The ideal version of `instrument`, potentially used when converting to an error-generator type. flatten_structure : bool, optional When `False`, the sub-members of composed and embedded operations are separately converted, leaving the original instrument's structure unchanged. When `True`, composed and embedded operations are "flattened" into a single instrument of the requested `to_type`. Returns ------- Instrument The converted instrument, usually a distinct object from the object passed as input.