pygsti.models.gaugegroup

GaugeGroup and derived objects, used primarily in gauge optimization

Module Contents

Classes

GaugeGroup

A parameterized set (ideally a group) of gauge transformations.

GaugeGroupElement

The element of a GaugeGroup, which represents a single gauge transformation.

InverseGaugeGroupElement

A gauge group element that represents the inverse action of another element.

OpGaugeGroup

A gauge group based on the parameterization of a single LinearOperator.

OpGaugeGroupWithBasis

A gauge group based on the parameterization of a single LinearOperator.

OpGaugeGroupElement

The element type for OpGaugeGroup-derived gauge groups

FullGaugeGroup

A fully-parameterized gauge group.

FullGaugeGroupElement

Element of a FullGaugeGroup

TPGaugeGroup

A gauge group spanning all trace-preserving (TP) gauge transformations.

TPGaugeGroupElement

Element of a TPGaugeGroup

DiagGaugeGroup

A gauge group consisting of just diagonal gauge-transform matrices.

DiagGaugeGroupElement

Element of a DiagGaugeGroup

TPDiagGaugeGroup

A gauge group consisting of just trace-preserving (TP) diagonal gauge-transform matrices.

TPDiagGaugeGroupElement

Element of a TPDiagGaugeGroup

UnitaryGaugeGroup

A gauge group consisting of unitary gauge-transform matrices.

UnitaryGaugeGroupElement

Element of a UnitaryGaugeGroup

SpamGaugeGroup

Gauge transformations which scale the SPAM and non-unital portions of the gates in a gate set.

SpamGaugeGroupElement

Element of a SpamGaugeGroup

TPSpamGaugeGroup

Similar to SpamGaugeGroup except with TP constrains.

TPSpamGaugeGroupElement

Element of TPSpamGaugeGroup

TrivialGaugeGroup

A trivial gauge group with no degrees of freedom.

TrivialGaugeGroupElement

Element of TrivialGaugeGroup

class pygsti.models.gaugegroup.GaugeGroup(name)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

A parameterized set (ideally a group) of gauge transformations.

Specifies the “optimization space” explored by gauge optimization algorithms. This base class is used to define the common interface of all types of gauge “groups” (even though they need not be groups in the mathematical sense).

Parameters

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

Creates a new gauge group object

Parameters

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

property num_params

Return the number of parameters (degrees of freedom) of this gauge group.

Returns

int

property initial_params

Return a good (or standard) starting parameter vector, used to initialize a gauge optimization.

Returns
numpy.ndarray

A 1D array of length num_params().

compute_element(param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters
param_vecnumpy.ndarray

A 1D array of length num_params().

Returns

GaugeGroupElement

class pygsti.models.gaugegroup.GaugeGroupElement

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

The element of a GaugeGroup, which represents a single gauge transformation.

Creates a new GaugeGroupElement

property transform_matrix

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

property num_params

Return the number of parameters of this gauge group element.

(This is equivalent to the number of parameters of the parent gauge group.)

Returns

int

deriv_wrt_params(wrt_filter=None)

Computes the derivative of the gauge group at this element.

That is, the derivative of a general element with respect to the gauge group’s parameters, evaluated at this element.

Parameters

wrt_filterlist or numpy.ndarray, optional

Indices of the gauge group parameters to differentiate with respect to. If None, differentiation is performed with respect to all the group’s parameters.

Returns

numpy.ndarray

to_vector()

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters

vnumpy.ndarray

A 1D array of length num_params()

Returns

None

inverse()

Creates a gauge group element that performs the inverse of this element.

Returns

InverseGaugeGroupElement

class pygsti.models.gaugegroup.InverseGaugeGroupElement(gauge_group_el)

Bases: GaugeGroupElement

A gauge group element that represents the inverse action of another element.

Parameters

gauge_group_elGaugeGroupElement

The element to invert.

Creates a new GaugeGroupElement

property transform_matrix

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

property num_params

Return the number of parameters of this gauge group element.

(This is equivalent to the number of parameters of the parent gauge group.)

Returns

int

deriv_wrt_params(wrt_filter=None)

Computes the derivative of the gauge group at this element.

That is, the derivative of a general element with respect to the gauge group’s parameters, evaluated at this element.

Parameters
wrt_filterlist or numpy.ndarray, optional

Indices of the gauge group parameters to differentiate with respect to. If None, differentiation is performed with respect to all the group’s parameters.

Returns

numpy.ndarray

to_vector()

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters
vnumpy.ndarray

A 1D array of length num_params()

Returns

None

inverse()

Creates a gauge group element that performs the inverse of this element.

Returns

GaugeGroupElement

class pygsti.models.gaugegroup.OpGaugeGroup(operation, elementcls, name)

Bases: GaugeGroup

A gauge group based on the parameterization of a single LinearOperator.

The parameterization of this linear operator is used to parameterize the gauge-transform matrix. This class is used as the base class for sevearl other of gauge group classes.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

property num_params

Return the number of parameters (degrees of freedom) of this gauge group.

Returns

int

property initial_params

Return a good (or standard) starting parameter vector, used to initialize a gauge optimization.

Returns
numpy.ndarray

A 1D array of length num_params().

compute_element(param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters
param_vecnumpy.ndarray

A 1D array of length num_params().

Returns

GaugeGroupElement

class pygsti.models.gaugegroup.OpGaugeGroupWithBasis(operation, elementcls, name, basis)

Bases: OpGaugeGroup

A gauge group based on the parameterization of a single LinearOperator.

The parameterization of this linear operator is used to parameterize the gauge-transform matrix. This class is used as the base class for sevearl other of gauge group classes.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

class pygsti.models.gaugegroup.OpGaugeGroupElement(operation)

Bases: GaugeGroupElement

The element type for OpGaugeGroup-derived gauge groups

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Create a new element based on operation

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

property transform_matrix

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

property num_params

Return the number of parameters (degrees of freedom) of this element.

Returns

int

deriv_wrt_params(wrt_filter=None)

Computes the derivative of the gauge group at this element.

That is, the derivative of a general element with respect to the gauge group’s parameters, evaluated at this element.

Parameters
wrt_filterlist or numpy.ndarray, optional

Indices of the gauge group parameters to differentiate with respect to. If None, differentiation is performed with respect to all the group’s parameters.

Returns

numpy.ndarray

to_vector()

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters
vnumpy.ndarray

A 1D array of length num_params()

Returns

None

class pygsti.models.gaugegroup.FullGaugeGroup(state_space, model_basis='pp', evotype='default')

Bases: OpGaugeGroupWithBasis

A fully-parameterized gauge group.

Every element of the gauge transformation matrix is an independent parameter.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

model_basisBasis or str, optional
The basis used for the superoperators of the model that this gauge

group will act on.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

class pygsti.models.gaugegroup.FullGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a FullGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.TPGaugeGroup(state_space, model_basis='pp', evotype='default')

Bases: OpGaugeGroupWithBasis

A gauge group spanning all trace-preserving (TP) gauge transformations.

Implemented as a gauge transformation matrix whose first row is locked as [1,0,0…0] and where every other element is an independent parameter.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

model_basisBasis or str, optional
The basis used for the superoperators of the model that this gauge

group will act on.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

class pygsti.models.gaugegroup.TPGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a TPGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

property transform_matrix_inverse

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

class pygsti.models.gaugegroup.DiagGaugeGroup(state_space, evotype='default')

Bases: OpGaugeGroup

A gauge group consisting of just diagonal gauge-transform matrices.

(Each diagonal element is a separate parameter.)

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

class pygsti.models.gaugegroup.DiagGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a DiagGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.TPDiagGaugeGroup(state_space, evotype='default')

Bases: TPGaugeGroup

A gauge group consisting of just trace-preserving (TP) diagonal gauge-transform matrices.

That is, where the first ([0,0]) element is fixed at 1.0, and each subsequent diagonal element is a separate parameter.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new gauge group with gauge-transform dimension dim, which should be the same as mdl.dim where mdl is a Model you might gauge-transform.

class pygsti.models.gaugegroup.TPDiagGaugeGroupElement(operation)

Bases: TPGaugeGroupElement

Element of a TPDiagGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.UnitaryGaugeGroup(state_space, basis, evotype='default')

Bases: OpGaugeGroupWithBasis

A gauge group consisting of unitary gauge-transform matrices.

This group includes those (superoperator) transformation matrices that correspond to unitary evolution. Parameterization is performed via a Lindblad parametrizaton with only Hamiltonian terms.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

basisBasis or {“pp”, “gm”, “std”}

The basis to use when parameterizing the Hamiltonian Lindblad terms.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new OpGaugeGroup.

Parameters

operationLinearOperator

The LinearOperator to base this Gauge group on.

elementclsclass

The element class to use when implementing the compute_element method.

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

class pygsti.models.gaugegroup.UnitaryGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a UnitaryGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.SpamGaugeGroup(state_space, evotype='default')

Bases: OpGaugeGroup

Gauge transformations which scale the SPAM and non-unital portions of the gates in a gate set.

A 2-dimensional gauge group spanning transform matrices of the form ::
[ [ a 0 … 0] where a and b are the 2 parameters. These diagonal

[ 0 b … 0] transform matrices do not affect the SPAM operations [ . . … .] much more than typical near-unital and TP operations, and [ 0 0 … b] ] so we call this group of transformations the “SPAM gauge”.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new gauge group with gauge-transform dimension dim, which should be the same as mdl.dim where mdl is a Model you might gauge-transform.

class pygsti.models.gaugegroup.SpamGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a SpamGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.TPSpamGaugeGroup(state_space, evotype='default')

Bases: OpGaugeGroup

Similar to SpamGaugeGroup except with TP constrains.

This means the [0,0] element of each transform matrix is fixed at 1.0 (so all gauge transforms are trace preserving), leaving just a single degree of freedom.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

evotypeEvotype or str, optional

The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Create a new gauge group with gauge-transform dimension dim, which should be the same as mdl.dim where mdl is a Model you might gauge-transform.

class pygsti.models.gaugegroup.TPSpamGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of TPSpamGaugeGroup

Parameters

operationLinearOperator

The operation to base this element on. It provides both parameterization information and the gauge transformation matrix itself.

Creates a new gauge group element based on operation, which is assumed to have the correct parameterization.

class pygsti.models.gaugegroup.TrivialGaugeGroup(state_space)

Bases: GaugeGroup

A trivial gauge group with no degrees of freedom.

Useful for telling pyGSTi that you don’t want to do any gauge optimization within the framework common to the other gauge groups. Using a TrivialGaugeGroup instead of None in gauge optimization will prevent pyGSTi from wondering if you meant to not-gauge-optimize and displaying warning messages.

Parameters

state_spaceStateSpace

The state space for this gauge group. This is the state space that elements of the gauge group act on. This should be the same as mdl.state_space where mdl is a Model you want to gauge-transform.

Creates a new gauge group object

Parameters

namestr

A name for this group - used for reporting what type of gauge optimization was performed.

property num_params

Return the number of parameters (degrees of freedom) of this gauge group.

Returns

int

property initial_params

Return a good (or standard) starting parameter vector, used to initialize a gauge optimization.

Returns
numpy.ndarray

A 1D array of length num_params().

compute_element(param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters
param_vecnumpy.ndarray

A 1D array of length num_params().

Returns

TrivialGaugeGroupElement

class pygsti.models.gaugegroup.TrivialGaugeGroupElement(dim)

Bases: GaugeGroupElement

Element of TrivialGaugeGroup

Parameters

dimint

The Hilbert-Schmidt space dimension of the gauge group.

Creates a new trivial gauge group element of dimension dim. (so transform matirx is a dim by dim identity matrix).

property transform_matrix

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

property num_params

Return the number of parameters (degrees of freedom) of this element.

Returns

int

deriv_wrt_params(wrt_filter=None)

Computes the derivative of the gauge group at this element.

That is, the derivative of a general element with respect to the gauge group’s parameters, evaluated at this element.

Parameters
wrt_filterlist or numpy.ndarray, optional

Indices of the gauge group parameters to differentiate with respect to. If None, differentiation is performed with respect to all the group’s parameters.

Returns

numpy.ndarray

to_vector()

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters
vnumpy.ndarray

A 1D array of length num_params()

Returns

None