:py:mod:`pygsti.modelmembers.operations.embeddedop` =================================================== .. py:module:: pygsti.modelmembers.operations.embeddedop .. autoapi-nested-parse:: The EmbeddedOp class and supporting functionality. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.modelmembers.operations.embeddedop.EmbeddedOp .. py:class:: EmbeddedOp(state_space, target_labels, operation_to_embed, allocated_to_parent=None) Bases: :py:obj:`pygsti.modelmembers.operations.linearop.LinearOperator` An operation containing a single lower (or equal) dimensional operation within it. An EmbeddedOp acts as the identity on all of its domain except the subspace of its contained operation, where it acts as the contained operation does. Parameters ---------- state_space : StateSpace Specifies the density matrix space upon which this operation acts. target_labels : list of strs The labels contained in `state_space` which demarcate the portions of the state space acted on by `operation_to_embed` (the "contained" operation). operation_to_embed : LinearOperator The operation object that is to be contained within this operation, and that specifies the only non-trivial action of the EmbeddedOp. Initialize a new LinearOperator .. py:property:: parameter_labels An array of labels (usually strings) describing this model member's parameters. .. py:property:: num_params Get the number of independent parameters which specify this operation. Returns ------- int the number of independent parameters. .. py:property:: total_term_magnitude Get the total (sum) of the magnitudes of all this operator's terms. The magnitude of a term is the absolute value of its coefficient, so this function returns the number you'd get from summing up the absolute-coefficients of all the Taylor terms (at all orders!) you get from expanding this operator in a Taylor series. Returns ------- float .. py:property:: total_term_magnitude_deriv The derivative of the sum of *all* this operator's terms. Computes the derivative of the total (sum) of the magnitudes of all this operator's terms with respect to the operators (local) parameters. Returns ------- numpy array An array of length self.num_params .. py:attribute:: target_labels .. py:attribute:: embedded_op .. py:method:: submembers() Get the ModelMember-derived objects contained in this one. Returns ------- list .. py:method:: set_time(t) Sets the current time for a time-dependent operator. For time-independent operators (the default), this function does nothing. Parameters ---------- t : float The current time. Returns ------- None .. py:method:: to_sparse(on_space: pygsti.SpaceT = 'minimal') Return the operation as a sparse matrix Returns ------- scipy.sparse.csr_matrix .. py:method:: to_dense(on_space: pygsti.SpaceT = 'minimal') Return the operation as a dense matrix Parameters ---------- on_space : {'minimal', 'Hilbert', 'HilbertSchmidt'} The space that the returned dense operation acts upon. For unitary matrices and bra/ket vectors, use `'Hilbert'`. For superoperator matrices and super-bra/super-ket vectors use `'HilbertSchmidt'`. `'minimal'` means that `'Hilbert'` is used if possible given this operator's evolution type, and otherwise `'HilbertSchmidt'` is used. Returns ------- numpy.ndarray .. 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: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. 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:: taylor_order_terms(order, max_polynomial_vars=100, return_coeff_polys=False) Get the `order`-th order Taylor-expansion terms of this operation. This function either constructs or returns a cached list of the terms at the given order. Each term is "rank-1", meaning that its action on a density matrix `rho` can be written: `rho -> A rho B` The coefficients of these terms are typically polynomials of the operation's parameters, where the polynomial's variable indices index the *global* parameters of the operation's parent (usually a :class:`Model`), not the operation's local parameter array (i.e. that returned from `to_vector`). Parameters ---------- order : int The order of terms to get. max_polynomial_vars : int, optional maximum number of variables the created polynomials can have. return_coeff_polys : bool Whether a parallel list of locally-indexed (using variable indices corresponding to *this* object's parameters rather than its parent's) polynomial coefficients should be returned as well. Returns ------- terms : list A list of :class:`RankOneTerm` objects. coefficients : list Only present when `return_coeff_polys == True`. A list of *compact* polynomial objects, meaning that each element is a `(vtape,ctape)` 2-tuple formed by concatenating together the output of :meth:`Polynomial.compact`. .. py:method:: taylor_order_terms_above_mag(order, max_polynomial_vars, min_term_mag) Get the `order`-th order Taylor-expansion terms of this operation that have magnitude above `min_term_mag`. This function constructs the terms at the given order which have a magnitude (given by the absolute value of their coefficient) that is greater than or equal to `min_term_mag`. It calls :meth:`taylor_order_terms` internally, so that all the terms at order `order` are typically cached for future calls. The coefficients of these terms are typically polynomials of the operation's parameters, where the polynomial's variable indices index the *global* parameters of the operation's parent (usually a :class:`Model`), not the operation's local parameter array (i.e. that returned from `to_vector`). Parameters ---------- order : int The order of terms to get (and filter). max_polynomial_vars : int, optional maximum number of variables the created polynomials can have. min_term_mag : float the minimum term magnitude. Returns ------- list A list of :class:`Rank1Term` objects. .. py:method:: transform_inplace(s) :abstractmethod: Update operation matrix `O` with `inv(s) * O * s`. Generally, the transform function updates the *parameters* of the operation such that the resulting operation matrix is altered as described above. If such an update cannot be done (because the operation parameters do not allow for it), ValueError is raised. In this particular case any TP gauge transformation is possible, i.e. when `s` is an instance of `TPGaugeGroupElement` or corresponds to a TP-like transform matrix. 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:: errorgen_coefficients(return_basis=False, logscale_nonham=False, label_type='global', identity_label='I') Constructs a dictionary of the Lindblad-error-generator coefficients of this operation. Note that these are not necessarily the parameter values, as these coefficients are generally functions of the parameters (so as to keep the coefficients positive, for instance). Parameters ---------- return_basis : bool, optional Whether to also return a :class:`Basis` containing the elements with which the error generator terms were constructed. logscale_nonham : bool, optional Whether or not the non-hamiltonian error generator coefficients should be scaled so that the returned dict contains: `(1 - exp(-d^2 * coeff)) / d^2` instead of `coeff`. This essentially converts the coefficient into a rate that is the contribution this term would have within a depolarizing channel where all stochastic generators had this same coefficient. This is the value returned by :meth:`error_rates`. label_type : str, optional (default 'global') String specifying which type of `ElementaryErrorgenLabel` to use as the keys for the returned dictionary. Allowed options are 'global' for `GlobalElementaryErrorgenLabel` and 'local' for `LocalElementaryErrorgenLabel`. identity_label : str, optional (default 'I') An optional string specifying the basis element label for the identity. Used when label_type is 'local' to allow for embedding local basis element labels into the appropriate higher dimensional space. Only change when using a basis for which 'I' does not denote the identity. Returns ------- embedded_coeffs : dict Keys are instances of `ElementaryErrorgenLabel`, which wrap the `(termType, basisLabel1, )` information for each coefficient. Where `termType` is `"H"` (Hamiltonian), `"S"` (Stochastic), `"C"`(Correlation) or `"A"` (Affine). Hamiltonian and S terms always have a single basis label while 'C' and 'A' terms have two. .. py:method:: errorgen_coefficient_labels(label_type='global', identity_label='I') The elementary error-generator labels corresponding to the elements of :meth:`errorgen_coefficients_array`. Parameters ---------- label_type : str, optional (default 'global') String specifying which type of `ElementaryErrorgenLabel` to use as the keys for the returned dictionary. Allowed options are 'global' for `GlobalElementaryErrorgenLabel` and 'local' for `LocalElementaryErrorgenLabel`. identity_label : str, optional (default 'I') An optional string specifying the basis element label for the identity. Used when label_type is 'local' to allow for embedding local basis element labels into the appropriate higher dimensional space. Only change when using a basis for which 'I' does not denote the identity. Returns ------- tuple A tuple of (, [, X*rho*X-rho error generator is set such that if this coefficient were used for all 3 (X,Y, and Z) terms the resulting depolarizing channel would have error rate 3*0.01 = 0.03. Note that because error generator terms do not necessarily commute with one another, the sum of the returned error rates is not necessarily the error rate of the overall channel. Parameters ---------- label_type : str, optional (default 'global') String specifying which type of `ElementaryErrorgenLabel` to use as the keys for the returned dictionary. Allowed options are 'global' for `GlobalElementaryErrorgenLabel` and 'local' for `LocalElementaryErrorgenLabel`. identity_label : str, optional (default 'I') An optional string specifying the basis element label for the identity. Used when label_type is 'local' to allow for embedding local basis element labels into the appropriate higher dimensional space. Only change when using a basis for which 'I' does not denote the identity. Returns ------- lindblad_term_dict : dict Keys are instances of `ElementaryErrorgenLabel`, which wrap the `(termType, basisLabel1, )` information for each coefficient. Where `termType` is `"H"` (Hamiltonian), `"S"` (Stochastic), `"C"`(Correlation) or `"A"` (Affine). Hamiltonian and S terms always have a single basis label while 'C' and 'A' terms have two. .. py:method:: set_errorgen_coefficients(lindblad_term_dict, action='update', logscale_nonham=False, truncate=True) Sets the coefficients of terms in the error generator of this operation. The dictionary `lindblad_term_dict` has tuple-keys describing the type of term and the basis elements used to construct it, e.g. `('H','X')`. Parameters ---------- lindblad_term_dict : dict Keys are instances of `ElementaryErrorgenLabel`, which wrap the `(termType, basisLabel1, )` information for each coefficient. Where `termType` is `"H"` (Hamiltonian), `"S"` (Stochastic), `"C"`(Correlation) or `"A"` (Affine). Hamiltonian and S terms always have a single basis label while 'C' and 'A' terms have two. Values are corresponding rates. action : {"update","add","reset"} How the values in `lindblad_term_dict` should be combined with existing error-generator coefficients. logscale_nonham : bool, optional Whether or not the values in `lindblad_term_dict` for non-hamiltonian error generators should be interpreted as error *rates* (of an "equivalent" depolarizing channel, see :meth:`errorgen_coefficients`) instead of raw coefficients. If True, then the non-hamiltonian coefficients are set to `-log(1 - d^2*rate)/d^2`, where `rate` is the corresponding value given in `lindblad_term_dict`. This is what is performed by the function :meth:`set_error_rates`. truncate : bool, optional Whether to allow adjustment of the errogen coefficients in order to meet constraints (e.g. to preserve CPTP) when necessary. If False, then an error is thrown when the given coefficients cannot be set as specified. Returns ------- None .. py:method:: set_error_rates(lindblad_term_dict, action='update') Sets the coeffcients of terms in the error generator of this operation. Values are set so that the contributions of the resulting channel's error rate are given by the values in `lindblad_term_dict`. See :meth:`error_rates` for more details. Parameters ---------- lindblad_term_dict : dict Keys are `(termType, basisLabel1, )` tuples, where `termType` is `"H"` (Hamiltonian), `"S"` (Stochastic), or `"A"` (Affine). Hamiltonian and Affine terms always have a single basis label (so key is a 2-tuple) whereas Stochastic tuples have 1 basis label to indicate a *diagonal* term and otherwise have 2 basis labels to specify off-diagonal non-Hamiltonian Lindblad terms. Values are real error rates except for the 2-basis-label case, when they may be complex. action : {"update","add","reset"} How the values in `lindblad_term_dict` should be combined with existing error rates. Returns ------- None .. py:method:: depolarize(amount) Depolarize this operation by the given `amount`. Generally, the depolarize function updates the *parameters* of the operation such that the resulting operation matrix is depolarized. If such an update cannot be done (because the operation parameters do not allow for it), ValueError is raised. 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 operation. In standard bases, depolarization corresponds to multiplying the operation matrix by a diagonal matrix whose first diagonal element (corresponding to the identity) equals 1.0 and whose subsequent elements (corresponding to non-identity basis elements) equal `1.0 - amount[i]` (or just `1.0 - amount` if `amount` is a float). Returns ------- None .. py:method:: rotate(amount, mx_basis='gm') Rotate this operation by the given `amount`. Generally, the rotate function updates the *parameters* of the operation such that the resulting operation matrix is rotated. If such an update cannot be done (because the operation parameters do not allow for it), ValueError is raised. Parameters ---------- amount : tuple of floats, optional Specifies the rotation "coefficients" along each of the non-identity Pauli-product axes. The operation'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:: 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_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.