:py:mod:`pygsti.modelmembers.operations.embeddederrorgen` ========================================================= .. py:module:: pygsti.modelmembers.operations.embeddederrorgen .. autoapi-nested-parse:: The EmbeddedErrorgen class and supporting functionality. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.modelmembers.operations.embeddederrorgen.EmbeddedErrorgen .. py:class:: EmbeddedErrorgen(state_space, target_labels, errgen_to_embed: pygsti.modelmembers.operations.lindbladerrorgen.LindbladErrorgen) Bases: :py:obj:`pygsti.modelmembers.operations.embeddedop.EmbeddedOp` An error generator containing a single lower (or equal) dimensional operation within it. An EmbeddedErrorGen acts as the null map (zero) on all of its domain except the subspace of its contained error generator, where it acts as the contained item 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 `errgen_to_embed` (the "contained" error generator). errgen_to_embed : LinearOperator The error generator object that is to be contained within this error generator, and that specifies the only non-trivial action of the EmbeddedErrorgen. Initialize a new LinearOperator .. 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:: 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 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:: coefficient_labels(label_type='global', identity_label='I') The elementary error-generator labels corresponding to the elements of :meth:`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_coefficients(lindblad_term_dict, action='update', logscale_nonham=False, truncate=True) Sets the coefficients of terms in this error generator. 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 truncate the projections onto the Lindblad terms 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 parameterized as specified. Returns ------- None .. py:method:: set_error_rates(lindblad_term_dict, action='update') Sets the coeffcients of terms in this error generator. Coefficients 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:: deriv_wrt_params(wrt_filter=None) The element-wise derivative this operation. Construct a matrix whose columns are the vectorized derivatives of the flattened error generator matrix with respect to a single operator 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, shape == (dimension^2, num_params) .. py:method:: hessian_wrt_params(wrt_filter1=None, wrt_filter2=None) Construct the Hessian of this error generator with respect to its parameters. This function returns a tensor whose first axis corresponds to the flattened operation matrix and whose 2nd and 3rd axes correspond to the parameters that are differentiated with respect to. Parameters ---------- wrt_filter1 : list or numpy.ndarray List of parameter indices to take 1st derivatives with respect to. (None means to use all the this operation's parameters.) wrt_filter2 : list or numpy.ndarray List of parameter indices to take 2nd derivatives with respect to. (None means to use all the this operation's parameters.) Returns ------- numpy array Hessian with shape (dimension^2, num_params1, num_params2) .. py:method:: onenorm_upperbound() Returns an upper bound on the 1-norm for this error generator (viewed as a matrix). Returns ------- float