pygsti.modelmembers.operations.linearop
¶
The LinearOperator class and supporting functionality.
Module Contents¶
Classes¶
Base class for all operation representations 
Functions¶

Computes a finitedifference Jacobian for a LinearOperator object. 

Computes a finitedifference Hessian for a LinearOperator object. 
 class pygsti.modelmembers.operations.linearop.LinearOperator(rep, evotype)¶
Bases:
pygsti.modelmembers.modelmember.ModelMember
Base class for all operation representations
 Parameters
rep (object) – A representation object containing the core data for this operator.
evotype (Evotype) – The evolution type.
 size¶
Return the number of independent elements in this operation (when viewed as a dense array)
 Type
int
 dirty¶
Whether this object has been modified in a way that could have affected its parameters. A parent
OpModel
uses this information to know when it needs to refresh it’s modelwide parameter vector. Type
bool
 property dim(self)¶
Return the dimension of this operation (when viewed as a dense matrix)
 Returns
int
 property size(self)¶
Return the number of independent elements in this operation (when viewed as a dense array)
 Returns
int
 set_dense(self, m)¶
Set the densematrix value of this operation.
Attempts to modify operation parameters so that the specified raw operation matrix becomes mx. Will raise ValueError if this operation is not possible.
 Parameters
m (array_like or LinearOperator) – An array of shape (dim, dim) or LinearOperator representing the operation action.
 Returns
None
 set_time(self, t)¶
Sets the current time for a timedependent operator.
For timeindependent operators (the default), this function does nothing.
 Parameters
t (float) – The current time.
 Returns
None
 abstract to_dense(self, on_space='minimal')¶
Return this 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 superbra/superket 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
 acton(self, state, on_space='minimal')¶
Act with this operator upon state
 Parameters
state (State) – The state to act on
 Returns
State – The output state
 abstract to_sparse(self, on_space='minimal')¶
Return this operation as a sparse matrix.
 Returns
scipy.sparse.csr_matrix
 abstract taylor_order_terms(self, order, max_polynomial_vars=100, return_coeff_polys=False)¶
Get the orderth order Taylorexpansion terms of this operation.
This function either constructs or returns a cached list of the terms at the given order. Each term is “rank1”, 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
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 locallyindexed (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
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) 2tuple formed by concatenating together the output of :method:`Polynomial.compact`.
 highmagnitude_terms(self, min_term_mag, force_firstorder=True, max_taylor_order=3, max_polynomial_vars=100)¶
Get terms with magnitude above min_term_mag.
Get the terms (from a Taylor expansion of this operator) that have magnitude above min_term_mag (the magnitude of a term is taken to be the absolute value of its coefficient), considering only those terms up to some maximum Taylor expansion order, max_taylor_order.
Note that this function also sets the magnitudes of the returned terms (by calling term.set_magnitude(…)) based on the current values of this operator’s parameters. This is an essential step to using these terms in prunedpathintegral calculations later on.
 Parameters
min_term_mag (float) – the threshold for term magnitudes: only terms with magnitudes above this value are returned.
force_firstorder (bool, optional) – if True, then always return all the firstorder Taylorseries terms, even if they have magnitudes smaller than min_term_mag. This behavior is needed for using GST with prunedterm calculations, as we may begin with a guess model that has no error (all terms have zero magnitude!) and still need to compute a meaningful jacobian at this point.
max_taylor_order (int, optional) – the maximum Taylororder to consider when checking whether term magnitudes exceed min_term_mag.
max_polynomial_vars (int, optional) – maximum number of variables the created polynomials can have.
 Returns
highmag_terms (list) – A list of the highmagnitude terms that were found. These terms are sorted in descending order by termmagnitude.
first_order_indices (list) – A list of the indices into highmag_terms that mark which of these terms are firstorder Taylor terms (useful when we’re forcing these terms to always be present).
 taylor_order_terms_above_mag(self, order, max_polynomial_vars, min_term_mag)¶
Get the orderth order Taylorexpansion 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 :method:`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
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
Rank1Term
objects.
 frobeniusdist_squared(self, other_op, transform=None, inv_transform=None)¶
Return the squared frobenius difference between this operation and other_op
Optionally transforms this operation first using matrices transform and inv_transform. Specifically, this operation gets transfomed as: O => inv_transform * O * transform before comparison with other_op.
 Parameters
other_op (DenseOperator) – The other operation.
transform (numpy.ndarray, optional) – Transformation matrix.
inv_transform (numpy.ndarray, optional) – Inverse of transform.
 Returns
float
 frobeniusdist(self, other_op, transform=None, inv_transform=None)¶
Return the frobenius distance between this operation and other_op.
Optionally transforms this operation first using matrices transform and inv_transform. Specifically, this operation gets transfomed as: O => inv_transform * O * transform before comparison with other_op.
 Parameters
other_op (DenseOperator) – The other operation.
transform (numpy.ndarray, optional) – Transformation matrix.
inv_transform (numpy.ndarray, optional) – Inverse of transform.
 Returns
float
 residuals(self, other_op, transform=None, inv_transform=None)¶
The perelement difference between this DenseOperator and other_op.
Optionally, tansforming this operation first as O => inv_transform * O * transform.
 Parameters
other_op (DenseOperator) – The operation to compare against.
transform (numpy.ndarray, optional) – Transformation matrix.
inv_transform (numpy.ndarray, optional) – Inverse of transform.
 Returns
numpy.ndarray – A 1Darray of size equal to that of the flattened operation matrix.
 jtracedist(self, other_op, transform=None, inv_transform=None)¶
Return the Jamiolkowski trace distance between this operation and other_op.
Optionally, tansforming this operation first as O => inv_transform * O * transform.
 Parameters
other_op (DenseOperator) – The operation to compare against.
transform (numpy.ndarray, optional) – Transformation matrix.
inv_transform (numpy.ndarray, optional) – Inverse of transform.
 Returns
float
 diamonddist(self, other_op, transform=None, inv_transform=None)¶
Return the diamond distance between this operation and other_op.
Optionally, tansforming this operation first as O => inv_transform * O * transform.
 Parameters
other_op (DenseOperator) – The operation to compare against.
transform (numpy.ndarray, optional) – Transformation matrix.
inv_transform (numpy.ndarray, optional) – Inverse of transform.
 Returns
float
 transform_inplace(self, s)¶
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 transform of the appropriate dimension is possible, since all operation matrix elements are parameters.
 Parameters
s (GaugeGroupElement) – A gauge group element which specifies the “s” matrix (and it’s inverse) used in the above similarity transform.
 Returns
None
 depolarize(self, 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 nonidentity basis elements) equal 1.0  amount[i] (or just 1.0  amount if amount is a float).
 Returns
None
 rotate(self, 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 nonidentity Pauliproduct 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 nonidentity unnormalized Pauli operators.
mx_basis ({'std', 'gm', 'pp', 'qt'} or Basis object) – The source and destination basis, respectively. Allowed values are Matrixunit (std), GellMann (gm), Pauliproduct (pp), and Qutrit (qt) (or a custom basis object).
 Returns
None
 deriv_wrt_params(self, wrt_filter=None)¶
The elementwise derivative this operation.
Constructs 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)
 has_nonzero_hessian(self)¶
Whether this operation has a nonzero Hessian with respect to its parameters.
(i.e. whether it only depends linearly on its parameters or not)
 Returns
bool
 hessian_wrt_params(self, wrt_filter1=None, wrt_filter2=None)¶
Construct the Hessian of this operation 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)
 __setstate__(self, state)¶
 static convert_to_matrix(m)¶
Static method that converts a matrixlike object to a 2D numpy array.
 Parameters
m (array_like) – matrixlike object
 Returns
numpy array
 property chp_str(self)¶
A string suitable for printing to a CHP input file after probabilistically selecting operation.
 Returns
s (str) – String of CHP code
 pygsti.modelmembers.operations.linearop.finite_difference_deriv_wrt_params(operation, wrt_filter, eps=1e07)¶
Computes a finitedifference Jacobian for a LinearOperator object.
The returned value is a matrix whose columns are the vectorized derivatives of the flattened operation matrix with respect to a single operation parameter, matching the format expected from the operation’s deriv_wrt_params method.
 Parameters
operation (LinearOperator) – The operation object to compute a Jacobian for.
wrt_filter (list or numpy.ndarray) – List of parameter indices to filter the result by (as though derivative is only taken with respect to these parameters).
eps (float, optional) – The finite difference step to use.
 Returns
numpy.ndarray – An M by N matrix where M is the number of operation elements and N is the number of operation parameters.
 pygsti.modelmembers.operations.linearop.finite_difference_hessian_wrt_params(operation, wrt_filter1, wrt_filter2, eps=0.0001)¶
Computes a finitedifference Hessian for a LinearOperator object.
The returned value is a tensor whose leading dimension corresponds to the elements of the flattened operation matrix, and whose remaining two dimensions correspond to derivatives with respect to the operations parameters (potentially filtered). This matches the format expected from the operation’s hessian_wrt_params method.
 Parameters
operation (LinearOperator) – The operation object to compute a Hessian for.
wrt_filter1 (list or numpy.ndarray) – List of parameter indices to filter the result by (as though the 1st derivative is only taken with respect to these parameters).
wrt_filter2 (list or numpy.ndarray) – List of parameter indices to filter the result by (as though the 2nd derivative is only taken with respect to these parameters).
eps (float, optional) – The finite difference step to use.
 Returns
numpy.ndarray – An M by N1 by N2 tensor where M is the number of operation elements and N1 and N2 are numbers of operation parameters.