:py:mod:`pygsti.modelmembers.operations.lindbladcoefficients` ============================================================= .. py:module:: pygsti.modelmembers.operations.lindbladcoefficients Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.modelmembers.operations.lindbladcoefficients.LindbladCoefficientBlock Functions ~~~~~~~~~ .. autoapisummary:: pygsti.modelmembers.operations.lindbladcoefficients.cached_diag_indices Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.modelmembers.operations.lindbladcoefficients.triu_indices pygsti.modelmembers.operations.lindbladcoefficients.IMAG_TOL .. py:data:: triu_indices .. py:data:: IMAG_TOL :value: '1e-07' .. py:class:: LindbladCoefficientBlock(block_type, basis, basis_element_labels=None, initial_block_data=None, param_mode='static', truncate=False) Bases: :py:obj:`pygsti.baseobjs.nicelyserializable.NicelySerializable` Class for storing and managing the parameters associated with particular subblocks of error-generator parameters. Responsible for management of different internal representations utilized when employing various error generator constraints. Parameters ---------- block_type : str String specifying the type of error generator parameters contained within this block. Allowed values are 'ham' (for Hamiltonian error generators), 'other_diagonal' (for Pauli stochastic error generators), and 'other' (for Pauli stochastic, Pauli correlation and active error generators). basis : `Basis` `Basis` object to be used by this coefficient block. Not this must be an actual `Basis` object, and not a string (as the coefficient block doesn't have the requisite dimensionality information needed for casting). basis_element_labels : list or tuple of str Iterable of strings corresponding to the basis element subscripts used by the error generators managed by this coefficient block. initial_block_data : _np.ndarray, optional (default None) Numpy array with initial parameter values to use in setting initial state of this coefficient block. param_mode : str, optional (default 'static') String specifying the type of internal parameterization used by this coefficient block. Allowed options are: - For all block types: 'static' - For 'ham': 'elements' - For 'other_diagonal': 'elements', 'cholesky', 'depol', 'reldepol' - For 'other': 'elements', 'cholesky' Note that the most commonly encounted settings in practice are 'elements' and 'cholesky', which when used in the right combination are utilized in the construction of GLND and CPTPLND parameterized models. For both GLND and CPTPLND the 'ham' block used the 'elements' `param_mode`. GLND the 'other' block uses 'elements', and for CPTPLND it uses 'cholesky'. 'depol' and 'reldepol' are special modes used only for Pauli stochastic only coefficient blocks (i.e. 'other_diagonal'), and correspond to special reduced parameterizations applicable to depolarizing channels. (TODO: Add better explanation of the difference between depol and reldepol). truncate : bool, optional (default False) Flag specifying whether to truncate the parameters given by `initial_block_data` in order to meet constraints (e.g. to preserve CPTP) when necessary. If False, then an error is thrown when the given intial data cannot be parameterized as specified. .. py:property:: basis_element_labels .. py:property:: num_params .. py:property:: elementary_errorgen_indices TODO docstring - rewrite this docstring - especially return value! Constructs a dictionary mapping Lindblad term labels to projection coefficients. This method is used for finding the index of a particular error generator coefficient in the 1D array formed by concatenating the Hamiltonian and flattened stochastic projection arrays. Parameters ---------- ham_basis : {'std', 'gm', 'pp', 'qt'}, list of matrices, or Basis object The basis used to construct `ham_projs`. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt), list of numpy arrays, or a custom basis object. other_basis : {'std', 'gm', 'pp', 'qt'}, list of matrices, or Basis object The basis used to construct `other_projs`. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt), list of numpy arrays, or a custom basis object. other_mode : {"diagonal", "diag_affine", "all"} Which non-Hamiltonian Lindblad error projections `other_projs` includes. Allowed values are: `"diagonal"` (only the diagonal Stochastic), `"diag_affine"` (diagonal + affine generators), and `"all"` (all generators). Returns ------- Ltermdict : 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. Basis labels are taken from `ham_basis` and `other_basis`. Values are integer indices. .. py:property:: elementary_errorgens Converts a set of coefficients for this block into a linear combination of elementary error generators. This linear combination is given by a dictionary with keys equal to elementary error generator labels and values equal to their coefficients in the linear combination. Parameters ---------- block_data : numpy.ndarray A 1- or 2-dimensional array with each dimension of size `len(self.basis_element_labels)`, specifying the coefficients of this block. Array is 1-dimensional when this block is of type `'ham'` or `'other_diagonal'` and is 2-dimensional for type `'other'`. Returns ------- elementary_errorgens : dict Specifies `block_data` as a linear combination of elementary error generators. Keys are :class:`LocalElementaryErrorgenLabel` objects and values are floats. .. py:property:: coefficient_labels Labels for the elements of `self.block_data` (flattened if relevant) .. py:property:: param_labels Generate human-readable labels for the parameters of this block. Returns ------- param_labels : list A list of strings that describe each parameter. .. py:method:: create_lindblad_term_superoperators(mx_basis='pp', sparse='auto', include_1norms=False, flat=False) Compute the superoperator-generators corresponding to the Lindblad coefficients in this block. TODO: docstring update Returns ------- generators : numpy.ndarray or list of SciPy CSR matrices If parent holds a dense basis, this is an array of shape `(n,d,d)` for 'ham' and 'other_diagonal' blocks or `(n,n,d,d)` for 'other' blocks, where `d` is the *dimension* of the relevant basis and `n` is the number of basis elements included in this coefficient block. In the case of 'ham' and 'other_diagonal' type blocks, `generators[i]` gives the superoperator matrix corresponding to the block's `i`-th coefficient (and `i`-th basis element). In the 'other' case, `generators[i,j]` corresponds to the `(i,j)`-th coefficient. If the parent holds a sparse basis, the dimensions of size `n` are lists of CSR matrices with shape `(d,d)`. .. py:method:: create_lindblad_term_objects(parameter_index_offset, max_polynomial_vars, evotype, state_space) .. py:method:: set_elementary_errorgens(elementary_errorgens, on_missing='ignore', truncate=False) .. py:method:: set_from_errorgen_projections(errorgen, errorgen_basis='pp', return_projected_errorgen=False, truncate=False) .. py:method:: to_vector() Compute parameter values for this coefficient block. Returns ------- param_vals : numpy.ndarray A 1D array of real parameter values. Length is `len(self.basis_element_labels)` in the case of `'ham'` or `'other_diagonal'` blocks, and `len(self.basis_element_labels)**2` in the case of `'other'` blocks. .. py:method:: from_vector(v) Construct Lindblad coefficients (for this block) from a set of parameter values. This function essentially performs the inverse of :meth:`coefficients_to_paramvals`. Parameters ---------- v : numpy.ndarray A 1D array of real parameter values. .. py:method:: deriv_wrt_params(v=None) Construct derivative of Lindblad coefficients (for this block) from a set of parameter values. This function gives the Jacobian of what is returned by :func:`paramvals_to_coefficients` (as a function of the parameters). Parameters ---------- v : numpy.ndarray, optional A 1D array of real parameter values. If not specified, then self.to_vector() is used. Returns ------- block_data_deriv : numpy.ndarray A real array of shape `(nBEL,nP)` or `(nBEL,nBEL,nP)`, depending on the block type, where `nBEL` is this block's number of basis elements (see `self.basis_element_labels`) and `nP` is the number of parameters (the length of `parameter_values`). .. py:method:: elementary_errorgen_deriv_wrt_params(v=None) .. py:method:: superop_deriv_wrt_params(superops, v=None, superops_are_flat=False) TODO: docstring superops : numpy.ndarray Output of create_lindblad_term_superoperators (with `flat=True` if `superops_are_flat==True`), so that this is a 3- or 4-dimensional array indexed by `(iSuperop, superop_row, superop_col)` or `(iSuperop1, iSuperop2, superop_row, superop_col)`. Returns ------- numpy.ndarray per-superop-element derivative, indexed by `(superop_row, superop_col, parameter_index)` or `(superop_row, superop_col, parameter_index1, parameter_index2)` where there are two parameter indices because parameters are indexed by an (i,j) pair rather than a single index. .. py:method:: superop_hessian_wrt_params(superops, v=None, superops_are_flat=False) TODO: docstring Returns ------- numpy.ndarray Indexed by (superop_row, superop_col, param1, param2). .. py:method:: is_similar(other_coeff_block) TODO: docstring .. py:method:: convert(param_mode) TODO: docstring - return a *new* LindbladCoefficientBlock with the same block type and data, but with the given parameterization mode. .. py:function:: cached_diag_indices(n)