pygsti.tools.edesigntools
Tools for working with ExperimentDesigns
Module Contents
Functions
|
Estimate the runtime for an ExperimentDesign from gate times and batch sizes. |
|
Helper function to calculate all Fisher information terms for each circuit. |
|
Calculate the Fisher information matrix for a set of circuits and a model. |
|
Calculate a set of Fisher information matrices for a set of circuits grouped by iteration. |
|
|
|
|
|
Utility to explicitly pad out ExperimentDesigns with idle lines. |
- pygsti.tools.edesigntools.calculate_edesign_estimated_runtime(edesign, gate_time_dict=None, gate_time_1Q=None, gate_time_2Q=None, measure_reset_time=0.0, interbatch_latency=0.0, total_shots_per_circuit=1000, shots_per_circuit_per_batch=None, circuits_per_batch=None)
Estimate the runtime for an ExperimentDesign from gate times and batch sizes.
The rough model is that the required circuit shots are split into batches, where each batch runs a subset of the circuits for some fraction of the needed shots. One round consists of running all batches once, i.e. collecting some shots for all circuits, and rounds are repeated until the required number of shots is met for all circuits.
In addition to gate times, the user can also provide the time at the end of each circuit for measurement and/or reset, as well as the latency between batches for classical upload/ communication of the next set of circuits. Since times are user-provided, this function makes no assumption on the units of time, only that a consistent unit is used for all times.
Parameters
- edesign: ExperimentDesign
An experiment design containing all required circuits.
- gate_time_dict: dict
Dictionary with keys as either gate names or gate labels (for qubit-specific overrides) and values as gate time in user-specified units. All operations in the circuits of edesign must be specified. Either gate_time_dict or both gate_time_1Q and gate_time_2Q must be specified.
- gate_time_1Q: float
Gate time in user-specified units for all operations acting on one qubit. Either gate_time_dict or both gate_time_1Q and gate_time_2Q must be specified.
- gate_time_2Q: float
Gate time in user-specified units for all operations acting on more than one qubit. Either gate_time_dict or both gate_time_1Q and gate_time_2Q must be specified.
- measure_reset_time: float
Measurement and/or reset time in user-specified units. This is applied once for every circuit.
- interbatch_latency: float
Time between batches in user-specified units.
- total_shots_per_circuit: int
Total number of shots per circuit. Together with shots_per_circuit_per_batch, this will determine the total number of rounds needed.
- shots_per_circuit_per_batch: int
Number of shots to do for each circuit within a batch. Together with total_shots_per_circuit, this will determine the total number of rounds needed. If None, this is set to the total shots, meaning that only one round is done.
- circuits_per_batch: int
Number of circuits to include in each batch. Together with the number of circuits in edesign, this will determine the number of batches in each round. If None, this is set to the total number of circuits such that only one batch is done.
Returns
- float
The estimated time to run the experiment design.
- pygsti.tools.edesigntools.calculate_fisher_information_per_circuit(regularized_model, circuits, approx=False, verbosity=1, comm=None, mem_limit=None)
Helper function to calculate all Fisher information terms for each circuit.
This function can be used to pre-generate a cache for the calculate_fisher_information_matrix() function, and this should be done for computational efficiency when computing many Fisher information matrices.
Parameters
- regularized_model: OpModel
The model used to calculate the terms of the Fisher information matrix. This model must already be “regularized” such that there are no small probabilities, usually by adding a small amount of SPAM error.
- circuits: list
List of circuits to compute Fisher information for.
- approx: bool, optional (default False)
When set to true use the approximate fisher information where we drop the hessian term. Significantly faster to compute than when including the hessian.
- verbosity: int, optional (default 1)
Used to control the level of output printed by a VerbosityPrinter object.
- 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 is used to determine job allocation when there are multiple processors.
Returns
- fisher_info_terms: dict
Dictionary where keys are circuits and values are (num_params, num_params) Fisher information matrices for a single circuit.
- pygsti.tools.edesigntools.calculate_fisher_information_matrix(model, circuits, num_shots=1, term_cache=None, regularize_spam=True, approx=False, mem_efficient_mode=False, circuit_chunk_size=100, verbosity=1, comm=None, mem_limit=None)
Calculate the Fisher information matrix for a set of circuits and a model.
Note that the model should be regularized so that no probability should be very small for numerical stability. This is done by default for models with a dense SPAM parameterization, but must be done manually if this is not the case (e.g. CPTP parameterization).
Parameters
- model: OpModel
The model used to calculate the terms of the Fisher information matrix.
- circuits: list
List of circuits in the experiment design.
- num_shots: int or dict
If int, specifies how many shots each circuit gets. If dict, keys must be circuits and values are per-circuit counts.
- term_cache: dict or None
If provided, should have circuits as keys and per-circuit Fisher information matrices as values, i.e. the output of calculate_fisher_information_per_circuit(). This cache will be updated with any additional circuits that need to be calculated in the given circuit list.
- regularize_spam: bool
If True, depolarizing SPAM noise is added to prevent 0 probabilities for numerical stability. Note that this may fail if the model does not have a dense SPAM paramerization. In that case, pass an already “regularized” model and set this to False.
- approx: bool, optional (default False)
When set to true use the approximate fisher information where we drop the hessian term. Significantly faster to compute than when including the hessian.
- mem_efficient_mode: bool, optional (default False)
If true avoid constructing the intermediate term cache to save on memory.
- circuit_chunk_size, int, optional (default 100)
Used in conjunction with mem_efficient_mode. This sets the maximum number of circuits to simultaneously construct the per-circuit contributions to the fisher information for at any one time.
- verbosity: int, optional (default 1)
Used to control the level of output printed by a VerbosityPrinter object.
- 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 is used to determine job allocation when there are multiple processors.
Returns
- fisher_information: numpy.ndarray
Fisher information matrix of size (num_params, num_params)
- pygsti.tools.edesigntools.calculate_fisher_information_matrices_by_L(model, circuit_lists, Ls, num_shots=1, term_cache=None, regularize_spam=True, cumulative=True, approx=False, mem_efficient_mode=False, circuit_chunk_size=100, verbosity=1, comm=None, mem_limit=None)
Calculate a set of Fisher information matrices for a set of circuits grouped by iteration.
Parameters
- model: OpModel
The model used to calculate the terms of the Fisher information matrix.
- circuit_lists: list of lists of circuits or CircuitLists
Circuit lists for the experiment design for each L. Most likely from the value of the circuit_lists attribute of most experiment design objects.
- Lslist of ints
A list of integer values corresponding to the circuit lengths associated with each circuit list as past in with circuit_lists.
- num_shots: int or dict
If int, specifies how many shots each circuit gets. If dict, keys must be circuits and values are per-circuit counts.
- term_cache: dict or None
If provided, should have circuits as keys and per-circuit Fisher information matrices as values, i.e. the output of calculate_fisher_information_per_circuit(). This cache will be updated with any additional circuits that need to be calculated in the given circuit list.
- regularize_spam: bool
If True, depolarizing SPAM noise is added to prevent 0 probabilities for numerical stability. Note that this may fail if the model does not have a dense SPAM paramerization. In that case, pass an already “regularized” model and set this to False.
- cumulative: bool
Whether to include Fisher information matrices for lower L (True) or not.
- approx: bool, optional (default False)
When set to true use the approximate fisher information where we drop the hessian term. Significantly faster to compute than when including the hessian.
- mem_efficient_mode: bool, optional (default False)
If true avoid constructing the intermediate term cache to save on memory.
- circuit_chunk_size, int, optional (default 100)
Used in conjunction with mem_efficient_mode. This sets the maximum number of circuits to simultaneously construct the per-circuit contributions to the fisher information for at any one time.
- verbosity: int, optional (default 1)
Used to control the level of output printed by a VerbosityPrinter object.
- 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 is used to determine job allocation when there are multiple processors.
Returns
- fisher_information_by_L: dict
Dictionary with keys as circuit length L and value as Fisher information matrices
- pygsti.tools.edesigntools.accumulate_fim_matrix(subcircuits, num_params, num_shots, outcomes, ps, js, printer, hs=None, approx=False)
- pygsti.tools.edesigntools.accumulate_fim_matrix_per_circuit(subcircuits, num_params, outcomes, ps, js, printer, hs=None, approx=False)
- pygsti.tools.edesigntools.pad_edesign_with_idle_lines(edesign, line_labels)
Utility to explicitly pad out ExperimentDesigns with idle lines.
Parameters
- edesign: ExperimentDesign
The edesign to be padded.
- line_labels: tuple of int or str
Full line labels for the padded edesign.
Returns
- ExperimentDesign
An edesign where all circuits have been padded out with missing idle lines