:py:mod:`pygsti.protocols.modeltest`
====================================

.. py:module:: pygsti.protocols.modeltest

.. autoapi-nested-parse::

   ModelTest Protocol objects






Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pygsti.protocols.modeltest.ModelTest
   pygsti.protocols.modeltest.ModelTestCheckpoint




.. py:class:: 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: :py:obj:`pygsti.protocols.protocol.Protocol`

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

   Parameters
   ----------
   model_to_test : Model
       The model to compare with data when :meth:`run` is called.

   target_model : Model, 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_suite : GSTGaugeOptSuite, optional
       Specifies which gauge optimizations to perform on each estimate.  Can also
       be any object that can be cast to a :class:`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_builder : ObjectiveFunctionBuilder
       The objective function (builder) that is used to compare the model to data,
       i.e. the objective function that defines this model test.

   badfit_options : GSTBadFitOptions
       Options specifing what constitutes a "bad fit" (or "failed test") and what
       additional actions to take if and when this occurs.

   set_trivial_gauge_group : bool, 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).

   verbosity : int, optional
       Level of detail printed to stdout.

   name : str, 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
   ----------
   name : str, 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

   .. py:attribute:: model_to_test

      

   .. py:attribute:: target_model
      :value: 'None'

      

   .. py:attribute:: gaugeopt_suite

      

   .. py:attribute:: badfit_options

      

   .. py:attribute:: verbosity
      :value: '2'

      

   .. py:attribute:: objfn_builders

      

   .. py:attribute:: profile
      :value: '1'

      

   .. py:attribute:: oplabel_aliases
      :value: 'None'

      

   .. py:attribute:: circuit_weights
      :value: 'None'

      

   .. py:attribute:: unreliable_ops
      :value: "('Gcnot', 'Gcphase', 'Gms', 'Gcn', 'Gcx', 'Gcz')"

      

   .. py:method:: create_objective_builder(obj)
      :classmethod:

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

      Parameters
      ----------
      obj : object
          If `obj` is already an :class:`ObjectiveFunctionBuilder` it is used directly.  A
          dictionary is assumed to hold arguments of :meth:`ObjectiveFunctionBuilder.simple`.
          A list or tuple is assumed to hold positional arguments of
          :meth:`ObjectiveFunctionBuilder.__init__`.

      Returns
      -------
      ObjectiveFunctionBuilder


   .. py:method:: run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None)

      Run this protocol on `data`.

      Parameters
      ----------
      data : ProtocolData
          The input data.

      memlimit : int, optional
          A rough per-processor memory limit in bytes.

      comm : mpi4py.MPI.Comm, optional
          When not ``None``, an MPI communicator used to run this protocol
          in parallel.

      checkpoint : ModelTestCheckpoint, optional (default None)
          If specified use a previously generated checkpoint object to restart
          or warm start this run part way through.

      checkpoint_path : str, 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_checkpointing : bool, 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.

      simulator : ForwardSimulator.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



.. py:class:: ModelTestCheckpoint(last_completed_iter=-1, last_completed_circuit_list=None, objfn_vals=None, chi2k_distributed_vals=None, name=None, parent=None)


   Bases: :py:obj:`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_iter : int, optional (default -1)
       Index of the last iteration what was successfully completed.

   last_completed_circuit_list : list of Circuit objects, CircuitList or equivalent, optional (default None)
       A list of Circuit objects corresponding to the last iteration successfully completed.

   objfn_vals : list, optional (default None)
       A list of the current objective function values for each iteration/circuit list
       evaluated during the ModelTest protocol.

   chi2k_distributed_vals : list, 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.
       
   name : str, 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. 

   parent : ProtocolCheckpoint, 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.


   .. py:attribute:: last_completed_iter
      :value: '-1'

      

   .. py:attribute:: last_completed_circuit_list
      :value: 'None'

      

   .. py:attribute:: objfn_vals
      :value: 'None'

      

   .. py:attribute:: chi2k_distributed_vals
      :value: 'None'