GateFolding

class GateFolding

Bases: MitigationTask

Calculates expectation values of observables using Zero Noise Extrapolation (ZNE) with gate folding mitigation method.

The class enables preparing a QuantumProgram with circuit mitigated using ZNE with gate folding method, that can be executed on hardware using the Executor, and post process the results to calculate mitigated expectation values of given observables. The task parameters should be given as input to the prepare function, and the relevant variables needed for post-processing are saved internally:

gf_task = GateFolding()
program = gf_task.prepare(circuit=circuit,
                       observables=observables,
                       parameters=parameter_values,
                       noise_factors=noise_factors_array,
                       extrapolator=extrapolators_list)
job = executor.run(program)
results = job.result()
mitigated_result = gf_task.postprocess(results)

To calculate expectation values of a loaded job result, a GateFolding task can be created from the job results with all the internal variables needed for post-processing. Alternatively, the variables required for post-processing can be given as input directly to the compute_expectation_value static method. Example for running post-processing for a loaded result:

gf_task = GateFolding()
program = gf_task.prepare(circuit=circuit,
                       observables=observables,
                       parameters=parameter_values,
                       noise_factors=noise_factors_array,
                       extrapolator=extrapolators_list)
job_id = executor.run(program).job_id

job = service.job(job_id)
results = job.result()
gf_task = load_tasks_from_result(results)[0]
mitigated_result = gf_task.postprocess(results)

Instantiate a GateFolding task.

Attributes

VERSION

Default value: '0.1'

Methods

compute_expectation_value

static compute_expectation_value(item_result, observables, param_shape=None, param_basis_pairs=None, meas_bases=None, broadcast_obs_and_params=False, measure_noise_data=None)

GitHub

Process expectation values for a single item result.

This function can be used to calculate expectation values for a single unmitigated item result without instantiating a new class instance.

Parameters

item_result (QuantumProgramItemResult) – The item result.
observables (ObservablesArray |Sequence[SparsePauliOp]) – The observables to calculate expectation values for.
param_shape (tuple[int, ...] | None) – The shape of the parameter values.
param_basis_pairs (list[tuple[tuple[int, ...], str]] | None) – The map between params ndindexes to measure basis.
meas_bases (Sequence[Pauli] | Sequence[str] | PauliList | None) – A list of the measured Pauli bases. The i th item is a measurement basis assumed to correspond to the i th slice of the data in item_result.
broadcast_obs_and_params (bool) – Whether to broadcast observables and parameter values.
measure_noise_data (PauliLindbladMap |ndarray | None) – Measurement noise calibration data for TREX mitigation.

Returns

A PubResult which contains evs and std as fields in its data, where evs are expectation values, and std are the standard deviation of the expectation values. If broadcast_obs_and_params is set to True, the data will contain also a twirl_stds field which is the standard deviation between different randomizations.

Raises

ValueError – If item_result has no '_meas' key.
ValueError – If item_result['_meas'] has invalid number of axes.
ValueError – If param_shape and observables.shape cannot be broadcasted against each other.

Return type

PubResult

compute_expectation_value_gate_folding

static compute_expectation_value_gate_folding(item_results, observables, param_shape, param_basis_pairs, noise_factors, extrapolator, extrapolated_noise_factors=None, meas_bases=None, broadcast_obs_and_params=False, measure_noise_data=None, custom_fit=None)

GitHub

Process expectation values for a single item result.

This function can be used to calculate expectation values for a single gate_folding mitigated item result without instantiating a new class instance.

Parameters

item_results (list[QuantumProgramItemResult]) – List of the item results - one for each noise factor.
observables (ObservablesArray |Sequence[SparsePauliOp]) – The observables to calculate expectation values for.
param_shape (tuple[int, ...] | None) – The shape of the parameter values.
param_basis_pairs (list[tuple[tuple[int, ...], str]] | None) – The map between params ndindexes to measure basis.
noise_factors (list[float]) – The noise factors that were used to amplify the noise.
extrapolated_noise_factors (float |int |list[float] | None) – Noise factors to evaluate the fits at.
extrapolator (list[Literal['linear', 'exponential', 'double_exponential', 'polynomial_degree_1', 'polynomial_degree_2', 'polynomial_degree_3', 'polynomial_degree_4', 'polynomial_degree_5', 'polynomial_degree_6', 'polynomial_degree_7', 'fallback', 'custom']]) –

The extrapolator model or models to use. Models will be tried in priority order. Supported models (each fits the named function of the noise factor x):
- "linear": a + b*x
- "polynomial_degree_k" (1 <= k <= 7): a degree-k polynomial
- "exponential": a*exp(b*x)
- "double_exponential": a*exp(b*x) + c*exp(d*x) (rates constrained to decay)
- "fallback": no fit; the measured value at the lowest noise factor
- custom: The custom extrapolation function given in custom_fit parameter
meas_bases (Sequence[Pauli] | Sequence[str] | PauliList | None) – A list of the measured Pauli bases. The i th item is a measurement basis assumed to correspond to the i th slice of the data in each of the item_results.
broadcast_obs_and_params (bool) – Whether to broadcast observables and parameter values.
measure_noise_data (PauliLindbladMap |ndarray | None) – Measurement noise calibration data for TREX mitigation. Can be either a PauliLindbladMap of a noise model learned upfront, or a result of a calibration circuit.
custom_fit (tuple[Callable[[...], ndarray], list[float], tuple[float, ...] | tuple[list[float], ...]] | None) – A custom fitting function that will be used for extrapolation. Should include a tuple in the form of: (function, p_0, bounds). The function should take the independent variable as the first argument and the parameters to fit as separate remaining arguments. p_0 is an array of the initial guess for the parameters, and bounds are the bounds on the parameters. These parameters will be sent as arguments for scipy.optimize.curve_fit function.

Returns

evs: expectation values evaluated at the zero noise point.
std: the standard deviations of the extrapolated expectation values evaluated at the zero noise point.
evs_noise_factors: expectation values calculated at the noise_factors points.
stds_noise_factors: standard deviations calculated at the noise_factors points.
stds_twirl_noise_factors: standard deviations between different randomizations calculated at the

noise_factors points.
evs_extrapolated: expectation values evaluated at the extrapolated_noise_factors points.

Set to None if extrapolated_noise_factors is None.
stds_extrapolated: standard deviations calculated at the extrapolated_noise_factors points.

Set to None if extrapolated_noise_factors is None.

The PubResult will also contain a selected_extrapolators field in the metadata, which is the valid extrapolators used to extrapolate the data for each observable term for the zero noise extrapolation point.

Return type

A PubResult which contains the following fields

Raises

ValueError – If one of the item_results has no '_meas' key.
ValueError – If one of the item_results’ '_meas' data has an invalid number of axes.
ValueError – If param_shape and observables.shape cannot be broadcasted against each other.
ValueError – If noise_factors is under-specified for any extrapolator.

create_instance_from_passthrough_data

static create_instance_from_passthrough_data(passthrough, trex=None)

GitHub

Create a GateFolding instance from a passthrough dictionary loaded from a quantum program execution result.

Parameters

passthrough (dict[str, Any]) – Passthrough_data dictionary loaded from a quantum program execution result.
trex (TREX | None) – A TREX instance containing a calibration circuit results executed in the same quantum program. Should remain None in case TREX mitigation was not used or a TREX calibration was not executed as part of thq same quantum program.

Returns

A GateFolding instance.

Return type

GateFolding

find_unique_layers

find_unique_layers(circuit, custom_boxing_options=None)

GitHub

Return the unique boxed layers of the given circuit using the given boxing options.

Parameters

circuit (QuantumCircuit) – The circuit to found its unique layers.
custom_boxing_options (dict | None) – The custom boxing options that will be used by generate_boxing_pass_manager() function.

Returns

Unique boxed layers of the given circuit.

Return type

list[CircuitInstruction]

postprocess

postprocess(results, measure_noise_data=None, *, noise_factors=None, extrapolator=None, extrapolated_noise_factors=None, custom_fit=None)

GitHub

Process expectation values for a single GateFolding task result.

Parameters

results (list[QuantumProgramItemResult] | QuantumProgramResult) – The execution results. Can be either the entire results object or the gate folding mitigated items of this task. If TREX calibration task is added to the quantum program, its results will be used to compute the measure noise data if the entire results object is provided.
noise_factors (Sequence[float] | None) – The noise factors that were used to amplify the noise.
extrapolated_noise_factors (list[float] | None) – Noise factors to evaluate the fits at.
extrapolator (Sequence[Literal['linear', 'exponential', 'double_exponential', 'polynomial_degree_1', 'polynomial_degree_2', 'polynomial_degree_3', 'polynomial_degree_4', 'polynomial_degree_5', 'polynomial_degree_6', 'polynomial_degree_7', 'fallback', 'custom']] | None) –

The extrapolator model or models to use. Models will be tried in priority order. Supported models (each fits the named function of the noise factor x):
- "linear": a + b*x
- "polynomial_degree_k" (1 <= k <= 7): a degree-k polynomial
- "exponential": a*exp(b*x)
- "double_exponential": a*exp(b*x) + c*exp(d*x) (rates constrained to decay)
- "fallback": no fit; the measured value at the lowest noise factor
- custom: The custom extrapolation function given in custom_fit parameter
measure_noise_data (PauliLindbladMap |ndarray | None) – Measurement noise calibration data for TREX mitigation. Can be either a PauliLindbladMap of a noise model learned upfront, or a result of a calibration circuit.
custom_fit (tuple[Callable[[...], ndarray], list[float], tuple[float, ...] | tuple[list[float], ...]] | None) – A custom fitting function that will be used for extrapolation. Should include a tuple in the form of: (function, p_0, bounds). The function should take the independent variable as the first argument and the parameters to fit as separate remaining arguments. p_0 is an array of the initial guess for the parameters, and bounds are the bounds on the parameters. These parameters will be sent as arguments for scipy.optimize.curve_fit function.

Returns

evs: expectation values evaluated at the zero noise point.
std: the standard deviations of the extrapolated expectation values evaluated at the zero noise point.
evs_noise_factors: expectation values calculated at the noise_factors points.
stds_noise_factors: standard deviations calculated at the noise_factors points.
stds_twirl_noise_factors: standard deviations between different randomizations calculated at the

noise_factors points.
evs_extrapolated: expectation values evaluated at the extrapolated_noise_factors points.

Set to None if extrapolated_noise_factors is None.
stds_extrapolated: standard deviations calculated at the extrapolated_noise_factors points.

Set to None if extrapolated_noise_factors is None.

Return type

A PubResult which contains the following fields

Raises

ValueError – If one of the task’s item results has no '_meas' key.
ValueError – If one of the item results’ '_meas' data has an invalid number of axes.
ValueError – If param_shape and observables.shape cannot be broadcasted against each other.

prepare

prepare(circuit, observables, parameters, custom_boxing_options=None, shots_per_randomization=64, num_randomizations=128, broadcast_obs_and_params=False, trex=None, quantum_program=None, *, folding_method='random', noise_factors=(1, 3, 5), extrapolator=None, extrapolated_noise_factors=None)

GitHub

Creates a QuantumProgram with GateFolding mitigated item for executing via Executor.

Creates an item for a QuantumProgram, that can be executed via Executor and is GateFolding mitigated (amplifies the noise using gate folding techniques and extrapolates to the zero noise point). If a quantum_program is provided, the new item will be added to the existing program, otherwise, a new program will be created, containing only the created item. If broadcast_obs_and_params is True, the observables and parameters will be broadcasted using the samplomatic broadcasting rules, to allow attaching some of the parameters to some of the observables. Otherwise, every parameter will be executed for each observable (outer product of the parameters and observables). Note that the post-processing of an outer product is usually faster.

Parameters

circuit (QuantumCircuit) – The quantum circuit.
observables (ObservablesArray |Sequence[SparsePauliOp]) – The observables to calculate their expectation values.
parameters (ndarray | None) – The parameters of a parametric circuit.
custom_boxing_options (dict | None) – The custom boxing options that will be used by generate_boxing_pass_manager() function.
shots_per_randomization (int) – The number of shots per randomization.
num_randomizations (int) – The number of randomizations.
broadcast_obs_and_params (bool) – Whether to broadcast observables and parameters.
trex (TREX | None) – A TREX mitigation instance that will be used to mitigate readout errors.
quantum_program (QuantumProgram | None) – The quantum program to add an item for. If None, a new program will be created.
folding_method (Literal['random', 'front', 'back']) –

The technique to use to fold the 2-qubit gates to amplify the noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected according to the method:
- "random" (default): the gates are chosen randomly.
- "front": the gates are selected from the front of the topologically ordered DAG circuit.
- "back": the gates are selected from the back of the topologically ordered DAG circuit.
noise_factors (Sequence[float |int]) – The noise factors to use for amplifying the noise.
extrapolator (Sequence[Literal['linear', 'exponential', 'double_exponential', 'polynomial_degree_1', 'polynomial_degree_2', 'polynomial_degree_3', 'polynomial_degree_4', 'polynomial_degree_5', 'polynomial_degree_6', 'polynomial_degree_7', 'fallback', 'custom']] | None) –

The extrapolator model or models planned to be used in post-processing. Used in preparation to validate that enough noise factors are present for a valid fit using these extrapolators. If None, not validation will be done. Supported models (each fits the named function of the noise factor x):
- "linear": a + b*x
- "polynomial_degree_k" (1 <= k <= 7): a degree-k polynomial
- "exponential": a*exp(b*x)
- "double_exponential": a*exp(b*x) + c*exp(d*x) (rates constrained to decay)
- "fallback": no fit; the measured value at the lowest noise factor
extrapolated_noise_factors (list[float] | None) – The noise factors to evaluate the fits at planned to be used in post-processing. Used for saving the data for easy post-processing. Can be overwritten in the post-processing.

Returns

A QuantumProgram with GateFolding mitigated item that can be executed via Executor.

Return type

QuantumProgram

Was this page helpful?

Report a bug, typo, or request content on GitHub.