pygsti.protocols.gst.ModelEstimateResults

class ModelEstimateResults(data, protocol_instance, init_circuits=True)

Bases: ProtocolResults

A results object that holds model estimates.

Parameters:

• data (ProtocolData) – The experimental data these results are generated from.

• protocol_instance (Protocol) – The protocol that generated these results.

• init_circuits (bool, optional) – Whether self.circuit_lists should be initialized or not. (In special cases, this can be disabled for speed.)

dataset

The underlying data set.

Type:

DataSet

Initialize an empty Results object.

Methods

__init__(data, protocol_instance[, ...])	Initialize an empty Results object.
add_estimate(estimate[, estimate_key, ...])	Add a set of Model estimates to this Results object.
add_estimates(results[, estimates_to_add, ...])	Add some or all of the estimates from results to self, possibly making copies in the process.
add_hessians([estimate_names, ...])	Compute and store objective-function Hessians for estimates in this results object.
add_model_test(target_model, themodel[, ...])	Add a new model-test (i.e. non-optimized) estimate to this Results object.
add_mongodb_write_ops(write_ops, mongodb[, ...])	Accumulate write and update operations for writing this object to a MongoDB database.
copy()	Creates a copy of this ModelEstimateResults object.
from_dir(dirname, name[, preloaded_data, ...])	Initialize a new ModelEstimateResults object from dirname / results / name.
from_mongodb(mongodb, doc_id, **kwargs)	Create and initialize an object from a MongoDB instance.
from_mongodb_doc(mongodb, collection_name, ...)	Create and initialize an object from a MongoDB instance and pre-loaded primary document.
remove_from_mongodb(mongodb, doc_id[, ...])	Remove the documents corresponding to an instance of this class from a MongoDB database.
remove_me_from_mongodb(mongodb[, session, ...])
rename_estimate(old_name, new_name)	Rename an estimate in this Results object.
to_dataframe([pivot_valuename, pivot_value, ...])	Convert these results into Pandas dataframe.
to_nameddict()	Convert these results into nested NamedDict objects.
view(estimate_keys[, gaugeopt_keys])	Creates a shallow copy of this Results object containing only the given estimate.
write([dirname, data_already_written])	Write these protocol results to a directory.
write_to_mongodb(mongodb[, session, ...])	Write this object to a MongoDB database.

Attributes

collection_name
dataset	The underlying data set.

add_estimate(estimate, estimate_key='default', silent_steal=False)

Add a set of Model estimates to this Results object.

Parameters:

• estimate (Estimate) – The estimate to add.

• estimate_key (str, optional) – The key or label used to identify this estimate.

• silent_steal (bool, optional) – If silent_steal is True, then then we can update estimate.parent without regard to its current value. If silent_steal is False and estimate.parent is neither None nor self, then we update self with a deep-copy of estimate.

Return type:

None

add_estimates(results, estimates_to_add=None, silent_steal=False)

Add some or all of the estimates from results to self, possibly making copies in the process.

Parameters:

• results (Results) – The object to import estimates from. Note that this object must contain the same data set and gate sequence information as the importing object or an error is raised.

• estimates_to_add (list, optional) – A list of estimate keys to import from results. If None, then all the estimates contained in results are imported.

• silent_steal (bool, optional) – Consider some est in results.estimates.values(). If silent_steal is True, then then we can update est.parent without regard to its current value. If silent_steal is False and est.parent is neither None nor self, then we update self with a deep-copy of est.

Return type:

None

add_hessians(estimate_names=None, compute_hessian_kwargs=None, project_hessian_kwargs=None)

Compute and store objective-function Hessians for estimates in this results object.

For each named estimate (except ‘Target’) and each of its gauge-optimized models, this method creates a confidence region factory for the ‘final’ circuit list, computes the Hessian of the final objective function at that model, and projects it onto the model’s non-gauge parameter space. Once this has run, report generation with a not-None confidence_level can render error bars for the affected estimates.

Models simulated with a MatrixForwardSimulator are switched to a MapForwardSimulator first, since that is the only forward simulator that can compute objective-function Hessians with a reasonable amount of memory.

Parameters:

• estimate_names (list of str, optional) – Names of the estimates (keys of self.estimates) to process. If None, all estimates are processed. The ‘Target’ estimate is always skipped.

• compute_hessian_kwargs (dict, optional) – Keyword arguments forwarded to ConfidenceRegionFactory.compute_hessian() (e.g. comm, mem_limit).

• project_hessian_kwargs (dict, optional) – Keyword arguments forwarded to ConfidenceRegionFactory.project_hessian(). If no ‘projection_type’ is given, ‘intrinsic error’ is used.

Return type:

None

add_model_test(target_model, themodel, estimate_key='test', gaugeopt_keys='auto', verbosity=2, simulator=None)

Add a new model-test (i.e. non-optimized) estimate to this Results object.

Parameters:

• target_model (Model) – The target model used for comparison to the model.

• themodel (Model) – The “model” model whose fit to the data and distance from target_model are assessed.

• estimate_key (str, optional) – The key or label used to identify this estimate.

• gaugeopt_keys (list, optional) – A list of gauge-optimization keys to add to the estimate. All of these keys will correspond to trivial gauge optimizations, as the model model is assumed to be fixed and to have no gauge degrees of freedom. The special value “auto” creates gauge-optimized estimates for all the gauge optimization labels currently in this Results object.

• verbosity (int, optional) – Level of detail printed to stdout.

• 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.

Return type:

None

add_mongodb_write_ops(write_ops, mongodb, overwrite_existing=False, **kwargs)

Accumulate write and update operations for writing this object to a MongoDB database.

Similar to write_to_mongodb() but collects write operations instead of actually executing any write operations on the database. This function may be preferred to write_to_mongodb() when this object is being written as a part of a larger entity and executing write operations is saved until the end.

As in write_to_mongodb(), self.collection_name is the collection name and _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

• write_ops (WriteOpsByCollection) – An object that keeps track of pymongo write operations on a per-collection basis. This object accumulates write operations to be performed at some point in the future.

• mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

• overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

copy()

Creates a copy of this ModelEstimateResults object.

Return type:

ModelEstimateResults

classmethod from_dir(dirname, name, preloaded_data=None, quick_load=False)

Initialize a new ModelEstimateResults object from dirname / results / name.

Parameters:

• dirname (str) – The root directory name (under which there is are ‘edesign’, ‘data’, and ‘results’ subdirectories).

• name (str) – The sub-directory name of the particular results object to load (there can be multiple under a given root dirname). This is the name of a subdirectory of dirname / results.

• preloaded_data (ProtocolData, optional) – In the case that the ProtocolData object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.

• quick_load (bool, optional) – Setting this to True skips the loading of data and experiment-design components that may take a long time to load. This can be useful all the information of interest lies only within the results object.

Return type:

ModelEstimateResults

classmethod from_mongodb(mongodb, doc_id, **kwargs)

Create and initialize an object from a MongoDB instance.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to load from.

• doc_id (bson.objecctid.ObjectId or dict) – The object ID or filter used to find a single object ID within the database. This document is loaded from the collection given by the collection_name attribute of this class.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

classmethod from_mongodb_doc(mongodb, collection_name, doc, **kwargs)

Create and initialize an object from a MongoDB instance and pre-loaded primary document.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to load from.

• collection_name (str) – The collection name within mongodb that doc was loaded from. This is needed for the sole purpose of setting the created (returned) object’s database “coordinates”.

• doc (dict) – The already-retrieved main document for the object being loaded. This takes the place of giving an identifier for this object.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

classmethod remove_from_mongodb(mongodb, doc_id, collection_name=None, session=None, recursive='default')

Remove the documents corresponding to an instance of this class from a MongoDB database.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to remove documents from.

• doc_id (bson.objectid.ObjectId) – The identifier of the root document stored in the database.

• collection_name (str, optional) – the MongoDB collection within mongodb where the main document resides. If None, then <this_class>.collection_name is used (which is usually what you want).

• session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

• recursive (RecursiveRemovalSpecification, optional) – An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Return type:

None

rename_estimate(old_name, new_name)

Rename an estimate in this Results object.

Ordering of estimates is not changed.

Parameters:

• old_name (str) – The labels of the estimate to be renamed

• new_name (str) – The new name for the estimate.

Return type:

None

to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False)

Convert these results into Pandas dataframe.

Parameters:

• pivot_valuename (str, optional) – If not None, the resulting dataframe is pivoted using pivot_valuename as the column whose values name the pivoted table’s column names. If None and pivot_value is not None,`”ValueName”` is used.

• pivot_value (str, optional) – If not None, the resulting dataframe is pivoted such that values of the pivot_value column are rearranged into new columns whose names are given by the values of the pivot_valuename column. If None and pivot_valuename is not None,`”Value”` is used.

• drop_columns (bool or list, optional) – A list of column names to drop (prior to performing any pivot). If True appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when drop_columns == False.

Return type:

DataFrame

to_nameddict()

Convert these results into nested NamedDict objects.

Return type:

NamedDict

view(estimate_keys, gaugeopt_keys=None)

Creates a shallow copy of this Results object containing only the given estimate.

This function an also filter based on gauge-optimization keys, only keeping a subset of those available.

Parameters:

• estimate_keys (str or list) – Either a single string-value estimate key or a list of such keys.

• 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.

Return type:

Results

write(dirname=None, data_already_written=False)

Write these protocol results to a directory.

Parameters:

• dirname (str) – The root directory to write into. This directory will have ‘edesign’, ‘data’, and ‘results/<myname>’ subdirectories, which will path be created if needed and overwritten if present. If None, then the this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).

• data_already_written (bool, optional) – Set this to True if you’re sure the .data ProtocolData object within this results object has already been written to dirname. Leaving this as the default is a safe option.

Return type:

None

write_to_mongodb(mongodb, session=None, overwrite_existing=False, **kwargs)

Write this object to a MongoDB database.

The collection name used is self.collection_name, and the _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

• session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

• overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

property dataset

The underlying data set.