pygsti.modelmembers.operations.lindbladcoefficients.LindbladCoefficientBlock

pygsti.modelmembers.operations.lindbladcoefficients.LindbladCoefficientBlock#

class LindbladCoefficientBlock(block_type=None, *args, **kwargs)#

Bases: NicelySerializable

Class for storing and managing the parameters associated with particular subblocks of error-generator parameters. Responsible for management of different internal representations utilized when employing various error generator constraints.

Parameters:

block_type (str) – String specifying the type of error generator parameters contained within this block. Allowed values are ‘ham’ (for Hamiltonian error generators), ‘other_diagonal’ (for Pauli stochastic error generators), and ‘other’ (for Pauli stochastic, Pauli correlation and active error generators).
basis (Basis) – Basis object to be used by this coefficient block. Note this must be an actual Basis object, and not a string (as the coefficient block doesn’t have the requisite dimensionality information needed for casting).
basis_element_labels (list or tuple of str) – Iterable of strings corresponding to the basis element subscripts used by the error generators managed by this coefficient block.
initial_block_data (_np.ndarray, optional (default None)) – Numpy array with initial parameter values to use in setting initial state of this coefficient block.
param_mode (str, optional (default 'static')) –
String specifying the type of internal parameterization used by this coefficient block. Allowed options are:
- For all block types: ‘static’
- For ‘ham’: ‘elements’
- For ‘other_diagonal’: ‘elements’, ‘cholesky’, ‘depol’, ‘reldepol’
- For ‘other’: ‘elements’, ‘cholesky’
Note that the most commonly encounted settings in practice are ‘elements’ and ‘cholesky’, which when used in the right combination are utilized in the construction of GLND and CPTPLND parameterized models. For both GLND and CPTPLND the ‘ham’ block used the ‘elements’ param_mode. GLND the ‘other’ block uses ‘elements’, and for CPTPLND it uses ‘cholesky’.

’depol’ and ‘reldepol’ are special modes used only for Pauli stochastic only coefficient blocks (i.e. ‘other_diagonal’), and correspond to special reduced parameterizations applicable to depolarizing channels. (TODO: Add better explanation of the difference between depol and reldepol).
truncate (bool, optional (default False)) – Flag specifying whether to truncate the parameters given by initial_block_data in order to meet constraints (e.g. to preserve CPTP) when necessary. If False, then an error is thrown when the given intial data cannot be parameterized as specified.
error_generator_labels (list or tuple of LocalElementaryErrorgenLabel, optional (default None)) – Keyword-only. Only supported by block types whose block_data is keyed directly by elementary error generators (e.g. ‘other_unconstrained’); mutually exclusive with basis_element_labels. When given, the block manages exactly the listed elementary error generators, enabling reduced / flexible parameterizations. Must be None for the other (basis-element-keyed) block types.

Methods

`__init__`(block_type, basis[, ...])
`add_mongodb_write_ops`(write_ops, mongodb[, ...])	Accumulate write and update operations for writing this object to a MongoDB database.
`convert`(param_mode)	TODO: docstring - return a new LindbladCoefficientBlock with the same block type and data, but with the given parameterization mode.
`create_lindblad_term_objects`(...)
`create_lindblad_term_superoperators`([...])
`deriv_wrt_params`([v])	Jacobian of block_data w.r.t.
`dump`(f[, format])	Serializes and writes this object to a given output stream.
`dumps`([format])	Serializes this object and returns it as a string.
`elementary_errorgen_deriv_wrt_params`([v])
`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.
`from_vector`(v)	Construct Lindblad coefficients (for this block) from a set of parameter values.
`is_similar`(other_coeff_block)	TODO: docstring
`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.
`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_elementary_errorgens`(elementary_errorgens)
`set_from_errorgen_projections`(errorgen[, ...])
`superop_deriv_wrt_params`(superops[, v, ...])	Derivative of the Lindblad-term superoperators w.r.t.
`superop_hessian_wrt_params`(superops[, v, ...])
`to_nice_serialization`()	Serialize this object in a way that adheres to "niceness" rules of common text file formats.
`to_vector`()	Compute parameter values for this coefficient block.
`write`(path, **format_kwargs)	Writes this object to a file.
`write_to_mongodb`(mongodb[, session, ...])	Write this object to a MongoDB database.

Attributes

`basis_element_labels`
`block_type`	'ham', 'other_diagonal', or 'other'.
`collection_name`
`elementary_errorgen_indices`	TODO docstring - rewrite this docstring - especially return value! Constructs a dictionary mapping Lindblad term labels to projection coefficients.
`elementary_errorgens`	Converts a set of coefficients for this block into a linear combination of elementary error generators.
`num_params`
`param_labels`	Generate human-readable labels for the parameters of this block.

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

convert(param_mode)#: TODO: docstring - return a new LindbladCoefficientBlock with the same block type and data, but with the given parameterization mode.

deriv_wrt_params(v=None)#: Jacobian of block_data w.r.t. the real parameters v. Dispatches to _deriv_wrt_params_<block_type>.

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

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

from_vector(v)#

Construct Lindblad coefficients (for this block) from a set of parameter values. This is now just a dispatcher into the three block-type specific implementations.

Parameters:: v (ndarray)

is_similar(other_coeff_block)#: TODO: docstring

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

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

superop_deriv_wrt_params(superops, v=None, superops_are_flat=False)#

Derivative of the Lindblad-term superoperators w.r.t. the real parameters.

Parameters:

superops (ndarray) – The output of create_lindblad_term_superoperators(…, sparse=False).
v (array, optional) – The parameter vector. Only needed for ‘other_diagonal’ blocks.
superops_are_flat (bool, optional) – True if superops is a flat list/array even for the ‘other’ block.

Return type:

ndarray

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

to_vector()#

Compute parameter values for this coefficient block.

Returns:: param_vals – A 1D array of real parameter values. Length is len(self.basis_element_labels) in the case of ‘ham’ or ‘other_diagonal’ blocks, and len(self.basis_element_labels)**2 in the case of ‘other’ blocks.
Return type:: numpy.ndarray

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

‘ham’, ‘other_diagonal’, or ‘other’.

Type:: The block-type string

property elementary_errorgen_indices#

TODO docstring - rewrite this docstring - especially return value! Constructs a dictionary mapping Lindblad term labels to projection coefficients.

This method is used for finding the index of a particular error generator coefficient in the 1D array formed by concatenating the Hamiltonian and flattened stochastic projection arrays.

Parameters:

ham_basis ({'std', 'gm', 'pp', 'qt'}, list of matrices, or Basis object) – The basis used to construct ham_projs. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt), list of numpy arrays, or a custom basis object.
other_basis ({'std', 'gm', 'pp', 'qt'}, list of matrices, or Basis object) – The basis used to construct other_projs. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt), list of numpy arrays, or a custom basis object.
other_mode ({"diagonal", "diag_affine", "all"}) – Which non-Hamiltonian Lindblad error projections other_projs includes. Allowed values are: “diagonal” (only the diagonal Stochastic), “diag_affine” (diagonal + affine generators), and “all” (all generators).

Returns:

Ltermdict – Keys are (termType, basisLabel1, <basisLabel2>) tuples, where termType is “H” (Hamiltonian), “S” (Stochastic), or “A” (Affine). Hamiltonian and Affine terms always have a single basis label (so key is a 2-tuple) whereas Stochastic tuples have 1 basis label to indicate a diagonal term and otherwise have 2 basis labels to specify off-diagonal non-Hamiltonian Lindblad terms. Basis labels are taken from ham_basis and other_basis. Values are integer indices.

Return type:

dict

property elementary_errorgens#

Converts a set of coefficients for this block into a linear combination of elementary error generators.

This linear combination is given by a dictionary with keys equal to elementary error generator labels and values equal to their coefficients in the linear combination.

Parameters:: block_data (numpy.ndarray) – A 1- or 2-dimensional array with each dimension of size len(self.basis_element_labels), specifying the coefficients of this block. Array is 1-dimensional when this block is of type ‘ham’ or ‘other_diagonal’ and is 2-dimensional for type ‘other’.
Returns:: elementary_errorgens – Specifies block_data as a linear combination of elementary error generators. Keys are LocalElementaryErrorgenLabel objects and values are floats.
Return type:: dict

property param_labels: list#: Generate human-readable labels for the parameters of this block.

pygsti.modelmembers.operations.lindbladcoefficients.LindbladCoefficientBlock

Contents

pygsti.modelmembers.operations.lindbladcoefficients.LindbladCoefficientBlock#