pygsti.protocols.rb.DirectRBDesign

pygsti.protocols.rb.DirectRBDesign#

class DirectRBDesign(pspec, clifford_compilations, depths, circuits_per_depth, qubit_labels=None, sampler='edgegrab', samplerargs=None, addlocal=False, lsargs=(), randomizeout=False, cliffordtwirl=True, conditionaltwirl=True, citerations=20, compilerargs=(), partitioned=False, descriptor='A DRB experiment', add_default_protocol=False, seed=None, verbosity=1, num_processes=1)#

Bases: BenchmarkingDesign

Experiment design for Direct randomized benchmarking.

This encapsulates a “direct randomized benchmarking” (DRB) experiments. DRB was a protocol introduced in arXiv:1807.07975 (2018).

An n-qubit DRB circuit consists of (1) a circuit the prepares a uniformly random stabilizer state; (2) a length-l circuit (specified by length) consisting of circuit layers sampled according to some user-specified distribution (specified by sampler), (3) a circuit that maps the output of the preceding circuit to a computational basis state. See arXiv:1807.07975 (2018) for further details.

Parameters:

  • pspec (QubitProcessorSpec) – The QubitProcessorSpec for the device that the circuit is being sampled for, which defines the “native” gate-set and the connectivity of the device. The returned DRB circuit will be over the gates in pspec, and will respect the connectivity encoded by pspec. Note that pspec is always handed to the sampler, as the first argument of the sampler function (this is only of importance when not using an in-built sampler for the “core” of the DRB circuit). Unless qubit_labels is not None, the circuit is sampled over all the qubits in pspec.

  • clifford_compilations (dict) – A dictionary with the potential keys ‘absolute’ and ‘paulieq’ and corresponding CompilationRules values. These compilation rules specify how to compile the “native” gates of pspec into Clifford gates.

  • depths (int) – The set of “direct RB depths” for the circuits. The DRB depths must be integers >= 0. Unless addlocal is True, the DRB length is the depth of the “core” random circuit, sampled according to sampler, specified in step (2) above. If addlocal is True, each layer in the “core” circuit sampled according to “sampler` is followed by a layer of 1-qubit gates, with sampling specified by lsargs (and the first layer is proceeded by a layer of 1-qubit gates), and so the circuit of step (2) is length 2*`length` + 1.

  • circuits_per_depth (int) – The number of (possibly) different DRB circuits sampled at each length.

  • qubit_labels (list, optional) – If not None, a list of the qubits to sample the circuit for. This is a subset of pspec.qubit_labels. If None, the circuit is sampled to act on all the qubits in pspec.

  • sampler (str or function, optional) – If a string, this should be one of: {‘edgegrab’, pairingQs’, ‘Qelimination’, ‘co2Qgates’, ‘local’}. Except for ‘local’, this corresponds to sampling layers according to the sampling function in rb.sampler named circuit_layer_by_* (with * replaced by ‘sampler’). For ‘local’, this corresponds to sampling according to rb.sampler.circuit_layer_of_oneQgates [which is not a valid form of sampling for n-qubit DRB, but is not explicitly forbidden in this function]. If sampler is a function, it should be a function that takes as the first argument a QubitProcessorSpec, and returns a random circuit layer as a list of gate Label objects. Note that the default ‘Qelimination’ is not necessarily the most useful in-built sampler, but it is the only sampler that requires no parameters beyond the QubitProcessorSpec and works for arbitrary connectivity devices. See the docstrings for each of these samplers for more information.

  • samplerargs (list, optional) – A list of arguments that are handed to the sampler function, specified by sampler. The first argument handed to the sampler is pspec, the second argument is qubit_labels, and samplerargs lists the remaining arguments handed to the sampler. This is not optional for some choices of sampler.

  • addlocal (bool, optional) – Whether to follow each layer in the “core” circuits, sampled according to sampler with a layer of 1-qubit gates.

  • lsargs (list, optional) – Only used if addlocal is True. A list of optional arguments handed to the 1Q gate layer sampler circuit_layer_by_oneQgate(). Specifies how to sample 1Q-gate layers.

  • randomizeout (bool, optional) – If False, the ideal output of the circuits (the “success” or “survival” outcome) is the all-zeros bit string. If True, the ideal output of each circuit is randomized to a uniformly random bit-string. This setting is useful for, e.g., detecting leakage/loss/measurement-bias etc.

  • cliffordtwirl (bool, optional) – Whether to begin the circuits with a sequence that generates a random stabilizer state. For standard DRB this should be set to True. There are a variety of reasons why it is better to have this set to True.

  • conditionaltwirl (bool, optional) – DRB only requires that the initial/final sequences of step (1) and (3) create/measure a uniformly random / particular stabilizer state, rather than implement a particular unitary. step (1) and (3) can be achieved by implementing a uniformly random Clifford gate and the unique inversion Clifford, respectively. This is implemented if conditionaltwirl is False. However, steps (1) and (3) can be implemented much more efficiently than this: the sequences of (1) and (3) only need to map a particular input state to a particular output state, if conditionaltwirl is True this more efficient option is chosen – this is option corresponds to “standard” DRB. (the term “conditional” refers to the fact that in this case we essentially implementing a particular Clifford conditional on a known input).

  • citerations (int, optional) – Some of the stabilizer state / Clifford compilation algorithms in pyGSTi (including the default algorithms) are randomized, and the lowest-cost circuit is chosen from all the circuits generated in the iterations of the algorithm. This is the number of iterations used. The time required to generate a DRB circuit is linear in citerations. Lower-depth / lower 2-qubit gate count compilations of steps (1) and (3) are important in order to successfully implement DRB on as many qubits as possible.

  • compilerargs (list, optional) – A list of arguments that are handed to the compile_stabilier_state/measurement()functions (or the compile_clifford() function if conditionaltwirl `is False). This includes all the optional arguments of these functions *after* the `iterations option (set by citerations). For most purposes the default options will be suitable (or at least near-optimal from the compilation methods in-built into pyGSTi). See the docstrings of these functions for more information.

  • partitioned (bool, optional) – If False, each circuit is returned as a single full circuit. If True, each circuit is returned as a list of three circuits consisting of: (1) the stabilizer-prep circuit, (2) the core random circuit, (3) the pre-measurement circuit. In that case the full circuit is obtained by appended (2) to (1) and then (3) to (1).

  • descriptor (str, optional) – A description of the experiment being generated. Stored in the output dictionary.

  • add_default_protocol (bool, optional) – Whether to add a default RB protocol to the experiment design, which can be run later (once data is taken) by using a DefaultProtocolRunner object.

  • seed (int, optional) – A seed to initialize the random number generator used for creating random clifford circuits.

  • verbosity (int, optional) – If > 0 the number of circuits generated so far is shown.

Create a new CircuitListsDesign object.

Parameters:

  • circuit_lists (list or PlaquetteGridCircuitStructure) – A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).

  • all_circuits_needing_data (list, optional) – A list of all the circuits needing data. By default, This is just the concatenation of the elements of circuit_lists with duplicates removed. The only reason to specify this separately is if you happen to have this list lying around.

  • qubit_labels (tuple, optional) – The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

  • nested (bool, optional) – Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.

  • remove_duplicates (bool, optional) – Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Return type:

CircuitListsDesign

Methods

__init__(pspec, clifford_compilations, ...)

Create a new CircuitListsDesign object.

add_default_protocol(default_protocol_instance)

Add a "default" protocol to this experiment design.

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

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

from_dir(dirname[, parent, name, quick_load])

Initialize a new ExperimentDesign object from dirname.

from_edesign(edesign)

Create a CircuitListsDesign out of an existing experiment design.

from_existing_circuits(...[, qubit_labels, ...])

Create a DirectRBDesign from an existing set of sampled RB circuits.

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.

items()

An iterator over the (child_name, child_node) pairs of this node.

keys()

An iterator over the keys (child names) of this tree node.

map_qubit_labels(mapper)

Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping.

merge_with(other_edesign[, ...])

Merge this experiment design with another one and return the result.

promote_to_combined([name])

Promote this experiment design to be a combined experiment design.

promote_to_simultaneous()

Promote this experiment design to be a simultaneous experiment design.

prune_tree(paths[, paths_are_sorted])

Prune the tree rooted here to include only the given paths, discarding all other leaves & branches.

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_actual_circuits_executed(actual_circuits)

Sets a list of circuits that will actually be executed.

setup_nameddict(final_dict)

Initializes a set of nested NamedDict dictionaries describing this design.

truncate_to_available_data(dataset)

Builds a new experiment design containing only those circuits present in dataset.

truncate_to_circuits(circuits_to_keep)

Builds a new experiment design containing only the specified circuits.

truncate_to_design(other_design)

Truncates this experiment design by only keeping the circuits also in other_design

truncate_to_lists(list_indices_to_keep)

Truncates this experiment design by only keeping a subset of its circuit lists.

underlying_tree_paths()

Dictionary paths leading to data objects/nodes beneath this one.

view(keys_to_keep)

Get a "view" of this tree node that only has a subset of this node's children.

write([dirname, parent])

Write this experiment design to a directory.

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

Write this object to a MongoDB database.

Attributes

collection_name

paired_with_circuit_attrs

List of attributes which are paired up with circuit lists
add_default_protocol(default_protocol_instance)#

Add a “default” protocol to this experiment design.

Default protocols are a way of designating protocols you mean to run on the the data corresponding to an experiment design before that data has been taken. Use a DefaultRunner object to run (all) the default protocols of the experiment designs within a ProtocolData object.

Note that default protocols are indexed by their names, and so when adding multiple default protocols they need to have distinct names (usually given to the protocol when it is constructed).

Parameters:

default_protocol_instance (Protocol) – The protocol to add. This protocol’s name is used to index it.

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

classmethod from_dir(dirname, parent=None, name=None, quick_load=False)#

Initialize a new ExperimentDesign object from dirname.

Parameters:

  • dirname (str) – The root directory name (under which there is a ‘edesign’ subdirectory).

  • parent (ExperimentDesign, optional) – The parent design object, if there is one. Primarily used internally - if in doubt, leave this as None.

  • name (str, optional) – The sub-name of the design object being loaded, i.e. the key of this data object beneath parent. Only used when parent is not None.

  • quick_load (bool, optional) – Setting this to True skips the loading of the potentially long circuit lists. This can be useful when loading takes a long time and all the information of interest lies elsewhere, e.g. in an encompassing results object.

Return type:

ExperimentDesign

classmethod from_edesign(edesign)#

Create a CircuitListsDesign out of an existing experiment design.

If edesign already is a circuit lists experiment design, it will just be returned (not a copy of it).

Parameters:

edesign (ExperimentDesign) – The experiment design to convert (use as a base).

Return type:

CircuitListsDesign

classmethod from_existing_circuits(circuits_and_idealouts_by_depth, qubit_labels=None, sampler='edgegrab', samplerargs=None, addlocal=False, lsargs=(), randomizeout=False, cliffordtwirl=True, conditionaltwirl=True, citerations=20, compilerargs=(), partitioned=False, descriptor='A DRB experiment', add_default_protocol=False)#

Create a DirectRBDesign from an existing set of sampled RB circuits.

This function serves as an alternative to the usual method of creating a direct RB experiment design by sampling a number of circuits randomly. This function takes a list of previously-sampled random circuits and does not sampling internally.

Parameters:

  • circuits_and_idealouts_by_depth (dict) – A dictionary whose keys are integer depths and whose values are lists of (circuit, ideal_outcome) 2-tuples giving each RB circuit and its ideal (correct) outcome.

  • qubit_labels (list, optional) – If not None, a list of the qubits to sample the circuit for. This is a subset of pspec.qubit_labels. If None, the circuit is sampled to act on all the qubits in pspec.

  • sampler (str or function, optional) – If a string, this should be one of: {‘edgegrab’, pairingQs’, ‘Qelimination’, ‘co2Qgates’, ‘local’}. Except for ‘local’, this corresponds to sampling layers according to the sampling function in rb.sampler named circuit_layer_by_* (with * replaced by ‘sampler’). For ‘local’, this corresponds to sampling according to rb.sampler.circuit_layer_of_oneQgates [which is not a valid form of sampling for n-qubit DRB, but is not explicitly forbidden in this function]. If sampler is a function, it should be a function that takes as the first argument a QubitProcessorSpec, and returns a random circuit layer as a list of gate Label objects. Note that the default ‘Qelimination’ is not necessarily the most useful in-built sampler, but it is the only sampler that requires no parameters beyond the QubitProcessorSpec and works for arbitrary connectivity devices. See the docstrings for each of these samplers for more information.

  • samplerargs (list, optional) – A list of arguments that are handed to the sampler function, specified by sampler. Defaults to [0.25, ]. The first argument handed to the sampler is pspec, the second argument is qubit_labels, and samplerargs lists the remaining arguments handed to the sampler. This is not optional for some choices of sampler.

  • addlocal (bool, optional) – Whether to follow each layer in the “core” circuits, sampled according to sampler with a layer of 1-qubit gates.

  • lsargs (list, optional) – Only used if addlocal is True. A list of optional arguments handed to the 1Q gate layer sampler circuit_layer_by_oneQgate(). Specifies how to sample 1Q-gate layers.

  • randomizeout (bool, optional) – If False, the ideal output of the circuits (the “success” or “survival” outcome) is the all-zeros bit string. If True, the ideal output of each circuit is randomized to a uniformly random bit-string. This setting is useful for, e.g., detecting leakage/loss/measurement-bias etc.

  • cliffordtwirl (bool, optional) – Whether to begin the circuits with a sequence that generates a random stabilizer state. For standard DRB this should be set to True. There are a variety of reasons why it is better to have this set to True.

  • conditionaltwirl (bool, optional) – DRB only requires that the initial/final sequences of step (1) and (3) create/measure a uniformly random / particular stabilizer state, rather than implement a particular unitary. step (1) and (3) can be achieved by implementing a uniformly random Clifford gate and the unique inversion Clifford, respectively. This is implemented if conditionaltwirl is False. However, steps (1) and (3) can be implemented much more efficiently than this: the sequences of (1) and (3) only need to map a particular input state to a particular output state, if conditionaltwirl is True this more efficient option is chosen – this is option corresponds to “standard” DRB. (the term “conditional” refers to the fact that in this case we essentially implementing a particular Clifford conditional on a known input).

  • citerations (int, optional) – Some of the stabilizer state / Clifford compilation algorithms in pyGSTi (including the default algorithms) are randomized, and the lowest-cost circuit is chosen from all the circuits generated in the iterations of the algorithm. This is the number of iterations used. The time required to generate a DRB circuit is linear in citerations. Lower-depth / lower 2-qubit gate count compilations of steps (1) and (3) are important in order to successfully implement DRB on as many qubits as possible.

  • compilerargs (list, optional) – A list of arguments that are handed to the compile_stabilier_state/measurement()functions (or the compile_clifford() function if conditionaltwirl `is False). This includes all the optional arguments of these functions *after* the `iterations option (set by citerations). For most purposes the default options will be suitable (or at least near-optimal from the compilation methods in-built into pyGSTi). See the docstrings of these functions for more information.

  • partitioned (bool, optional) – If False, each circuit is returned as a single full circuit. If True, each circuit is returned as a list of three circuits consisting of: (1) the stabilizer-prep circuit, (2) the core random circuit, (3) the pre-measurement circuit. In that case the full circuit is obtained by appended (2) to (1) and then (3) to (1).

  • descriptor (str, optional) – A description of the experiment being generated. Stored in the output dictionary.

  • add_default_protocol (bool, optional) – Whether to add a default RB protocol to the experiment design, which can be run later (once data is taken) by using a DefaultProtocolRunner object.

Return type:

DirectRBDesign

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

items()#

An iterator over the (child_name, child_node) pairs of this node.

keys()#

An iterator over the keys (child names) of this tree node.

map_qubit_labels(mapper)#

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters:

mapper (dict or function) – A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label.

Return type:

DirectRBDesign

merge_with(other_edesign, remove_duplicates=True, sort_depths=False)#

Merge this experiment design with another one and return the result.

The returned design will contain the union of the circuits in the two experiment designs being merged, and will contain depth, ideal-output, etc. metadata that is updated appropriately.

Parameters:

other_edesign (BenchmarkingDesign) – The other experiment design to merge

Return type:

BenchmarkingDesign

promote_to_combined(name='subdesign-0')#

Promote this experiment design to be a combined experiment design.

Wraps this experiment design in a new CombinedExperimentDesign whose only sub-design is this one, and returns the combined design.

Parameters:

name (str, optional) – The sub-design-name of this experiment design within the created combined experiment design.

Return type:

CombinedExperimentDesign

promote_to_simultaneous()#

Promote this experiment design to be a simultaneous experiment design.

Wraps this experiment design in a new SimultaneousExperimentDesign whose only sub-design is this one, and returns the simultaneous design.

Return type:

SimultaneousExperimentDesign

prune_tree(paths, paths_are_sorted=False)#

Prune the tree rooted here to include only the given paths, discarding all other leaves & branches.

Parameters:

  • paths (list) – A list of tuples specifying the paths to keep.

  • paths_are_sorted (bool, optional) – Whether paths is sorted (lexicographically). Setting this to True will save a little time.

Returns:

A view of this node and its descendants where unwanted children have been removed.

Return type:

TreeNode

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_actual_circuits_executed(actual_circuits)#

Sets a list of circuits that will actually be executed.

This list must be parallel, and corresponding circuits must be logically equivalent, to those in self.all_circuits_needing_data. For example, when the circuits in this design are run simultaneously with other circuits, the circuits in this design may need to be padded with idles.

Parameters:

actual_circuits (list) – A list of Circuit objects that must be the same length as self.all_circuits_needing_data.

Return type:

None

setup_nameddict(final_dict)#

Initializes a set of nested NamedDict dictionaries describing this design.

This function is used by ProtocolResults objects when they’re creating nested dictionaries of their contents. This function returns a set of nested, single (key,val)-pair named-dictionaries which describe the particular attributes of this ExperimentDesign object named within its self._nameddict_attributes tuple. The final nested dictionary is set to be final_dict, which allows additional result quantities to easily be added.

Parameters:

final_dict (NamedDict) – the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Return type:

NamedDict

truncate_to_available_data(dataset)#

Builds a new experiment design containing only those circuits present in dataset.

Parameters:

dataset (DataSet) – The dataset to filter based upon.

Return type:

ExperimentDesign

truncate_to_circuits(circuits_to_keep)#

Builds a new experiment design containing only the specified circuits.

Parameters:

circuits_to_keep (list) – A list of the circuits to keep.

Return type:

ExperimentDesign

truncate_to_design(other_design)#

Truncates this experiment design by only keeping the circuits also in other_design

Parameters:

other_design (ExperimentDesign) – The experiment design to compare with.

Returns:

The truncated experiment design.

Return type:

ExperimentDesign

truncate_to_lists(list_indices_to_keep)#

Truncates this experiment design by only keeping a subset of its circuit lists.

Parameters:

list_indices_to_keep (iterable) – A list of the (integer) list indices to keep.

Returns:

The truncated experiment design.

Return type:

BenchmarkingDesign

underlying_tree_paths()#

Dictionary paths leading to data objects/nodes beneath this one.

Returns:

A list of tuples, each specifying the tree traversal to a child node. The first tuple is the empty tuple, referring to this (root) node.

Return type:

list

view(keys_to_keep)#

Get a “view” of this tree node that only has a subset of this node’s children.

Parameters:

keys_to_keep (iterable) – A sequence of key names to keep.

Return type:

TreeNode

write(dirname=None, parent=None)#

Write this experiment design to a directory.

Parameters:

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

  • parent (ExperimentDesign, optional) – The parent experiment design, when a parent is writing this design as a sub-experiment-design. Otherwise leave as None.

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

paired_with_circuit_attrs = None#

List of attributes which are paired up with circuit lists

These will be saved as external files during serialization, and are truncated when circuit lists are truncated.