--- title: QESEM by Qedma API reference description: API reference for QESEM, a Qiskit Function by Qedma source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/functions/qedma-qesem --- # QESEM by Qedma API reference - [**Qiskit Functions**](/docs/guides/qedma-qesem) — 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. ## Inputs ### `pubs` Type: [`EstimatorPubLike`](/docs/guides/primitive-input-output) This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used. The PUB precision can be either a float or a dictionary. A float sets the target precision for the returned expectation values. A dictionary maps noise scale factors to target precisions and requests Quasi-probabilistic Error Tuning (QET) results at the specified scales. QESEM will also return complementary scale factors around `1.0`; target precision is guaranteed for the requested scale factors only. - Required: Yes - Example: `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` - QET example: `[(circuit, [obs1, obs2], None, {0.5: 0.15, 1.3: 0.2})]` ### `backend_name` Type: `` `str` `` Default value: `QESEM will get least busy device reported by IBM` Name of the backend to use - Required: No - Example: `"ibm_fez"` ### `instance` Type: `` `str` `` The cloud resource name of the instance to use in that format - Required: No - Example: `"CRN"` ### Options Type: `` `dict` `` Input options for this function are specified as a nested dictionary. See the full [list of options](#options-list) and their default values. - Required: No - Example: `{ "default_precision": 0.03, "max_execution_time": 3600, "transpilation_level": "standard"}` #### Options list ##### `estimate_time_only` Default value: `None` This flag enables users to obtain an estimate for the QPU time required to execute the circuit with QESEM. - When set to None, the circuit will be executed with QESEM. - If set to `"analytical"`, an upper bound of the QPU time is calculated without consuming any QPU usage. This estimation has a 30-minute resolution (for example, 30 minutes, 60 minutes, 90 minutes, and so forth). It is typically pessimistic, and can only be obtained for single Pauli observables or sums of Paulis without intersecting supports (for example, Z0+Z1). It is primarily useful for comparing the complexity levels of different parameters provided by the user (circuit, accuracy, and so on). - To obtain a more accurate QPU time estimation, set this flag to `"empirical"`. Although this option requires running a small number of circuits, it provides a significantly more accurate QPU time estimation. This estimation has a 5-minute resolution (for example, 20 minutes, 25 minutes, 30 minutes, and so on). The user may choose to run the empirical time estimation in either batch or session mode. For more details, please see the `execution_mode` description. For example, in batch mode, empirical time estimation will consume less than 10 minutes of QPU time. - Choices: `"analytical"` / `"empirical"` / None ##### `default_precision` Default value: `0.02` Will apply to `pubs` that don't have precision. The precision signifies the acceptable error on the expectation values of the observables in absolute value. Namely, the QPU runtime for mitigation will be determined to provide output values for all the observables of interest that fall within a 1$\sigma$ confidence interval of the target precision. If multiple observables are provided, the mitigation will run until the target precision is reached for each of the input observables. - Choices: 0 \< float ##### `max_execution_time` Default value: `3,600 (one hour)` Allows you to limit the QPU time, specified in seconds, to be used for the entire QESEM process. The default value is 3,600 seconds (one hour). Since the final QPU time required to reach the target accuracy is determined dynamically during the QESEM job, this parameter enables you to limit the cost of the experiment. If the dynamically-determined QPU time is shorter than the time allocated by the user, this parameter will not affect the experiment. The `max_execution_time` parameter is particularly useful in cases where the analytical time estimate provided by QESEM before the job starts is too pessimistic and the user wants to initiate a mitigation job anyway. After the time limit is reached, QESEM stops sending new circuits. Circuits that have already been sent continue running (so the total time may surpass the limit by up to 30 minutes), and the user receives the processed results from the circuits that ran up to that point. If you want to apply a QPU time limit shorter than the analytical time estimate, consult with Qedma to obtain an estimate for the accuracy achievable within the time limit. - Choices: 0 \< integer \< 28,800 (8 hours) ##### `transpilation_level` Default value: `standard` After a circuit is submitted to QESEM, it automatically prepares several alternative circuit transpilations and chooses the one that minimizes QPU time. For instance, alternative transpilations might utilize Qedma-optimized fractional RZZ gates to reduce the circuit depth. Of course, all transpilations are equivalent to the input circuit, in terms of their ideal output. To exert more control over the circuit transpilation, set the transpilation level in the `options`. While `"transpilation_level": "standard"` corresponds to the default behavior described above, `"transpilation_level": "minimal_with_layout_opt"` includes only minimal modifications required to the original circuit; for example, mapping the circuit to the device connectivity graph. Note that automatic hardware-mapping onto high-fidelity qubits is applied in any case. | `transpilation_level` | Description | | :--------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "standard" | Default QESEM transpilation. Prepares several alternative transpilations and chooses the one that minimizes QPU time. Barriers may be modified in the layerification step. | | "minimal\_with\_layout\_opt" | Minimal transpilation: the mitigated circuit will closely resemble the input circuit structurally. Circuits provided in this level should match the device basis gate set, and thus you should transpile your circuit to the basis gate set of the device separately. For example: CX, Rzz(α), and standard single-qubit gates (U, x, sx, rz, and so on). Barriers will be respected in the layerification step. | For jobs that contain multiple input PUBs or multiple parameter-bound circuit instances, use `"minimal_with_layout_opt"`. - Choices: "minimal\_with\_layout\_opt" / "standard" ##### `execution_mode` Default value: `batch` The user can choose to run the QESEM job in either a dedicated [IBM session](/docs/guides/execution-modes#session-mode) or across multiple [IBM batches](/docs/guides/execution-modes#batch-mode): - **Session Mode**: Sessions are more expensive but result in a shorter time-to-result. Once the session begins, the QPU is reserved exclusively for the QESEM job. The usage calculation includes both the time spent on QPU execution and the associated classical computations (performed by QESEM and IBM). The QESEM Qiskit Function takes care of creating and closing the session automatically. For users with unlimited access to QPUs (for example, on-premises setups), it is recommended to use session mode for faster QESEM execution. - **Batch Mode**: In batch mode, the QPU is released during classical computations, leading to lower QPU usage. As batch jobs typically span a longer period, there is a greater risk of hardware drifts; QESEM incorporates measures to detect and compensate for drifts, retaining reliability over extended runs. - Choices: `"session"` / `"batch"` ##### `parallel_execution` Default value: `True` This flag allows the user to execute the input circuit in parallel on the QPU. QESEM checks whether other patches on the QPU have sufficient fidelity. If such patches reduce QPU time, QESEM runs the input circuit on those patches in parallel. The results from the patches are combined using inverse variance weighting. - Example: A user wants to run an 8-qubit circuit on `ibm_marrakesh`, a 156-qubit device, with `parallel_execution=True`. QESEM creates nine copies of the transpiled circuit, each mapped to a distinct 8-qubit patch on Marrakesh’s connectivity graph. After execution, the user receives a single expectation value and error bar for each input observable. - Choices: `"False"` / `"True"` ##### `description` Default value: `None` Optional description to attach to the QESEM job. > **Caution** > > The QPU time estimation changes from one backend to another. Therefore, when executing the QESEM function, make sure to run it on the same backend that was selected when obtaining the QPU time estimation. > **Note** > > QESEM will end its run when it reaches the target precision or when it reaches `max_execution_time`, whichever comes first. > **Note** > > Barrier operations are typically used to specify the layers of two-qubit gates in quantum circuits. With `"minimal_with_layout_opt"`, QESEM preserves the layers specified by the barriers. With `"standard"`, the layers specified by the barriers are considered as one transpilation alternative when minimizing QPU time. ## Outputs The output of the QESEM function is a [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult), which contains one [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) per input PUB and job-level metadata. Each `PubResult` can be accessed by indexing the `PrimitiveResult` and 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`), including the detailed QESEM results and execution metrics. Common `PubResult.metadata` fields include: | Field | Description | | :----------------- | :-------------------------------------------------------------------------------------------- | | `results` | Per-circuit and per-observable QESEM results. | | `noisy_results` | Unmitigated expectation values and error bars, when available. | | `transpiled_circs` | Transpiled circuit information, including qubit mappings and the number of measurement bases. | | `total_qpu_time` | QPU time used by the job. | | `gate_fidelities` | Gate fidelities measured during the experiment. | | `total_shots` | Total number of shots used by the job. | | `mitigation_shots` | Number of shots used for mitigation. | | `resource_usage` | Resource usage breakdown for the job. | The per-observable QESEM details are stored in `metadata["results"]`. Results are grouped first by circuit instance and then by observable. Each observable entry can include the QESEM result (`qesem`), the unmitigated result (`unmitigated`), noise-scaling results (`noise_scaling`), and QESEM heuristic results (`qesem_heuristic`).