pygsti.protocols.modeltest

ModelTest Protocol objects

Module Contents

Classes

ModelTest

A protocol that tests how well a model agrees with a given set of data.

ModelTestCheckpoint

A class for storing intermediate results associated with running

class pygsti.protocols.modeltest.ModelTest(model_to_test, target_model=None, gaugeopt_suite=None, objfn_builder=None, badfit_options=None, set_trivial_gauge_group=True, verbosity=2, name=None)

Bases: pygsti.protocols.protocol.Protocol

A protocol that tests how well a model agrees with a given set of data.

Parameters

model_to_testModel

The model to compare with data when run() is called.

target_modelModel, optional

The ideal or desired model of perfect operations. It is often useful to bundle this together with model_to_test so that comparison metrics can be easily computed.

gaugeopt_suiteGSTGaugeOptSuite, optional

Specifies which gauge optimizations to perform on each estimate. Can also be any object that can be cast to a GSTGaugeOptSuite object, such as a string or list of strings (see below) specifying built-in sets of gauge optimizations. This object also optionally stores an alternate target model for gauge optimization. This model is used as the “target” for gauge- optimization (only), and is useful when you want to gauge optimize toward something other than the ideal target gates.

objfn_builderObjectiveFunctionBuilder

The objective function (builder) that is used to compare the model to data, i.e. the objective function that defines this model test.

badfit_optionsGSTBadFitOptions

Options specifing what constitutes a “bad fit” (or “failed test”) and what additional actions to take if and when this occurs.

set_trivial_gauge_groupbool, optional

A convenience flag that updates the default gauge group of model_to_test to the trivial gauge group before performing the test, so that no actual gauge optimization is performed (even if gaugeopt_suite is non-None).

verbosityint, optional

Level of detail printed to stdout.

namestr, optional

The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new Protocol object.

Parameters

namestr, optional

The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

Protocol

classmethod create_objective_builder(obj)

Creates objective function builders from obj that are commonly used in model tests.

Parameters
objobject

If obj is already an ObjectiveFunctionBuilder it is used directly. A dictionary is assumed to hold arguments of ObjectiveFunctionBuilder.simple(). A list or tuple is assumed to hold positional arguments of ObjectiveFunctionBuilder.__init__().

Returns

ObjectiveFunctionBuilder

run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable | None = None)

Run this protocol on data.

Parameters
dataProtocolData

The input data.

memlimitint, optional

A rough per-processor memory limit in bytes.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to run this protocol in parallel.

checkpointModelTestCheckpoint, optional (default None)

If specified use a previously generated checkpoint object to restart or warm start this run part way through.

checkpoint_pathstr, optional (default None)

A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run.

disable_checkpointingbool, optional (default False)

When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints.

simulatorForwardSimulator.Castable or None
Ignored if None. If not None, then we call

fwdsim = ForwardSimulator.cast(simulator),

and we set the .sim attribute of every Model we encounter to fwdsim.

Returns

ModelEstimateResults

class pygsti.protocols.modeltest.ModelTestCheckpoint(last_completed_iter=-1, last_completed_circuit_list=None, objfn_vals=None, chi2k_distributed_vals=None, name=None, parent=None)

Bases: pygsti.protocols.protocol.ProtocolCheckpoint

A class for storing intermediate results associated with running a ModelTest protocol’s run method to allow for restarting that method partway through.

Parameters

last_completed_iterint, optional (default -1)

Index of the last iteration what was successfully completed.

last_completed_circuit_listlist of Circuit objects, CircuitList or equivalent, optional (default None)

A list of Circuit objects corresponding to the last iteration successfully completed.

objfn_valslist, optional (default None)

A list of the current objective function values for each iteration/circuit list evaluated during the ModelTest protocol.

chi2k_distributed_valslist, optional (default None)
A list of the current objective function values for each iteration/circuit list

evaluated during the ModelTest protocol rescaled so as to have an expected chi-squared distribution under the null hypothesis of Wilks’ theorem.

namestr, optional (default None)

An optional name for the checkpoint. Note this is not necessarily the name used in the automatic generation of filenames when written to disk.

parentProtocolCheckpoint, optional (default None)

When specified this checkpoint object is treated as the child of another ProtocolCheckpoint object that acts as the parent. When present, the parent’s write method supersedes the child objects and is called when calling write on the child. Currently only used in the implementation of StandardGSTCheckpoint.