pygsti.algorithms.gaugeopt
GST gauge optimization algorithms
Module Contents
Functions

Optimize the gauge degrees of freedom of a model to that of a target. 

Optimize the gauge of a model using a custom objective function. 
 pygsti.algorithms.gaugeopt.gaugeopt_to_target(model, target_model, item_weights=None, cptp_penalty_factor=0, spam_penalty_factor=0, gates_metric='frobenius', spam_metric='frobenius', gauge_group=None, method='auto', maxiter=100000, maxfev=None, tol=1e08, oob_check_interval=0, convert_model_to=None, return_all=False, comm=None, verbosity=0, check_jac=False)
Optimize the gauge degrees of freedom of a model to that of a target.
Parameters
 modelModel
The model to gaugeoptimize
 target_modelModel
The model to optimize to. The metric used for comparing models is given by gates_metric and spam_metric.
 item_weightsdict, optional
Dictionary of weighting factors for gates and spam operators. Keys can be gate, state preparation, or POVM effect, as well as the special values “spam” or “gates” which apply the given weighting to all spam operators or gates respectively. Values are floating point numbers. Values given for specific gates or spam operators take precedence over “gates” and “spam” values. The precise use of these weights depends on the model metric(s) being used.
 cptp_penalty_factorfloat, optional
If greater than zero, the objective function also contains CPTP penalty terms which penalize nonCPTPness of the gates being optimized. This factor multiplies these CPTP penalty terms.
 spam_penalty_factorfloat, optional
If greater than zero, the objective function also contains SPAM penalty terms which penalize nonpositiveness of the state preps being optimized. This factor multiplies these SPAM penalty terms.
 gates_metric{“frobenius”, “fidelity”, “tracedist”}, optional
The metric used to compare gates within models. “frobenius” computes the normalized sqrt(sumofsquareddifferences), with weights multiplying the squared differences (see
Model.frobeniusdist()
). “fidelity” and “tracedist” sum the individual infidelities or trace distances of each gate, weighted by the weights. spam_metric{“frobenius”, “fidelity”, “tracedist”}, optional
The metric used to compare spam vectors within models. “frobenius” computes the normalized sqrt(sumofsquareddifferences), with weights multiplying the squared differences (see
Model.frobeniusdist()
). “fidelity” and “tracedist” sum the individual infidelities or trace distances of each “SPAM gate”, weighted by the weights. gauge_groupGaugeGroup, optional
The gauge group which defines which gauge trasformations are optimized over. If None, then the model’s default gauge group is used.
 methodstring, optional
The method used to optimize the objective function. Can be any method known by scipy.optimize.minimize such as ‘BFGS’, ‘NelderMead’, ‘CG’, ‘LBFGSB’, or additionally:
‘auto’ – ‘ls’ when allowed, otherwise ‘LBFGSB’
‘ls’ – custom leastsquares optimizer.
‘custom’ – custom CG that often works better than ‘CG’
‘supersimplex’ – repeated application of ‘NelderMead’ to converge it
‘basinhopping’ – scipy.optimize.basinhopping using LBFGSB as a local optimizer
‘swarm’ – particle swarm global optimization algorithm
‘evolve’ – evolutionary global optimization algorithm using DEAP
‘brute’ – Experimental: scipy.optimize.brute using 4 points along each dimensions
 maxiterint, optional
Maximum number of iterations for the gauge optimization.
 maxfevint, optional
Maximum number of function evaluations for the gauge optimization. Defaults to maxiter.
 tolfloat, optional
The tolerance for the gauge optimization.
 oob_check_intervalint, optional
If greater than zero, gauge transformations are allowed to fail (by raising any exception) to indicate an outofbounds condition that the gauge optimizer will avoid. If zero, then any gaugetransform failures just terminate the optimization.
 convert_model_tostr, dict, list, optional
For use when model is an ExplicitOpModel. When not None, calls model.convert_members_inplace(convert_model_to, set_default_gauge_group=False) if convert_model_to is a string, model.convert_members_inplace(**convert_model_to) if it is a dict, and repeated calls to either of the above instances when convert_model_to is a list or tuple prior to performing the gauge optimization. This allows the gauge optimization to be performed using a differently constrained model.
 return_allbool, optional
When True, return best “goodness” value and gauge matrix in addition to the gauge optimized model.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 verbosityint, optional
How much detail to send to stdout.
 check_jacbool
When True, check least squares analytic jacobian against finite differences
Returns
model : if return_all == False
 (goodnessMin, gaugeMx, model)if return_all == True
Where goodnessMin is the minimum value of the goodness function (the best ‘goodness’) found, gaugeMx is the gauge matrix used to transform the model, and model is the final gaugetransformed model.
 pygsti.algorithms.gaugeopt.gaugeopt_custom(model, objective_fn, gauge_group=None, method='LBFGSB', maxiter=100000, maxfev=None, tol=1e08, oob_check_interval=0, return_all=False, jacobian_fn=None, comm=None, verbosity=0)
Optimize the gauge of a model using a custom objective function.
Parameters
 modelModel
The model to gaugeoptimize
 objective_fnfunction
The function to be minimized. The function must take a single Model argument and return a float.
 gauge_groupGaugeGroup, optional
The gauge group which defines which gauge trasformations are optimized over. If None, then the model’s default gauge group is used.
 methodstring, optional
The method used to optimize the objective function. Can be any method known by scipy.optimize.minimize such as ‘BFGS’, ‘NelderMead’, ‘CG’, ‘LBFGSB’, or additionally:
‘custom’ – custom CG that often works better than ‘CG’
‘supersimplex’ – repeated application of ‘NelderMead’ to converge it
‘basinhopping’ – scipy.optimize.basinhopping using LBFGSB as a local optimizer
‘swarm’ – particle swarm global optimization algorithm
‘evolve’ – evolutionary global optimization algorithm using DEAP
‘brute’ – Experimental: scipy.optimize.brute using 4 points along each dimensions
 maxiterint, optional
Maximum number of iterations for the gauge optimization.
 maxfevint, optional
Maximum number of function evaluations for the gauge optimization. Defaults to maxiter.
 tolfloat, optional
The tolerance for the gauge optimization.
 oob_check_intervalint, optional
If greater than zero, gauge transformations are allowed to fail (by raising any exception) to indicate an outofbounds condition that the gauge optimizer will avoid. If zero, then any gaugetransform failures just terminate the optimization.
 return_allbool, optional
When True, return best “goodness” value and gauge matrix in addition to the gauge optimized model.
 jacobian_fnfunction, optional
The jacobian of objective_fn. The function must take three parameters, 1) the untransformed Model, 2) the transformed Model, and 3) the GaugeGroupElement representing the transformation that brings the first argument into the second.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 verbosityint, optional
How much detail to send to stdout.
Returns
 model
if return_all == False
 (goodnessMin, gaugeMx, model)
if return_all == True where goodnessMin is the minimum value of the goodness function (the best ‘goodness’) found, gaugeMx is the gauge matrix used to transform the model, and model is the final gaugetransformed model.