IBM Circuit function API reference

Qiskit Functions
Qiskit Functions — pre-built tools created by partner organizations — abstract away parts of the software development workflow to simplify and accelerate utility-scale algorithm discovery and application development. Click to view the guide for this Qiskit Function.
IBM Circuit function guide

Inputs

See the following list for all input parameters the IBM Circuit function accepts. The subsequent Options section goes into more details about the available options.

`backend_name`

Type: str

Name of the backend to make the query.

Required: Yes
Example: ibm_fez

`pubs`

Type: Iterable[EstimatorPubLike]

An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples (circuit, observables) or (circuit, observables, parameter_values). See Overview of PUBs for more information. The circuits can be abstract (non-ISA).

Required: Yes
Example: (circuit, observables, parameter_values)

`instance`

Type: str

Default value: One is randomly picked if your account has access to multiple instances

The cloud resource name of the instance to use in that format.

Required: No
Example: CRN

Options

Type: dict

Input options. See the Options list for more details.

Required:No
Example: {"optimization_level": 3}

Structure

Similar to Qiskit Runtime primitives, options for IBM Circuit function can be specified as a nested dictionary. Commonly used options, such as optimization_level and mitigation_level, are at the first level. Other, more advanced options are grouped into different categories, such as resilience.

Defaults

If you do not specify a value for an option, the default value specified by the service is used.

Mitigation level

IBM Circuit function also supports mitigation_level. The mitigation level specifies how much error suppression and mitigation to apply to the job. Higher levels generate more accurate results, at the expense of longer processing times. The degree of error reduction depends on the method applied. The mitigation level abstracts the detailed choice of error mitigation and suppression methods to allow users to reason about the cost/accuracy trade-off appropriate to their application. The following table shows the corresponding methods for each level.

Note

While the names are similar, mitigation_level applies different techniques than the ones used by Estimator's resilience_level.

Similar to resilience_level in Qiskit Runtime Estimator, mitigation_level specifies a base set of curated options. Any options you manually specify in addition to the mitigation level are applied on top of the base set of options defined by the mitigation level. Therefore, in principle, you could set the mitigation level to 1, but then turn off measurement mitigation, although this is not advised.

Mitigation Level	Technique
1 [Default]	Dynamical decoupling + measurement twirling + TREX
2	Level 1 + gate twirling + ZNE via gate folding
3	Level 1 + gate twirling + ZNE via PEA

Note

While the names are similar, mitigation_level applies different techniques than the ones used by Estimator's resilience_level.

Options list

In addition to mitigation_level, the IBM Circuit function also provides a select number of advanced options that allow you to fine-tune the cost/accuracy trade-off.

`default_precision`

Default value: 0.015625

The default precision to use for any PUB or run() call that does not specify one. Each input PUB can specify its own precision. If the run() method is given a precision, then that value is used for all PUBs in the run() call that do not specify their own.

Choices: float > 0

`max_execution_time`

Maximum execution time in seconds, which is based on QPU usage (not wall clock time). QPU usage is the amount of time that the QPU is dedicated to processing your job. If a job exceeds this time limit, it is forcibly canceled.

Choices: Integer number of seconds in the range [1, 10800]

`mitigation_level`

Default value: 1

How much error suppression and mitigation to apply. Refer to the Mitigation level section for more information about the methods used at each level.

Choices: 1 / 2 / 3

`optimization_level`

Default value: 2

How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time.

Choices: 1 / 2 / 3

`dynamical_decoupling`

enable

Default value: True

Whether to enable dynamical decoupling. Refer to Error suppression and mitigation techniques for the explanation of the method.

Choices: True/False

sequence_type

Default value: XX

Which dynamical decoupling sequence to use.

XX: use the sequence tau/2 - (+X) - tau - (+X) - tau/2
XpXm: use the sequence tau/2 - (+X) - tau - (-X) - tau/2
XY4: use the sequence tau/2 - (+X) - tau - (+Y) - tau (-X) - tau - (-Y) - tau/2
Choices: 'XX'/'XpXm'/'XY4'

`twirling`

enable_gates

Default value: False

Whether to apply two-qubit Clifford gate twirling.

Choices: True/False

enable_measure

Default value: True

Whether to enable twirling of measurements.

Choices: True/False

`resilience`

measure_mitigation

Default value: True

Whether to enable TREX measurement error mitigation method. Refer to Error suppression and mitigation techniques for the explanation of the method.

Choices: True/False

zne

amplifier

Default value: gate_folding

Which technique to use for amplifying noise. One of:

gate_folding (default) uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are chosen randomly.
gate_folding_front uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the front of the topologically ordered DAG circuit.
gate_folding_back uses two-qubit gate folding to amplify noise. If the noise factor requires amplifying only a subset of the gates, then these gates are selected from the back of the topologically ordered DAG circuit.
pea uses a technique called Probabilistic error amplification (PEA) to amplify noise. Refer to Error suppression and mitigation techniques for the explanation of the method.
Choices: gate_folding / gate_folding_front / gate_folding_back / pea

noise_factors

Default value: (1, 1.5, 2) for PEA, and (1, 3, 5) otherwise

Noise factors to use for noise amplification.

Choices: list of floats; each float >= 1

extrapolator

Default value: (exponential, linear)

Noise factors at which to evaluate the fit extrapolation models. This option does not affect execution or model fitting in any way; it only determines the points at which the extrapolator objects are evaluated to be returned in the data fields called evs_extrapolated and stds_extrapolated.

Choices: One or more of exponential,linear, double_exponential,polynomial_degree_(1 <= k <= 7)

pec_mitigation

Default value: False

Whether to turn on Probabilistic Error Cancellation error mitigation method. Refer to Error suppression and mitigation techniques for the explanation of the method.

Choices: True/False

pec

max_overhead

Default value: 100

The maximum circuit sampling overhead allowed, or None for no maximum.

Choices: None/ integer > 1

zne_mitigation

Default value: False

Whether to turn on Zero Noise Extrapolation error mitigation method. Refer to Error suppression and mitigation techniques for the explanation of the method.

Choices: True/False

Outputs

The output of a Circuit function is a PrimitiveResult, which contains two fields:

One or more PubResult objects. These can be indexed directly from the PrimitiveResult.
Job-level metadata.

Each PubResult contains a data and a metadata field.

The data field contains at least an array of expectation values (PubResult.data.evs) and an array of standard errors (PubResult.data.stds). It can also contain more data, depending on the options used.
The metadata field contains PUB-level metadata (PubResult.metadata).

Was this page helpful?

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