:py:mod:`pygsti.protocols.estimate` =================================== .. py:module:: pygsti.protocols.estimate .. autoapi-nested-parse:: Defines the Estimate class. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.protocols.estimate.CRFkey pygsti.protocols.estimate.Estimate .. py:class:: CRFkey Bases: :py:obj:`tuple` .. py:attribute:: model .. py:attribute:: circuit_list .. py:class:: Estimate(parent, models=None, parameters=None, extra_parameters=None) Bases: :py:obj:`pygsti.baseobjs.mongoserializable.MongoSerializable` A class encapsulating the `Model` objects related to a single GST estimate up-to-gauge freedoms. Thus, this class holds the "iteration" `Model`s leading up to a final `Model`, and then different gauge optimizations of the final set. Parameters ---------- parent : Results The parent Results object containing the dataset and circuit structure used for this Estimate. models : dict, optional A dictionary of models to included in this estimate parameters : dict, optional A dictionary of parameters associated with how these models were obtained. Initialize an empty Estimate object. Parameters ---------- parent : Results The parent Results object containing the dataset and circuit structure used for this Estimate. models : dict, optional A dictionary of models to included in this estimate parameters : dict, optional A dictionary of parameters associated with how these models were obtained. .. py:property:: parameters .. py:property:: goparameters .. py:attribute:: collection_name :value: "'pygsti_estimates'" .. py:attribute:: parent .. py:attribute:: circuit_weights .. py:attribute:: protocol .. py:attribute:: profiler .. py:attribute:: final_objfn_builder .. py:attribute:: extra_parameters :value: 'None' .. py:attribute:: models .. py:attribute:: num_iterations :value: '0' .. py:attribute:: confidence_region_factories .. py:attribute:: meta .. py:attribute:: auxfile_types .. py:method:: from_dir(dirname, quick_load=False) :classmethod: Initialize a new Protocol object from `dirname`. quick_load : bool, optional Setting this to True skips the loading of components that may take a long time to load. Parameters ---------- dirname : str The directory name. quick_load : bool, optional Setting this to True skips the loading of components that may take a long time to load. Returns ------- Protocol .. py:method:: create_gst_estimate(parent, target_model=None, seed_model=None, models_by_iter=None, parameters=None) :classmethod: Initialize an empty Estimate object. Parameters ---------- parent : Results The parent Results object containing the dataset and circuit structure used for this Estimate. target_model : Model The target model used when optimizing the objective. seed_model : Model The initial model used to seed the iterative part of the objective optimization. Typically this is obtained via LGST. models_by_iter : list of Models The estimated model at each GST iteration. Typically these are the estimated models *before* any gauge optimization is performed. parameters : dict A dictionary of parameters associated with how these models were obtained. Returns ------- Estimate .. py:method:: write(dirname) Write this protocol to a directory. Parameters ---------- dirname : str The directory name to write. This directory will be created if needed, and the files in an existing directory will be overwritten. Returns ------- None .. py:method:: remove_from_mongodb(mongodb_collection, doc_id, session=None) :classmethod: Remove an Estimate from a MongoDB database. Returns ------- bool `True` if the specified experiment design was removed, `False` if it didn't exist. .. py:method:: retrieve_start_model(goparams) Returns the starting model for the gauge optimization given by `goparams`. This has a particular (and perhaps singular) use for deciding whether the gauge-optimized model for one estimate can be simply copied to another estimate, without actually re-gauge-optimizing. Parameters ---------- goparams : dict or list A dictionary of gauge-optimization parameters, just as in :func:`add_gaugeoptimized`. Returns ------- Model .. py:method:: add_gaugeoptimized(goparams, model=None, label=None, comm=None, verbosity=None) Adds a gauge-optimized Model (computing it if needed) to this object. Parameters ---------- goparams : dict or list A dictionary of gauge-optimization parameters, typically arguments to :func:`gaugeopt_to_target`, specifying how the gauge optimization was (or should be) performed. When `model` is `None` (and this function computes the model internally) the keys and values of this dictionary must correspond to allowed arguments of :func:`gaugeopt_to_target`. By default, :func:`gaugeopt_to_target`'s first two arguments, the `Model` to optimize and the target, are taken to be `self.models['final iteration estimate']` and self.models['target']. This argument can also be a *list* of such parameter dictionaries, which specifies a multi-stage gauge- optimization whereby the output of one stage is the input of the next. model : Model, optional The gauge-optimized model to store. If None, then this model is computed by calling :func:`gaugeopt_to_target` with the contents of `goparams` as arguments as described above. label : str, optional A label for this gauge-optimized model, used as the key in this object's `models` and `goparameters` member dictionaries. If None, then the next available "go", where is a non-negative integer, is used as the label. comm : mpi4py.MPI.Comm, optional A default MPI communicator to use when one is not specified as the 'comm' element of/within `goparams`. verbosity : int, optional An integer specifying the level of detail printed to stdout during the calculations performed in this function. If not None, this value will override any verbosity values set within `goparams`. Returns ------- None .. py:method:: add_confidence_region_factory(model_label='final iteration estimate', circuits_label='final') Creates a new confidence region factory. An instance of :class:`ConfidenceRegionFactory` serves to create confidence intervals and regions in reports and elsewhere. This function creates such a factory, which is specific to a given `Model` (given by this object's `.models[model_label]` ) and circuit list (given by the parent `Results`'s `.circuit_lists[gastrings_label]` list). Parameters ---------- model_label : str, optional The label of a `Model` held within this `Estimate`. circuits_label : str, optional The label of a circuit list within this estimate's parent `Results` object. Returns ------- ConfidenceRegionFactory The newly created factory (also cached internally) and accessible via the :func:`create_confidence_region_factory` method. .. py:method:: has_confidence_region_factory(model_label='final iteration estimate', circuits_label='final') Checks whether a confidence region factory for the given model and circuit list labels exists. Parameters ---------- model_label : str, optional The label of a `Model` held within this `Estimate`. circuits_label : str, optional The label of a circuit list within this estimate's parent `Results` object. Returns ------- bool .. py:method:: create_confidence_region_factory(model_label='final iteration estimate', circuits_label='final', create_if_needed=False) Retrieves a confidence region factory for the given model and circuit list labels. For more information about confidence region factories, see :func:`add_confidence_region_factory`. Parameters ---------- model_label : str, optional The label of a `Model` held within this `Estimate`. circuits_label : str, optional The label of a circuit list within this estimate's parent `Results` object. create_if_needed : bool, optional If True, a new confidence region factory will be created if none exists. Otherwise a `KeyError` is raised when the requested factory doesn't exist. Returns ------- ConfidenceRegionFactory .. py:method:: gauge_propagate_confidence_region_factory(to_model_label, from_model_label='final iteration estimate', circuits_label='final', eps=0.001, verbosity=0) Propagates a confidence region among gauge-equivalent models. More specifically, this function propagates an existing "reference" confidence region for a Model "G0" to a new confidence region for a gauge-equivalent model "G1". When successful, a new confidence region factory is created for the `.models[to_model_label]` `Model` and `circuits_label` gate string list from the existing factory for `.models[from_model_label]`. Parameters ---------- to_model_label : str The key into this `Estimate` object's `models` and `goparameters` dictionaries that identifies the final gauge-optimized result to create a factory for. This gauge optimization must have begun at "from" reference model, i.e., `models[from_model_label]` must equal (by frobeinus distance) `goparameters[to_model_label]['model']`. from_model_label : str, optional The key into this `Estimate` object's `models` dictionary that identifies the reference model. circuits_label : str, optional The key of the circuit list (within the parent `Results`'s `.circuit_lists` dictionary) that identifies the circuit list used by the old (&new) confidence region factories. eps : float, optional A small offset used for constructing finite-difference derivatives. Usually the default value is fine. verbosity : int, optional A non-negative integer indicating the amount of detail to print to stdout. Returns ------- ConfidenceRegionFactory Note: this region is also stored internally and as such the return value of this function can often be ignored. .. py:method:: create_effective_dataset(return_submxs=False) Generate a `DataSet` containing the effective counts as dictated by the "weights" parameter. An estimate's `self.parameters['weights']` value specifies a dictionary of circuits weights, which modify (typically *reduce*) the counts given in its (parent's) data set. This function rescales the actual data contained in this Estimate's parent :class:`ModelEstimteResults` object according to the estimate's "weights" parameter. The scaled data set is returned, along with (optionall) a list-of-lists of matrices containing the scaling values which can be easily plotted via a `ColorBoxPlot`. Parameters ---------- return_submxs : boolean If true, also return a list-of-lists of matrices containing the scaling values, as described above. Returns ------- ds : DataSet The "effective" (scaled) data set. subMxs : list-of-lists Only returned if `return_submxs == True`. Contains the scale values (see above). .. py:method:: final_mdc_store(resource_alloc=None, array_types=('e', 'ep')) The final (not intermediate) model-dataset-circuit storage object (MDC store) for this estimate. This object is created and cached as needed, and combined the final model, data set, and circuit list for this estimate. Parameters ---------- resource_alloc : ResourceAllocation The resource allocation object used to create the MDC store. This can just be left as `None` unless multiple processors are being utilized. Note that this argument is only used when a MDC store needs to be created -- if this estimate has already created one then this argument is ignored. array_types : tuple A tuple of array types passed to the MDC store constructor (if a new MDC store needs to be created). These affect how memory is allocated within the MDC store object and can enable (or disable) the use of certain MDC store functionality later on (e.g. the use of Jacobian or Hessian quantities). Returns ------- ModelDatasetCircuitsStore .. py:method:: final_objective_fn(resource_alloc=None) The final (not intermediate) objective function object for this estimate. This object is created and cached as needed, and is the evaluated (and sometimes optimized) objective function associated with this estimate. Often this is a log-likelihood or chi-squared function, or a close variant. Parameters ---------- resource_alloc : ResourceAllocation The resource allocation object used to create the MDC store underlying the objective function. This can just be left as `None` unless multiple processors are being utilized. Note that this argument is only used when an underlying MDC store needs to be created -- if this estimate has already created a MDC store then this argument is ignored. Returns ------- MDCObjectiveFunction .. py:method:: final_objective_fn_cache(resource_alloc=None) The final (not intermediate) *serializable* ("cached") objective function object for this estimate. This is an explicitly serializable version of the final objective function, useful because is often doesn't need be constructed. To become serializable, however, the objective function is stripped of any MPI comm or multi-processor information (since this may be different between loading and saving). This makes the cached objective function convenient for fast calls/usages of the objective function. Parameters ---------- resource_alloc : ResourceAllocation The resource allocation object used to create the MDC store underlying the objective function. This can just be left as `None` unless multiple processors are being utilized - and in this case the *cached* objective function doesn't even benefit from these processors (but calls to :meth:`final_objective_fn` will return an objective function setup for multiple processors). Note that this argument is only used when there is no existing cached objective function and an underlying MDC store needs to be created. Returns ------- CachedObjectiveFunction .. py:method:: misfit_sigma(resource_alloc=None) Returns the number of standard deviations (sigma) of model violation. Parameters ---------- resource_alloc : ResourceAllocation, optional What resources are available for this computation. Returns ------- float .. py:method:: view(gaugeopt_keys, parent=None) Creates a shallow copy of this Results object containing only the given gauge-optimization keys. Parameters ---------- gaugeopt_keys : str or list, optional Either a single string-value gauge-optimization key or a list of such keys. If `None`, then all gauge-optimization keys are retained. parent : Results, optional The parent `Results` object of the view. If `None`, then the current `Estimate`'s parent is used. Returns ------- Estimate .. py:method:: copy() Creates a copy of this Estimate object. Returns ------- Estimate .. py:method:: set_parent(parent) Sets the parent object of this estimate. This is used, for instance, to re-establish parent-child links after loading objects from disk. Parameters ---------- parent : ModelEstimateResults This object's parent. Returns ------- None