pygsti.models.gaugegroup
GaugeGroup and derived objects, used primarily in gauge optimization
Module Contents
Classes
A parameterized set (ideally a group) of gauge transformations. |
|
The element of a |
|
A gauge group element that represents the inverse action of another element. |
|
A gauge group based on the parameterization of a single LinearOperator. |
|
A gauge group based on the parameterization of a single LinearOperator. |
|
The element type for OpGaugeGroup-derived gauge groups |
|
A fully-parameterized gauge group. |
|
Element of a |
|
A gauge group spanning all trace-preserving (TP) gauge transformations. |
|
Element of a |
|
A gauge group consisting of just diagonal gauge-transform matrices. |
|
Element of a |
|
A gauge group consisting of just trace-preserving (TP) diagonal gauge-transform matrices. |
|
Element of a |
|
Element of a |
|
A gauge group consisting of unitary gauge-transform matrices. |
|
Gauge transformations which scale the SPAM and non-unital portions of the gates in a gate set. |
|
Element of a |
|
Similar to |
|
Element of |
|
A trivial gauge group with no degrees of freedom. |
|
Element of |
|
A subgroup of the unitary group on a Hilbert space H, where H has a direct sum structure. |
|
The element of a |
- class pygsti.models.gaugegroup.GaugeGroup(name: str)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializableA 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().
- name
- compute_element(param_vec: numpy.ndarray) GaugeGroupElement
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.NicelySerializableThe element of a
GaugeGroup, which represents a single gauge transformation.Creates a new GaugeGroupElement
- property transform_matrix_inverse: numpy.ndarray | None
The inverse of the gauge-transform matrix.
Returns
numpy.ndarray
- property num_params: int
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: numpy.ndarray | list | None = None) numpy.ndarray | 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() numpy.ndarray
Get the parameter vector corresponding to this transform.
Returns
numpy.ndarray
- from_vector(v: numpy.ndarray) None
Reinitialize this GaugeGroupElement using the the parameter vector v.
Parameters
- vnumpy.ndarray
A 1D array of length
num_params()
Returns
None
- inverse() InverseGaugeGroupElement
Creates a gauge group element that performs the inverse of this element.
Returns
InverseGaugeGroupElement
- class pygsti.models.gaugegroup.InverseGaugeGroupElement(gauge_group_el: GaugeGroupElement)
Bases:
GaugeGroupElementA 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_inverse: numpy.ndarray
The inverse of the gauge-transform matrix.
Returns
numpy.ndarray
- property num_params: int
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_element
- deriv_wrt_params(wrt_filter=None) numpy.ndarray
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() numpy.ndarray
Get the parameter vector corresponding to this transform.
Returns
numpy.ndarray
- from_vector(v: numpy.ndarray) None
Reinitialize this GaugeGroupElement using the the parameter vector v.
Parameters
- vnumpy.ndarray
A 1D array of length
num_params()
Returns
None
- inverse() GaugeGroupElement
Creates a gauge group element that performs the inverse of this element.
Returns
GaugeGroupElement
- class pygsti.models.gaugegroup.OpGaugeGroup(operation: pygsti.modelmembers.operations.LinearOperator, elementcls, name: str)
Bases:
GaugeGroupA 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: int
Return the number of parameters (degrees of freedom) of this gauge group.
Returns
int
- property initial_params: numpy.ndarray
Return a good (or standard) starting parameter vector, used to initialize a gauge optimization.
Returns
- numpy.ndarray
A 1D array of length
num_params().
- element
- compute_element(param_vec: numpy.ndarray)
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: pygsti.modelmembers.operations.LinearOperator, elementcls, name: str, basis)
Bases:
OpGaugeGroupA 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: pygsti.modelmembers.operations.LinearOperator)
Bases:
GaugeGroupElementThe 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 operation
- property transform_matrix_inverse: numpy.ndarray
The inverse of the gauge-transform matrix.
Returns
numpy.ndarray
- property num_params: int
Return the number of parameters (degrees of freedom) of this element.
Returns
int
- deriv_wrt_params(wrt_filter: list | numpy.ndarray | None = None) numpy.ndarray
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() numpy.ndarray
Get the parameter vector corresponding to this transform.
Returns
numpy.ndarray
- from_vector(v: numpy.ndarray) None
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: pygsti.baseobjs.StateSpace, model_basis: pygsti.baseobjs.basis.Basis | str | None = 'pp', evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupWithBasisA 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
Modelyou 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: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of a
FullGaugeGroupParameters
- 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: pygsti.baseobjs.StateSpace, model_basis: pygsti.baseobjs.basis.Basis | str | None = 'pp', evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupWithBasisA 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
Modelyou 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: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of a
TPGaugeGroupParameters
- 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.DiagGaugeGroup(state_space: pygsti.baseobjs.StateSpace, evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupA 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
Modelyou 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: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of a
DiagGaugeGroupParameters
- 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: pygsti.baseobjs.StateSpace, evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
TPGaugeGroupA 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
Modelyou 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
Modelyou might gauge-transform.
- class pygsti.models.gaugegroup.TPDiagGaugeGroupElement(operation: pygsti.modelmembers.operations.LinearOperator)
Bases:
TPGaugeGroupElementElement of a
TPDiagGaugeGroupParameters
- 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.UnitaryGaugeGroupElement(operation: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of a
UnitaryGaugeGroupParameters
- 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 operation: pygsti.modelmembers.operations.LinearOperator
- class pygsti.models.gaugegroup.UnitaryGaugeGroup(state_space: pygsti.baseobjs.StateSpace, basis: pygsti.baseobjs.basis.Basis | str, evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupWithBasisA 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
Modelyou 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.
- state_space
- compute_element(param_vec) UnitaryGaugeGroupElement
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.SpamGaugeGroup(state_space: pygsti.baseobjs.StateSpace, evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupGauge 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
Modelyou 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
Modelyou might gauge-transform.
- class pygsti.models.gaugegroup.SpamGaugeGroupElement(operation: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of a
SpamGaugeGroupParameters
- 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: pygsti.baseobjs.StateSpace, evotype: pygsti.evotypes.evotype.Evotype | str | None = 'default')
Bases:
OpGaugeGroupSimilar to
SpamGaugeGroupexcept 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
Modelyou 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
Modelyou might gauge-transform.
- class pygsti.models.gaugegroup.TPSpamGaugeGroupElement(operation: pygsti.modelmembers.operations.LinearOperator)
Bases:
OpGaugeGroupElementElement of
TPSpamGaugeGroupParameters
- 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: pygsti.baseobjs.StateSpace)
Bases:
GaugeGroupA 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
Modelyou 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: int
Return the number of parameters (degrees of freedom) of this gauge group.
Returns
int
- property initial_params: numpy.array
Return a good (or standard) starting parameter vector, used to initialize a gauge optimization.
Returns
- numpy.ndarray
A 1D array of length
num_params().
- state_space
- compute_element(param_vec: numpy.ndarray)
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:
GaugeGroupElementElement of
TrivialGaugeGroupParameters
- dimint
The Hilbert-Schmidt space dimension of the gauge group.
Creates a new trivial gauge group element of dimension dim. (so transform matrix is a dim by dim identity matrix).
- property transform_matrix_inverse: numpy.ndarry
The inverse of the gauge-transform matrix.
Returns
numpy.ndarray
- property num_params: int
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() numpy.ndarray
Get the parameter vector corresponding to this transform.
Returns
numpy.ndarray
- from_vector(v: numpy.ndarray) None
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.DirectSumUnitaryGroup(subgroups: Tuple[UnitaryGaugeGroup | TrivialGaugeGroup, Ellipsis], basis, name='Direct sum gauge group')
Bases:
GaugeGroupA subgroup of the unitary group on a Hilbert space H, where H has a direct sum structure.
Unitaries in this group are block diagonal and preserve the direct sum structure of H.
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().
- basis
- subgroups
- 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.DirectSumUnitaryGroupElement(subelements: Tuple[UnitaryGaugeGroupElement | TrivialGaugeGroupElement, Ellipsis], basis)
Bases:
GaugeGroupElementThe element of a
GaugeGroup, which represents a single gauge transformation.Creates a new GaugeGroupElement
- 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
- subelements
- basis
- abstractmethod 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
- from_vector(v)
Reinitialize this GaugeGroupElement using the the parameter vector v.
Parameters
- vnumpy.ndarray
A 1D array of length
num_params()
Returns
None