pygsti.protocols.confidenceregionfactory.ConfidenceRegionFactory

pygsti.protocols.confidenceregionfactory.ConfidenceRegionFactory#

class ConfidenceRegionFactory(parent, model_lbl, circuit_list_lbl, hessian=None, non_mark_radius_sq=None)#

Bases: NicelySerializable

An object which is capable of generating confidence intervals/regions.

Often times, it does so by holding the Hessian of a fit function with respect to a Model’s parameters and related projections of it onto the non-gauge space.

Alternative (non-Hessian-based) means of computing confidence intervals are also available, such as by using so-called “linear response error bars”.

Parameters:

  • parent (Estimate) – the parent estimate object, needed to resolve model and gate string list labels.

  • model_lbl (str) – The key into the parent Estimate’s .models dictionary that gives the Model about which confidence regions will be constructed.

  • circuit_list_lbl (str) – The key into the parent Results’s .circuit_lists dictionary that specifies which circuits should be or were included when computing fit functions (the log-likelihood or chi2).

  • hessian (numpy array, optional) – A pre-computed num_params x num_params Hessian matrix, where num_params is the number of dimensions of model space, i.e. model.num_params.

  • non_mark_radius_sq (float, optional) – The non-Markovian radius associated with the goodness of fit found at the point where hessian was computed. This must be specified whenever hessian is, and should be left as None when hessian is not specified.

Initializes a new ConfidenceRegionFactory.

Parameters:

  • parent (Estimate) – the parent estimate object, needed to resolve model and gate string list labels.

  • model_lbl (str) – The key into the parent Estimate’s .models dictionary that gives the Model about which confidence regions will be constructed.

  • circuit_list_lbl (str) – The key into the parent Results’s .circuit_lists dictionary that specifies which circuits should be or were included when computing fit functions (the log-likelihood or chi2).

  • hessian (numpy array, optional) – A pre-computed num_params x num_params Hessian matrix, where num_params is the number of dimensions of model space, i.e. model.num_params.

  • non_mark_radius_sq (float, optional) – The non-Markovian radius associated with the goodness of fit found at the point where hessian was computed. This must be specified whenever hessian is, and should be left as None when hessian is not specified.

Methods

__init__(parent, model_lbl, circuit_list_lbl)

Initializes a new ConfidenceRegionFactory.

add_mongodb_write_ops(write_ops, mongodb[, ...])

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

can_construct_views()

Checks whether this factory has enough information to construct 'views' of itself.

compute_hessian([comm, mem_limit, approximate])

Computes the Hessian for this factory.

dump(f[, format])

Serializes and writes this object to a given output stream.

dumps([format])

Serializes this object and returns it as a string.

enable_linear_response_errorbars([...])

Stores the parameters needed to compute (on-demand) linear response error bars.

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.

from_nice_serialization(state)

Create and initialize an object from a "nice" serialization.

load(f[, format])

Load an object of this type, or a subclass of this type, from an input stream.

loads(s[, format])

Load an object of this type, or a subclass of this type, from a string.

project_hessian(projection_type[, label, ...])

Projects the Hessian onto the non-gauge space.

read(path[, format])

Read an object of this type, or a subclass of this type, from a file.

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, ...])

set_parent(parent)

Sets the parent Estimate object of this ConfidenceRegionFactory.

to_nice_serialization()

Serialize this object in a way that adheres to "niceness" rules of common text file formats.

view(confidence_level[, region_type, ...])

Constructs a "view" of this ConfidenceRegionFactory for a particular type and confidence level.

write(path, **format_kwargs)

Writes this object to a file.

write_to_mongodb(mongodb[, session, ...])

Write this object to a MongoDB database.

Attributes

collection_name

has_hessian

Returns whether or not the Hessian has already been computed.

model

Retrieve the associated model.
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

can_construct_views()#

Checks whether this factory has enough information to construct ‘views’ of itself.

ConfidenceRegionFactoryView view objects are created using the view() method, which can in turn be used to construct confidence intervals.

Return type:

bool

compute_hessian(comm=None, mem_limit=None, approximate=False)#

Computes the Hessian for this factory.

Parameters:

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.

  • approximate (bool, optional) – Whether to compute the true Hessian or just an approximation of it. See logl_approximate_hessian(). Setting to True can significantly reduce the run time.

Returns:

The Hessian matrix (also stored internally)

Return type:

numpy.ndarray

dump(f, format='json', **format_kwargs)#

Serializes and writes this object to a given output stream.

Parameters:

  • f (file-like) – A writable output stream.

  • format ({'json', 'repr'}) – The format to write.

  • format_kwargs (dict, optional) – Additional arguments specific to the format being used. For example, the JSON format accepts indent as an argument because json.dump does.

Return type:

None

dumps(format='json', **format_kwargs)#

Serializes this object and returns it as a string.

Parameters:

  • format ({'json', 'repr'}) – The format to write.

  • format_kwargs (dict, optional) – Additional arguments specific to the format being used. For example, the JSON format accepts indent as an argument because json.dump does.

Return type:

str

enable_linear_response_errorbars(resource_alloc=None)#

Stores the parameters needed to compute (on-demand) linear response error bars.

In particular, this function sets up the parameters needed to perform the model optimizations needed to compute error bars on quantities.

‘linear response’ mode obtains elements of the Hessian via the linear response of a “forcing term”. This requires a likelihood optimization for every computed error bar, but avoids pre- computation of the entire Hessian matrix, which can be prohibitively costly on large parameter spaces.

Parameters:

resoure_alloc (ResourceAllocation) – Allocation for running linear-response GST fits.

Return type:

None

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 from_nice_serialization(state)#

Create and initialize an object from a “nice” serialization.

A “nice” serialization here means one created by a prior call to to_nice_serialization using this class or a subclass of it. Nice serializations adhere to additional rules (e.g. that dictionary keys must be strings) that make them amenable to common file formats (e.g. JSON).

The state argument is typically a dictionary containing ‘module’ and ‘state’ keys specifying the type of object that should be created. This type must be this class or a subclass of it.

Parameters:

state (object) – An object, usually a dictionary, representing the object to de-serialize.

Return type:

object

classmethod load(f, format='json')#

Load an object of this type, or a subclass of this type, from an input stream.

Parameters:

  • f (file-like) – An open input stream to read from.

  • format ({'json'}) – The format of the input stream data.

Return type:

NicelySerializable

classmethod loads(s, format='json')#

Load an object of this type, or a subclass of this type, from a string.

Parameters:

  • s (str) – The serialized object.

  • format ({'json'}) – The format of the string data.

Return type:

NicelySerializable

project_hessian(projection_type, label=None, tol=1e-07, maxiter=10000, verbosity=3)#

Projects the Hessian onto the non-gauge space.

This is a necessary step before confidence regions/intervals can be computed via Hessian-based methods.

Parameters:

  • projection_type (string) –

    Specifies how (and whether) to project the given hessian matrix onto a non-gauge space. Allowed values are:

    • ’std’ – standard projection onto the space perpendicular to the gauge space.

    • ’none’ – no projection is performed. Useful if the supplied hessian has already been projected.

    • ’optimal gate CIs’ – a lengthier projection process in which a numerical optimization is performed to find the non-gauge space which minimizes the (average) size of the confidence intervals corresponding to gate (as opposed to SPAM vector) parameters.

    • ’intrinsic error’ – compute separately the intrinsic error in the gate and spam Model parameters and set weighting metric based on their ratio.

  • label (str, optional) – The internal label to use for this projection. If None, then projection_type is used, which is usually fine.

  • tol (float, optional) – Tolerance for optimal Hessian projection. Only used when projection_type == ‘optimal gate CIs’.

  • maxiter (int, optional) – Maximum iterations for optimal Hessian projection. Only used when projection_type == ‘optimal gate CIs’.

  • verbosity (int or VerbosityPrinter, optional) – Controls amount of detail printed to stdout (higher = more detail).

Returns:

The inverse of the projected Hessian matrix (also stored internally)

Return type:

numpy.ndarray

classmethod read(path, format=None)#

Read an object of this type, or a subclass of this type, from a file.

Parameters:

  • path (str or Path or file-like) – The filename to open or an already open input stream.

  • format ({'json', None}) – The format of the file. If None this is determined automatically by the filename extension of a given path.

Return type:

NicelySerializable

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

set_parent(parent)#

Sets the parent Estimate object of this ConfidenceRegionFactory.

This function is usually only needed internally to re-link a ConfidenceRegionFactory with its parent after be un-serialized from disk.

Parameters:

parent (Estimate) – The parent of this object.

Return type:

None

to_nice_serialization()#

Serialize this object in a way that adheres to “niceness” rules of common text file formats.

Returns:

Usually a dictionary representing the serialized object, but may also be another native Python type, e.g. a string or list.

Return type:

object

view(confidence_level, region_type='normal', hessian_projection_label=None)#

Constructs a “view” of this ConfidenceRegionFactory for a particular type and confidence level.

The returned view object can then be used to construct confidence intervals/regions.

Parameters:

  • confidence_level (float) – The confidence level as a percentage, i.e. between 0 and 100.

  • region_type ({'normal', 'non-markovian'}) – The type of confidence regions. ‘normal’ constructs standard intervals based on the inverted Hessian matrix or linear-response optimizations. ‘non-markovian’ attempts to enlarge the intervals to account for the badness-of-fit at the current location.

  • hessian_projection_label (str, optional) – A label specifying which Hessian projection to use (only useful when there are multiple). These labels are either the projection_type values of project_hessian() or the custom label argument provided to that function. If None, then the most recent (perhaps the only) projection is used.

Return type:

ConfidenceRegionFactoryView

write(path, **format_kwargs)#

Writes this object to a file.

Parameters:

  • path (str or Path) – The name of the file that is written.

  • format_kwargs (dict, optional) – Additional arguments specific to the format being used. For example, the JSON format accepts indent as an argument because json.dump does.

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 has_hessian#

Returns whether or not the Hessian has already been computed.

When True, project_hessian() can be used to project the Hessian for use in creating confidence intervals. When False, either compute_hessian() can be called to compute the Hessian or slower methods must be used to estimate the necessary portion of the Hessian. The result of this function is often used to decide whether or not to proceed with an error-bar computation.

Return type:

bool

property model#

Retrieve the associated model.

Returns:

the model marking the center location of this confidence region.

Return type:

Model