Q-CTRL Performance Management API reference
Fire Opal Performance Management accepts abstract circuits, in contrast to the native IBM Quantum primitives, which only accept circuits that are written in the target backend's Instruction Set Architecture (ISA). For best results, do not transpile circuits before submitting via the Performance Management function.
Estimator inputs
QctrlEstimatorPubLike components (derived from the Quantum Compute PUB definition):
- A single circuit defined as a
QuantumCircuitor in OpenQASM 2.0 or 3.0 string format. - One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list "Supported observables formats".
- (Optional) A collection of parameter values to bind the circuit against, which follow the same array broadcasting rules as the
QiskitRuntimeprimitives. - (Optional) A target precision for expectation values to estimate.
- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example:
{"shots": <int>}.
Supported observables formats:
- Any one of the
ObservablesArrayLikeformats, such asPauli,SparsePauliOp,PauliList, orstr - A Pauli string:
"XY" - A dictionary - Pauli strings with coefficients:
{"XY": 0.5, "YZ": 0.3} - A list of Pauli strings:
["XY", "YZ", "ZX"] - A list of Pauli strings with coefficients:
[("XY", 0.5), ("YZ", 0.3)] - A nested list of Pauli strings:
[["XY", "YZ"], ["ZX", "XX"]] - A nested list of Pauli strings with coefficients:
[[("XY", 0.1), ("YZ", 0.2)], [("ZX", 0.3), ("XX", 0.4)]]
pubs
Type: `QctrlEstimatorPubLike` or `list[QctrlEstimatorPubLike]`
Default value: N/A
One or more tuples containing the inputs listed under EstimatorPubLike components
- Required: Yes
- Example:
(circuit, observables, parameter_values)
backend_name
Type: `str`
Default value: The least busy backend that your instance has access to
The name of the backend
- Required: No
- Example:
"ibm_fez"
function_size
Type: str
Default value: "M"
Size the job runs at: "S", "M", or "L". The required size depends on the number of active qubits and the two-qubit gate depth of each circuit after it is mapped and routed to the selected backend: up to 40 of each is "S", up to 100 of each is "M", and more than 100 of either is "L". To calculate the size before you submit a job, see Function sizes. If the size is too small, the job fails with error 4600. If the size is larger than the job needs, the job runs normally and records a 4601 advisory event.
- Required: No
- Example:
"L"
Options
Type: `dict`
Default value: See Options section for more details
Input options for this function are specified as a nested dictionary. See the full list of options and their default values.
- Required: No
- Example:
{"default_shots": 2048}
Options list
session_id
Type: `str`
An existing IBM Quantum Compute Service session ID
- Example:
"cw4r3je6f0t010870y3g"
default_shots
Type: `int`
Default value: `2048`
The number of shots to use for each circuit
default_precision
Type: `float`
The target precision for expectation values to estimate for each circuit
- Example:
0.015625
job_tags
Type: `list[str]`
Default value: `[]`
A list of job tags
Estimator outputs
Type: `PrimitiveResult`
The PrimitiveResult corresponding to the list of input PUBs
- Example:
PubResult(data=DataBin(evs=[0.1234], stds=[0.1]))
Sampler inputs
QctrlSamplerPubLike components (derived from the Quantum Compute PUB definition):
- A single circuit defined as a
QuantumCircuitor in OpenQASM 2.0 or 3.0 string format. - (Optional) A collection of parameter values to bind the circuit against.
- (Optional) An integer representing the shot count, or a dictionary of runtime options containing the shot count. For example:
(circ, None, 123)or(circ, None, {"shots": 123}).
pubs
Type: `QctrlSamplerPubLike` or `list[QctrlSamplerPubLike]`
One or more tuples containing the inputs listed under SamplerPubLike components
- Required: Yes
- Example:
(circuit, parameter_values)
backend_name
Type: `str`
Default value: The least busy backend that your instance has access to
The name of the backend
- Required: No
- Example:
"ibm_fez"
function_size
Type: str
Default value: "M"
Size the job runs at: "S", "M", or "L". The required size depends on the number of active qubits and the two-qubit gate depth of each circuit after it is mapped and routed to the selected backend: up to 40 of each is "S", up to 100 of each is "M", and more than 100 of either is "L". To calculate the size before you submit a job, see Function sizes. If the size is too small, the job fails with error 4600. If the size is larger than the job needs, the job runs normally and records a 4601 advisory event.
- Required: No
- Example:
"L"
Options
Type: `dict`
Default value: See the Options section for details
Input options for this function are specified as a nested dictionary. See the full list of options and their default values.
- Required: No
- Example:
{"default_shots": 2048}
Options list
session_id
Type: `str`
An existing Quantum Compute session ID
- Example:
"cw4r3je6f0t010870y3g"
default_shots
Type: `int`
Default value: `2048`
The number of shots to use for each circuit
job_tags
Type: `list[str]`
Default value: `[]`
The list of desired job tags
Sampler outputs
Type: `PrimitiveResult`
The PrimitiveResult corresponding to the list of input PUBs
- Example:
PrimitiveResult([PubResult(data=DataBin(c=BitArray(<shape=(), num_shots=2048, num_bits=35>)), metadata={'shots': 2048})], metadata={provider_job_ids: 1234678})
Error handling
The function reports the following errors that relate to function_size. For all error codes, see the IBM Quantum error codes.
Code | Cause |
|---|---|
4600 | The function_size is too small for the workload. The job fails, and the message names the size to use. |
4601 | The function_size is larger than the workload needs. The job runs normally and records an advisory event that you can read with job.events(). |