pygsti.protocols.confidenceregionfactory

Classes for constructing confidence regions

Module Contents

Classes

ConfidenceRegionFactory	An object which is capable of generating confidence intervals/regions.
ConfidenceRegionFactoryView	Encapsulates a lightweight "view" of a ConfidenceRegionFactory.

class pygsti.protocols.confidenceregionfactory.ConfidenceRegionFactory(parent, model_lbl, circuit_list_lbl, hessian=None, non_mark_radius_sq=None)

Bases: pygsti.baseobjs.nicelyserializable.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 reponse error bars”.

Parameters

parentEstimate

the parent estimate object, needed to resolve model and gate string list labels.

model_lblstr

The key into the parent Estimate’s .models dictionary that gives the Model about which confidence regions will be constructed.

circuit_list_lblstr

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

hessiannumpy 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_sqfloat, optional

The non-Markovian radius associated with the goodness of fit found at the point where hessian was computed. This must be specified whenver hessian is, and should be left as None when hessian is not specified.

Initializes a new ConfidenceRegionFactory.

Parameters

parentEstimate

the parent estimate object, needed to resolve model and gate string list labels.

model_lblstr

The key into the parent Estimate’s .models dictionary that gives the Model about which confidence regions will be constructed.

circuit_list_lblstr

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

hessiannumpy 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_sqfloat, optional

The non-Markovian radius associated with the goodness of fit found at the point where hessian was computed. This must be specified whenver hessian is, and should be left as None when hessian is not specified.

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.

Returns

bool

property model

Retrieve the associated model.

Returns

Model

the model marking the center location of this confidence region.

collection_name = "'pygsti_confidence_region_factories'"

hessian

jacobian = 'None'

nonMarkRadiusSq

hessian_projection_parameters

inv_hessian_projections

linresponse_gstfit_params = 'None'

model_lbl

circuit_list_lbl

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

parentEstimate

The parent of this object.

Returns

None

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.

Returns

bool

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

Computes the Hessian for this factory.

Parameters

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

mem_limitint, optional

A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.

approximatebool, 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

numpy.ndarray

The Hessian matrix (also stored internally)

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_typestring

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.

labelstr, optional

The internal label to use for this projection. If None, then projection_type is used, which is usually fine.

tolfloat, optional

Tolerance for optimal Hessian projection. Only used when projection_type == ‘optimal gate CIs’.

maxiterint, optional

Maximum iterations for optimal Hessian projection. Only used when projection_type == ‘optimal gate CIs’.

verbosityint or VerbosityPrinter, optional

Controls amount of detail printed to stdout (higher = more detail).

Returns

numpy.ndarray

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

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 requres 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_allocResourceAllocation

Allocation for running linear-response GST fits.

Returns

None

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_levelfloat

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_labelstr, 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.

Returns

ConfidenceRegionFactoryView

class pygsti.protocols.confidenceregionfactory.ConfidenceRegionFactoryView(model, inv_projected_hessian, mlgst_params, confidence_level, non_mark_radius_sq, n_non_gauge_params, n_gauge_params)

Bases: object

Encapsulates a lightweight “view” of a ConfidenceRegionFactory.

A view object is principally defined by it’s having a fixed confidence-level. Thus, a “view” is like a factory that generates confidence intervals for just a single confidence level. As such, it is a useful object to pass around to routines which compute and display error bars, as these routines typically don’t depend on what confidence-level is being used.

Parameters

modelModel

The model at the center of this confidence region.

inv_projected_hessiannumpy.ndarray

The computed inverse of the non-gauge-projected Hessian.

mlgst_paramsdict

A dictionary of ML-GST parameters only used for linear-response error bars.

confidence_levelfloat

the confidence level (between 0 and 100) used in the computation of confidence regions/intervals.

non_mark_radius_sqfloat, optional

When non-zero, “a non-Markovian error region” is constructed using this value as the squared “non-markovian radius”. This specifies the portion of 2*(max-log-likelihood - model-log-likelihood) that we attribute to non-Markovian errors (typically the previous difference minus it’s expected value, the difference in number of parameters between the maximal and model models). If set to zero (the default), a standard and thereby statistically rigorous conficence region is created. Non-zero values should only be supplied if you really know what you’re doing.

n_non_gauge_paramsint

The numbers of non-gauge parameters. This could be computed from model but can be passed in to save compuational time.

n_gauge_paramsint

The numbers of gauge parameters. This could be computed from model but can be passed in to save compuational time.

Creates a new ConfidenceRegionFactoryView.

Usually this constructor is not called directly, and objects of this type are obtained by calling the view() method of a ConfidenceRegionFactory object.

Parameters

modelModel

The model at the center of this confidence region.

inv_projected_hessiannumpy.ndarray

The computed inverse of the non-gauge-projected Hessian.

mlgst_paramsdict

A dictionary of ML-GST parameters only used for linear-response error bars.

confidence_levelfloat

the confidence level (between 0 and 100) used in the computation of confidence regions/intervals.

non_mark_radius_sqfloat, optional

When non-zero, “a non-Markovian error region” is constructed using this value as the squared “non-markovian radius”. This specifies the portion of 2*(max-log-likelihood - model-log-likelihood) that we attribute to non-Markovian errors (typically the previous difference minus it’s expected value, the difference in number of parameters between the maximal and model models). If set to zero (the default), a standard and thereby statistically rigorous conficence region is created. Non-zero values should only be supplied if you really know what you’re doing.

n_non_gauge_params, n_gauge_paramsint

The numbers of non-gauge and gauge parameters, respectively. These could be computed from model but they’re passed in to save compuational time.

property errorbar_type

Return the type of error bars this view will generate, either “standard” or “non-markovian”.

Returns

str

nonMarkRadiusSq

model

level

nNonGaugeParams

nGaugeParams

mlgst_params

mlgst_evaltree_cache

retrieve_profile_likelihood_confidence_intervals(label=None, component_label=None)

Retrieve the profile-likelihood confidence intervals for a specified model object (or all such intervals).

Parameters

labelLabel, optional

If not None, can be either a gate or SPAM vector label to specify the confidence intervals corresponding to gate, rhoVec, or EVec parameters respectively. If None, then intervals corresponding to all of the model’s parameters are returned.

component_labelLabel, optional

Labels an effect within a POVM or a member within an instrument.

Returns

numpy array

One-dimensional array of (positive) interval half-widths which specify a symmetric confidence interval.

compute_confidence_interval(fn_obj, eps=1e-07, return_fn_val=False, verbosity=0)

Compute the confidence interval for an arbitrary function.

This “function”, however, must be encapsulated as a ModelFunction object, which allows it to neatly specify what its dependencies are and allows it to compaute finite- different derivatives more efficiently.

Parameters

fn_objModelFunction

An object representing the function to evaluate. The returned confidence interval is based on linearizing this function and propagating the model-space confidence region.

epsfloat, optional

Step size used when taking finite-difference derivatives of fnOfOp.

return_fn_valbool, optional

If True, return the value of fnOfOp along with it’s confidence region half-widths.

verbosityint, optional

Specifies level of detail in standard output.

Returns

dffloat or numpy array

Half-widths of confidence intervals for each of the elements in the float or array returned by fnOfOp. Thus, shape of df matches that returned by fnOfOp.

f0float or numpy array

Only returned when return_fn_val == True. Value of fnOfOp at the gate specified by op_label.