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.

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

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

property num_params(self)

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

Returns

int

compute_element(self, param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters

param_vec (numpy.ndarray) – A 1D array of length :method:`num_params`.

Returns

GaugeGroupElement

property initial_params(self)

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

Returns

numpy.ndarray – A 1D array of length :method:`num_params`.

class pygsti.models.gaugegroup.GaugeGroupElement

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

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

property transform_matrix(self)

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse(self)

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

deriv_wrt_params(self, 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_filter (list 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(self)

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(self, v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters

v (numpy.ndarray) – A 1D array of length :method:`num_params`

Returns

None

property num_params(self)

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

inverse(self)

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_el (GaugeGroupElement) – The element to invert.

property transform_matrix(self)

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse(self)

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

deriv_wrt_params(self, 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_filter (list 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(self)

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(self, v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters

v (numpy.ndarray) – A 1D array of length :method:`num_params`

Returns

None

property num_params(self)

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

inverse(self)

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
  • operation (LinearOperator) – The LinearOperator to base this Gauge group on.

  • elementcls (class) – The element class to use when implementing the element method.

  • name (str) – A name for this group - used for reporting what type of gauge optimization was performed.

property num_params(self)

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

Returns

int

compute_element(self, param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters

param_vec (numpy.ndarray) – A 1D array of length :method:`num_params`.

Returns

GaugeGroupElement

property initial_params(self)

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

Returns

numpy.ndarray – A 1D array of length :method:`num_params`.

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
class pygsti.models.gaugegroup.OpGaugeGroupElement(operation)

Bases: GaugeGroupElement

The element type for OpGaugeGroup-derived gauge groups

Parameters

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

property transform_matrix(self)

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse(self)

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

deriv_wrt_params(self, 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_filter (list 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(self)

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(self, v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters

v (numpy.ndarray) – A 1D array of length :method:`num_params`

Returns

None

property num_params(self)

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

Returns

int

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
class pygsti.models.gaugegroup.FullGaugeGroup(state_space, evotype='default')

Bases: OpGaugeGroup

A fully-parameterized gauge group.

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

Parameters
  • state_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.FullGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a FullGaugeGroup

Parameters

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

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

Bases: OpGaugeGroup

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_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.TPGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a TPGaugeGroup

Parameters

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

property transform_matrix_inverse(self)

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_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.DiagGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a DiagGaugeGroup

Parameters

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

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_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.TPDiagGaugeGroupElement(operation)

Bases: TPGaugeGroupElement

Element of a TPDiagGaugeGroup

Parameters

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

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

Bases: OpGaugeGroup

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_space (StateSpace) – 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.

  • basis (Basis or {"pp", "gm", "std"}) – The basis to use when parameterizing the Hamiltonian Lindblad terms.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
class pygsti.models.gaugegroup.UnitaryGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a UnitaryGaugeGroup

Parameters

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

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_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.SpamGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of a SpamGaugeGroup

Parameters

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

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_space (StateSpace) – 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.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

class pygsti.models.gaugegroup.TPSpamGaugeGroupElement(operation)

Bases: OpGaugeGroupElement

Element of TPSpamGaugeGroup

Parameters

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

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_space (StateSpace) – 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.

property num_params(self)

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

Returns

int

compute_element(self, param_vec)

Retrieve the element of this group corresponding to param_vec

Parameters

param_vec (numpy.ndarray) – A 1D array of length :method:`num_params`.

Returns

TrivialGaugeGroupElement

property initial_params(self)

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

Returns

numpy.ndarray – A 1D array of length :method:`num_params`.

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
class pygsti.models.gaugegroup.TrivialGaugeGroupElement(dim)

Bases: GaugeGroupElement

Element of TrivialGaugeGroup

Parameters

dim (int) – The Hilbert-Schmidt space dimension of the gauge group.

property transform_matrix(self)

The gauge-transform matrix.

Returns

numpy.ndarray

property transform_matrix_inverse(self)

The inverse of the gauge-transform matrix.

Returns

numpy.ndarray

deriv_wrt_params(self, 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_filter (list 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(self)

Get the parameter vector corresponding to this transform.

Returns

numpy.ndarray

from_vector(self, v)

Reinitialize this GaugeGroupElement using the the parameter vector v.

Parameters

v (numpy.ndarray) – A 1D array of length :method:`num_params`

Returns

None

property num_params(self)

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

Returns

int

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)