diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackend.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackend.mdx index bcea2a9b027..ed089d218e2 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackend.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackend.mdx @@ -8,733 +8,693 @@ python_api_name: qiskit_ibm_provider.IBMBackend # IBMBackend - + + Backend class interfacing with an IBM Quantum device. -`IBMBackend(configuration, provider, api_client, instance=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/ibm_backend.py "view source code") + You can run experiments on a backend using the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: -Backend class interfacing with an IBM Quantum device. + ```python + from qiskit import transpile + from qiskit_ibm_provider import IBMProvider + from qiskit.circuit.random import random_circuit -You can run experiments on a backend using the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: + provider = IBMProvider() + backend = provider.backend.ibmq_vigo + qx = random_circuit(n_qubits=5, depth=4) + transpiled = transpile(qx, backend=backend) + job = backend.run(transpiled) + retrieved_job = provider.backend.retrieve_job(job.job_id()) + ``` -```python -from qiskit import transpile -from qiskit_ibm_provider import IBMProvider -from qiskit.circuit.random import random_circuit + + * Unlike `qiskit.execute()`, the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. + * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. + -provider = IBMProvider() -backend = provider.backend.ibmq_vigo -qx = random_circuit(n_qubits=5, depth=4) -transpiled = transpile(qx, backend=backend) -job = backend.run(transpiled) -retrieved_job = provider.backend.retrieve_job(job.job_id()) -``` + Other methods return information about the backend. For example, the [`status()`](qiskit_ibm_provider.IBMBackend#status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: - - * Unlike `qiskit.execute()`, the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. - * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. - + ```python + status = backend.status() + is_operational = status.operational + jobs_in_queue = status.pending_jobs + ``` -Other methods return information about the backend. For example, the [`status()`](qiskit_ibm_provider.IBMBackend#status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: + **Here is list of attributes available on the `IBMBackend` class:** -```python -status = backend.status() -is_operational = status.operational -jobs_in_queue = status.pending_jobs -``` + * name: backend name. -**Here is list of attributes available on the `IBMBackend` class:** + * backend\_version: backend version in the form X.Y.Z. -* name: backend name. + * num\_qubits: number of qubits. -* backend\_version: backend version in the form X.Y.Z. + * target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. -* num\_qubits: number of qubits. + * basis\_gates: list of basis gates names on the backend. -* target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. + * gates: list of basis gates on the backend. -* basis\_gates: list of basis gates names on the backend. + * local: backend is local or remote. -* gates: list of basis gates on the backend. + * simulator: backend is a simulator. -* local: backend is local or remote. + * conditional: backend supports conditional operations. -* simulator: backend is a simulator. + * open\_pulse: backend supports open pulse. -* conditional: backend supports conditional operations. + * memory: backend supports memory. -* open\_pulse: backend supports open pulse. + * max\_shots: maximum number of shots supported. -* memory: backend supports memory. + * coupling\_map (list): The coupling map for the device -* max\_shots: maximum number of shots supported. + * supported\_instructions (List\[str]): Instructions supported by the backend. -* coupling\_map (list): The coupling map for the device + * dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. -* supported\_instructions (List\[str]): Instructions supported by the backend. + * rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. -* dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + * default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. -* rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + * n\_uchannels: Number of u-channels. -* default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + * u\_channel\_lo: U-channel relationship on device los. -* n\_uchannels: Number of u-channels. + * meas\_levels: Supported measurement levels. -* u\_channel\_lo: U-channel relationship on device los. + * qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. -* meas\_levels: Supported measurement levels. + * meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. -* qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. + * dt: Qubit drive channel timestep in nanoseconds. -* meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. + * dtm: Measurement drive channel timestep in nanoseconds. -* dt: Qubit drive channel timestep in nanoseconds. + * rep\_times: Supported repetition times (program execution time) for backend in μs. -* dtm: Measurement drive channel timestep in nanoseconds. + * meas\_kernels: Supported measurement kernels. -* rep\_times: Supported repetition times (program execution time) for backend in μs. + * discriminators: Supported discriminators. -* meas\_kernels: Supported measurement kernels. + * hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. -* discriminators: Supported discriminators. + * channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) -* hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. + * acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. -* channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) + * conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m -* acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. + * meas\_map (list): Grouping of measurement which are multiplexed -* conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m + * max\_circuits (int): The maximum number of experiments per job -* meas\_map (list): Grouping of measurement which are multiplexed + * sample\_name (str): Sample name for the backend -* max\_circuits (int): The maximum number of experiments per job + * n\_registers (int): Number of register slots available for feedback (if conditional is True) -* sample\_name (str): Sample name for the backend + * register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. -* n\_registers (int): Number of register slots available for feedback (if conditional is True) + * configurable (bool): True if the backend is configurable, if the backend is a simulator -* register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + * credits\_required (bool): True if backend requires credits to run a job. -* configurable (bool): True if the backend is configurable, if the backend is a simulator + * online\_date (datetime): The date that the device went online -* credits\_required (bool): True if backend requires credits to run a job. + * display\_name (str): Alternate name field for the backend -* online\_date (datetime): The date that the device went online + * description (str): A description for the backend -* display\_name (str): Alternate name field for the backend + * tags (list): A list of string tags to describe the backend -* description (str): A description for the backend + * version: version of `Backend` class (Ex: 1, 2) -* tags (list): A list of string tags to describe the backend + * channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. -* version: version of `Backend` class (Ex: 1, 2) + * parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` -* channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. + * processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. -* parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + > * family: Processor family of this backend. + > * revision: Revision version of this processor. + > * segment: Segment this processor belongs to within a larger chip. -* processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + IBMBackend constructor. - > * family: Processor family of this backend. - > * revision: Revision version of this processor. - > * segment: Segment this processor belongs to within a larger chip. + **Parameters** -IBMBackend constructor. + * **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")]) – Backend configuration. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. -**Parameters** + ## Attributes -* **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")]) – Backend configuration. -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. + -## Attributes + ### backend\_version - + + Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + -### backend\_version + -Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + ### coupling\_map - + + Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)") object + -### coupling\_map + -Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)") object + ### description - + + Optional human-readable description. + -### description + -Optional human-readable description. + ### dt - + + Return the system time resolution of input signals -### dt + This is required to be implemented if the backend supports Pulse scheduling. - + **Return type** -`float | None` + `Optional`\[`float`] -Return the system time resolution of input signals + **Returns** -This is required to be implemented if the backend supports Pulse scheduling. + The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + -**Return type** + -`Optional`\[`float`] + ### dtm -**Returns** + + Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + -The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + - + ### id\_warning\_issued -### dtm + - + -`float` + ### instruction\_durations -Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + + Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)") object. + - + -### id\_warning\_issued + ### instruction\_schedule\_map - + + Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.45)") for the instructions defined in this backend’s target. + -`= False` + - + ### instructions -### instruction\_durations + + A list of Instruction tuples on the backend of the form `(instruction, (qubits)` -Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)") object. + **Return type** - + `List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)"), `Tuple`\[`int`]]] + -### instruction\_schedule\_map + -Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.45)") for the instructions defined in this backend’s target. + ### max\_circuits - + + The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. -### instructions + **Return type** - + `int` + -`List[Tuple[Instruction, Tuple[int]]]` + -A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + ### meas\_map -**Return type** + + Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + -`List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)"), `Tuple`\[`int`]]] + - + ### name -### max\_circuits + + Name of the backend. + - + -`int` + ### num\_qubits -The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. + + Return the number of qubits the backend has. -**Return type** + **Return type** -`int` + `int` + - + -### meas\_map + ### online\_date - + + Date that the backend came online. + -`List[List[int]]` + -Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + ### operation\_names - + + A list of instruction names that the backend supports. -### name + **Return type** -Name of the backend. + `List`\[`str`] + - + -### num\_qubits + ### operations - + + A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)") instances that the backend supports. -`int` + **Return type** -Return the number of qubits the backend has. + `List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")] + -**Return type** + -`int` + ### options - + + Return the options for the backend -### online\_date + The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method. + -Date that the backend came online. + - + ### provider -### operation\_names + + Return the backend Provider. - + **Returns** -`List[str]` + the Provider responsible for the backend. -A list of instruction names that the backend supports. + **Return type** -**Return type** + Provider + -`List`\[`str`] + - + ### session -### operations + + Return session - + **Return type** -`List[Instruction]` + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)") instances that the backend supports. + -**Return type** + ### target -`List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")] + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target + - + -### options + ### version -Return the options for the backend + -The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") method. + ## Methods - + -### provider + ### acquire\_channel -Return the backend Provider. + + Return the acquisition channel for the given qubit. -**Returns** + **Returns** -the Provider responsible for the backend. + The Qubit measurement acquisition line. -**Return type** + **Return type** -Provider + AcquireChannel + - + -### session + ### cancel\_session - + + Cancel session. All pending jobs will be cancelled. -`Session` + **Return type** -Return session + `None` + -**Return type** + -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + ### close\_session - + + Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. -### target + **Return type** - + `None` + -`Target` + -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target + ### configuration - + + Return the backend configuration. -### version + Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. - + The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). -`= 2` + **Return type** -## Methods + `Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")] - + **Returns** -### acquire\_channel + The configuration for the backend. + - + -`IBMBackend.acquire_channel(qubit)` + ### control\_channel -Return the acquisition channel for the given qubit. + + Return the secondary drive channel for the given qubit. -**Returns** + This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. -The Qubit measurement acquisition line. + **Parameters** -**Return type** + **qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. -AcquireChannel + **Returns** - + The Qubit measurement acquisition line. -### cancel\_session + **Return type** - + List\[ControlChannel] + -`IBMBackend.cancel_session()` + -Cancel session. All pending jobs will be cancelled. + ### defaults -**Return type** + + Return the pulse defaults for the backend. -`None` + The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). - + **Parameters** -### close\_session + **refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. - + **Return type** -`IBMBackend.close_session()` + `Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.45)")] -Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. + **Returns** -**Return type** + The backend pulse defaults or `None` if the backend does not support pulse. + -`None` + - + ### drive\_channel -### configuration + + Return the drive channel for the given qubit. - + **Returns** -`IBMBackend.configuration()` + The Qubit drive channel -Return the backend configuration. + **Return type** -Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. + DriveChannel + -The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). + -**Return type** + ### get\_translation\_stage\_plugin -`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")] + + Return the default translation stage plugin name for IBM backends. -**Returns** + **Return type** -The configuration for the backend. + `str` + - + -### control\_channel + ### measure\_channel - + + Return the measure stimulus channel for the given qubit. -`IBMBackend.control_channel(qubits)` + **Returns** -Return the secondary drive channel for the given qubit. + The Qubit measurement stimulus line -This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + **Return type** -**Parameters** + MeasureChannel + -**qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + -**Returns** + ### open\_session -The Qubit measurement acquisition line. + + Open session -**Return type** + **Return type** -List\[ControlChannel] + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + - + -### defaults + ### properties - + + Return the backend properties, subject to optional filtering. -`IBMBackend.defaults(refresh=False)` + This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. -Return the pulse defaults for the backend. + The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). -The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). + **Parameters** -**Parameters** + * **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + * **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)") whose timestamp is closest to, but older than, the specified datetime. -**refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. + **Return type** -**Return type** + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] -`Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.45)")] + **Returns** -**Returns** + The backend properties or `None` if the backend properties are not currently available. -The backend pulse defaults or `None` if the backend does not support pulse. + **Raises** - + **TypeError** – If an input argument is not of the correct type. + -### drive\_channel + - + ### qubit\_properties -`IBMBackend.drive_channel(qubit)` + + Return QubitProperties for a given qubit. -Return the drive channel for the given qubit. + If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. -**Returns** + **Parameters** -The Qubit drive channel + **qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order -**Return type** + **Return type** -DriveChannel + `Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)")]] - + **Returns** -### get\_translation\_stage\_plugin + The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. - + **Raises** -`classmethod IBMBackend.get_translation_stage_plugin()` + **NotImplementedError** – if the backend doesn’t support querying the qubit properties + -Return the default translation stage plugin name for IBM backends. + -**Return type** + ### run -`str` + + Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. - + **Parameters** -### measure\_channel + * **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`]]]) – An individual or a list of `QuantumCircuit`. - + * **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) -`IBMBackend.measure_channel(qubit)` + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. -Return the measure stimulus channel for the given qubit. + * **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. -**Returns** + * **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. -The Qubit measurement stimulus line + * **or** (*The following parameters are applicable only if dynamic=False is specified*) – -**Return type** + * **to.** (*defaulted*) – -MeasureChannel + * **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. - + * **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. -### open\_session + * **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. - + * **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – -`IBMBackend.open_session(max_time=None)` + Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: -Open session + * `0`, measurements of the raw signal (the measurement output pulse envelope) + * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) + * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) -**Return type** + * **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + Level of measurement data for the backend to return. For `meas_level` 0 and 1: - + * `single` returns information from every shot. + * `avg` returns average measurement output (averaged over number of shots). -### properties + * **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. - + * **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. -`IBMBackend.properties(refresh=False, datetime=None)` + * **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. -Return the backend properties, subject to optional filtering. + * **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) -This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. + * **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) -The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). + * **\*\*run\_config** – Extra arguments used to configure the run. -**Parameters** + **Return type** -* **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. -* **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)") whose timestamp is closest to, but older than, the specified datetime. + `IBMJob` -**Return type** + **Returns** -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] + The job to be executed. -**Returns** + **Raises** -The backend properties or `None` if the backend properties are not currently available. + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. -**Raises** + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. -**TypeError** – If an input argument is not of the correct type. + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – - + * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. + -### qubit\_properties + - + ### set\_options -`IBMBackend.qubit_properties(qubit)` + + Set the options fields for the backend -Return QubitProperties for a given qubit. + This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. -If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + **Parameters** -**Parameters** + **fields** – The fields to update the options -**qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order + **Raises** -**Return type** + **AttributeError** – If the field passed in is not part of the options + -`Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)")]] + -**Returns** + ### status -The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + + Return the backend status. -**Raises** + + If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. + -**NotImplementedError** – if the backend doesn’t support querying the qubit properties + **Return type** - + [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") -### run + **Returns** - + The status of the backend. -`IBMBackend.run(circuits, dynamic=None, job_tags=None, init_circuit=None, init_num_resets=None, header=None, shots=None, memory=None, meas_level=None, meas_return=None, rep_delay=None, init_qubits=None, use_measure_esp=None, noise_model=None, seed_simulator=None, **run_config)` + **Raises** -Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. + [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. + -**Parameters** + -* **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`]]]) – An individual or a list of `QuantumCircuit`. + ### target\_history -* **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) - -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. - -* **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - -* **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. - -* **or** (*The following parameters are applicable only if dynamic=False is specified*) – - -* **to.** (*defaulted*) – - -* **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. - -* **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. - -* **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. - -* **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – - - Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - - * `0`, measurements of the raw signal (the measurement output pulse envelope) - * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) - * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) - -* **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – - - Level of measurement data for the backend to return. For `meas_level` 0 and 1: - - * `single` returns information from every shot. - * `avg` returns average measurement output (averaged over number of shots). - -* **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. - -* **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - -* **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. - -* **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) - -* **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) - -* **\*\*run\_config** – Extra arguments used to configure the run. - -**Return type** - -`IBMJob` - -**Returns** - -The job to be executed. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. - -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. - -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – - - * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. - - - -### set\_options - - - -`IBMBackend.set_options(**fields)` - -Set the options fields for the backend - -This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. - -**Parameters** - -**fields** – The fields to update the options - -**Raises** - -**AttributeError** – If the field passed in is not part of the options - - - -### status - - - -`IBMBackend.status()` - -Return the backend status. - - - If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. - - -**Return type** - -[`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") - -**Returns** - -The status of the backend. - -**Raises** - -[**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. - - - -### target\_history - - - -`IBMBackend.target_history(datetime=None)` - -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target with properties found on datetime + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target with properties found on datetime + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiError.mdx index 7c3cedb45af..79d21efd50f 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiError # IBMBackendApiError - + + Errors that occur unexpectedly when querying the server. -`IBMBackendApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx index e8083f83e9e..ed105ef77a0 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiProtocolError # IBMBackendApiProtocolError - + + Errors raised when an unexpected value is received from the server. -`IBMBackendApiProtocolError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Errors raised when an unexpected value is received from the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendError.mdx index 04a892e560c..7159518bcc5 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendError # IBMBackendError - + + Base class for errors raised by the backend modules. -`IBMBackendError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendService.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendService.mdx index 3cf203c3492..89a03ab8c96 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendService.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendService.mdx @@ -8,167 +8,159 @@ python_api_name: qiskit_ibm_provider.IBMBackendService # IBMBackendService - + + Backend namespace for an IBM Quantum account. -`IBMBackendService(provider, hgp)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/ibm_backend_service.py "view source code") + Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: -Backend namespace for an IBM Quantum account. + ```python + backends = provider.backends() # Invoke backends() to get the backends. + sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. + ``` -Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: + Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: -```python -backends = provider.backends() # Invoke backends() to get the backends. -sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. -``` + ```python + most_recent_jobs = provider.backend.jobs(limit=10) + ``` -Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: + It is also possible to retrieve a single job without specifying the backend name: -```python -most_recent_jobs = provider.backend.jobs(limit=10) -``` + ```python + job = provider.backend.retrieve_job() + ``` -It is also possible to retrieve a single job without specifying the backend name: + IBMBackendService constructor. -```python -job = provider.backend.retrieve_job() -``` + **Parameters** -IBMBackendService constructor. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. -**Parameters** + ## Methods -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. + -## Methods + ### backends - + + Return all backends accessible via this account, subject to optional filtering. -### backends + **Parameters** - + * **name** (`Optional`\[`str`]) – Backend name to filter by. -`IBMBackendService.backends(name=None, filters=None, min_num_qubits=None, instance=None, dynamic_circuits=None, **kwargs)` + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -Return all backends accessible via this account, subject to optional filtering. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -**Parameters** + * **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. -* **name** (`Optional`\[`str`]) – Backend name to filter by. + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + More complex filters, such as lambda functions. For example: -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -* **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. + * **\*\*kwargs** – -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. - More complex filters, such as lambda functions. For example: + Examples: - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **\*\*kwargs** – + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. + **Return type** - Examples: + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Returns** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + The list of available backends that match the filter. -**Return type** + **Raises** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. + * **QiskitBackendNotFoundError** – If the backend is not found in any instance. + -**Returns** + -The list of available backends that match the filter. + ### jobs -**Raises** + + Return a list of jobs, subject to optional filtering. -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. -* **QiskitBackendNotFoundError** – If the backend is not found in any instance. + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. - + **Parameters** -### jobs + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by + * **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. + * **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – - + **Return type** -`IBMBackendService.jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + `List`\[`IBMJob`] -Return a list of jobs, subject to optional filtering. + **Returns** -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + A list of `IBMJob` instances. -**Parameters** + **Raises** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by -* **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. -* **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. + * **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + -**Return type** + -`List`\[`IBMJob`] + ### retrieve\_job -**Returns** + + Return a single job. -A list of `IBMJob` instances. + **Parameters** -**Raises** + **job\_id** (`str`) – The ID of the job to retrieve. -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. -* **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + **Return type** - + `IBMJob` -### retrieve\_job + **Returns** - + The job with the given id. -`IBMBackendService.retrieve_job(job_id)` + **Raises** -Return a single job. - -**Parameters** - -**job\_id** (`str`) – The ID of the job to retrieve. - -**Return type** - -`IBMJob` - -**Returns** - -The job with the given id. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. -* **IBMJobNotFoundError** – If job cannot be found. -* **IBMInputValueError** – If job exists but was run from a different service. + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. + * **IBMJobNotFoundError** – If job cannot be found. + * **IBMInputValueError** – If job exists but was run from a different service. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendValueError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendValueError.mdx index 589fe100632..b2ab99d6db6 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMBackendValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendValueError # IBMBackendValueError - + + Value errors raised by the backend modules. -`IBMBackendValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMError.mdx index 03b3f29344f..37b965b2783 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMError # IBMError - + + Base class for errors raised by the provider modules. -`IBMError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the provider modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProvider.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProvider.mdx index 3a2986951a9..0ae1aa74179 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProvider.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProvider.mdx @@ -8,379 +8,355 @@ python_api_name: qiskit_ibm_provider.IBMProvider # IBMProvider - + + Provides access to the IBM Quantum services available to an account. -`IBMProvider(token=None, url=None, name=None, instance=None, proxies=None, verify=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/ibm_provider.py "view source code") + Authenticate against IBM Quantum for use from saved credentials or during session. -Provides access to the IBM Quantum services available to an account. + Credentials can be saved to disk by calling the save\_account() method: -Authenticate against IBM Quantum for use from saved credentials or during session. + ```python + from qiskit_ibm_provider import IBMProvider + IBMProvider.save_account(token=) + ``` -Credentials can be saved to disk by calling the save\_account() method: + You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: -```python -from qiskit_ibm_provider import IBMProvider -IBMProvider.save_account(token=) -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: + Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: + You can also enable an account just for the current session by instantiating the provider with the API token: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider(token=) + ``` -You can also enable an account just for the current session by instantiating the provider with the API token: + token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider(token=) -``` + + The hub/group/project is selected based on the below selection order, in decreasing order of priority. -token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. + * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. + * The hub/group/project required for the service. + * The default hub/group/project you set using save\_account(). + * A premium hub/group/project in your account. + * An open access hub/group/project. + - - The hub/group/project is selected based on the below selection order, in decreasing order of priority. + The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. - * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. - * The hub/group/project required for the service. - * The default hub/group/project you set using save\_account(). - * A premium hub/group/project in your account. - * An open access hub/group/project. - + You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: -The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. + ```python + backend_service = provider.backend + ``` -You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: + Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. -```python -backend_service = provider.backend -``` + The [`backends()`](qiskit_ibm_provider.IBMProvider#backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: -Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. + ```python + backends = provider.backends() + ``` -The [`backends()`](qiskit_ibm_provider.IBMProvider#backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: + The [`get_backend()`](qiskit_ibm_provider.IBMProvider#get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: -```python -backends = provider.backends() -``` + ```python + simulator_backend = provider.get_backend('ibmq_qasm_simulator') + ``` -The [`get_backend()`](qiskit_ibm_provider.IBMProvider#get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: + IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](qiskit_ibm_provider.IBMProvider#get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. -```python -simulator_backend = provider.get_backend('ibmq_qasm_simulator') -``` + It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: -IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](qiskit_ibm_provider.IBMProvider#get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. + ```python + simulator_backend = provider.backend.ibmq_qasm_simulator + ``` -It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: + + The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. + -```python -simulator_backend = provider.backend.ibmq_qasm_simulator -``` + IBMProvider constructor - - The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. - + **Parameters** -IBMProvider constructor + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). + * **name** (`Optional`\[`str`]) – Name of the account to load. + * **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. -**Parameters** + **Returns** -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). -* **name** (`Optional`\[`str`]) – Name of the account to load. -* **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. + An instance of IBMProvider -**Returns** + **Raises** -An instance of IBMProvider + **IBMInputValueError** – If an input is invalid. -**Raises** + ## Attributes -**IBMInputValueError** – If an input is invalid. + -## Attributes + ### backend - + + Return the backend service. -### backend + **Return type** - + [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") -`IBMBackendService` + **Returns** -Return the backend service. + The backend service instance. + -**Return type** + -[`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") + ### version -**Returns** + -The backend service instance. + ## Methods - + -### version + ### active\_account - + + Return the IBM Quantum account currently in use for the session. -`= 1` + **Return type** -## Methods + `Optional`\[`Dict`\[`str`, `str`]] - + **Returns** -### active\_account + A dictionary with information about the account currently in the session. + - + -`IBMProvider.active_account()` + ### backends -Return the IBM Quantum account currently in use for the session. + + Return all backends accessible via this account, subject to optional filtering. -**Return type** + **Parameters** -`Optional`\[`Dict`\[`str`, `str`]] + * **name** (`Optional`\[`str`]) – Backend name to filter by. -**Returns** + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -A dictionary with information about the account currently in the session. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. - + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – -### backends + More complex filters, such as lambda functions. For example: - + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -`IBMProvider.backends(name=None, filters=None, min_num_qubits=None, instance=None, **kwargs)` + * **\*\*kwargs** – -Return all backends accessible via this account, subject to optional filtering. + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: -**Parameters** + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **name** (`Optional`\[`str`]) – Backend name to filter by. + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + **Return type** -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + **Returns** - More complex filters, such as lambda functions. For example: + The list of available backends that match the filter. + - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + -* **\*\*kwargs** – + ### delete\_account - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: + + Delete a saved account from disk. - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Parameters** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + **name** (`Optional`\[`str`]) – Name of the saved account to delete. -**Return type** + **Return type** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + `bool` -**Returns** + **Returns** -The list of available backends that match the filter. + True if the account was deleted. False if no account was found. + - + -### delete\_account + ### get\_backend - + + Return a single backend matching the specified filtering. -`static IBMProvider.delete_account(name=None)` + **Parameters** -Delete a saved account from disk. + * **name** (*str*) – Name of the backend. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **\*\*kwargs** – Dict used for filtering. -**Parameters** + **Returns** -**name** (`Optional`\[`str`]) – Name of the saved account to delete. + a backend matching the filtering. -**Return type** + **Return type** -`bool` + Backend -**Returns** + **Raises** -True if the account was deleted. False if no account was found. + * **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. + * [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + - + -### get\_backend + ### instances - + + Return the IBM Quantum instances list currently in use for the session. -`IBMProvider.get_backend(name=None, instance=None, **kwargs)` + **Return type** -Return a single backend matching the specified filtering. + `List`\[`str`] -**Parameters** + **Returns** -* **name** (*str*) – Name of the backend. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **\*\*kwargs** – Dict used for filtering. + A list with instances currently in the session. + -**Returns** + -a backend matching the filtering. + ### jobs -**Return type** + + Return a list of jobs, subject to optional filtering. -Backend + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -**Raises** + **Parameters** -* **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. -* [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – - + **Return type** -### instances + `List`\[`IBMJob`] - + **Returns** -`IBMProvider.instances()` + A list of `IBMJob` instances. + -Return the IBM Quantum instances list currently in use for the session. + -**Return type** + ### retrieve\_job -`List`\[`str`] + + Return a single job. -**Returns** + **Parameters** -A list with instances currently in the session. + **job\_id** (`str`) – The ID of the job to retrieve. - + **Return type** -### jobs + `IBMJob` - + **Returns** -`IBMProvider.jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + The job with the given id. + -Return a list of jobs, subject to optional filtering. + -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + ### save\_account -**Parameters** + + Save the account to disk for future use. -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + **Parameters** -**Return type** + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) + * **instance** (`Optional`\[`str`]) – The hub/group/project. + * **name** (`Optional`\[`str`]) – Name of the account to save. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. + * **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. -`List`\[`IBMJob`] + **Return type** -**Returns** + `None` + -A list of `IBMJob` instances. + - + ### saved\_accounts -### retrieve\_job + + List the accounts saved on disk. - + **Parameters** -`IBMProvider.retrieve_job(job_id)` + * **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. + * **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. -Return a single job. + **Return type** -**Parameters** + `dict` -**job\_id** (`str`) – The ID of the job to retrieve. + **Returns** -**Return type** + A dictionary with information about the accounts saved on disk. -`IBMJob` + **Raises** -**Returns** - -The job with the given id. - - - -### save\_account - - - -`static IBMProvider.save_account(token=None, url=None, instance=None, name=None, proxies=None, verify=None, overwrite=False)` - -Save the account to disk for future use. - -**Parameters** - -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) -* **instance** (`Optional`\[`str`]) – The hub/group/project. -* **name** (`Optional`\[`str`]) – Name of the account to save. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. -* **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. - -**Return type** - -`None` - - - -### saved\_accounts - - - -`static IBMProvider.saved_accounts(default=None, name=None)` - -List the accounts saved on disk. - -**Parameters** - -* **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. -* **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. - -**Return type** - -`dict` - -**Returns** - -A dictionary with information about the accounts saved on disk. - -**Raises** - -**ValueError** – If an invalid account is found on disk. + **ValueError** – If an invalid account is found on disk. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderError.mdx index 4ea70d81f99..2be0507352a 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderError # IBMProviderError - + + Base class for errors raise by IBMProvider. -`IBMProviderError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raise by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderValueError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderValueError.mdx index 76833ee0411..bc4cbc0e321 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.IBMProviderValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderValueError # IBMProviderValueError - + + Value errors raised by IBMProvider. -`IBMProviderValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.Session.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.Session.mdx index 74e4c0bb91f..dfba2da3bac 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.Session.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.Session.mdx @@ -8,102 +8,94 @@ python_api_name: qiskit_ibm_provider.Session # Session - + + Class for creating a flexible Qiskit Runtime session. -`Session(max_time=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/session.py "view source code") + A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. -Class for creating a flexible Qiskit Runtime session. + You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. -A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. + For example: -You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. + ```python + from qiskit.test.reference_circuits import ReferenceCircuits + from qiskit_ibm_provider import IBMProvider -For example: + circ = ReferenceCircuits.bell() + backend = IBMProvider().get_backend("ibmq_qasm_simulator") + backend.open_session() + job = backend.run(circ) + print(f"Job ID: {job.job_id()}") + print(f"Result: {job.result()}") + # Close the session only if all jobs are finished and + # you don't need to run more in the session. + backend.cancel_session() + ``` -```python -from qiskit.test.reference_circuits import ReferenceCircuits -from qiskit_ibm_provider import IBMProvider + Session can also be used as a context manager: -circ = ReferenceCircuits.bell() -backend = IBMProvider().get_backend("ibmq_qasm_simulator") -backend.open_session() -job = backend.run(circ) -print(f"Job ID: {job.job_id()}") -print(f"Result: {job.result()}") -# Close the session only if all jobs are finished and -# you don't need to run more in the session. -backend.cancel_session() -``` + ```python + with backend.open_session() as session: + job = backend.run(ReferenceCircuits.bell()) + assert job.job_id() == session.session_id + ``` -Session can also be used as a context manager: + Session constructor. -```python -with backend.open_session() as session: - job = backend.run(ReferenceCircuits.bell()) - assert job.job_id() == session.session_id -``` + **Parameters** -Session constructor. + **max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). -**Parameters** + **Raises** -**max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). + **ValueError** – If an input value is invalid. -**Raises** + ## Attributes -**ValueError** – If an input value is invalid. + -## Attributes + ### active - + + Return the status of the session. -### active + **Return type** - + `bool` -`bool` + **Returns** -Return the status of the session. + True if the session is active, False otherwise. + -**Return type** + -`bool` + ### session\_id -**Returns** + + Return the session ID. -True if the session is active, False otherwise. + **Return type** - + `str` -### session\_id + **Returns** - + Session ID. None until a job runs in the session. + -`str` + ## Methods -Return the session ID. + -**Return type** + ### cancel -`str` + + Set the session.\_active status to False -**Returns** + **Return type** -Session ID. None until a job runs in the session. - -## Methods - - - -### cancel - - - -`Session.cancel()` - -Set the session.\_active status to False - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCircuitJob.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCircuitJob.mdx index b74fd72b897..056a9a8cc68 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCircuitJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCircuitJob.mdx @@ -8,668 +8,608 @@ python_api_name: qiskit_ibm_provider.job.IBMCircuitJob # IBMCircuitJob - + + Representation of a job that executes on an IBM Quantum backend. -`IBMCircuitJob(backend, api_client, job_id, creation_date=None, status=None, runtime_client=None, kind=None, name=None, time_per_step=None, result=None, error=None, session_id=None, tags=None, run_mode=None, client_info=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/ibm_circuit_job.py "view source code") + The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. -Representation of a job that executes on an IBM Quantum backend. + If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](qiskit_ibm_provider.job.IBMCircuitJob#status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") members. For example: -The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. - -If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](qiskit_ibm_provider.job.IBMCircuitJob#status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") members. For example: - -```python -from qiskit.providers.jobstatus import JobStatus - -job = backend.run(...) - -try: - job_status = job.status() # Query the backend server for job status. - if job_status is JobStatus.RUNNING: - print("The job is still running") -except IBMJobApiError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - - - An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. - - -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](qiskit_ibm_provider.job.IBMCircuitJob#result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: - -```python -job = backend.run(...) - -try: - job_result = job.result() # It will block until the job finishes. - print("The job finished with result {}".format(job_result)) -except JobError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - -Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](qiskit_ibm_provider.job.IBMCircuitJob#creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. - -IBMCircuitJob constructor. - -**Parameters** - -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`str`) – Job ID. -* **creation\_date** (`Optional`\[`str`]) – Job creation date. -* **status** (`Optional`\[`str`]) – Job status returned by the server. -* **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server -* **kind** (`Optional`\[`str`]) – Job type. -* **name** (`Optional`\[`str`]) – Job name. -* **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. -* **result** (`Optional`\[`dict`]) – Job result. -* **error** (`Optional`\[`dict`]) – Job error. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. -* **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. -* **kwargs** (`Any`) – Additional job attributes. - -## Attributes - - - -### client\_version - - - -`Dict[str, str]` - -Return version of the client used for this job. - -**Return type** - -`Dict`\[`str`, `str`] - -**Returns** - -**Client version in dictionary format, where the key is the name** - -of the client and the value is the version. - - - -### usage\_estimation - - - -`Dict[str, Any]` - -Return usage estimation information for this job. - -**Return type** - -`Dict`\[`str`, `Any`] - -**Returns** - -`quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. - - - -### version - - - -`= 1` - -## Methods - - - -### backend - - - -`IBMCircuitJob.backend()` - -Return the backend where this job was executed. - -**Return type** - -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") - - - -### backend\_options - - - -`IBMCircuitJob.backend_options()` - -Return the backend configuration options used for this job. - -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. - -**Return type** - -`Dict` - -**Returns** - -Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. - - - -### cancel - - - -`IBMCircuitJob.cancel()` - -Attempt to cancel the job. + ```python + from qiskit.providers.jobstatus import JobStatus - - Depending on the state the job is in, it might be impossible to cancel the job. - + job = backend.run(...) -**Return type** + try: + job_status = job.status() # Query the backend server for job status. + if job_status is JobStatus.RUNNING: + print("The job is still running") + except IBMJobApiError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` -`bool` + + An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. + -**Returns** + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](qiskit_ibm_provider.job.IBMCircuitJob#result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: -`True` if the job is cancelled, else `False`. + ```python + job = backend.run(...) -**Raises** + try: + job_result = job.result() # It will block until the job finishes. + print("The job finished with result {}".format(job_result)) + except JobError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. -* [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](qiskit_ibm_provider.job.IBMCircuitJob#creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. - + IBMCircuitJob constructor. -### cancelled + **Parameters** - + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`str`) – Job ID. + * **creation\_date** (`Optional`\[`str`]) – Job creation date. + * **status** (`Optional`\[`str`]) – Job status returned by the server. + * **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server + * **kind** (`Optional`\[`str`]) – Job type. + * **name** (`Optional`\[`str`]) – Job name. + * **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. + * **result** (`Optional`\[`dict`]) – Job result. + * **error** (`Optional`\[`dict`]) – Job error. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. + * **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. + * **kwargs** (`Any`) – Additional job attributes. -`IBMCircuitJob.cancelled()` + ## Attributes -Return whether the job has been cancelled. + -**Return type** + ### client\_version -`bool` + + Return version of the client used for this job. - + **Return type** -### circuits + `Dict`\[`str`, `str`] - + **Returns** -`IBMCircuitJob.circuits()` + **Client version in dictionary format, where the key is the name** -Return the circuits for this job. + of the client and the value is the version. + -**Return type** + -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] + ### usage\_estimation -**Returns** + + Return usage estimation information for this job. -The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + **Return type** - + `Dict`\[`str`, `Any`] -### creation\_date + **Returns** - + `quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. + -`IBMCircuitJob.creation_date()` + -Return job creation date, in local time. + ### version -**Return type** + -`datetime` + ## Methods -**Returns** + -The job creation date as a datetime object, in local time. + ### backend - + + Return the backend where this job was executed. -### done + **Return type** - + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + -`IBMCircuitJob.done()` + -Return whether the job has successfully run. + ### backend\_options -**Return type** + + Return the backend configuration options used for this job. -`bool` + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. - + **Return type** -### error\_message + `Dict` - + **Returns** -`IBMCircuitJob.error_message()` + Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. + -Provide details about the reason of failure. + -**Return type** + ### cancel -`Optional`\[`str`] + + Attempt to cancel the job. -**Returns** + + Depending on the state the job is in, it might be impossible to cancel the job. + -An error report if the job failed or `None` otherwise. + **Return type** - + `bool` -### header + **Returns** - + `True` if the job is cancelled, else `False`. -`IBMCircuitJob.header()` + **Raises** -Return the user header specified for this job. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. + * [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + -**Return type** + -`Dict` + ### cancelled -**Returns** + + Return whether the job has been cancelled. -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + **Return type** - + `bool` + -### in\_final\_state + - + ### circuits -`IBMCircuitJob.in_final_state()` + + Return the circuits for this job. -Return whether the job is in a final job state such as `DONE` or `ERROR`. + **Return type** -**Return type** + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] -`bool` + **Returns** - + The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + -### job\_id + - + ### creation\_date -`IBMCircuitJob.job_id()` + + Return job creation date, in local time. -Return the job ID assigned by the server. + **Return type** -**Return type** + `datetime` -`str` + **Returns** -**Returns** + The job creation date as a datetime object, in local time. + -Job ID. + - + ### done -### name + + Return whether the job has successfully run. - + **Return type** -`IBMCircuitJob.name()` + `bool` + -Return the name assigned to this job. + -**Return type** + ### error\_message -`Optional`\[`str`] + + Provide details about the reason of failure. -**Returns** + **Return type** -Job name or `None` if no name was assigned to this job. + `Optional`\[`str`] - + **Returns** -### properties + An error report if the job failed or `None` otherwise. + - + -`IBMCircuitJob.properties(refresh=False)` + ### header -Return the backend properties for this job. + + Return the user header specified for this job. -**Parameters** + **Return type** -**refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + `Dict` -**Return type** + **Returns** -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -**Returns** + -The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + ### in\_final\_state - + + Return whether the job is in a final job state such as `DONE` or `ERROR`. -### queue\_info + **Return type** - + `bool` + -`IBMCircuitJob.queue_info()` + -Return queue information for this job. + ### job\_id -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + + Return the job ID assigned by the server. - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + **Return type** -**Return type** + `str` -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + **Returns** -**Returns** + Job ID. + -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - + ### name -### queue\_position + + Return the name assigned to this job. - + **Return type** -`IBMCircuitJob.queue_position(refresh=False)` + `Optional`\[`str`] -Return the position of the job in the server queue. + **Returns** - - The position returned is within the scope of the provider and may differ from the global queue position. - + Job name or `None` if no name was assigned to this job. + -**Parameters** + -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + ### properties -**Return type** + + Return the backend properties for this job. -`Optional`\[`int`] + **Parameters** -**Returns** + **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. -Position in the queue or `None` if position is unknown or not applicable. + **Return type** - + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] -### refresh + **Returns** - + The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + -`IBMCircuitJob.refresh()` + -Obtain the latest job information from the server. + ### queue\_info -This method may add additional attributes to this job instance, if new information becomes available. + + Return queue information for this job. -**Raises** + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -**Return type** + **Return type** -`None` + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] - + **Returns** -### result + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - + -`IBMCircuitJob.result(timeout=None, refresh=False)` + ### queue\_position -Return the result of the job. + + Return the position of the job in the server queue. - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + + The position returned is within the scope of the provider and may differ from the global queue position. + - The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + **Parameters** - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. - For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: + **Return type** - ```python - try: - counts = result.get_counts("failed_experiment") - except QiskitError: - print("Experiment failed!") - ``` - + `Optional`\[`int`] -If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCircuitJob#error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + **Returns** -**Parameters** + Position in the queue or `None` if position is unknown or not applicable. + -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + -**Return type** + ### refresh -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") + + Obtain the latest job information from the server. -**Returns** + This method may add additional attributes to this job instance, if new information becomes available. -Job result. + **Raises** -**Raises** + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + **Return type** - + `None` + -### running + - + ### result -`IBMCircuitJob.running()` + + Return the result of the job. -Return whether the job is actively running. + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -**Return type** + The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -`bool` + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. - + For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: -### scheduling\_mode + ```python + try: + counts = result.get_counts("failed_experiment") + except QiskitError: + print("Experiment failed!") + ``` + - + If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCircuitJob#error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. -`IBMCircuitJob.scheduling_mode()` + **Parameters** -Return the scheduling mode the job is in. + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. -**Return type** + **Return type** -`Optional`\[`str`] + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") -**Returns** + **Returns** -The scheduling mode the job is in or `None` if the information is not available. + Job result. - + **Raises** -### status + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - + -`IBMCircuitJob.status()` + ### running -Query the server for the latest job status. + + Return whether the job is actively running. - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](qiskit_ibm_provider.job.IBMCircuitJob#wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. - + **Return type** - - If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCircuitJob#error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. - + `bool` + -**Return type** + -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") + ### scheduling\_mode -**Returns** + + Return the scheduling mode the job is in. -The status of the job. + **Return type** -**Raises** + `Optional`\[`str`] -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + **Returns** - + The scheduling mode the job is in or `None` if the information is not available. + -### submit + - + ### status -`IBMCircuitJob.submit()` + + Query the server for the latest job status. -Unsupported method. + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](qiskit_ibm_provider.job.IBMCircuitJob#wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. + - - This method is not supported, please use `run()` to submit a job. - + + If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCircuitJob#error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + -**Raises** + **Return type** -**NotImplementedError** – Upon invocation. + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") -**Return type** + **Returns** -`None` + The status of the job. - + **Raises** -### tags + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - + -`IBMCircuitJob.tags()` + ### submit -Return the tags assigned to this job. + + Unsupported method. -**Return type** + + This method is not supported, please use `run()` to submit a job. + -`List`\[`str`] + **Raises** -**Returns** + **NotImplementedError** – Upon invocation. -Tags assigned to this job. + **Return type** - + `None` + -### time\_per\_step + - + ### tags -`IBMCircuitJob.time_per_step()` + + Return the tags assigned to this job. -Return the date and time information on each step of the job processing. + **Return type** -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: + `List`\[`str`] -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` + **Returns** -**Return type** + Tags assigned to this job. + -`Optional`\[`Dict`] + -**Returns** + ### time\_per\_step -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + + Return the date and time information on each step of the job processing. - + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: -### update\_name + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` - + **Return type** -`IBMCircuitJob.update_name(name)` + `Optional`\[`Dict`] -Update the name associated with this job. + **Returns** -**Parameters** + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + -**name** (`str`) – The new name for this job. + -**Return type** + ### update\_name -`str` + + Update the name associated with this job. -**Returns** + **Parameters** -The new name associated with this job. + **name** (`str`) – The new name for this job. - + **Return type** -### update\_tags + `str` - + **Returns** -`IBMCircuitJob.update_tags(new_tags)` + The new name associated with this job. + -Update the tags associated with this job. + -**Parameters** + ### update\_tags -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. + + Update the tags associated with this job. -**Return type** + **Parameters** -`List`\[`str`] + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -**Returns** + **Return type** -The new tags associated with this job. + `List`\[`str`] -**Raises** + **Returns** -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + The new tags associated with this job. - + **Raises** -### wait\_for\_final\_state + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + - + -`IBMCircuitJob.wait_for_final_state(timeout=None, wait=3)` + ### wait\_for\_final\_state -#### Use the websocket server to wait for the final the state of a job. The server + + #### Use the websocket server to wait for the final the state of a job. The server -will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. + will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. -**Parameters** + **Parameters** -**timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. + **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. -**Raises** + **Raises** -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. -**Return type** + **Return type** -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCompositeJob.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCompositeJob.mdx index 32067b46e33..ee9015fef7c 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCompositeJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMCompositeJob.mdx @@ -8,816 +8,746 @@ python_api_name: qiskit_ibm_provider.job.IBMCompositeJob # IBMCompositeJob - + + Representation of a set of jobs that execute on an IBM Quantum backend. -`IBMCompositeJob(backend, api_client, job_id=None, creation_date=None, jobs=None, circuits_list=None, run_config=None, name=None, tags=None, client_version=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/ibm_composite_job.py "view source code") + An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. -Representation of a set of jobs that execute on an IBM Quantum backend. + This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](qiskit_ibm_provider.job.IBMCompositeJob#status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](qiskit_ibm_provider.job.IBMCompositeJob#result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. -An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. + You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. -This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](qiskit_ibm_provider.job.IBMCompositeJob#status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](qiskit_ibm_provider.job.IBMCompositeJob#result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. + `IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](qiskit_ibm_provider.job.IBMCompositeJob#rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. -You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](qiskit_ibm_provider.job.IBMCompositeJob#result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. -`IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](qiskit_ibm_provider.job.IBMCompositeJob#rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + `IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](qiskit_ibm_provider.job.IBMCompositeJob#result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. + IBMCompositeJob constructor. -`IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. + **Parameters** -IBMCompositeJob constructor. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **creation\_date** (`Optional`\[`datetime`]) – Job creation date. + * **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. + * **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]]]) – Circuits for this job. + * **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. + * **name** (`Optional`\[`str`]) – Job name. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **client\_version** (`Optional`\[`Dict`]) – Client used for the job. -**Parameters** + **Raises** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **creation\_date** (`Optional`\[`datetime`]) – Job creation date. -* **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. -* **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]]]) – Circuits for this job. -* **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. -* **name** (`Optional`\[`str`]) – Job name. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **client\_version** (`Optional`\[`Dict`]) – Client used for the job. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. -**Raises** + ## Attributes -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. + -## Attributes + ### client\_version - + + Return version of the client used for this job. -### client\_version + **Return type** - + `Dict`\[`str`, `str`] -`Dict[str, str]` + **Returns** -Return version of the client used for this job. + **Client version in dictionary format, where the key is the name** -**Return type** + of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + -`Dict`\[`str`, `str`] + -**Returns** + ### version -**Client version in dictionary format, where the key is the name** + -of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + ## Methods - + -### version + ### backend - + + Return the backend where this job was executed. -`= 1` + **Return type** -## Methods + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + - + -### backend + ### backend\_options - + + Return the backend configuration options used for this job. -`IBMCompositeJob.backend()` + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -Return the backend where this job was executed. + **Return type** -**Return type** + `Dict`\[`str`, `Any`] -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + **Returns** - + Backend options used for this job. + -### backend\_options + - + ### block\_for\_submit -`IBMCompositeJob.backend_options()` + + Block until all sub-jobs are submitted. -Return the backend configuration options used for this job. + **Return type** -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. + `None` + -**Return type** + -`Dict`\[`str`, `Any`] + ### cancel -**Returns** + + Attempt to cancel the job. -Backend options used for this job. + + Depending on the state the job is in, it might be impossible to cancel the job. + - + **Return type** -### block\_for\_submit + `bool` - + **Returns** -`IBMCompositeJob.block_for_submit()` + `True` if the job is cancelled, else `False`. -Block until all sub-jobs are submitted. + **Raises** -**Return type** + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -`None` + - + ### cancelled -### cancel + + Return whether the job has been cancelled. - + **Return type** -`IBMCompositeJob.cancel()` + `bool` + -Attempt to cancel the job. + - - Depending on the state the job is in, it might be impossible to cancel the job. - + ### circuits -**Return type** + + Return the circuits for this job. -`bool` + **Return type** -**Returns** + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] -`True` if the job is cancelled, else `False`. + **Returns** -**Raises** + The circuits for this job. + -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - + ### creation\_date -### cancelled + + Return job creation date, in local time. - + **Return type** -`IBMCompositeJob.cancelled()` + `Optional`\[`datetime`] -Return whether the job has been cancelled. + **Returns** -**Return type** + The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + -`bool` + - + ### done -### circuits + + Return whether the job has successfully run. - + **Return type** -`IBMCompositeJob.circuits()` + `bool` + -Return the circuits for this job. + -**Return type** + ### error\_message -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] + + Provide details about the reason of failure. -**Returns** + + This method blocks until the job finishes. + -The circuits for this job. + **Return type** - + `Optional`\[`str`] -### creation\_date + **Returns** - + An error report if the job failed or `None` otherwise. + -`IBMCompositeJob.creation_date()` + -Return job creation date, in local time. + ### from\_jobs -**Return type** + + Return an instance of this class. -`Optional`\[`datetime`] + The input job ID is used to query for sub-job information from the server. -**Returns** + **Parameters** -The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + * **job\_id** (`str`) – Job ID. + * **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. + * **api\_client** (`AccountClient`) – Client to use to communicate with the server. - + **Return type** -### done + [`IBMCompositeJob`](qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") - + **Returns** -`IBMCompositeJob.done()` + An instance of this class. + -Return whether the job has successfully run. + -**Return type** + ### header -`bool` + + Return the user header specified for this job. - + **Return type** -### error\_message + `Dict` - + **Returns** -`IBMCompositeJob.error_message()` + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -Provide details about the reason of failure. + - - This method blocks until the job finishes. - + ### in\_final\_state -**Return type** + + Return whether the job is in a final job state such as `DONE` or `ERROR`. -`Optional`\[`str`] + **Return type** -**Returns** + `bool` + -An error report if the job failed or `None` otherwise. + - + ### job\_id -### from\_jobs + + Return a unique id identifying the job. - + **Return type** -`classmethod IBMCompositeJob.from_jobs(job_id, jobs, api_client)` + `str` + -Return an instance of this class. + -The input job ID is used to query for sub-job information from the server. + ### name -**Parameters** + + Return the name assigned to this job. -* **job\_id** (`str`) – Job ID. -* **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. -* **api\_client** (`AccountClient`) – Client to use to communicate with the server. + **Return type** -**Return type** + `Optional`\[`str`] -[`IBMCompositeJob`](qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") + **Returns** -**Returns** + Job name or `None` if no name was assigned to this job. + -An instance of this class. + - + ### properties -### header + + Return the backend properties for this job. - + > #### Args: + > + > #### refresh: If `True`, re-query the server for the backend properties. + > + > Otherwise, return a cached version. -`IBMCompositeJob.header()` + + This method blocks until all sub-jobs are submitted. + -Return the user header specified for this job. + **Return type** -**Return type** + `Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)"), `None`] -`Dict` + **Returns** -**Returns** + The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + **Raises** - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -### in\_final\_state + - + ### queue\_info -`IBMCompositeJob.in_final_state()` + + Return queue information for this job. -Return whether the job is in a final job state such as `DONE` or `ERROR`. + This method returns the queue information of the sub-job that is last in queue. -**Return type** + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`bool` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + - + **Return type** -### job\_id + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] - + **Returns** -`IBMCompositeJob.job_id()` + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + -Return a unique id identifying the job. + -**Return type** + ### queue\_position -`str` + + Return the position of the job in the server queue. - + This method returns the queue position of the sub-job that is last in queue. -### name + + The position returned is within the scope of the provider and may differ from the global queue position. + - + **Parameters** -`IBMCompositeJob.name()` + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. -Return the name assigned to this job. + **Return type** -**Return type** + `Optional`\[`int`] -`Optional`\[`str`] + **Returns** -**Returns** + Position in the queue or `None` if position is unknown or not applicable. + -Job name or `None` if no name was assigned to this job. + - + ### refresh -### properties + + Obtain the latest job information from the server. - + This method may add additional attributes to this job instance, if new information becomes available. -`IBMCompositeJob.properties(refresh=False)` + **Raises** -Return the backend properties for this job. + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -> #### Args: -> -> #### refresh: If `True`, re-query the server for the backend properties. -> -> Otherwise, return a cached version. + **Return type** - - This method blocks until all sub-jobs are submitted. - + `None` + -**Return type** + -`Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)"), `None`] + ### report -**Returns** + + Return a report on current sub-job statuses. -The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. + **Parameters** -**Raises** + **detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + **Return type** - + `str` -### queue\_info + **Returns** - + A report on sub-job statuses. + -`IBMCompositeJob.queue_info()` + -Return queue information for this job. + ### rerun\_failed -This method returns the queue information of the sub-job that is last in queue. + + Re-submit all failed sub-jobs. -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + + All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + **Return type** -**Return type** + `None` + -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + -**Returns** + ### result -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + + Return the result of the job. - + + This method blocks until all sub-jobs finish. + -### queue\_position + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. - + The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -`IBMCompositeJob.queue_position(refresh=False)` + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. -Return the position of the job in the server queue. + For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: -This method returns the queue position of the sub-job that is last in queue. + ```python + try: + counts = result.get_counts("failed_circuit") + except QiskitError: + print("Circuit execution failed!") + ``` + - - The position returned is within the scope of the provider and may differ from the global queue position. - + If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCompositeJob#error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. -**Parameters** + **Parameters** -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **wait** (`float`) – Time in seconds between queries. + * **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. -**Return type** + **Return type** -`Optional`\[`int`] + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") -**Returns** + **Returns** -Position in the queue or `None` if position is unknown or not applicable. + Job result. - + **Raises** -### refresh + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - + -`IBMCompositeJob.refresh()` + ### running -Obtain the latest job information from the server. + + Return whether the job is actively running. -This method may add additional attributes to this job instance, if new information becomes available. + **Return type** -**Raises** + `bool` + -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Return type** + ### scheduling\_mode -`None` + + Return the scheduling mode the job is in. - + The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. -### report + `fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. - + This information is only available if the job status is `RUNNING` or `DONE`. -`IBMCompositeJob.report(detailed=True)` + **Return type** -Return a report on current sub-job statuses. + `Optional`\[`str`] -**Parameters** + **Returns** -**detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. + The scheduling mode the job is in or `None` if the information is not available. + -**Return type** + -`str` + ### status -**Returns** + + Query the server for the latest job status. -A report on sub-job statuses. + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](qiskit_ibm_provider.job.IBMCompositeJob#wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. + - + + If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCompositeJob#error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + -### rerun\_failed + + Since this job contains multiple sub-jobs, the returned status is mapped in the following order: - + > * INITIALIZING - if any sub-job is being initialized. + > * VALIDATING - if any sub-job is being validated. + > * QUEUED - if any sub-job is queued. + > * RUNNING - if any sub-job is still running. + > * ERROR - if any sub-job incurred an error. + > * CANCELLED - if any sub-job is cancelled. + > * DONE - if all sub-jobs finished. + -`IBMCompositeJob.rerun_failed()` + **Return type** -Re-submit all failed sub-jobs. + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") - - All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. - + **Returns** -**Return type** + The status of the job. -`None` + **Raises** - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -### result + - + ### sub\_job -`IBMCompositeJob.result(timeout=None, wait=5, partial=False, refresh=False)` + + Retrieve the job used to submit the specified circuit. -Return the result of the job. + **Parameters** - - This method blocks until all sub-jobs finish. - + **circuit\_index** (`int`) – Index of the circuit whose job is to be returned. - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + **Return type** - The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + `Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. + **Returns** - For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: + The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. - ```python - try: - counts = result.get_counts("failed_circuit") - except QiskitError: - print("Circuit execution failed!") - ``` - + **Raises** -If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCompositeJob#error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + -**Parameters** + -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **wait** (`float`) – Time in seconds between queries. -* **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + ### sub\_jobs -**Return type** + + Return all submitted sub-jobs. -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") + **Parameters** -**Returns** + **block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. -Job result. + **Return type** -**Raises** + `List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + **Returns** - + All submitted sub-jobs. + -### running + - + ### submit -`IBMCompositeJob.running()` + + Unsupported method. -Return whether the job is actively running. + + This method is not supported, please use `run()` to submit a job. + -**Return type** + **Raises** -`bool` + **NotImplementedError** – Upon invocation. - + **Return type** -### scheduling\_mode + `None` + - + -`IBMCompositeJob.scheduling_mode()` + ### tags -Return the scheduling mode the job is in. + + Return the tags assigned to this job. -The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. + **Return type** -`fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. + `List`\[`str`] -This information is only available if the job status is `RUNNING` or `DONE`. + **Returns** -**Return type** + Tags assigned to this job. + -`Optional`\[`str`] + -**Returns** + ### time\_per\_step -The scheduling mode the job is in or `None` if the information is not available. + + Return the date and time information on each step of the job processing. - + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: -### status + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` - + **Return type** -`IBMCompositeJob.status()` + `Optional`\[`Dict`] -Query the server for the latest job status. + **Returns** - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](qiskit_ibm_provider.job.IBMCompositeJob#wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. - + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + - - If the job failed, you can use [`error_message()`](qiskit_ibm_provider.job.IBMCompositeJob#error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. - + - - Since this job contains multiple sub-jobs, the returned status is mapped in the following order: + ### update\_name - > * INITIALIZING - if any sub-job is being initialized. - > * VALIDATING - if any sub-job is being validated. - > * QUEUED - if any sub-job is queued. - > * RUNNING - if any sub-job is still running. - > * ERROR - if any sub-job incurred an error. - > * CANCELLED - if any sub-job is cancelled. - > * DONE - if all sub-jobs finished. - + + Update the name associated with this job. -**Return type** + + This method blocks until all sub-jobs are submitted. + -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") + **Parameters** -**Returns** + **name** (`str`) – The new name for this job. -The status of the job. + **Return type** -**Raises** + `str` -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + **Returns** - + The new name associated with this job. -### sub\_job + **Raises** - + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. + -`IBMCompositeJob.sub_job(circuit_index)` + -Retrieve the job used to submit the specified circuit. + ### update\_tags -**Parameters** + + Update the tags associated with this job. -**circuit\_index** (`int`) – Index of the circuit whose job is to be returned. + + This method blocks until all sub-jobs are submitted. + -**Return type** + **Parameters** -`Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -**Returns** + **Return type** -The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. + `List`\[`str`] -**Raises** + **Returns** -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + The new tags associated with this job. - + **Raises** -### sub\_jobs + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + - + -`IBMCompositeJob.sub_jobs(block_for_submit=True)` + ### wait\_for\_final\_state -Return all submitted sub-jobs. + + Wait until the job progresses to a final state such as `DONE` or `ERROR`. -**Parameters** + **Parameters** -**block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. + * **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. -**Return type** + * **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. -`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + * **callback** (`Optional`\[`Callable`]) – -**Returns** + Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: -All submitted sub-jobs. + > * job\_id: Job ID + > * job\_status: Status of the job from the last query. + > * job: This `IBMCompositeJob` instance. - + In addition, the following keyword arguments are also provided: -### submit + > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. - + **Raises** -`IBMCompositeJob.submit()` + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. -Unsupported method. + **Return type** - - This method is not supported, please use `run()` to submit a job. - - -**Raises** - -**NotImplementedError** – Upon invocation. - -**Return type** - -`None` - - - -### tags - - - -`IBMCompositeJob.tags()` - -Return the tags assigned to this job. - -**Return type** - -`List`\[`str`] - -**Returns** - -Tags assigned to this job. - - - -### time\_per\_step - - - -`IBMCompositeJob.time_per_step()` - -Return the date and time information on each step of the job processing. - -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` - -**Return type** - -`Optional`\[`Dict`] - -**Returns** - -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. - - - -### update\_name - - - -`IBMCompositeJob.update_name(name)` - -Update the name associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**name** (`str`) – The new name for this job. - -**Return type** - -`str` - -**Returns** - -The new name associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. - - - -### update\_tags - - - -`IBMCompositeJob.update_tags(new_tags)` - -Update the tags associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. - -**Return type** - -`List`\[`str`] - -**Returns** - -The new tags associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. - - - -### wait\_for\_final\_state - - - -`IBMCompositeJob.wait_for_final_state(timeout=None, wait=None, callback=None)` - -Wait until the job progresses to a final state such as `DONE` or `ERROR`. - -**Parameters** - -* **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - -* **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. - -* **callback** (`Optional`\[`Callable`]) – - - Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: - - > * job\_id: Job ID - > * job\_status: Status of the job from the last query. - > * job: This `IBMCompositeJob` instance. - - In addition, the following keyword arguments are also provided: - - > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. - -**Raises** - -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobApiError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobApiError.mdx index 44b6d463e97..7b910d8dc1c 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobApiError # IBMJobApiError - + + Errors that occur unexpectedly when querying the server. -`IBMJobApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobError.mdx index 98114f5b0d0..2ed5e3d9f07 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobError # IBMJobError - + + Base class for errors raised by the job modules. -`IBMJobError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/exceptions.py "view source code") - -Base class for errors raised by the job modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobFailureError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobFailureError.mdx index 9125e7c5f50..7d2981e7622 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobFailureError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobFailureError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobFailureError # IBMJobFailureError - + + Errors raised when a job failed. -`IBMJobFailureError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job failed. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx index 52bfe481d7d..1d75f8307f4 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobInvalidStateError # IBMJobInvalidStateError - + + Errors raised when a job is not in a valid state for the operation. -`IBMJobInvalidStateError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job is not in a valid state for the operation. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx index 1e01dde2590..5a311946168 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobTimeoutError # IBMJobTimeoutError - + + Errors raised when a job operation times out. -`IBMJobTimeoutError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job operation times out. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.QueueInfo.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.QueueInfo.mdx index d9fc3df80d0..c9ddf258b0c 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.QueueInfo.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.QueueInfo.mdx @@ -8,73 +8,65 @@ python_api_name: qiskit_ibm_provider.job.QueueInfo # QueueInfo - + + Queue information for a job. -`QueueInfo(position_in_queue=None, status=None, estimated_start_time=None, estimated_completion_time=None, hub_priority=None, group_priority=None, project_priority=None, job_id=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/queueinfo.py "view source code") + QueueInfo constructor. -Queue information for a job. + **Parameters** -QueueInfo constructor. + * **position** – Position in the queue. + * **status** (`Optional`\[`str`]) – Job status. + * **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. + * **estimated\_complete\_time** – Estimated complete time for the job, in UTC. + * **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. + * **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. + * **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **kwargs** (`Any`) – Additional attributes. -**Parameters** + ## Attributes -* **position** – Position in the queue. -* **status** (`Optional`\[`str`]) – Job status. -* **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. -* **estimated\_complete\_time** – Estimated complete time for the job, in UTC. -* **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. -* **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. -* **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **kwargs** (`Any`) – Additional attributes. + -## Attributes + ### estimated\_complete\_time - + + Return estimated complete time in local time. -### estimated\_complete\_time + **Return type** - + `Optional`\[`datetime`] + -`datetime | None` + -Return estimated complete time in local time. + ### estimated\_start\_time -**Return type** + + Return estimated start time in local time. -`Optional`\[`datetime`] + **Return type** - + `Optional`\[`datetime`] + -### estimated\_start\_time + ## Methods - + -`datetime | None` + ### format -Return estimated start time in local time. + + Build a user-friendly report for the job queue information. -**Return type** + **Return type** -`Optional`\[`datetime`] + `str` -## Methods + **Returns** - - -### format - - - -`QueueInfo.format()` - -Build a user-friendly report for the job queue information. - -**Return type** - -`str` - -**Returns** - -The job queue information report. + The job queue information report. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.job_monitor.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.job_monitor.mdx index f3263eb91ae..39eb9c0f7e2 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.job_monitor.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.job.job_monitor.mdx @@ -10,19 +10,17 @@ python_api_name: qiskit_ibm_provider.job.job_monitor # job\_monitor - + + Monitor the status of an `IBMJob` instance. -`job_monitor(job, interval=None, output=<_io.TextIOWrapper name='' mode='w' encoding='utf-8'>)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/job/job_monitor.py "view source code") + **Parameters** -Monitor the status of an `IBMJob` instance. + * **job** (`IBMJob`) – Job to monitor. + * **interval** (`Optional`\[`float`]) – Time interval between status queries. + * **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. -**Parameters** + **Return type** -* **job** (`IBMJob`) – Job to monitor. -* **interval** (`Optional`\[`float`]) – Time interval between status queries. -* **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.least_busy.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.least_busy.mdx index 91d44b052dd..d4ab0d4160c 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.least_busy.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.least_busy.mdx @@ -10,27 +10,25 @@ python_api_name: qiskit_ibm_provider.least_busy # least\_busy - + + Return the least busy backend from a list. -`least_busy(backends)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/__init__.py "view source code") + Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. -Return the least busy backend from a list. + **Parameters** -Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. + **backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")]) – The backends to choose from. -**Parameters** + **Return type** -**backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")]) – The backends to choose from. + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") -**Return type** + **Returns** -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + The backend with the fewest number of pending jobs. -**Returns** + **Raises** -The backend with the fewest number of pending jobs. - -**Raises** - -[**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + [**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx index 7dbeead727d..27d7041dbdf 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx @@ -8,156 +8,148 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAn # ALAPScheduleAnalysis - + + Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. -`ALAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + -## Attributes + ### is\_analysis\_pass - + + Check if the pass is an analysis pass. -### is\_analysis\_pass + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -Check if the pass is an analysis pass. + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ### is\_transformation\_pass - + + Check if the pass is a transformation pass. -### is\_transformation\_pass + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -Check if the pass is a transformation pass. + ## Methods -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -## Methods + ### \_\_call\_\_ - + + Runs the pass on circuit. -### \_\_call\_\_ + **Parameters** - + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -`ALAPScheduleAnalysis.__call__(circuit, property_set=None)` + **Return type** -Runs the pass on circuit. + QuantumCircuit -**Parameters** + **Returns** -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Return type** + -QuantumCircuit + ### execute -**Returns** + + Execute optimization task for input Qiskit IR. -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Parameters** - + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -### execute + **Return type** - + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -`ALAPScheduleAnalysis.execute(passmanager_ir, state, callback=None)` + **Returns** -Execute optimization task for input Qiskit IR. + Optimized Qiskit IR and state of the workflow. + -**Parameters** + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### name -**Return type** + + Name of the pass. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Return type** -**Returns** + `str` + -Optimized Qiskit IR and state of the workflow. + - + ### run -### name + + Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit - + **Raises** -`ALAPScheduleAnalysis.name()` + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -Name of the pass. + **Return type** -**Return type** + `None` -`str` + **Returns** - + The scheduled DAGCircuit. + -### run + - + ### update\_status -`ALAPScheduleAnalysis.run(dag)` + + Update workflow status. -Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit + **Parameters** -**Raises** + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. + **Return type** -**Return type** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -`None` + **Returns** -**Returns** - -The scheduled DAGCircuit. - - - -### update\_status - - - -`ALAPScheduleAnalysis.update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx index 1cf6db7ae40..7a928f9adf2 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx @@ -8,156 +8,148 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAn # ASAPScheduleAnalysis - + + Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. -`ASAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + -## Attributes + ### is\_analysis\_pass - + + Check if the pass is an analysis pass. -### is\_analysis\_pass + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -Check if the pass is an analysis pass. + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ### is\_transformation\_pass - + + Check if the pass is a transformation pass. -### is\_transformation\_pass + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -Check if the pass is a transformation pass. + ## Methods -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -## Methods + ### \_\_call\_\_ - + + Runs the pass on circuit. -### \_\_call\_\_ + **Parameters** - + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -`ASAPScheduleAnalysis.__call__(circuit, property_set=None)` + **Return type** -Runs the pass on circuit. + QuantumCircuit -**Parameters** + **Returns** -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Return type** + -QuantumCircuit + ### execute -**Returns** + + Execute optimization task for input Qiskit IR. -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Parameters** - + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -### execute + **Return type** - + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -`ASAPScheduleAnalysis.execute(passmanager_ir, state, callback=None)` + **Returns** -Execute optimization task for input Qiskit IR. + Optimized Qiskit IR and state of the workflow. + -**Parameters** + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### name -**Return type** + + Name of the pass. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Return type** -**Returns** + `str` + -Optimized Qiskit IR and state of the workflow. + - + ### run -### name + + Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit - + **Raises** -`ASAPScheduleAnalysis.name()` + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -Name of the pass. + **Return type** -**Return type** + [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") -`str` + **Returns** - + The scheduled DAGCircuit. + -### run + - + ### update\_status -`ASAPScheduleAnalysis.run(dag)` + + Update workflow status. -Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit + **Parameters** -**Raises** + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. + **Return type** -**Return type** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -[`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") + **Returns** -**Returns** - -The scheduled DAGCircuit. - - - -### update\_status - - - -`ASAPScheduleAnalysis.update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx index 1703655e2f7..b7c7549ad0f 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx @@ -8,150 +8,142 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadde # BlockBasePadder - + + The base class of padding pass. -`BlockBasePadder(schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py "view source code") + This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. -The base class of padding pass. + This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. -This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. + Note that padding pass subclasses should define interleaving sequences satisfying: -This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. + > * Interleaved sequence does not change start time of other nodes + > * Interleaved sequence should have total duration of the provided `time_interval`. -Note that padding pass subclasses should define interleaving sequences satisfying: + Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. -> * Interleaved sequence does not change start time of other nodes -> * Interleaved sequence should have total duration of the provided `time_interval`. + ## Attributes -Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. + -## Attributes + ### is\_analysis\_pass - + + Check if the pass is an analysis pass. -### is\_analysis\_pass + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -Check if the pass is an analysis pass. + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ### is\_transformation\_pass - + + Check if the pass is a transformation pass. -### is\_transformation\_pass + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -Check if the pass is a transformation pass. + ## Methods -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -## Methods + ### \_\_call\_\_ - + + Runs the pass on circuit. -### \_\_call\_\_ + **Parameters** - + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -`BlockBasePadder.__call__(circuit, property_set=None)` + **Return type** -Runs the pass on circuit. + QuantumCircuit -**Parameters** + **Returns** -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Return type** + -QuantumCircuit + ### execute -**Returns** + + Execute optimization task for input Qiskit IR. -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Parameters** - + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -### execute + **Return type** - + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -`BlockBasePadder.execute(passmanager_ir, state, callback=None)` + **Returns** -Execute optimization task for input Qiskit IR. + Optimized Qiskit IR and state of the workflow. + -**Parameters** + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### name -**Return type** + + Name of the pass. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Return type** -**Returns** + `str` + -Optimized Qiskit IR and state of the workflow. + - + ### run -### name + + Run the padding pass on `dag`. - + **Parameters** -`BlockBasePadder.name()` + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -Name of the pass. + **Returns** -**Return type** + DAG with idle time filled with instructions. -`str` + **Return type** - + DAGCircuit -### run + **Raises** - + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`BlockBasePadder.run(dag)` + -Run the padding pass on `dag`. + ### update\_status -**Parameters** + + Update workflow status. -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + **Parameters** -**Returns** + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -DAG with idle time filled with instructions. + **Return type** -**Return type** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -DAGCircuit + **Returns** -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - - - -### update\_status - - - -`BlockBasePadder.update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx index 7d4161945dc..68e930ee946 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx @@ -8,133 +8,119 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuit # DynamicCircuitInstructionDurations - + + For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. -`DynamicCircuitInstructionDurations(instruction_durations=None, dt=None, enable_patching=True)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py "view source code") + Dynamic circuit instruction durations. -For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. + ## Attributes -Dynamic circuit instruction durations. + -## Attributes + ### MEASURE\_PATCH\_CYCLES - + -### MEASURE\_PATCH\_CYCLES + - + ### MEASURE\_PATCH\_ODD\_OFFSET -`= 160` + - + ## Methods -### MEASURE\_PATCH\_ODD\_OFFSET + - + ### from\_backend -`= 64` + + Construct an `InstructionDurations` object from the backend. -## Methods + **Parameters** - + **backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")) – backend from which durations (gate lengths) and dt are extracted. -### from\_backend + **Returns** - + The InstructionDurations constructed from backend. -`classmethod DynamicCircuitInstructionDurations.from_backend(backend)` + **Return type** -Construct an `InstructionDurations` object from the backend. + InstructionDurations -**Parameters** + **Raises** -**backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")) – backend from which durations (gate lengths) and dt are extracted. + **TranspilerError** – If dt and dtm is different in the backend. + -**Returns** + -The InstructionDurations constructed from backend. + ### get -**Return type** + + Get the duration of the instruction with the name, qubits, and parameters. -InstructionDurations + Some instructions may have a parameter dependent duration. -**Raises** + **Parameters** -**TranspilerError** – If dt and dtm is different in the backend. + * **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")) – An instruction or its name to be queried. + * **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. + * **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. + * **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. - + **Returns** -### get + The duration of the instruction on the qubits. - + **Return type** -`DynamicCircuitInstructionDurations.get(inst, qubits, unit='dt', parameters=None)` + float|int -Get the duration of the instruction with the name, qubits, and parameters. + **Raises** -Some instructions may have a parameter dependent duration. + **TranspilerError** – No duration is defined for the instruction. + -**Parameters** + -* **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")) – An instruction or its name to be queried. -* **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. -* **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. -* **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. + ### units\_used -**Returns** + + Get the set of all units used in this instruction durations. -The duration of the instruction on the qubits. + **Return type** -**Return type** + `set`\[`str`] -float|int + **Returns** -**Raises** + Set of units used in this instruction durations. + -**TranspilerError** – No duration is defined for the instruction. + - + ### update -### units\_used + + Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. - + **Parameters** -`DynamicCircuitInstructionDurations.units_used()` + * **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)"), `None`]) – Instruction durations to be merged into self (overwriting self). + * **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. -Get the set of all units used in this instruction durations. + **Returns** -**Return type** + The updated InstructionDurations. -`set`\[`str`] + **Return type** -**Returns** + InstructionDurations -Set of units used in this instruction durations. + **Raises** - - -### update - - - -`DynamicCircuitInstructionDurations.update(inst_durations, dt=None)` - -Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. - -**Parameters** - -* **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)"), `None`]) – Instruction durations to be merged into self (overwriting self). -* **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. - -**Returns** - -The updated InstructionDurations. - -**Return type** - -InstructionDurations - -**Raises** - -**TranspilerError** – If the format of instruction\_durations is invalid. + **TranspilerError** – If the format of instruction\_durations is invalid. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx index 9d9cc31ea96..ec9131ebba7 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx @@ -8,162 +8,154 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay # PadDelay - + + Padding idle time with Delay instructions. -`PadDelay(fill_very_end=True, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/pad_delay.py "view source code") + Consecutive delays will be merged in the output of this pass. -Padding idle time with Delay instructions. + The ASAP-scheduled circuit output may become -Consecutive delays will be merged in the output of this pass. + ```python + ┌────────────────┐ + q_0: ┤ Delay(160[dt]) ├──■── + └─────┬───┬──────┘┌─┴─┐ + q_1: ──────┤ X ├───────┤ X ├ + └───┘ └───┘ + ``` -The ASAP-scheduled circuit output may become + Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. -```python - ┌────────────────┐ -q_0: ┤ Delay(160[dt]) ├──■── - └─────┬───┬──────┘┌─┴─┐ -q_1: ──────┤ X ├───────┤ X ├ - └───┘ └───┘ -``` + See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. -Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. + Create new padding delay pass. -See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. + **Parameters** -Create new padding delay pass. + * **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -**Parameters** + ## Attributes -* **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + -## Attributes + ### is\_analysis\_pass - + + Check if the pass is an analysis pass. -### is\_analysis\_pass + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -Check if the pass is an analysis pass. + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ### is\_transformation\_pass - + + Check if the pass is a transformation pass. -### is\_transformation\_pass + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -Check if the pass is a transformation pass. + ## Methods -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -## Methods + ### \_\_call\_\_ - + + Runs the pass on circuit. -### \_\_call\_\_ + **Parameters** - + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -`PadDelay.__call__(circuit, property_set=None)` + **Return type** -Runs the pass on circuit. + QuantumCircuit -**Parameters** + **Returns** -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Return type** + -QuantumCircuit + ### execute -**Returns** + + Execute optimization task for input Qiskit IR. -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Parameters** - + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -### execute + **Return type** - + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -`PadDelay.execute(passmanager_ir, state, callback=None)` + **Returns** -Execute optimization task for input Qiskit IR. + Optimized Qiskit IR and state of the workflow. + -**Parameters** + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### name -**Return type** + + Name of the pass. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Return type** -**Returns** + `str` + -Optimized Qiskit IR and state of the workflow. + - + ### run -### name + + Run the padding pass on `dag`. - + **Parameters** -`PadDelay.name()` + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -Name of the pass. + **Returns** -**Return type** + DAG with idle time filled with instructions. -`str` + **Return type** - + DAGCircuit -### run + **Raises** - + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`PadDelay.run(dag)` + -Run the padding pass on `dag`. + ### update\_status -**Parameters** + + Update workflow status. -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + **Parameters** -**Returns** + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -DAG with idle time filled with instructions. + **Return type** -**Return type** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -DAGCircuit + **Returns** -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - - - -### update\_status - - - -`PadDelay.update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx index 8196b825b4e..65020671dd2 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx @@ -8,297 +8,289 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDe # PadDynamicalDecoupling - - -`PadDynamicalDecoupling(durations, dd_sequences, qubits=None, spacings=None, skip_reset_qubits=True, pulse_alignment=16, extra_slack_distribution='middle', sequence_min_length_ratios=None, insert_multiple_cycles=False, coupling_map=None, alt_spacings=None, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") - -Dynamical decoupling insertion pass for IBM dynamic circuit backends. - -This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). - -```python -import numpy as np -from qiskit.circuit import QuantumCircuit -from qiskit.circuit.library import XGate -from qiskit.transpiler import PassManager, InstructionDurations -from qiskit.visualization import timeline_drawer - -from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis -from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling - -circ = QuantumCircuit(4) -circ.h(0) -circ.cx(0, 1) -circ.cx(1, 2) -circ.cx(2, 3) -circ.measure_all() -durations = InstructionDurations( - [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), - ("cx", [1, 2], 200), ("cx", [2, 3], 300), - ("x", None, 50), ("measure", None, 1000)] -) -``` - -```python -# balanced X-X sequence on all qubits -dd_sequence = [XGate(), XGate()] -pm = PassManager([ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence)]) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌───────────────┐ ┌───┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» - ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» - ├────────────────┤ └───┘ ┌─┴─┐ » - q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» - └────────────────┘ └───┘ » -meas: 4/═════════════════════════════════════════════════════════» - » -« ┌────────────────┐ ┌───┐ ┌───────────────┐ » -« q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» -« └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» -« q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» -« └───┘ └───────────────┘ └───┘ └───────────────┘» -« q_2: ─────────────────────────────────────────────────────────────────────» -« » -« q_3: ─────────────────────────────────────────────────────────────────────» -« » -«meas: 4/═════════════════════════════════════════════════════════════════════» -« » -« ░ ┌─┐ -« q_0: ─░─┤M├───────── -« ░ └╥┘┌─┐ -« q_1: ─░──╫─┤M├────── -« ░ ║ └╥┘┌─┐ -« q_2: ─░──╫──╫─┤M├─── -« ░ ║ ║ └╥┘┌─┐ -« q_3: ─░──╫──╫──╫─┤M├ -« ░ ║ ║ ║ └╥┘ -«meas: 4/════╩══╩══╩══╩═ -« 0 1 2 3 -``` - -```python -# Uhrig sequence on qubit 0 -n = 8 -dd_sequence = [XGate()] * n -def uhrig_pulse_location(k): - return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 -spacings = [] -for k in range(n): - spacings.append(uhrig_pulse_location(k) - sum(spacings)) -spacings.append(1 - sum(spacings)) -pm = PassManager( - [ - ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), - ] -) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌────────────────┐ ░ ┌─┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» - ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» - ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» - q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» - └────────────────┘ └───┘ ░ ║ ║ ║ » -meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» - 0 1 2 » -« -« q_0: ─── -« -« q_1: ─── -« -« q_2: ─── -« ┌─┐ -« q_3: ┤M├ -« └╥┘ -«meas: 4/═╩═ -« 3 -``` + + Dynamical decoupling insertion pass for IBM dynamic circuit backends. + + This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + + ```python + import numpy as np + from qiskit.circuit import QuantumCircuit + from qiskit.circuit.library import XGate + from qiskit.transpiler import PassManager, InstructionDurations + from qiskit.visualization import timeline_drawer + + from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis + from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling + + circ = QuantumCircuit(4) + circ.h(0) + circ.cx(0, 1) + circ.cx(1, 2) + circ.cx(2, 3) + circ.measure_all() + durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] + ) + ``` + + ```python + # balanced X-X sequence on all qubits + dd_sequence = [XGate(), XGate()] + pm = PassManager([ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence)]) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌───────────────┐ ┌───┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» + ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» + ├────────────────┤ └───┘ ┌─┴─┐ » + q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» + └────────────────┘ └───┘ » + meas: 4/═════════════════════════════════════════════════════════» + » + « ┌────────────────┐ ┌───┐ ┌───────────────┐ » + « q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» + « └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» + « q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» + « └───┘ └───────────────┘ └───┘ └───────────────┘» + « q_2: ─────────────────────────────────────────────────────────────────────» + « » + « q_3: ─────────────────────────────────────────────────────────────────────» + « » + «meas: 4/═════════════════════════════════════════════════════════════════════» + « » + « ░ ┌─┐ + « q_0: ─░─┤M├───────── + « ░ └╥┘┌─┐ + « q_1: ─░──╫─┤M├────── + « ░ ║ └╥┘┌─┐ + « q_2: ─░──╫──╫─┤M├─── + « ░ ║ ║ └╥┘┌─┐ + « q_3: ─░──╫──╫──╫─┤M├ + « ░ ║ ║ ║ └╥┘ + «meas: 4/════╩══╩══╩══╩═ + « 0 1 2 3 + ``` + + ```python + # Uhrig sequence on qubit 0 + n = 8 + dd_sequence = [XGate()] * n + def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 + spacings = [] + for k in range(n): + spacings.append(uhrig_pulse_location(k) - sum(spacings)) + spacings.append(1 - sum(spacings)) + pm = PassManager( + [ + ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), + ] + ) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌────────────────┐ ░ ┌─┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» + ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» + ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» + q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» + └────────────────┘ └───┘ ░ ║ ║ ║ » + meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» + 0 1 2 » + « + « q_0: ─── + « + « q_1: ─── + « + « q_2: ─── + « ┌─┐ + « q_3: ┤M├ + « └╥┘ + «meas: 4/═╩═ + « 3 + ``` + + + You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. + + + Dynamical decoupling initializer. - - You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. - + **Parameters** -Dynamical decoupling initializer. + * **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -**Parameters** + * **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. -* **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + * **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). -* **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. + * **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified -* **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). + * **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). -* **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified + * **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. -* **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). + * **extra\_slack\_distribution** (`str`) – -* **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. + The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. -* **extra\_slack\_distribution** (`str`) – + > * ”middle”: Put the extra slack to the interval at the middle of the sequence. + > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. - The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. + * **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. - > * ”middle”: Put the extra slack to the interval at the middle of the sequence. - > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. + * **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. -* **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. + * **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. -* **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. + * **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. -* **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -* **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. + **Raises** -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + * **TranspilerError** – When invalid DD sequence is specified. + * **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. + * **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) -**Raises** + ## Attributes -* **TranspilerError** – When invalid DD sequence is specified. -* **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. -* **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) + -## Attributes + ### is\_analysis\_pass - + + Check if the pass is an analysis pass. -### is\_analysis\_pass + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -Check if the pass is an analysis pass. + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ### is\_transformation\_pass - + + Check if the pass is a transformation pass. -### is\_transformation\_pass + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -Check if the pass is a transformation pass. + ## Methods -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -## Methods + ### \_\_call\_\_ - + + Runs the pass on circuit. -### \_\_call\_\_ + **Parameters** - + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -`PadDynamicalDecoupling.__call__(circuit, property_set=None)` + **Return type** -Runs the pass on circuit. + QuantumCircuit -**Parameters** + **Returns** -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Return type** + -QuantumCircuit + ### execute -**Returns** + + Execute optimization task for input Qiskit IR. -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Parameters** - + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -### execute + **Return type** - + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -`PadDynamicalDecoupling.execute(passmanager_ir, state, callback=None)` + **Returns** -Execute optimization task for input Qiskit IR. + Optimized Qiskit IR and state of the workflow. + -**Parameters** + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### name -**Return type** + + Name of the pass. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Return type** -**Returns** + `str` + -Optimized Qiskit IR and state of the workflow. + - + ### run -### name + + Run the padding pass on `dag`. - + **Parameters** -`PadDynamicalDecoupling.name()` + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -Name of the pass. + **Returns** -**Return type** + DAG with idle time filled with instructions. -`str` + **Return type** - + DAGCircuit -### run + **Raises** - + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`PadDynamicalDecoupling.run(dag)` + -Run the padding pass on `dag`. + ### update\_status -**Parameters** + + Update workflow status. -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + **Parameters** -**Returns** + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -DAG with idle time filled with instructions. + **Return type** -**Return type** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -DAGCircuit + **Returns** -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - - - -### update\_status - - - -`PadDynamicalDecoupling.update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.seconds_to_duration.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.seconds_to_duration.mdx index 5b8c6a4e7f3..c1290c1b037 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.seconds_to_duration.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.seconds_to_duration.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.seconds_to_duration # seconds\_to\_duration - + + Converts seconds in a datetime delta to a duration. -`seconds_to_duration(seconds)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Converts seconds in a datetime delta to a duration. + **seconds** (`float`) – Number of seconds in time delta. -**Parameters** + **Return type** -**seconds** (`float`) – Number of seconds in time delta. + `Tuple`\[`int`, `int`, `int`, `int`, `int`] -**Return type** + **Returns** -`Tuple`\[`int`, `int`, `int`, `int`, `int`] - -**Returns** - -A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.to_python_identifier.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.to_python_identifier.mdx index 2b2c0a271c5..9eff68e6f3f 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.to_python_identifier.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.to_python_identifier.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.to_python_identifier # to\_python\_identifier - + + Convert a name to a valid Python identifier. -`to_python_identifier(name)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Convert a name to a valid Python identifier. + **name** (`str`) – Name to be converted. -**Parameters** + **Return type** -**name** (`str`) – Name to be converted. + `str` -**Return type** + **Returns** -`str` - -**Returns** - -Name that is a valid Python identifier. + Name that is a valid Python identifier. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.utc_to_local.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.utc_to_local.mdx index df2a316fdb0..99c6147d3f1 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.utc_to_local.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.utc_to_local.mdx @@ -10,25 +10,23 @@ python_api_name: qiskit_ibm_provider.utils.utc_to_local # utc\_to\_local - + + Convert a UTC `datetime` object or string to a local timezone `datetime`. -`utc_to_local(utc_dt)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Convert a UTC `datetime` object or string to a local timezone `datetime`. + **utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. -**Parameters** + **Return type** -**utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. + `datetime` -**Return type** + **Returns** -`datetime` + A `datetime` with the local timezone. -**Returns** + **Raises** -A `datetime` with the local timezone. - -**Raises** - -**TypeError** – If the input parameter value is not valid. + **TypeError** – If the input parameter value is not valid. + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.validate_job_tags.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.validate_job_tags.mdx index f9dfc7933e1..495a69e94be 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.validate_job_tags.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.utils.validate_job_tags.mdx @@ -10,22 +10,20 @@ python_api_name: qiskit_ibm_provider.utils.validate_job_tags # validate\_job\_tags - + + Validates input job tags. -`validate_job_tags(job_tags, exception)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Validates input job tags. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. + * **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. -**Parameters** + **Raises** -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. -* **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. + **Exception** – If the job tags are invalid. -**Raises** + **Return type** -**Exception** – If the job tags are invalid. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_error_map.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_error_map.mdx index 382b7625e6d..de11040725e 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_error_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_error_map.mdx @@ -10,43 +10,41 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_error_map # iplot\_error\_map - + + Plot the error map of a device. -`iplot_error_map(backend, figsize=(800, 500), show_title=True, remove_badcal_edges=True, background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/visualization/interactive/error_map.py "view source code") + **Parameters** -Plot the error map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. + * **figsize** (`Tuple`\[`int`]) – Figure size in pixels. + * **show\_title** (`bool`) – Whether to show figure title. + * **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. + * **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. -* **figsize** (`Tuple`\[`int`]) – Figure size in pixels. -* **show\_title** (`bool`) – Whether to show figure title. -* **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. -* **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The error map figure. -**Returns** + **Raises** -The error map figure. + * **VisualizationValueError** – If an invalid input is received. + * **VisualizationTypeError** – If the specified backend is a simulator. -**Raises** + **Example** -* **VisualizationValueError** – If an invalid input is received. -* **VisualizationTypeError** – If the specified backend is a simulator. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_error_map -**Example** + provider = IBMProvider(group='open', project='main') + backend = provider.get_backend('ibmq_vigo') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_error_map - -provider = IBMProvider(group='open', project='main') -backend = provider.get_backend('ibmq_vigo') - -iplot_error_map(backend, as_widget=True) -``` + iplot_error_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_gate_map.mdx b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_gate_map.mdx index 1ed9da04d67..3cb6f72642c 100644 --- a/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_gate_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.7/qiskit_ibm_provider.visualization.iplot_gate_map.mdx @@ -10,44 +10,42 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_gate_map # iplot\_gate\_map - + + Plots an interactive gate map of a device. -`iplot_gate_map(backend, figsize=(None, None), label_qubits=True, qubit_size=None, line_width=None, font_size=None, qubit_color='#2f4b7c', qubit_labels=None, line_color='#2f4b7c', font_color='white', background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.7/qiskit_ibm_provider/visualization/interactive/gate_map.py "view source code") + **Parameters** -Plots an interactive gate map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. + * **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. + * **label\_qubits** (`bool`) – Labels for the qubits. + * **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. + * **line\_width** (`Optional`\[`float`]) – Width of lines. + * **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. + * **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. + * **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels + * **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. + * **font\_color** (`str`) – The font color for the qubit labels. + * **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. -* **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. -* **label\_qubits** (`bool`) – Labels for the qubits. -* **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. -* **line\_width** (`Optional`\[`float`]) – Width of lines. -* **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. -* **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. -* **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels -* **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. -* **font\_color** (`str`) – The font color for the qubit labels. -* **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The gate map figure. -**Returns** + **Example** -The gate map figure. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_gate_map -**Example** + provider = IBMProvider(group='open', project='main') + backend = provider.get_backend('ibmq_vigo') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_gate_map - -provider = IBMProvider(group='open', project='main') -backend = provider.get_backend('ibmq_vigo') - -iplot_gate_map(backend, as_widget=True) -``` + iplot_gate_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackend.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackend.mdx index 5df823a15f8..a666232baa8 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackend.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackend.mdx @@ -8,657 +8,619 @@ python_api_name: qiskit_ibm_provider.IBMBackend # IBMBackend - + + Backend class interfacing with an IBM Quantum device. -`IBMBackend(configuration, provider, api_client, instance=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/ibm_backend.py "view source code") + You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: -Backend class interfacing with an IBM Quantum device. + ```python + from qiskit import transpile + from qiskit_ibm_provider import IBMProvider + from qiskit.circuit.random import random_circuit -You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: + provider = IBMProvider() + backend = provider.backend.ibmq_vigo + qx = random_circuit(n_qubits=5, depth=4) + transpiled = transpile(qx, backend=backend) + job = backend.run(transpiled) + retrieved_job = provider.backend.retrieve_job(job.job_id()) + ``` -```python -from qiskit import transpile -from qiskit_ibm_provider import IBMProvider -from qiskit.circuit.random import random_circuit + + * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. + * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. + -provider = IBMProvider() -backend = provider.backend.ibmq_vigo -qx = random_circuit(n_qubits=5, depth=4) -transpiled = transpile(qx, backend=backend) -job = backend.run(transpiled) -retrieved_job = provider.backend.retrieve_job(job.job_id()) -``` + Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: - - * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. - * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. - + ```python + status = backend.status() + is_operational = status.operational + jobs_in_queue = status.pending_jobs + ``` -Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: + **Here is list of attributes available on the `IBMBackend` class:** -```python -status = backend.status() -is_operational = status.operational -jobs_in_queue = status.pending_jobs -``` + * name: backend name. -**Here is list of attributes available on the `IBMBackend` class:** + * backend\_version: backend version in the form X.Y.Z. -* name: backend name. + * num\_qubits: number of qubits. -* backend\_version: backend version in the form X.Y.Z. + * target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. -* num\_qubits: number of qubits. + * basis\_gates: list of basis gates names on the backend. -* target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. + * gates: list of basis gates on the backend. -* basis\_gates: list of basis gates names on the backend. + * local: backend is local or remote. -* gates: list of basis gates on the backend. + * simulator: backend is a simulator. -* local: backend is local or remote. + * conditional: backend supports conditional operations. -* simulator: backend is a simulator. + * open\_pulse: backend supports open pulse. -* conditional: backend supports conditional operations. + * memory: backend supports memory. -* open\_pulse: backend supports open pulse. + * max\_shots: maximum number of shots supported. -* memory: backend supports memory. + * coupling\_map (list): The coupling map for the device -* max\_shots: maximum number of shots supported. + * supported\_instructions (List\[str]): Instructions supported by the backend. -* coupling\_map (list): The coupling map for the device + * dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. -* supported\_instructions (List\[str]): Instructions supported by the backend. + * rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. -* dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + * default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. -* rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + * n\_uchannels: Number of u-channels. -* default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + * u\_channel\_lo: U-channel relationship on device los. -* n\_uchannels: Number of u-channels. + * meas\_levels: Supported measurement levels. -* u\_channel\_lo: U-channel relationship on device los. + * qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. -* meas\_levels: Supported measurement levels. + * meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. -* qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. + * dt: Qubit drive channel timestep in nanoseconds. -* meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. + * dtm: Measurement drive channel timestep in nanoseconds. -* dt: Qubit drive channel timestep in nanoseconds. + * rep\_times: Supported repetition times (program execution time) for backend in μs. -* dtm: Measurement drive channel timestep in nanoseconds. + * meas\_kernels: Supported measurement kernels. -* rep\_times: Supported repetition times (program execution time) for backend in μs. + * discriminators: Supported discriminators. -* meas\_kernels: Supported measurement kernels. + * hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. -* discriminators: Supported discriminators. + * channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) -* hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. + * acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. -* channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) + * conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m -* acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. + * meas\_map (list): Grouping of measurement which are multiplexed -* conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m + * max\_circuits (int): The maximum number of experiments per job -* meas\_map (list): Grouping of measurement which are multiplexed + * sample\_name (str): Sample name for the backend -* max\_circuits (int): The maximum number of experiments per job + * n\_registers (int): Number of register slots available for feedback (if conditional is True) -* sample\_name (str): Sample name for the backend + * register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. -* n\_registers (int): Number of register slots available for feedback (if conditional is True) + * configurable (bool): True if the backend is configurable, if the backend is a simulator -* register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + * credits\_required (bool): True if backend requires credits to run a job. -* configurable (bool): True if the backend is configurable, if the backend is a simulator + * online\_date (datetime): The date that the device went online -* credits\_required (bool): True if backend requires credits to run a job. + * display\_name (str): Alternate name field for the backend -* online\_date (datetime): The date that the device went online + * description (str): A description for the backend -* display\_name (str): Alternate name field for the backend + * tags (list): A list of string tags to describe the backend -* description (str): A description for the backend + * version: version of `Backend` class (Ex: 1, 2) -* tags (list): A list of string tags to describe the backend + * channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. -* version: version of `Backend` class (Ex: 1, 2) + * parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` -* channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. + * processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. -* parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + > * family: Processor family of this backend. + > * revision: Revision version of this processor. + > * segment: Segment this processor belongs to within a larger chip. -* processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + IBMBackend constructor. - > * family: Processor family of this backend. - > * revision: Revision version of this processor. - > * segment: Segment this processor belongs to within a larger chip. + **Parameters** -IBMBackend constructor. + * **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")]) – Backend configuration. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. -**Parameters** + ## Attributes -* **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")]) – Backend configuration. -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. + ### coupling\_map -## Attributes + + Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)") object + - + ### dt -### coupling\_map + + Return the system time resolution of input signals -Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)") object + This is required to be implemented if the backend supports Pulse scheduling. - + **Return type** -### dt + `Optional`\[`float`] -Return the system time resolution of input signals + **Returns** -This is required to be implemented if the backend supports Pulse scheduling. + The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + -**Return type** + ### dtm -`Optional`\[`float`] + + Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + -**Returns** + ### id\_warning\_issued -The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + - + ### instruction\_durations -### dtm + + Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)") object. + -Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + ### instruction\_schedule\_map - + + Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.45)") for the instructions defined in this backend’s target. + -### id\_warning\_issued + ### instructions -`= False` + + A list of Instruction tuples on the backend of the form `(instruction, (qubits)` - + **Return type** -### instruction\_durations + `List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)"), `Tuple`\[`int`]]] + -Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)") object. + ### max\_circuits - + + The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. -### instruction\_schedule\_map + **Return type** -Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.45)") for the instructions defined in this backend’s target. + `int` + - + ### meas\_map -### instructions + + Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + -A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + ### num\_qubits -**Return type** + + Return the number of qubits the backend has. -`List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)"), `Tuple`\[`int`]]] + **Return type** - + `int` + -### max\_circuits + ### operation\_names -The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. + + A list of instruction names that the backend supports. -**Return type** + **Return type** -`int` + `List`\[`str`] + - + ### operations -### meas\_map + + A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)") instances that the backend supports. -Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + **Return type** - + `List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")] + -### num\_qubits + ### options -Return the number of qubits the backend has. + + Return the options for the backend -**Return type** + The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + -`int` + ### provider - + + Return the backend Provider. -### operation\_names + **Returns** -A list of instruction names that the backend supports. + the Provider responsible for the backend. -**Return type** + **Return type** -`List`\[`str`] + Provider + - + ### session -### operations + + Return session -A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)") instances that the backend supports. + **Return type** -**Return type** + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -`List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")] + ### target - + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target + -### options + ### version -Return the options for the backend + -The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + ### name - + + Name of the backend. + -### provider + ### description -Return the backend Provider. + + Optional human-readable description. + -**Returns** + ### online\_date -the Provider responsible for the backend. + + Date that the backend came online. + -**Return type** + ### backend\_version -Provider + + Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + - + ## Methods -### session + ### acquire\_channel -Return session + + Return the acquisition channel for the given qubit. -**Return type** + **Returns** -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + The Qubit measurement acquisition line. - + **Return type** -### target + AcquireChannel + -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target + ### cancel\_session - + + Cancel session. All pending jobs will be cancelled. -### version + **Return type** -`= 2` + `None` + - + ### close\_session -### name + + Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. -Name of the backend. + **Return type** - + `None` + -### description + ### configuration -Optional human-readable description. + + Return the backend configuration. - + Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. -### online\_date + The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). -Date that the backend came online. + **Return type** - + `Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")] -### backend\_version + **Returns** -Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + The configuration for the backend. + -## Methods + ### control\_channel -### acquire\_channel + + Return the secondary drive channel for the given qubit. - + This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. -`acquire_channel(qubit)` + **Parameters** -Return the acquisition channel for the given qubit. + **qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. -**Returns** + **Returns** -The Qubit measurement acquisition line. + The Qubit measurement acquisition line. -**Return type** + **Return type** -AcquireChannel + List\[ControlChannel] + -### cancel\_session + ### defaults - + + Return the pulse defaults for the backend. -`cancel_session()` + The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). -Cancel session. All pending jobs will be cancelled. + **Parameters** -**Return type** + **refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. -`None` + **Return type** -### close\_session + `Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.45)")] - + **Returns** -`close_session()` + The backend pulse defaults or `None` if the backend does not support pulse. + -Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. + ### drive\_channel -**Return type** + + Return the drive channel for the given qubit. -`None` + **Returns** -### configuration + The Qubit drive channel - + **Return type** -`configuration()` + DriveChannel + -Return the backend configuration. + ### get\_translation\_stage\_plugin -Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. + + Return the default translation stage plugin name for IBM backends. -The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). + **Return type** -**Return type** + `str` + -`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.45)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.45)")] + ### measure\_channel -**Returns** + + Return the measure stimulus channel for the given qubit. -The configuration for the backend. + **Returns** -### control\_channel + The Qubit measurement stimulus line - + **Return type** -`control_channel(qubits)` + MeasureChannel + -Return the secondary drive channel for the given qubit. + ### open\_session -This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + + Open session -**Parameters** + **Return type** -**qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -**Returns** + ### properties -The Qubit measurement acquisition line. + + Return the backend properties, subject to optional filtering. -**Return type** + This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. -List\[ControlChannel] + The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). -### defaults + **Parameters** - + * **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + * **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)") whose timestamp is closest to, but older than, the specified datetime. -`defaults(refresh=False)` + **Return type** -Return the pulse defaults for the backend. + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] -The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). + **Returns** -**Parameters** + The backend properties or `None` if the backend properties are not currently available. -**refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. + **Raises** -**Return type** + **TypeError** – If an input argument is not of the correct type. + -`Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.45)")] + ### qubit\_properties -**Returns** + + Return QubitProperties for a given qubit. -The backend pulse defaults or `None` if the backend does not support pulse. + If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. -### drive\_channel + **Parameters** - + **qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order -`drive_channel(qubit)` + **Return type** -Return the drive channel for the given qubit. + `Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)")]] -**Returns** + **Returns** -The Qubit drive channel + The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. -**Return type** + **Raises** -DriveChannel + **NotImplementedError** – if the backend doesn’t support querying the qubit properties + -### get\_translation\_stage\_plugin + ### run - + + Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. -`classmethod get_translation_stage_plugin()` + **Parameters** -Return the default translation stage plugin name for IBM backends. + * **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`]]]) – An individual or a list of `QuantumCircuit`. -**Return type** + * **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) -`str` + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. -### measure\_channel + * **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - + * **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. -`measure_channel(qubit)` + * **or** (*The following parameters are applicable only if dynamic=False is specified*) – -Return the measure stimulus channel for the given qubit. + * **to.** (*defaulted*) – -**Returns** + * **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. -The Qubit measurement stimulus line + * **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. -**Return type** + * **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. -MeasureChannel + * **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – -### open\_session + Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - + * `0`, measurements of the raw signal (the measurement output pulse envelope) + * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) + * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) -`open_session(max_time=None)` + * **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – -Open session + Level of measurement data for the backend to return. For `meas_level` 0 and 1: -**Return type** + * `single` returns information from every shot. + * `avg` returns average measurement output (averaged over number of shots). -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + * **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. -### properties + * **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - + * **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. -`properties(refresh=False, datetime=None)` + * **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) -Return the backend properties, subject to optional filtering. + * **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) -This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. + * **\*\*run\_config** – Extra arguments used to configure the run. -The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). + **Return type** -**Parameters** + `IBMJob` -* **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. -* **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)") whose timestamp is closest to, but older than, the specified datetime. + **Returns** -**Return type** + The job to be executed. -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] + **Raises** -**Returns** + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. -The backend properties or `None` if the backend properties are not currently available. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. -**Raises** + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – -**TypeError** – If an input argument is not of the correct type. + * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. + -### qubit\_properties + ### set\_options - + + Set the options fields for the backend -`qubit_properties(qubit)` + This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. -Return QubitProperties for a given qubit. + **Parameters** -If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + **fields** – The fields to update the options -**Parameters** + **Raises** -**qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order + **AttributeError** – If the field passed in is not part of the options + -**Return type** + ### status -`Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.45)")]] + + Return the backend status. -**Returns** + + If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. + -The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + **Return type** -**Raises** + [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") -**NotImplementedError** – if the backend doesn’t support querying the qubit properties + **Returns** -### run + The status of the backend. - + **Raises** -`run(circuits, dynamic=None, job_tags=None, init_circuit=None, init_num_resets=None, header=None, shots=None, memory=None, meas_level=None, meas_return=None, rep_delay=None, init_qubits=None, use_measure_esp=None, noise_model=None, seed_simulator=None, **run_config)` + [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. + -Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. + ### target\_history -**Parameters** - -* **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)"), `str`]]]) – An individual or a list of `QuantumCircuit`. - -* **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) - -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. - -* **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - -* **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. - -* **or** (*The following parameters are applicable only if dynamic=False is specified*) – - -* **to.** (*defaulted*) – - -* **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. - -* **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. - -* **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. - -* **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – - - Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - - * `0`, measurements of the raw signal (the measurement output pulse envelope) - * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) - * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) - -* **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – - - Level of measurement data for the backend to return. For `meas_level` 0 and 1: - - * `single` returns information from every shot. - * `avg` returns average measurement output (averaged over number of shots). - -* **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. - -* **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - -* **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. - -* **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) - -* **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) - -* **\*\*run\_config** – Extra arguments used to configure the run. - -**Return type** - -`IBMJob` - -**Returns** - -The job to be executed. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. - -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. - -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – - - * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. - -### set\_options - - - -`set_options(**fields)` - -Set the options fields for the backend - -This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. - -**Parameters** - -**fields** – The fields to update the options - -**Raises** - -**AttributeError** – If the field passed in is not part of the options - -### status - - - -`status()` - -Return the backend status. - - - If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. - - -**Return type** - -[`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.45)") - -**Returns** - -The status of the backend. - -**Raises** - -[**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. - -### target\_history - - - -`target_history(datetime=None)` - -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target with properties found on datetime + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.45)") :returns: Target with properties found on datetime + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiError.mdx index 7ecf2b3a4a8..eaa1a6cc217 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiError # IBMBackendApiError - + + Errors that occur unexpectedly when querying the server. -`IBMBackendApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx index 26392efadf0..d1bbd842781 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiProtocolError # IBMBackendApiProtocolError - + + Errors raised when an unexpected value is received from the server. -`IBMBackendApiProtocolError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Errors raised when an unexpected value is received from the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendError.mdx index 944d84deb6b..243eaedc772 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendError # IBMBackendError - + + Base class for errors raised by the backend modules. -`IBMBackendError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendService.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendService.mdx index 3018960227a..ae56defb11c 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendService.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendService.mdx @@ -8,161 +8,153 @@ python_api_name: qiskit_ibm_provider.IBMBackendService # IBMBackendService - + + Backend namespace for an IBM Quantum account. -`IBMBackendService(provider, hgp)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/ibm_backend_service.py "view source code") + Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: -Backend namespace for an IBM Quantum account. + ```python + backends = provider.backends() # Invoke backends() to get the backends. + sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. + ``` -Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: + Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: -```python -backends = provider.backends() # Invoke backends() to get the backends. -sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. -``` + ```python + most_recent_jobs = provider.backend.jobs(limit=10) + ``` -Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: + It is also possible to retrieve a single job without specifying the backend name: -```python -most_recent_jobs = provider.backend.jobs(limit=10) -``` + ```python + job = provider.backend.retrieve_job() + ``` -It is also possible to retrieve a single job without specifying the backend name: + IBMBackendService constructor. -```python -job = provider.backend.retrieve_job() -``` + **Parameters** -IBMBackendService constructor. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. -**Parameters** + ## Methods -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. + ### backends -## Methods + + Return all backends accessible via this account, subject to optional filtering. -### backends + **Parameters** - + * **name** (`Optional`\[`str`]) – Backend name to filter by. -`backends(name=None, filters=None, min_num_qubits=None, instance=None, dynamic_circuits=None, **kwargs)` + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -Return all backends accessible via this account, subject to optional filtering. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -**Parameters** + * **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. -* **name** (`Optional`\[`str`]) – Backend name to filter by. + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + More complex filters, such as lambda functions. For example: -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -* **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. + * **\*\*kwargs** – -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. - More complex filters, such as lambda functions. For example: + Examples: - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **\*\*kwargs** – + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. + **Return type** - Examples: + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Returns** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + The list of available backends that match the filter. -**Return type** + **Raises** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. + * **QiskitBackendNotFoundError** – If the backend is not found in any instance. + -**Returns** + ### jobs -The list of available backends that match the filter. + + Return a list of jobs, subject to optional filtering. -**Raises** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. -* **QiskitBackendNotFoundError** – If the backend is not found in any instance. + **Parameters** -### jobs + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by + * **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. + * **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – - + **Return type** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + `List`\[`IBMJob`] -Return a list of jobs, subject to optional filtering. + **Returns** -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + A list of `IBMJob` instances. -**Parameters** + **Raises** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by -* **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. -* **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. + * **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + -**Return type** + ### retrieve\_job -`List`\[`IBMJob`] + + Return a single job. -**Returns** + **Parameters** -A list of `IBMJob` instances. + **job\_id** (`str`) – The ID of the job to retrieve. -**Raises** + **Return type** -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. -* **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + `IBMJob` -### retrieve\_job + **Returns** - + The job with the given id. -`retrieve_job(job_id)` + **Raises** -Return a single job. - -**Parameters** - -**job\_id** (`str`) – The ID of the job to retrieve. - -**Return type** - -`IBMJob` - -**Returns** - -The job with the given id. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. -* **IBMJobNotFoundError** – If job cannot be found. -* **IBMInputValueError** – If job exists but was run from a different service. + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. + * **IBMJobNotFoundError** – If job cannot be found. + * **IBMInputValueError** – If job exists but was run from a different service. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendValueError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendValueError.mdx index 373f5500c91..0cee250e42f 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMBackendValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendValueError # IBMBackendValueError - + + Value errors raised by the backend modules. -`IBMBackendValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMError.mdx index 8aa55270cf8..ca32c9522a0 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMError # IBMError - + + Base class for errors raised by the provider modules. -`IBMError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the provider modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProvider.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProvider.mdx index 791d8189d58..b9fbdc59faf 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProvider.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProvider.mdx @@ -8,355 +8,333 @@ python_api_name: qiskit_ibm_provider.IBMProvider # IBMProvider - + + Provides access to the IBM Quantum services available to an account. -`IBMProvider(token=None, url=None, name=None, instance=None, proxies=None, verify=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/ibm_provider.py "view source code") + Authenticate against IBM Quantum for use from saved credentials or during session. -Provides access to the IBM Quantum services available to an account. + Credentials can be saved to disk by calling the save\_account() method: -Authenticate against IBM Quantum for use from saved credentials or during session. + ```python + from qiskit_ibm_provider import IBMProvider + IBMProvider.save_account(token=) + ``` -Credentials can be saved to disk by calling the save\_account() method: + You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: -```python -from qiskit_ibm_provider import IBMProvider -IBMProvider.save_account(token=) -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: + Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: + You can also enable an account just for the current session by instantiating the provider with the API token: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider(token=) + ``` -You can also enable an account just for the current session by instantiating the provider with the API token: + token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider(token=) -``` + + The hub/group/project is selected based on the below selection order, in decreasing order of priority. -token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. + * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. + * The hub/group/project required for the service. + * The default hub/group/project you set using save\_account(). + * A premium hub/group/project in your account. + * An open access hub/group/project. + - - The hub/group/project is selected based on the below selection order, in decreasing order of priority. + The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. - * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. - * The hub/group/project required for the service. - * The default hub/group/project you set using save\_account(). - * A premium hub/group/project in your account. - * An open access hub/group/project. - + You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: -The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. + ```python + backend_service = provider.backend + ``` -You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: + Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. -```python -backend_service = provider.backend -``` + The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: -Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. + ```python + backends = provider.backends() + ``` -The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: + The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: -```python -backends = provider.backends() -``` + ```python + simulator_backend = provider.get_backend('ibmq_qasm_simulator') + ``` -The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: + IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. -```python -simulator_backend = provider.get_backend('ibmq_qasm_simulator') -``` + It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: -IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. + ```python + simulator_backend = provider.backend.ibmq_qasm_simulator + ``` -It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: + + The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. + -```python -simulator_backend = provider.backend.ibmq_qasm_simulator -``` + IBMProvider constructor - - The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. - + **Parameters** -IBMProvider constructor + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). + * **name** (`Optional`\[`str`]) – Name of the account to load. + * **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. -**Parameters** + **Returns** -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). -* **name** (`Optional`\[`str`]) – Name of the account to load. -* **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. + An instance of IBMProvider -**Returns** + **Raises** -An instance of IBMProvider + **IBMInputValueError** – If an input is invalid. -**Raises** + ## Attributes -**IBMInputValueError** – If an input is invalid. + ### backend -## Attributes + + Return the backend service. - + **Return type** -### backend + [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") -Return the backend service. + **Returns** -**Return type** + The backend service instance. + -[`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") + ### version -**Returns** + -The backend service instance. + ## Methods - + ### active\_account -### version + + Return the IBM Quantum account currently in use for the session. -`= 1` + **Return type** -## Methods + `Optional`\[`Dict`\[`str`, `str`]] -### active\_account + **Returns** - + A dictionary with information about the account currently in the session. + -`active_account()` + ### backends -Return the IBM Quantum account currently in use for the session. + + Return all backends accessible via this account, subject to optional filtering. -**Return type** + **Parameters** -`Optional`\[`Dict`\[`str`, `str`]] + * **name** (`Optional`\[`str`]) – Backend name to filter by. -**Returns** + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -A dictionary with information about the account currently in the session. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -### backends + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – - + More complex filters, such as lambda functions. For example: -`backends(name=None, filters=None, min_num_qubits=None, instance=None, **kwargs)` + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -Return all backends accessible via this account, subject to optional filtering. + * **\*\*kwargs** – -**Parameters** + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: -* **name** (`Optional`\[`str`]) – Backend name to filter by. + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + **Return type** -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - More complex filters, such as lambda functions. For example: + **Returns** - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + The list of available backends that match the filter. + -* **\*\*kwargs** – + ### delete\_account - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: + + Delete a saved account from disk. - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Parameters** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + **name** (`Optional`\[`str`]) – Name of the saved account to delete. -**Return type** + **Return type** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + `bool` -**Returns** + **Returns** -The list of available backends that match the filter. + True if the account was deleted. False if no account was found. + -### delete\_account + ### get\_backend - + + Return a single backend matching the specified filtering. -`static delete_account(name=None)` + **Parameters** -Delete a saved account from disk. + * **name** (*str*) – Name of the backend. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **\*\*kwargs** – Dict used for filtering. -**Parameters** + **Returns** -**name** (`Optional`\[`str`]) – Name of the saved account to delete. + a backend matching the filtering. -**Return type** + **Return type** -`bool` + Backend -**Returns** + **Raises** -True if the account was deleted. False if no account was found. + * **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. + * [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + -### get\_backend + ### instances - + + Return the IBM Quantum instances list currently in use for the session. -`get_backend(name=None, instance=None, **kwargs)` + **Return type** -Return a single backend matching the specified filtering. + `List`\[`str`] -**Parameters** + **Returns** -* **name** (*str*) – Name of the backend. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **\*\*kwargs** – Dict used for filtering. + A list with instances currently in the session. + -**Returns** + ### jobs -a backend matching the filtering. + + Return a list of jobs, subject to optional filtering. -**Return type** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -Backend + **Parameters** -**Raises** + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – -* **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. -* [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + **Return type** -### instances + `List`\[`IBMJob`] - + **Returns** -`instances()` + A list of `IBMJob` instances. + -Return the IBM Quantum instances list currently in use for the session. + ### retrieve\_job -**Return type** + + Return a single job. -`List`\[`str`] + **Parameters** -**Returns** + **job\_id** (`str`) – The ID of the job to retrieve. -A list with instances currently in the session. + **Return type** -### jobs + `IBMJob` - + **Returns** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + The job with the given id. + -Return a list of jobs, subject to optional filtering. + ### save\_account -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + + Save the account to disk for future use. -**Parameters** + **Parameters** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) + * **instance** (`Optional`\[`str`]) – The hub/group/project. + * **name** (`Optional`\[`str`]) – Name of the account to save. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. + * **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. -**Return type** + **Return type** -`List`\[`IBMJob`] + `None` + -**Returns** + ### saved\_accounts -A list of `IBMJob` instances. + + List the accounts saved on disk. -### retrieve\_job + **Parameters** - + * **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. + * **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. -`retrieve_job(job_id)` + **Return type** -Return a single job. + `dict` -**Parameters** + **Returns** -**job\_id** (`str`) – The ID of the job to retrieve. + A dictionary with information about the accounts saved on disk. -**Return type** + **Raises** -`IBMJob` - -**Returns** - -The job with the given id. - -### save\_account - - - -`static save_account(token=None, url=None, instance=None, name=None, proxies=None, verify=None, overwrite=False)` - -Save the account to disk for future use. - -**Parameters** - -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) -* **instance** (`Optional`\[`str`]) – The hub/group/project. -* **name** (`Optional`\[`str`]) – Name of the account to save. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. -* **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. - -**Return type** - -`None` - -### saved\_accounts - - - -`static saved_accounts(default=None, name=None)` - -List the accounts saved on disk. - -**Parameters** - -* **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. -* **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. - -**Return type** - -`dict` - -**Returns** - -A dictionary with information about the accounts saved on disk. - -**Raises** - -**ValueError** – If an invalid account is found on disk. + **ValueError** – If an invalid account is found on disk. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderError.mdx index f7dc3dccf58..eb11df1bfad 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderError # IBMProviderError - + + Base class for errors raise by IBMProvider. -`IBMProviderError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raise by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderValueError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderValueError.mdx index f078a9de916..51f43518dce 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.IBMProviderValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderValueError # IBMProviderValueError - + + Value errors raised by IBMProvider. -`IBMProviderValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.Session.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.Session.mdx index ee5f1c7281d..3e89b2afbd8 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.Session.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.Session.mdx @@ -8,92 +8,88 @@ python_api_name: qiskit_ibm_provider.Session # Session - + + Class for creating a flexible Qiskit Runtime session. -`Session(max_time=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/session.py "view source code") + A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. -Class for creating a flexible Qiskit Runtime session. + You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. -A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. + For example: -You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. + ```python + from qiskit.test.reference_circuits import ReferenceCircuits + from qiskit_ibm_provider import IBMProvider -For example: + circ = ReferenceCircuits.bell() + backend = IBMProvider().get_backend("ibmq_qasm_simulator") + backend.open_session() + job = backend.run(circ) + print(f"Job ID: {job.job_id()}") + print(f"Result: {job.result()}") + # Close the session only if all jobs are finished and + # you don't need to run more in the session. + backend.cancel_session() + ``` -```python -from qiskit.test.reference_circuits import ReferenceCircuits -from qiskit_ibm_provider import IBMProvider + Session can also be used as a context manager: -circ = ReferenceCircuits.bell() -backend = IBMProvider().get_backend("ibmq_qasm_simulator") -backend.open_session() -job = backend.run(circ) -print(f"Job ID: {job.job_id()}") -print(f"Result: {job.result()}") -# Close the session only if all jobs are finished and -# you don't need to run more in the session. -backend.cancel_session() -``` + ```python + with backend.open_session() as session: + job = backend.run(ReferenceCircuits.bell()) + assert job.job_id() == session.session_id + ``` -Session can also be used as a context manager: + Session constructor. -```python -with backend.open_session() as session: - job = backend.run(ReferenceCircuits.bell()) - assert job.job_id() == session.session_id -``` + **Parameters** -Session constructor. + **max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). -**Parameters** + **Raises** -**max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). + **ValueError** – If an input value is invalid. -**Raises** + ## Attributes -**ValueError** – If an input value is invalid. + ### active -## Attributes + + Return the status of the session. - + **Return type** -### active + `bool` -Return the status of the session. + **Returns** -**Return type** + True if the session is active, False otherwise. + -`bool` + ### session\_id -**Returns** + + Return the session ID. -True if the session is active, False otherwise. + **Return type** - + `str` -### session\_id + **Returns** -Return the session ID. + Session ID. None until a job runs in the session. + -**Return type** + ## Methods -`str` + ### cancel -**Returns** + + Set the session.\_active status to False -Session ID. None until a job runs in the session. + **Return type** -## Methods - -### cancel - - - -`cancel()` - -Set the session.\_active status to False - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCircuitJob.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCircuitJob.mdx index 61fbc13b31b..f007c72daca 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCircuitJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCircuitJob.mdx @@ -8,606 +8,550 @@ python_api_name: qiskit_ibm_provider.job.IBMCircuitJob # IBMCircuitJob - + + Representation of a job that executes on an IBM Quantum backend. -`IBMCircuitJob(backend, api_client, job_id, creation_date=None, status=None, runtime_client=None, kind=None, name=None, time_per_step=None, result=None, error=None, session_id=None, tags=None, run_mode=None, client_info=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/ibm_circuit_job.py "view source code") + The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. -Representation of a job that executes on an IBM Quantum backend. + If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") members. For example: -The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. - -If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") members. For example: - -```python -from qiskit.providers.jobstatus import JobStatus - -job = backend.run(...) - -try: - job_status = job.status() # Query the backend server for job status. - if job_status is JobStatus.RUNNING: - print("The job is still running") -except IBMJobApiError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - - - An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. - - -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: - -```python -job = backend.run(...) - -try: - job_result = job.result() # It will block until the job finishes. - print("The job finished with result {}".format(job_result)) -except JobError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - -Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. - -IBMCircuitJob constructor. - -**Parameters** - -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`str`) – Job ID. -* **creation\_date** (`Optional`\[`str`]) – Job creation date. -* **status** (`Optional`\[`str`]) – Job status returned by the server. -* **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server -* **kind** (`Optional`\[`str`]) – Job type. -* **name** (`Optional`\[`str`]) – Job name. -* **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. -* **result** (`Optional`\[`dict`]) – Job result. -* **error** (`Optional`\[`dict`]) – Job error. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. -* **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. -* **kwargs** (`Any`) – Additional job attributes. - -## Attributes - - - -### client\_version - -Return version of the client used for this job. - -**Return type** - -`Dict`\[`str`, `str`] - -**Returns** - -**Client version in dictionary format, where the key is the name** - -of the client and the value is the version. - - - -### usage\_estimation - -Return usage estimation information for this job. - -**Return type** - -`Dict`\[`str`, `Any`] - -**Returns** - -`quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. - - - -### version - -`= 1` - -## Methods - -### backend - - - -`backend()` - -Return the backend where this job was executed. - -**Return type** - -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") - -### backend\_options - - - -`backend_options()` - -Return the backend configuration options used for this job. - -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. - -**Return type** - -`Dict` - -**Returns** - -Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. - -### cancel - - - -`cancel()` - -Attempt to cancel the job. - - - Depending on the state the job is in, it might be impossible to cancel the job. - - -**Return type** - -`bool` - -**Returns** - -`True` if the job is cancelled, else `False`. - -**Raises** + ```python + from qiskit.providers.jobstatus import JobStatus -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. -* [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + job = backend.run(...) -### cancelled + try: + job_status = job.status() # Query the backend server for job status. + if job_status is JobStatus.RUNNING: + print("The job is still running") + except IBMJobApiError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` - + + An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. + -`cancelled()` + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: -Return whether the job has been cancelled. + ```python + job = backend.run(...) -**Return type** + try: + job_result = job.result() # It will block until the job finishes. + print("The job finished with result {}".format(job_result)) + except JobError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` -`bool` + Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. -### circuits + IBMCircuitJob constructor. - + **Parameters** -`circuits()` + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`str`) – Job ID. + * **creation\_date** (`Optional`\[`str`]) – Job creation date. + * **status** (`Optional`\[`str`]) – Job status returned by the server. + * **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server + * **kind** (`Optional`\[`str`]) – Job type. + * **name** (`Optional`\[`str`]) – Job name. + * **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. + * **result** (`Optional`\[`dict`]) – Job result. + * **error** (`Optional`\[`dict`]) – Job error. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. + * **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. + * **kwargs** (`Any`) – Additional job attributes. -Return the circuits for this job. + ## Attributes -**Return type** + ### client\_version -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] + + Return version of the client used for this job. -**Returns** + **Return type** -The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + `Dict`\[`str`, `str`] -### creation\_date + **Returns** - + **Client version in dictionary format, where the key is the name** -`creation_date()` + of the client and the value is the version. + -Return job creation date, in local time. + ### usage\_estimation -**Return type** + + Return usage estimation information for this job. -`datetime` + **Return type** -**Returns** + `Dict`\[`str`, `Any`] -The job creation date as a datetime object, in local time. + **Returns** -### done + `quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. + - + ### version -`done()` + -Return whether the job has successfully run. + ## Methods -**Return type** + ### backend -`bool` + + Return the backend where this job was executed. -### error\_message + **Return type** - + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + -`error_message()` + ### backend\_options -Provide details about the reason of failure. + + Return the backend configuration options used for this job. -**Return type** + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -`Optional`\[`str`] + **Return type** -**Returns** + `Dict` -An error report if the job failed or `None` otherwise. + **Returns** -### header + Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. + - + ### cancel -`header()` + + Attempt to cancel the job. -Return the user header specified for this job. + + Depending on the state the job is in, it might be impossible to cancel the job. + -**Return type** + **Return type** -`Dict` + `bool` -**Returns** + **Returns** -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + `True` if the job is cancelled, else `False`. -### in\_final\_state + **Raises** - + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. + * [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + -`in_final_state()` + ### cancelled -Return whether the job is in a final job state such as `DONE` or `ERROR`. + + Return whether the job has been cancelled. -**Return type** + **Return type** -`bool` + `bool` + -### job\_id + ### circuits - + + Return the circuits for this job. -`job_id()` + **Return type** -Return the job ID assigned by the server. + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] -**Return type** + **Returns** -`str` + The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + -**Returns** + ### creation\_date -Job ID. + + Return job creation date, in local time. -### name + **Return type** - + `datetime` -`name()` + **Returns** -Return the name assigned to this job. + The job creation date as a datetime object, in local time. + -**Return type** + ### done -`Optional`\[`str`] + + Return whether the job has successfully run. -**Returns** + **Return type** -Job name or `None` if no name was assigned to this job. + `bool` + -### properties + ### error\_message - + + Provide details about the reason of failure. -`properties(refresh=False)` + **Return type** -Return the backend properties for this job. + `Optional`\[`str`] -**Parameters** + **Returns** -**refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + An error report if the job failed or `None` otherwise. + -**Return type** + ### header -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] + + Return the user header specified for this job. -**Returns** + **Return type** -The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + `Dict` -### queue\_info + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`queue_info()` + ### in\_final\_state -Return queue information for this job. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + **Return type** - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + `bool` + -**Return type** + ### job\_id -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Return the job ID assigned by the server. -**Returns** + **Return type** -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + `str` -### queue\_position + **Returns** - + Job ID. + -`queue_position(refresh=False)` + ### name -Return the position of the job in the server queue. + + Return the name assigned to this job. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + `Optional`\[`str`] -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job name or `None` if no name was assigned to this job. + -`Optional`\[`int`] + ### properties -**Returns** + + Return the backend properties for this job. -Position in the queue or `None` if position is unknown or not applicable. + **Parameters** -### refresh + **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. - + **Return type** -`refresh()` + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")] -Obtain the latest job information from the server. + **Returns** -This method may add additional attributes to this job instance, if new information becomes available. + The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + -**Raises** + ### queue\_info -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return queue information for this job. -**Return type** + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`None` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -### result + **Return type** - + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`result(timeout=None, refresh=False)` + **Returns** -Return the result of the job. + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + ### queue\_position - The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + + Return the position of the job in the server queue. - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. + + The position returned is within the scope of the provider and may differ from the global queue position. + - For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: + **Parameters** - ```python - try: - counts = result.get_counts("failed_experiment") - except QiskitError: - print("Experiment failed!") - ``` - + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + **Return type** -**Parameters** + `Optional`\[`int`] -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job result. + This method may add additional attributes to this job instance, if new information becomes available. -**Raises** + **Raises** -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -### running + **Return type** - + `None` + -`running()` + ### result -Return whether the job is actively running. + + Return the result of the job. -**Return type** + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -`bool` + The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -### scheduling\_mode + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. - + For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: -`scheduling_mode()` + ```python + try: + counts = result.get_counts("failed_experiment") + except QiskitError: + print("Experiment failed!") + ``` + -Return the scheduling mode the job is in. + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. -**Return type** + **Parameters** -`Optional`\[`str`] + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. -**Returns** + **Return type** -The scheduling mode the job is in or `None` if the information is not available. + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") -### status + **Returns** - + Job result. -`status()` + **Raises** -Query the server for the latest job status. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. - + ### running - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. - + + Return whether the job is actively running. -**Return type** + **Return type** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") + `bool` + -**Returns** + ### scheduling\_mode -The status of the job. + + Return the scheduling mode the job is in. -**Raises** + **Return type** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `Optional`\[`str`] -### submit + **Returns** - + The scheduling mode the job is in or `None` if the information is not available. + -`submit()` + ### status -Unsupported method. + + Query the server for the latest job status. - - This method is not supported, please use `run()` to submit a job. - + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. + -**Raises** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + -**NotImplementedError** – Upon invocation. + **Return type** -**Return type** + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") -`None` + **Returns** -### tags + The status of the job. - + **Raises** -`tags()` + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Return the tags assigned to this job. + ### submit -**Return type** + + Unsupported method. -`List`\[`str`] + + This method is not supported, please use `run()` to submit a job. + -**Returns** + **Raises** -Tags assigned to this job. + **NotImplementedError** – Upon invocation. -### time\_per\_step + **Return type** - + `None` + -`time_per_step()` + ### tags -Return the date and time information on each step of the job processing. + + Return the tags assigned to this job. -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: + **Return type** -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` + `List`\[`str`] -**Return type** + **Returns** -`Optional`\[`Dict`] + Tags assigned to this job. + -**Returns** + ### time\_per\_step -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + + Return the date and time information on each step of the job processing. -### update\_name + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`update_name(name)` + **Return type** -Update the name associated with this job. + `Optional`\[`Dict`] -**Parameters** + **Returns** -**name** (`str`) – The new name for this job. + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + -**Return type** + ### update\_name -`str` + + Update the name associated with this job. -**Returns** + **Parameters** -The new name associated with this job. + **name** (`str`) – The new name for this job. -### update\_tags + **Return type** - + `str` -`update_tags(new_tags)` + **Returns** -Update the tags associated with this job. + The new name associated with this job. + -**Parameters** + ### update\_tags -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. + + Update the tags associated with this job. -**Return type** + **Parameters** -`List`\[`str`] + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -**Returns** + **Return type** -The new tags associated with this job. + `List`\[`str`] -**Raises** + **Returns** -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + The new tags associated with this job. -### wait\_for\_final\_state + **Raises** - + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -`wait_for_final_state(timeout=None, wait=3)` + ### wait\_for\_final\_state -**Use the websocket server to wait for the final the state of a job. The server** + + **Use the websocket server to wait for the final the state of a job. The server** -will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. + will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. -**Parameters** + **Parameters** -**timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. + **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. -**Raises** + **Raises** -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. -**Return type** + **Return type** -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCompositeJob.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCompositeJob.mdx index 2a0eeba6b54..bbc12475796 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCompositeJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMCompositeJob.mdx @@ -8,746 +8,678 @@ python_api_name: qiskit_ibm_provider.job.IBMCompositeJob # IBMCompositeJob - + + Representation of a set of jobs that execute on an IBM Quantum backend. -`IBMCompositeJob(backend, api_client, job_id=None, creation_date=None, jobs=None, circuits_list=None, run_config=None, name=None, tags=None, client_version=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/ibm_composite_job.py "view source code") + An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. -Representation of a set of jobs that execute on an IBM Quantum backend. + This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. -An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. + You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. -This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. + `IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. -You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. -`IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + `IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. + IBMCompositeJob constructor. -`IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. + **Parameters** -IBMCompositeJob constructor. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **creation\_date** (`Optional`\[`datetime`]) – Job creation date. + * **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. + * **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]]]) – Circuits for this job. + * **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. + * **name** (`Optional`\[`str`]) – Job name. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **client\_version** (`Optional`\[`Dict`]) – Client used for the job. -**Parameters** + **Raises** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **creation\_date** (`Optional`\[`datetime`]) – Job creation date. -* **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. -* **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")]]]) – Circuits for this job. -* **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. -* **name** (`Optional`\[`str`]) – Job name. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **client\_version** (`Optional`\[`Dict`]) – Client used for the job. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. -**Raises** + ## Attributes -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. + ### client\_version -## Attributes + + Return version of the client used for this job. - + **Return type** -### client\_version + `Dict`\[`str`, `str`] -Return version of the client used for this job. + **Returns** -**Return type** + **Client version in dictionary format, where the key is the name** -`Dict`\[`str`, `str`] + of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + -**Returns** + ### version -**Client version in dictionary format, where the key is the name** + -of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + ## Methods - + ### backend -### version + + Return the backend where this job was executed. -`= 1` + **Return type** -## Methods + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + -### backend + ### backend\_options - + + Return the backend configuration options used for this job. -`backend()` + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -Return the backend where this job was executed. + **Return type** -**Return type** + `Dict`\[`str`, `Any`] -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + **Returns** -### backend\_options + Backend options used for this job. + - + ### block\_for\_submit -`backend_options()` + + Block until all sub-jobs are submitted. -Return the backend configuration options used for this job. + **Return type** -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. + `None` + -**Return type** + ### cancel -`Dict`\[`str`, `Any`] + + Attempt to cancel the job. -**Returns** + + Depending on the state the job is in, it might be impossible to cancel the job. + -Backend options used for this job. + **Return type** -### block\_for\_submit + `bool` - + **Returns** -`block_for_submit()` + `True` if the job is cancelled, else `False`. -Block until all sub-jobs are submitted. + **Raises** -**Return type** + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -`None` + ### cancelled -### cancel + + Return whether the job has been cancelled. - + **Return type** -`cancel()` + `bool` + -Attempt to cancel the job. + ### circuits - - Depending on the state the job is in, it might be impossible to cancel the job. - + + Return the circuits for this job. -**Return type** + **Return type** -`bool` + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] -**Returns** + **Returns** -`True` if the job is cancelled, else `False`. + The circuits for this job. + -**Raises** + ### creation\_date -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return job creation date, in local time. -### cancelled + **Return type** - + `Optional`\[`datetime`] -`cancelled()` + **Returns** -Return whether the job has been cancelled. + The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + -**Return type** + ### done -`bool` + + Return whether the job has successfully run. -### circuits + **Return type** - + `bool` + -`circuits()` + ### error\_message -Return the circuits for this job. + + Provide details about the reason of failure. -**Return type** + + This method blocks until the job finishes. + -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.45)")] + **Return type** -**Returns** + `Optional`\[`str`] -The circuits for this job. + **Returns** -### creation\_date + An error report if the job failed or `None` otherwise. + - + ### from\_jobs -`creation_date()` + + Return an instance of this class. -Return job creation date, in local time. + The input job ID is used to query for sub-job information from the server. -**Return type** + **Parameters** -`Optional`\[`datetime`] + * **job\_id** (`str`) – Job ID. + * **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. + * **api\_client** (`AccountClient`) – Client to use to communicate with the server. -**Returns** + **Return type** -The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + [`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") -### done + **Returns** - + An instance of this class. + -`done()` + ### header -Return whether the job has successfully run. + + Return the user header specified for this job. -**Return type** + **Return type** -`bool` + `Dict` -### error\_message + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`error_message()` + ### in\_final\_state -Provide details about the reason of failure. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. - - This method blocks until the job finishes. - + **Return type** -**Return type** + `bool` + -`Optional`\[`str`] + ### job\_id -**Returns** + + Return a unique id identifying the job. -An error report if the job failed or `None` otherwise. + **Return type** -### from\_jobs + `str` + - + ### name -`classmethod from_jobs(job_id, jobs, api_client)` + + Return the name assigned to this job. -Return an instance of this class. + **Return type** -The input job ID is used to query for sub-job information from the server. + `Optional`\[`str`] -**Parameters** + **Returns** -* **job\_id** (`str`) – Job ID. -* **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. -* **api\_client** (`AccountClient`) – Client to use to communicate with the server. + Job name or `None` if no name was assigned to this job. + -**Return type** + ### properties -[`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") + + Return the backend properties for this job. -**Returns** + > **Args:** + > + > **refresh: If `True`, re-query the server for the backend properties.** + > + > Otherwise, return a cached version. -An instance of this class. + + This method blocks until all sub-jobs are submitted. + -### header + **Return type** - + `Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)"), `None`] -`header()` + **Returns** -Return the user header specified for this job. + The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. -**Return type** + **Raises** -`Dict` + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Returns** + ### queue\_info -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + + Return queue information for this job. -### in\_final\_state + This method returns the queue information of the sub-job that is last in queue. - + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`in_final_state()` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -Return whether the job is in a final job state such as `DONE` or `ERROR`. + **Return type** -**Return type** + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`bool` + **Returns** -### job\_id + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - + ### queue\_position -`job_id()` + + Return the position of the job in the server queue. -Return a unique id identifying the job. + This method returns the queue position of the sub-job that is last in queue. -**Return type** + + The position returned is within the scope of the provider and may differ from the global queue position. + -`str` + **Parameters** -### name + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. - + **Return type** -`name()` + `Optional`\[`int`] -Return the name assigned to this job. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -`Optional`\[`str`] + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job name or `None` if no name was assigned to this job. + This method may add additional attributes to this job instance, if new information becomes available. -### properties + **Raises** - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -`properties(refresh=False)` + **Return type** -Return the backend properties for this job. + `None` + -> **Args:** -> -> **refresh: If `True`, re-query the server for the backend properties.** -> -> Otherwise, return a cached version. + ### report - - This method blocks until all sub-jobs are submitted. - + + Return a report on current sub-job statuses. -**Return type** + **Parameters** -`Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.45)"), `None`] + **detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. -**Returns** + **Return type** -The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. + `str` -**Raises** + **Returns** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + A report on sub-job statuses. + -### queue\_info + ### rerun\_failed - + + Re-submit all failed sub-jobs. -`queue_info()` + + All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + -Return queue information for this job. + **Return type** -This method returns the queue information of the sub-job that is last in queue. + `None` + -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + ### result - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + + Return the result of the job. -**Return type** + + This method blocks until all sub-jobs finish. + -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -**Returns** + The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. -### queue\_position + For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: - + ```python + try: + counts = result.get_counts("failed_circuit") + except QiskitError: + print("Circuit execution failed!") + ``` + -`queue_position(refresh=False)` + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. -Return the position of the job in the server queue. + **Parameters** -This method returns the queue position of the sub-job that is last in queue. + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **wait** (`float`) – Time in seconds between queries. + * **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job result. -`Optional`\[`int`] + **Raises** -**Returns** + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Position in the queue or `None` if position is unknown or not applicable. + ### running -### refresh + + Return whether the job is actively running. - + **Return type** -`refresh()` + `bool` + -Obtain the latest job information from the server. + ### scheduling\_mode -This method may add additional attributes to this job instance, if new information becomes available. + + Return the scheduling mode the job is in. -**Raises** + The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. -**Return type** + This information is only available if the job status is `RUNNING` or `DONE`. -`None` + **Return type** -### report + `Optional`\[`str`] - + **Returns** -`report(detailed=True)` + The scheduling mode the job is in or `None` if the information is not available. + -Return a report on current sub-job statuses. + ### status -**Parameters** + + Query the server for the latest job status. -**detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. + -**Return type** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + -`str` + + Since this job contains multiple sub-jobs, the returned status is mapped in the following order: -**Returns** + > * INITIALIZING - if any sub-job is being initialized. + > * VALIDATING - if any sub-job is being validated. + > * QUEUED - if any sub-job is queued. + > * RUNNING - if any sub-job is still running. + > * ERROR - if any sub-job incurred an error. + > * CANCELLED - if any sub-job is cancelled. + > * DONE - if all sub-jobs finished. + -A report on sub-job statuses. + **Return type** -### rerun\_failed + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") - + **Returns** -`rerun_failed()` + The status of the job. -Re-submit all failed sub-jobs. + **Raises** - - All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Return type** + ### sub\_job -`None` + + Retrieve the job used to submit the specified circuit. -### result + **Parameters** - + **circuit\_index** (`int`) – Index of the circuit whose job is to be returned. -`result(timeout=None, wait=5, partial=False, refresh=False)` + **Return type** -Return the result of the job. + `Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] - - This method blocks until all sub-jobs finish. - + **Returns** - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. - The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + **Raises** - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") instance can be used to verify whether it contains partial results. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + - For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: + ### sub\_jobs - ```python - try: - counts = result.get_counts("failed_circuit") - except QiskitError: - print("Circuit execution failed!") - ``` - + + Return all submitted sub-jobs. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + **Parameters** -**Parameters** + **block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **wait** (`float`) – Time in seconds between queries. -* **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Return type** -**Return type** + `List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.45)") + **Returns** -**Returns** + All submitted sub-jobs. + -Job result. + ### submit -**Raises** + + Unsupported method. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + This method is not supported, please use `run()` to submit a job. + -### running + **Raises** - + **NotImplementedError** – Upon invocation. -`running()` + **Return type** -Return whether the job is actively running. + `None` + -**Return type** + ### tags -`bool` + + Return the tags assigned to this job. -### scheduling\_mode + **Return type** - + `List`\[`str`] -`scheduling_mode()` + **Returns** -Return the scheduling mode the job is in. + Tags assigned to this job. + -The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. + ### time\_per\_step -`fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. + + Return the date and time information on each step of the job processing. -This information is only available if the job status is `RUNNING` or `DONE`. + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: -**Return type** + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`Optional`\[`str`] + **Return type** -**Returns** + `Optional`\[`Dict`] -The scheduling mode the job is in or `None` if the information is not available. + **Returns** -### status + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + - + ### update\_name -`status()` + + Update the name associated with this job. -Query the server for the latest job status. + + This method blocks until all sub-jobs are submitted. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. - + **Parameters** - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. - + **name** (`str`) – The new name for this job. - - Since this job contains multiple sub-jobs, the returned status is mapped in the following order: + **Return type** - > * INITIALIZING - if any sub-job is being initialized. - > * VALIDATING - if any sub-job is being validated. - > * QUEUED - if any sub-job is queued. - > * RUNNING - if any sub-job is still running. - > * ERROR - if any sub-job incurred an error. - > * CANCELLED - if any sub-job is cancelled. - > * DONE - if all sub-jobs finished. - + `str` -**Return type** + **Returns** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.45)") + The new name associated with this job. -**Returns** + **Raises** -The status of the job. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. + -**Raises** + ### update\_tags -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Update the tags associated with this job. -### sub\_job + + This method blocks until all sub-jobs are submitted. + - + **Parameters** -`sub_job(circuit_index)` + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -Retrieve the job used to submit the specified circuit. + **Return type** -**Parameters** + `List`\[`str`] -**circuit\_index** (`int`) – Index of the circuit whose job is to be returned. + **Returns** -**Return type** + The new tags associated with this job. -`Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. + ### wait\_for\_final\_state -**Raises** + + Wait until the job progresses to a final state such as `DONE` or `ERROR`. -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + **Parameters** -### sub\_jobs + * **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - + * **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. -`sub_jobs(block_for_submit=True)` + * **callback** (`Optional`\[`Callable`]) – -Return all submitted sub-jobs. + Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: -**Parameters** + > * job\_id: Job ID + > * job\_status: Status of the job from the last query. + > * job: This `IBMCompositeJob` instance. -**block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. + In addition, the following keyword arguments are also provided: -**Return type** + > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. -`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. -All submitted sub-jobs. + **Return type** -### submit - - - -`submit()` - -Unsupported method. - - - This method is not supported, please use `run()` to submit a job. - - -**Raises** - -**NotImplementedError** – Upon invocation. - -**Return type** - -`None` - -### tags - - - -`tags()` - -Return the tags assigned to this job. - -**Return type** - -`List`\[`str`] - -**Returns** - -Tags assigned to this job. - -### time\_per\_step - - - -`time_per_step()` - -Return the date and time information on each step of the job processing. - -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` - -**Return type** - -`Optional`\[`Dict`] - -**Returns** - -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. - -### update\_name - - - -`update_name(name)` - -Update the name associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**name** (`str`) – The new name for this job. - -**Return type** - -`str` - -**Returns** - -The new name associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. - -### update\_tags - - - -`update_tags(new_tags)` - -Update the tags associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. - -**Return type** - -`List`\[`str`] - -**Returns** - -The new tags associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. - -### wait\_for\_final\_state - - - -`wait_for_final_state(timeout=None, wait=None, callback=None)` - -Wait until the job progresses to a final state such as `DONE` or `ERROR`. - -**Parameters** - -* **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - -* **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. - -* **callback** (`Optional`\[`Callable`]) – - - Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: - - > * job\_id: Job ID - > * job\_status: Status of the job from the last query. - > * job: This `IBMCompositeJob` instance. - - In addition, the following keyword arguments are also provided: - - > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. - -**Raises** - -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobApiError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobApiError.mdx index 55489113f09..8d17060b5ac 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobApiError # IBMJobApiError - + + Errors that occur unexpectedly when querying the server. -`IBMJobApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobError.mdx index 89538972cce..63b9c7df146 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobError # IBMJobError - + + Base class for errors raised by the job modules. -`IBMJobError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/exceptions.py "view source code") - -Base class for errors raised by the job modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobFailureError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobFailureError.mdx index 29b06ab70b6..4a5530ae1f8 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobFailureError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobFailureError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobFailureError # IBMJobFailureError - + + Errors raised when a job failed. -`IBMJobFailureError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job failed. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx index 0ae61b58ab9..201486397a9 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobInvalidStateError # IBMJobInvalidStateError - + + Errors raised when a job is not in a valid state for the operation. -`IBMJobInvalidStateError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job is not in a valid state for the operation. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx index 8762b8517d9..c81baeb4834 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobTimeoutError # IBMJobTimeoutError - + + Errors raised when a job operation times out. -`IBMJobTimeoutError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job operation times out. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.QueueInfo.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.QueueInfo.mdx index 27e8f0720d6..3100ceda825 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.QueueInfo.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.QueueInfo.mdx @@ -8,63 +8,59 @@ python_api_name: qiskit_ibm_provider.job.QueueInfo # QueueInfo - + + Queue information for a job. -`QueueInfo(position_in_queue=None, status=None, estimated_start_time=None, estimated_completion_time=None, hub_priority=None, group_priority=None, project_priority=None, job_id=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/queueinfo.py "view source code") + QueueInfo constructor. -Queue information for a job. + **Parameters** -QueueInfo constructor. + * **position** – Position in the queue. + * **status** (`Optional`\[`str`]) – Job status. + * **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. + * **estimated\_complete\_time** – Estimated complete time for the job, in UTC. + * **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. + * **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. + * **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **kwargs** (`Any`) – Additional attributes. -**Parameters** + ## Attributes -* **position** – Position in the queue. -* **status** (`Optional`\[`str`]) – Job status. -* **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. -* **estimated\_complete\_time** – Estimated complete time for the job, in UTC. -* **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. -* **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. -* **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **kwargs** (`Any`) – Additional attributes. + ### estimated\_complete\_time -## Attributes + + Return estimated complete time in local time. - + **Return type** -### estimated\_complete\_time + `Optional`\[`datetime`] + -Return estimated complete time in local time. + ### estimated\_start\_time -**Return type** + + Return estimated start time in local time. -`Optional`\[`datetime`] + **Return type** - + `Optional`\[`datetime`] + -### estimated\_start\_time + ## Methods -Return estimated start time in local time. + ### format -**Return type** + + Build a user-friendly report for the job queue information. -`Optional`\[`datetime`] + **Return type** -## Methods + `str` -### format + **Returns** - - -`format()` - -Build a user-friendly report for the job queue information. - -**Return type** - -`str` - -**Returns** - -The job queue information report. + The job queue information report. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.job_monitor.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.job_monitor.mdx index 24cf5ede658..ec3991b3fd2 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.job_monitor.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.job.job_monitor.mdx @@ -10,19 +10,17 @@ python_api_name: qiskit_ibm_provider.job.job_monitor # job\_monitor - + + Monitor the status of an `IBMJob` instance. -`job_monitor(job, interval=None, output=<_io.TextIOWrapper name='' mode='w' encoding='utf-8'>)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/job/job_monitor.py "view source code") + **Parameters** -Monitor the status of an `IBMJob` instance. + * **job** (`IBMJob`) – Job to monitor. + * **interval** (`Optional`\[`float`]) – Time interval between status queries. + * **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. -**Parameters** + **Return type** -* **job** (`IBMJob`) – Job to monitor. -* **interval** (`Optional`\[`float`]) – Time interval between status queries. -* **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.least_busy.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.least_busy.mdx index ce5ccf091d6..bde921b14a2 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.least_busy.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.least_busy.mdx @@ -10,27 +10,25 @@ python_api_name: qiskit_ibm_provider.least_busy # least\_busy - + + Return the least busy backend from a list. -`least_busy(backends)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/__init__.py "view source code") + Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. -Return the least busy backend from a list. + **Parameters** -Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. + **backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")]) – The backends to choose from. -**Parameters** + **Return type** -**backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")]) – The backends to choose from. + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") -**Return type** + **Returns** -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)") + The backend with the fewest number of pending jobs. -**Returns** + **Raises** -The backend with the fewest number of pending jobs. - -**Raises** - -[**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + [**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx index 0c94cc34930..d38fc29495d 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAn # ALAPScheduleAnalysis - + + Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. -`ALAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + + Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + `None` -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` + **Return type** -Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -`None` - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx index aa17b1750e9..eab53e9d689 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAn # ASAPScheduleAnalysis - + + Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. -`ASAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + + Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` + **Return type** -Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -[`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)") - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx index 253e271bbc1..0d86d922493 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx @@ -8,140 +8,128 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadde # BlockBasePadder - + + The base class of padding pass. -`BlockBasePadder(schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py "view source code") + This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. -The base class of padding pass. + This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. -This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. + Note that padding pass subclasses should define interleaving sequences satisfying: -This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. + > * Interleaved sequence does not change start time of other nodes + > * Interleaved sequence should have total duration of the provided `time_interval`. -Note that padding pass subclasses should define interleaving sequences satisfying: + Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. -> * Interleaved sequence does not change start time of other nodes -> * Interleaved sequence should have total duration of the provided `time_interval`. + ## Attributes -Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx index d7c560371d2..a1c83cc58eb 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx @@ -8,121 +8,107 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuit # DynamicCircuitInstructionDurations - + + For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. -`DynamicCircuitInstructionDurations(instruction_durations=None, dt=None, enable_patching=True)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py "view source code") + Dynamic circuit instruction durations. -For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. + ## Attributes -Dynamic circuit instruction durations. + ### MEASURE\_PATCH\_CYCLES -## Attributes + - + ### MEASURE\_PATCH\_ODD\_OFFSET -### MEASURE\_PATCH\_CYCLES + -`= 160` + ## Methods - + ### from\_backend -### MEASURE\_PATCH\_ODD\_OFFSET + + Construct an `InstructionDurations` object from the backend. -`= 64` + **Parameters** -## Methods + **backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")) – backend from which durations (gate lengths) and dt are extracted. -### from\_backend + **Returns** - + The InstructionDurations constructed from backend. -`classmethod from_backend(backend)` + **Return type** -Construct an `InstructionDurations` object from the backend. + InstructionDurations -**Parameters** + **Raises** -**backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.45)")) – backend from which durations (gate lengths) and dt are extracted. + **TranspilerError** – If dt and dtm is different in the backend. + -**Returns** + ### get -The InstructionDurations constructed from backend. + + Get the duration of the instruction with the name, qubits, and parameters. -**Return type** + Some instructions may have a parameter dependent duration. -InstructionDurations + **Parameters** -**Raises** + * **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")) – An instruction or its name to be queried. + * **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. + * **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. + * **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. -**TranspilerError** – If dt and dtm is different in the backend. + **Returns** -### get + The duration of the instruction on the qubits. - + **Return type** -`get(inst, qubits, unit='dt', parameters=None)` + float|int -Get the duration of the instruction with the name, qubits, and parameters. + **Raises** -Some instructions may have a parameter dependent duration. + **TranspilerError** – No duration is defined for the instruction. + -**Parameters** + ### units\_used -* **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.45)")) – An instruction or its name to be queried. -* **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. -* **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. -* **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. + + Get the set of all units used in this instruction durations. -**Returns** + **Return type** -The duration of the instruction on the qubits. + `set`\[`str`] -**Return type** + **Returns** -float|int + Set of units used in this instruction durations. + -**Raises** + ### update -**TranspilerError** – No duration is defined for the instruction. + + Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. -### units\_used + **Parameters** - + * **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)"), `None`]) – Instruction durations to be merged into self (overwriting self). + * **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. -`units_used()` + **Returns** -Get the set of all units used in this instruction durations. + The updated InstructionDurations. -**Return type** + **Return type** -`set`\[`str`] + InstructionDurations -**Returns** + **Raises** -Set of units used in this instruction durations. - -### update - - - -`update(inst_durations, dt=None)` - -Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. - -**Parameters** - -* **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)"), `None`]) – Instruction durations to be merged into self (overwriting self). -* **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. - -**Returns** - -The updated InstructionDurations. - -**Return type** - -InstructionDurations - -**Raises** - -**TranspilerError** – If the format of instruction\_durations is invalid. + **TranspilerError** – If the format of instruction\_durations is invalid. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx index c3d9557b397..a938a735e20 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx @@ -8,152 +8,140 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay # PadDelay - + + Padding idle time with Delay instructions. -`PadDelay(fill_very_end=True, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/pad_delay.py "view source code") + Consecutive delays will be merged in the output of this pass. -Padding idle time with Delay instructions. + The ASAP-scheduled circuit output may become -Consecutive delays will be merged in the output of this pass. + ```python + ┌────────────────┐ + q_0: ┤ Delay(160[dt]) ├──■── + └─────┬───┬──────┘┌─┴─┐ + q_1: ──────┤ X ├───────┤ X ├ + └───┘ └───┘ + ``` -The ASAP-scheduled circuit output may become + Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. -```python - ┌────────────────┐ -q_0: ┤ Delay(160[dt]) ├──■── - └─────┬───┬──────┘┌─┴─┐ -q_1: ──────┤ X ├───────┤ X ├ - └───┘ └───┘ -``` + See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. -Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. + Create new padding delay pass. -See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. + **Parameters** -Create new padding delay pass. + * **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -**Parameters** + ## Attributes -* **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx index b962ac9cc2b..62c635b5329 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx @@ -8,287 +8,275 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDe # PadDynamicalDecoupling - - -`PadDynamicalDecoupling(durations, dd_sequences, qubits=None, spacings=None, skip_reset_qubits=True, pulse_alignment=16, extra_slack_distribution='middle', sequence_min_length_ratios=None, insert_multiple_cycles=False, coupling_map=None, alt_spacings=None, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") - -Dynamical decoupling insertion pass for IBM dynamic circuit backends. - -This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). - -```python -import numpy as np -from qiskit.circuit import QuantumCircuit -from qiskit.circuit.library import XGate -from qiskit.transpiler import PassManager, InstructionDurations -from qiskit.visualization import timeline_drawer - -from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis -from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling - -circ = QuantumCircuit(4) -circ.h(0) -circ.cx(0, 1) -circ.cx(1, 2) -circ.cx(2, 3) -circ.measure_all() -durations = InstructionDurations( - [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), - ("cx", [1, 2], 200), ("cx", [2, 3], 300), - ("x", None, 50), ("measure", None, 1000)] -) -``` - -```python -# balanced X-X sequence on all qubits -dd_sequence = [XGate(), XGate()] -pm = PassManager([ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence)]) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌───────────────┐ ┌───┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» - ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» - ├────────────────┤ └───┘ ┌─┴─┐ » - q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» - └────────────────┘ └───┘ » -meas: 4/═════════════════════════════════════════════════════════» - » -« ┌────────────────┐ ┌───┐ ┌───────────────┐ » -« q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» -« └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» -« q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» -« └───┘ └───────────────┘ └───┘ └───────────────┘» -« q_2: ─────────────────────────────────────────────────────────────────────» -« » -« q_3: ─────────────────────────────────────────────────────────────────────» -« » -«meas: 4/═════════════════════════════════════════════════════════════════════» -« » -« ░ ┌─┐ -« q_0: ─░─┤M├───────── -« ░ └╥┘┌─┐ -« q_1: ─░──╫─┤M├────── -« ░ ║ └╥┘┌─┐ -« q_2: ─░──╫──╫─┤M├─── -« ░ ║ ║ └╥┘┌─┐ -« q_3: ─░──╫──╫──╫─┤M├ -« ░ ║ ║ ║ └╥┘ -«meas: 4/════╩══╩══╩══╩═ -« 0 1 2 3 -``` - -```python -# Uhrig sequence on qubit 0 -n = 8 -dd_sequence = [XGate()] * n -def uhrig_pulse_location(k): - return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 -spacings = [] -for k in range(n): - spacings.append(uhrig_pulse_location(k) - sum(spacings)) -spacings.append(1 - sum(spacings)) -pm = PassManager( - [ - ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), - ] -) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌────────────────┐ ░ ┌─┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» - ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» - ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» - q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» - └────────────────┘ └───┘ ░ ║ ║ ║ » -meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» - 0 1 2 » -« -« q_0: ─── -« -« q_1: ─── -« -« q_2: ─── -« ┌─┐ -« q_3: ┤M├ -« └╥┘ -«meas: 4/═╩═ -« 3 -``` + + Dynamical decoupling insertion pass for IBM dynamic circuit backends. + + This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + + ```python + import numpy as np + from qiskit.circuit import QuantumCircuit + from qiskit.circuit.library import XGate + from qiskit.transpiler import PassManager, InstructionDurations + from qiskit.visualization import timeline_drawer + + from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis + from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling + + circ = QuantumCircuit(4) + circ.h(0) + circ.cx(0, 1) + circ.cx(1, 2) + circ.cx(2, 3) + circ.measure_all() + durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] + ) + ``` + + ```python + # balanced X-X sequence on all qubits + dd_sequence = [XGate(), XGate()] + pm = PassManager([ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence)]) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌───────────────┐ ┌───┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» + ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» + ├────────────────┤ └───┘ ┌─┴─┐ » + q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» + └────────────────┘ └───┘ » + meas: 4/═════════════════════════════════════════════════════════» + » + « ┌────────────────┐ ┌───┐ ┌───────────────┐ » + « q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» + « └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» + « q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» + « └───┘ └───────────────┘ └───┘ └───────────────┘» + « q_2: ─────────────────────────────────────────────────────────────────────» + « » + « q_3: ─────────────────────────────────────────────────────────────────────» + « » + «meas: 4/═════════════════════════════════════════════════════════════════════» + « » + « ░ ┌─┐ + « q_0: ─░─┤M├───────── + « ░ └╥┘┌─┐ + « q_1: ─░──╫─┤M├────── + « ░ ║ └╥┘┌─┐ + « q_2: ─░──╫──╫─┤M├─── + « ░ ║ ║ └╥┘┌─┐ + « q_3: ─░──╫──╫──╫─┤M├ + « ░ ║ ║ ║ └╥┘ + «meas: 4/════╩══╩══╩══╩═ + « 0 1 2 3 + ``` + + ```python + # Uhrig sequence on qubit 0 + n = 8 + dd_sequence = [XGate()] * n + def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 + spacings = [] + for k in range(n): + spacings.append(uhrig_pulse_location(k) - sum(spacings)) + spacings.append(1 - sum(spacings)) + pm = PassManager( + [ + ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), + ] + ) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌────────────────┐ ░ ┌─┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» + ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» + ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» + q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» + └────────────────┘ └───┘ ░ ║ ║ ║ » + meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» + 0 1 2 » + « + « q_0: ─── + « + « q_1: ─── + « + « q_2: ─── + « ┌─┐ + « q_3: ┤M├ + « └╥┘ + «meas: 4/═╩═ + « 3 + ``` + + + You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. + + + Dynamical decoupling initializer. + + **Parameters** - - You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. - + * **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. -Dynamical decoupling initializer. + * **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. -**Parameters** + * **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). -* **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.45)")) – Durations of instructions to be used in scheduling. + * **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified -* **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.45)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. + * **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). -* **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). + * **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. -* **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified + * **extra\_slack\_distribution** (`str`) – -* **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). + The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. -* **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. + > * ”middle”: Put the extra slack to the interval at the middle of the sequence. + > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. -* **extra\_slack\_distribution** (`str`) – + * **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. - The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. + * **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. - > * ”middle”: Put the extra slack to the interval at the middle of the sequence. - > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. + * **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. -* **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. + * **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. -* **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -* **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.45)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. + **Raises** -* **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. + * **TranspilerError** – When invalid DD sequence is specified. + * **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. + * **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ## Attributes -**Raises** + ### is\_analysis\_pass -* **TranspilerError** – When invalid DD sequence is specified. -* **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. -* **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) + + Check if the pass is an analysis pass. -## Attributes + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + - + ### is\_transformation\_pass -### is\_analysis\_pass + + Check if the pass is a transformation pass. -Check if the pass is an analysis pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ## Methods - + ### \_\_call\_\_ -### is\_transformation\_pass + + Runs the pass on circuit. -Check if the pass is a transformation pass. + **Parameters** -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -## Methods + **Return type** -### \_\_call\_\_ + QuantumCircuit - + **Returns** -`__call__(circuit, property_set=None)` + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -Runs the pass on circuit. + ### execute -**Parameters** + + Execute optimization task for input Qiskit IR. -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + **Parameters** -**Return type** + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -QuantumCircuit + **Return type** -**Returns** + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Returns** -### execute + Optimized Qiskit IR and state of the workflow. + - + ### name -`execute(passmanager_ir, state, callback=None)` + + Name of the pass. -Execute optimization task for input Qiskit IR. + **Return type** -**Parameters** + `str` + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### run -**Return type** + + Run the padding pass on `dag`. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")] + **Parameters** -**Returns** + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. -Optimized Qiskit IR and state of the workflow. + **Returns** -### name + DAG with idle time filled with instructions. - + **Return type** -`name()` + DAGCircuit -Name of the pass. + **Raises** -**Return type** + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`str` + ### update\_status -### run + + Update workflow status. - + **Parameters** -`run(dag)` + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -Run the padding pass on `dag`. + **Return type** -**Parameters** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.45)")) – DAG to be checked. + **Returns** -**Returns** - -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.45)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.seconds_to_duration.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.seconds_to_duration.mdx index 7a7deac2b7f..b4573999979 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.seconds_to_duration.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.seconds_to_duration.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.seconds_to_duration # seconds\_to\_duration - + + Converts seconds in a datetime delta to a duration. -`seconds_to_duration(seconds)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Converts seconds in a datetime delta to a duration. + **seconds** (`float`) – Number of seconds in time delta. -**Parameters** + **Return type** -**seconds** (`float`) – Number of seconds in time delta. + `Tuple`\[`int`, `int`, `int`, `int`, `int`] -**Return type** + **Returns** -`Tuple`\[`int`, `int`, `int`, `int`, `int`] - -**Returns** - -A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.to_python_identifier.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.to_python_identifier.mdx index 174b09403a5..d68536cb14c 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.to_python_identifier.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.to_python_identifier.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.to_python_identifier # to\_python\_identifier - + + Convert a name to a valid Python identifier. -`to_python_identifier(name)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Convert a name to a valid Python identifier. + **name** (`str`) – Name to be converted. -**Parameters** + **Return type** -**name** (`str`) – Name to be converted. + `str` -**Return type** + **Returns** -`str` - -**Returns** - -Name that is a valid Python identifier. + Name that is a valid Python identifier. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.utc_to_local.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.utc_to_local.mdx index a65a4fdae2a..57b21b70b98 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.utc_to_local.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.utc_to_local.mdx @@ -10,25 +10,23 @@ python_api_name: qiskit_ibm_provider.utils.utc_to_local # utc\_to\_local - + + Convert a UTC `datetime` object or string to a local timezone `datetime`. -`utc_to_local(utc_dt)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Convert a UTC `datetime` object or string to a local timezone `datetime`. + **utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. -**Parameters** + **Return type** -**utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. + `datetime` -**Return type** + **Returns** -`datetime` + A `datetime` with the local timezone. -**Returns** + **Raises** -A `datetime` with the local timezone. - -**Raises** - -**TypeError** – If the input parameter value is not valid. + **TypeError** – If the input parameter value is not valid. + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.validate_job_tags.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.validate_job_tags.mdx index 471ccb866aa..3a034f98595 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.validate_job_tags.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.utils.validate_job_tags.mdx @@ -10,22 +10,20 @@ python_api_name: qiskit_ibm_provider.utils.validate_job_tags # validate\_job\_tags - + + Validates input job tags. -`validate_job_tags(job_tags, exception)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Validates input job tags. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. + * **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. -**Parameters** + **Raises** -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. -* **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. + **Exception** – If the job tags are invalid. -**Raises** + **Return type** -**Exception** – If the job tags are invalid. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_error_map.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_error_map.mdx index 10c1c78914a..d16d35c8303 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_error_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_error_map.mdx @@ -10,43 +10,41 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_error_map # iplot\_error\_map - + + Plot the error map of a device. -`iplot_error_map(backend, figsize=(800, 500), show_title=True, remove_badcal_edges=True, background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/visualization/interactive/error_map.py "view source code") + **Parameters** -Plot the error map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. + * **figsize** (`Tuple`\[`int`]) – Figure size in pixels. + * **show\_title** (`bool`) – Whether to show figure title. + * **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. + * **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. -* **figsize** (`Tuple`\[`int`]) – Figure size in pixels. -* **show\_title** (`bool`) – Whether to show figure title. -* **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. -* **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The error map figure. -**Returns** + **Raises** -The error map figure. + * **VisualizationValueError** – If an invalid input is received. + * **VisualizationTypeError** – If the specified backend is a simulator. -**Raises** + **Example** -* **VisualizationValueError** – If an invalid input is received. -* **VisualizationTypeError** – If the specified backend is a simulator. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_error_map -**Example** + provider = IBMProvider(group='open', project='main') + backend = provider.get_backend('ibmq_vigo') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_error_map - -provider = IBMProvider(group='open', project='main') -backend = provider.get_backend('ibmq_vigo') - -iplot_error_map(backend, as_widget=True) -``` + iplot_error_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_gate_map.mdx b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_gate_map.mdx index 3094345f11c..34ba43a4931 100644 --- a/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_gate_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.8/qiskit_ibm_provider.visualization.iplot_gate_map.mdx @@ -10,44 +10,42 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_gate_map # iplot\_gate\_map - + + Plots an interactive gate map of a device. -`iplot_gate_map(backend, figsize=(None, None), label_qubits=True, qubit_size=None, line_width=None, font_size=None, qubit_color='#2f4b7c', qubit_labels=None, line_color='#2f4b7c', font_color='white', background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.8/qiskit_ibm_provider/visualization/interactive/gate_map.py "view source code") + **Parameters** -Plots an interactive gate map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. + * **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. + * **label\_qubits** (`bool`) – Labels for the qubits. + * **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. + * **line\_width** (`Optional`\[`float`]) – Width of lines. + * **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. + * **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. + * **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels + * **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. + * **font\_color** (`str`) – The font color for the qubit labels. + * **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. -* **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. -* **label\_qubits** (`bool`) – Labels for the qubits. -* **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. -* **line\_width** (`Optional`\[`float`]) – Width of lines. -* **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. -* **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. -* **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels -* **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. -* **font\_color** (`str`) – The font color for the qubit labels. -* **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The gate map figure. -**Returns** + **Example** -The gate map figure. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_gate_map -**Example** + provider = IBMProvider(group='open', project='main') + backend = provider.get_backend('ibmq_vigo') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_gate_map - -provider = IBMProvider(group='open', project='main') -backend = provider.get_backend('ibmq_vigo') - -iplot_gate_map(backend, as_widget=True) -``` + iplot_gate_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/0.9/ibm_utils.mdx b/docs/api/qiskit-ibm-provider/0.9/ibm_utils.mdx index 0fe6f58e4fd..8c78a6b1e82 100644 --- a/docs/api/qiskit-ibm-provider/0.9/ibm_utils.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/ibm_utils.mdx @@ -42,73 +42,61 @@ Utility functions related to the IBM Quantum Provider. Message broker for the Publisher / Subscriber mechanism - + + Represents a “publisher”. -`Publisher` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/pubsub.py "view source code") + Every component (class) can become a [`Publisher`](#qiskit_ibm_provider.utils.pubsub.Publisher "qiskit_ibm_provider.utils.pubsub.Publisher") and send events by inheriting this class. Functions can call this class like: -Represents a “publisher”. + ```python + Publisher().publish("event", args, ... ) + ``` -Every component (class) can become a [`Publisher`](#qiskit_ibm_provider.utils.pubsub.Publisher "qiskit_ibm_provider.utils.pubsub.Publisher") and send events by inheriting this class. Functions can call this class like: + ### publish -```python -Publisher().publish("event", args, ... ) -``` + + Triggers an event, and associates some data to it, so if there are any subscribers, their callback will be called synchronously. -### publish + **Return type** - + `None` + + -`publish(event, *args, **kwargs)` + + Represents a “subscriber”. -Triggers an event, and associates some data to it, so if there are any subscribers, their callback will be called synchronously. + Every component (class) can become a [`Subscriber`](#qiskit_ibm_provider.utils.pubsub.Subscriber "qiskit_ibm_provider.utils.pubsub.Subscriber") and subscribe to events, that will call callback functions when they are emitted. -**Return type** + ### clear -`None` + + Unsubscribe everything - + **Return type** -`Subscriber` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/pubsub.py "view source code") + `None` + -Represents a “subscriber”. + ### subscribe -Every component (class) can become a [`Subscriber`](#qiskit_ibm_provider.utils.pubsub.Subscriber "qiskit_ibm_provider.utils.pubsub.Subscriber") and subscribe to events, that will call callback functions when they are emitted. + + Subscribes to an event, associating a callback function to that event, so when the event occurs, the callback will be called. -### clear + This is a blocking call, so try to keep callbacks as lightweight as possible. - + **Return type** -`clear()` + `bool` + -Unsubscribe everything + ### unsubscribe -**Return type** + + Unsubscribe a pair event-callback, so the callback will not be called anymore when the event occurs. -`None` + **Return type** -### subscribe - - - -`subscribe(event, callback)` - -Subscribes to an event, associating a callback function to that event, so when the event occurs, the callback will be called. - -This is a blocking call, so try to keep callbacks as lightweight as possible. - -**Return type** - -`bool` - -### unsubscribe - - - -`unsubscribe(event, callback)` - -Unsubscribe a pair event-callback, so the callback will not be called anymore when the event occurs. - -**Return type** - -`bool` + `bool` + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackend.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackend.mdx index 57e7b5e90a5..eda66746482 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackend.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackend.mdx @@ -8,657 +8,619 @@ python_api_name: qiskit_ibm_provider.IBMBackend # IBMBackend - + + Backend class interfacing with an IBM Quantum device. -`IBMBackend(configuration, provider, api_client, instance=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/ibm_backend.py "view source code") + You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: -Backend class interfacing with an IBM Quantum device. + ```python + from qiskit import transpile + from qiskit_ibm_provider import IBMProvider + from qiskit.circuit.random import random_circuit -You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: + provider = IBMProvider() + backend = provider.backend.ibmq_vigo + qx = random_circuit(n_qubits=5, depth=4) + transpiled = transpile(qx, backend=backend) + job = backend.run(transpiled) + retrieved_job = provider.backend.retrieve_job(job.job_id()) + ``` -```python -from qiskit import transpile -from qiskit_ibm_provider import IBMProvider -from qiskit.circuit.random import random_circuit + + * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. + * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. + -provider = IBMProvider() -backend = provider.backend.ibmq_vigo -qx = random_circuit(n_qubits=5, depth=4) -transpiled = transpile(qx, backend=backend) -job = backend.run(transpiled) -retrieved_job = provider.backend.retrieve_job(job.job_id()) -``` + Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: - - * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. - * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. - + ```python + status = backend.status() + is_operational = status.operational + jobs_in_queue = status.pending_jobs + ``` -Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: + **Here is list of attributes available on the `IBMBackend` class:** -```python -status = backend.status() -is_operational = status.operational -jobs_in_queue = status.pending_jobs -``` + * name: backend name. -**Here is list of attributes available on the `IBMBackend` class:** + * backend\_version: backend version in the form X.Y.Z. -* name: backend name. + * num\_qubits: number of qubits. -* backend\_version: backend version in the form X.Y.Z. + * target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. -* num\_qubits: number of qubits. + * basis\_gates: list of basis gates names on the backend. -* target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. + * gates: list of basis gates on the backend. -* basis\_gates: list of basis gates names on the backend. + * local: backend is local or remote. -* gates: list of basis gates on the backend. + * simulator: backend is a simulator. -* local: backend is local or remote. + * conditional: backend supports conditional operations. -* simulator: backend is a simulator. + * open\_pulse: backend supports open pulse. -* conditional: backend supports conditional operations. + * memory: backend supports memory. -* open\_pulse: backend supports open pulse. + * max\_shots: maximum number of shots supported. -* memory: backend supports memory. + * coupling\_map (list): The coupling map for the device -* max\_shots: maximum number of shots supported. + * supported\_instructions (List\[str]): Instructions supported by the backend. -* coupling\_map (list): The coupling map for the device + * dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. -* supported\_instructions (List\[str]): Instructions supported by the backend. + * rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. -* dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + * default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. -* rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + * n\_uchannels: Number of u-channels. -* default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + * u\_channel\_lo: U-channel relationship on device los. -* n\_uchannels: Number of u-channels. + * meas\_levels: Supported measurement levels. -* u\_channel\_lo: U-channel relationship on device los. + * qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. -* meas\_levels: Supported measurement levels. + * meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. -* qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. + * dt: Qubit drive channel timestep in nanoseconds. -* meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. + * dtm: Measurement drive channel timestep in nanoseconds. -* dt: Qubit drive channel timestep in nanoseconds. + * rep\_times: Supported repetition times (program execution time) for backend in μs. -* dtm: Measurement drive channel timestep in nanoseconds. + * meas\_kernels: Supported measurement kernels. -* rep\_times: Supported repetition times (program execution time) for backend in μs. + * discriminators: Supported discriminators. -* meas\_kernels: Supported measurement kernels. + * hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. -* discriminators: Supported discriminators. + * channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) -* hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. + * acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. -* channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) + * conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m -* acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. + * meas\_map (list): Grouping of measurement which are multiplexed -* conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m + * max\_circuits (int): The maximum number of experiments per job -* meas\_map (list): Grouping of measurement which are multiplexed + * sample\_name (str): Sample name for the backend -* max\_circuits (int): The maximum number of experiments per job + * n\_registers (int): Number of register slots available for feedback (if conditional is True) -* sample\_name (str): Sample name for the backend + * register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. -* n\_registers (int): Number of register slots available for feedback (if conditional is True) + * configurable (bool): True if the backend is configurable, if the backend is a simulator -* register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + * credits\_required (bool): True if backend requires credits to run a job. -* configurable (bool): True if the backend is configurable, if the backend is a simulator + * online\_date (datetime): The date that the device went online -* credits\_required (bool): True if backend requires credits to run a job. + * display\_name (str): Alternate name field for the backend -* online\_date (datetime): The date that the device went online + * description (str): A description for the backend -* display\_name (str): Alternate name field for the backend + * tags (list): A list of string tags to describe the backend -* description (str): A description for the backend + * version: version of `Backend` class (Ex: 1, 2) -* tags (list): A list of string tags to describe the backend + * channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. -* version: version of `Backend` class (Ex: 1, 2) + * parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` -* channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. + * processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. -* parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + > * family: Processor family of this backend. + > * revision: Revision version of this processor. + > * segment: Segment this processor belongs to within a larger chip. -* processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + IBMBackend constructor. - > * family: Processor family of this backend. - > * revision: Revision version of this processor. - > * segment: Segment this processor belongs to within a larger chip. + **Parameters** -IBMBackend constructor. + * **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.46)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.46)")]) – Backend configuration. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. -**Parameters** + ## Attributes -* **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.46)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.46)")]) – Backend configuration. -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. + ### coupling\_map -## Attributes + + Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.46)") object + - + ### dt -### coupling\_map + + Return the system time resolution of input signals -Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.46)") object + This is required to be implemented if the backend supports Pulse scheduling. - + **Return type** -### dt + `Optional`\[`float`] -Return the system time resolution of input signals + **Returns** -This is required to be implemented if the backend supports Pulse scheduling. + The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + -**Return type** + ### dtm -`Optional`\[`float`] + + Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + -**Returns** + ### id\_warning\_issued -The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + - + ### instruction\_durations -### dtm + + Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)") object. + -Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + ### instruction\_schedule\_map - + + Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.46)") for the instructions defined in this backend’s target. + -### id\_warning\_issued + ### instructions -`= False` + + A list of Instruction tuples on the backend of the form `(instruction, (qubits)` - + **Return type** -### instruction\_durations + `List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)"), `Tuple`\[`int`]]] + -Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)") object. + ### max\_circuits - + + The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. -### instruction\_schedule\_map + **Return type** -Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v0.46)") for the instructions defined in this backend’s target. + `int` + - + ### meas\_map -### instructions + + Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + -A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + ### num\_qubits -**Return type** + + Return the number of qubits the backend has. -`List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)"), `Tuple`\[`int`]]] + **Return type** - + `int` + -### max\_circuits + ### operation\_names -The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. + + A list of instruction names that the backend supports. -**Return type** + **Return type** -`int` + `List`\[`str`] + - + ### operations -### meas\_map + + A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)") instances that the backend supports. -Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + **Return type** - + `List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)")] + -### num\_qubits + ### options -Return the number of qubits the backend has. + + Return the options for the backend -**Return type** + The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + -`int` + ### provider - + + Return the backend Provider. -### operation\_names + **Returns** -A list of instruction names that the backend supports. + the Provider responsible for the backend. -**Return type** + **Return type** -`List`\[`str`] + Provider + - + ### session -### operations + + Return session -A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)") instances that the backend supports. + **Return type** -**Return type** + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -`List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)")] + ### target - + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") :returns: Target + -### options + ### version -Return the options for the backend + -The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + ### name - + + Name of the backend. + -### provider + ### description -Return the backend Provider. + + Optional human-readable description. + -**Returns** + ### online\_date -the Provider responsible for the backend. + + Date that the backend came online. + -**Return type** + ### backend\_version -Provider + + Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + - + ## Methods -### session + ### acquire\_channel -Return session + + Return the acquisition channel for the given qubit. -**Return type** + **Returns** -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + The Qubit measurement acquisition line. - + **Return type** -### target + AcquireChannel + -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") :returns: Target + ### cancel\_session - + + Cancel session. All pending jobs will be cancelled. -### version + **Return type** -`= 2` + `None` + - + ### close\_session -### name + + Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. -Name of the backend. + **Return type** - + `None` + -### description + ### configuration -Optional human-readable description. + + Return the backend configuration. - + Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. -### online\_date + The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). -Date that the backend came online. + **Return type** - + `Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.46)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.46)")] -### backend\_version + **Returns** -Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + The configuration for the backend. + -## Methods + ### control\_channel -### acquire\_channel + + Return the secondary drive channel for the given qubit. - + This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. -`acquire_channel(qubit)` + **Parameters** -Return the acquisition channel for the given qubit. + **qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. -**Returns** + **Returns** -The Qubit measurement acquisition line. + The Qubit measurement acquisition line. -**Return type** + **Return type** -AcquireChannel + List\[ControlChannel] + -### cancel\_session + ### defaults - + + Return the pulse defaults for the backend. -`cancel_session()` + The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). -Cancel session. All pending jobs will be cancelled. + **Parameters** -**Return type** + **refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. -`None` + **Return type** -### close\_session + `Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.46)")] - + **Returns** -`close_session()` + The backend pulse defaults or `None` if the backend does not support pulse. + -Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. + ### drive\_channel -**Return type** + + Return the drive channel for the given qubit. -`None` + **Returns** -### configuration + The Qubit drive channel - + **Return type** -`configuration()` + DriveChannel + -Return the backend configuration. + ### get\_translation\_stage\_plugin -Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. + + Return the default translation stage plugin name for IBM backends. -The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). + **Return type** -**Return type** + `str` + -`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v0.46)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v0.46)")] + ### measure\_channel -**Returns** + + Return the measure stimulus channel for the given qubit. -The configuration for the backend. + **Returns** -### control\_channel + The Qubit measurement stimulus line - + **Return type** -`control_channel(qubits)` + MeasureChannel + -Return the secondary drive channel for the given qubit. + ### open\_session -This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + + Open session -**Parameters** + **Return type** -**qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -**Returns** + ### properties -The Qubit measurement acquisition line. + + Return the backend properties, subject to optional filtering. -**Return type** + This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. -List\[ControlChannel] + The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). -### defaults + **Parameters** - + * **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + * **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)") whose timestamp is closest to, but older than, the specified datetime. -`defaults(refresh=False)` + **Return type** -Return the pulse defaults for the backend. + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")] -The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). + **Returns** -**Parameters** + The backend properties or `None` if the backend properties are not currently available. -**refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. + **Raises** -**Return type** + **TypeError** – If an input argument is not of the correct type. + -`Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v0.46)")] + ### qubit\_properties -**Returns** + + Return QubitProperties for a given qubit. -The backend pulse defaults or `None` if the backend does not support pulse. + If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. -### drive\_channel + **Parameters** - + **qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order -`drive_channel(qubit)` + **Return type** -Return the drive channel for the given qubit. + `Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.46)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.46)")]] -**Returns** + **Returns** -The Qubit drive channel + The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. -**Return type** + **Raises** -DriveChannel + **NotImplementedError** – if the backend doesn’t support querying the qubit properties + -### get\_translation\_stage\_plugin + ### run - + + Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. -`classmethod get_translation_stage_plugin()` + **Parameters** -Return the default translation stage plugin name for IBM backends. + * **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)"), `str`]]]) – An individual or a list of `QuantumCircuit`. -**Return type** + * **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) -`str` + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. -### measure\_channel + * **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - + * **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. -`measure_channel(qubit)` + * **or** (*The following parameters are applicable only if dynamic=False is specified*) – -Return the measure stimulus channel for the given qubit. + * **to.** (*defaulted*) – -**Returns** + * **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. -The Qubit measurement stimulus line + * **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. -**Return type** + * **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. -MeasureChannel + * **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – -### open\_session + Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - + * `0`, measurements of the raw signal (the measurement output pulse envelope) + * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) + * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) -`open_session(max_time=None)` + * **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – -Open session + Level of measurement data for the backend to return. For `meas_level` 0 and 1: -**Return type** + * `single` returns information from every shot. + * `avg` returns average measurement output (averaged over number of shots). -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + * **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. -### properties + * **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - + * **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. -`properties(refresh=False, datetime=None)` + * **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) -Return the backend properties, subject to optional filtering. + * **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) -This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. + * **\*\*run\_config** – Extra arguments used to configure the run. -The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). + **Return type** -**Parameters** + `IBMJob` -* **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. -* **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)") whose timestamp is closest to, but older than, the specified datetime. + **Returns** -**Return type** + The job to be executed. -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")] + **Raises** -**Returns** + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. -The backend properties or `None` if the backend properties are not currently available. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. -**Raises** + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – -**TypeError** – If an input argument is not of the correct type. + * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. + -### qubit\_properties + ### set\_options - + + Set the options fields for the backend -`qubit_properties(qubit)` + This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. -Return QubitProperties for a given qubit. + **Parameters** -If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + **fields** – The fields to update the options -**Parameters** + **Raises** -**qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order + **AttributeError** – If the field passed in is not part of the options + -**Return type** + ### status -`Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.46)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v0.46)")]] + + Return the backend status. -**Returns** + + If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. + -The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + **Return type** -**Raises** + [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") -**NotImplementedError** – if the backend doesn’t support querying the qubit properties + **Returns** -### run + The status of the backend. - + **Raises** -`run(circuits, dynamic=None, job_tags=None, init_circuit=None, init_num_resets=None, header=None, shots=None, memory=None, meas_level=None, meas_return=None, rep_delay=None, init_qubits=None, use_measure_esp=None, noise_model=None, seed_simulator=None, **run_config)` + [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. + -Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. + ### target\_history -**Parameters** - -* **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)"), `str`]]]) – An individual or a list of `QuantumCircuit`. - -* **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) - -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. - -* **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - -* **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. - -* **or** (*The following parameters are applicable only if dynamic=False is specified*) – - -* **to.** (*defaulted*) – - -* **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. - -* **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. - -* **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. - -* **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – - - Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - - * `0`, measurements of the raw signal (the measurement output pulse envelope) - * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) - * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) - -* **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – - - Level of measurement data for the backend to return. For `meas_level` 0 and 1: - - * `single` returns information from every shot. - * `avg` returns average measurement output (averaged over number of shots). - -* **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. - -* **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - -* **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. - -* **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) - -* **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) - -* **\*\*run\_config** – Extra arguments used to configure the run. - -**Return type** - -`IBMJob` - -**Returns** - -The job to be executed. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. - -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. - -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – - - * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. - -### set\_options - - - -`set_options(**fields)` - -Set the options fields for the backend - -This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. - -**Parameters** - -**fields** – The fields to update the options - -**Raises** - -**AttributeError** – If the field passed in is not part of the options - -### status - - - -`status()` - -Return the backend status. - - - If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. - - -**Return type** - -[`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v0.46)") - -**Returns** - -The status of the backend. - -**Raises** - -[**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. - -### target\_history - - - -`target_history(datetime=None)` - -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") :returns: Target with properties found on datetime + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)") :returns: Target with properties found on datetime + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiError.mdx index bee60588b58..b1e927bc783 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiError # IBMBackendApiError - + + Errors that occur unexpectedly when querying the server. -`IBMBackendApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx index f061d96df0f..e73a1b0ca8a 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiProtocolError # IBMBackendApiProtocolError - + + Errors raised when an unexpected value is received from the server. -`IBMBackendApiProtocolError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Errors raised when an unexpected value is received from the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendError.mdx index 978751e8c9c..c596d8593d6 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendError # IBMBackendError - + + Base class for errors raised by the backend modules. -`IBMBackendError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendService.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendService.mdx index 5ea2323b570..c62321fa670 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendService.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendService.mdx @@ -8,161 +8,153 @@ python_api_name: qiskit_ibm_provider.IBMBackendService # IBMBackendService - + + Backend namespace for an IBM Quantum account. -`IBMBackendService(provider, hgp)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/ibm_backend_service.py "view source code") + Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: -Backend namespace for an IBM Quantum account. + ```python + backends = provider.backends() # Invoke backends() to get the backends. + sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. + ``` -Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: + Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: -```python -backends = provider.backends() # Invoke backends() to get the backends. -sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. -``` + ```python + most_recent_jobs = provider.backend.jobs(limit=10) + ``` -Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: + It is also possible to retrieve a single job without specifying the backend name: -```python -most_recent_jobs = provider.backend.jobs(limit=10) -``` + ```python + job = provider.backend.retrieve_job() + ``` -It is also possible to retrieve a single job without specifying the backend name: + IBMBackendService constructor. -```python -job = provider.backend.retrieve_job() -``` + **Parameters** -IBMBackendService constructor. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. -**Parameters** + ## Methods -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. + ### backends -## Methods + + Return all backends accessible via this account, subject to optional filtering. -### backends + **Parameters** - + * **name** (`Optional`\[`str`]) – Backend name to filter by. -`backends(name=None, filters=None, min_num_qubits=None, instance=None, dynamic_circuits=None, **kwargs)` + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -Return all backends accessible via this account, subject to optional filtering. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -**Parameters** + * **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. -* **name** (`Optional`\[`str`]) – Backend name to filter by. + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + More complex filters, such as lambda functions. For example: -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -* **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. + * **\*\*kwargs** – -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. - More complex filters, such as lambda functions. For example: + Examples: - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **\*\*kwargs** – + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. + **Return type** - Examples: + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Returns** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + The list of available backends that match the filter. -**Return type** + **Raises** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. + * **QiskitBackendNotFoundError** – If the backend is not found in any instance. + -**Returns** + ### jobs -The list of available backends that match the filter. + + Return a list of jobs, subject to optional filtering. -**Raises** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. -* **QiskitBackendNotFoundError** – If the backend is not found in any instance. + **Parameters** -### jobs + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by + * **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. + * **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – - + **Return type** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + `List`\[`IBMJob`] -Return a list of jobs, subject to optional filtering. + **Returns** -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + A list of `IBMJob` instances. -**Parameters** + **Raises** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by -* **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. -* **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. + * **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + -**Return type** + ### retrieve\_job -`List`\[`IBMJob`] + + Return a single job. -**Returns** + **Parameters** -A list of `IBMJob` instances. + **job\_id** (`str`) – The ID of the job to retrieve. -**Raises** + **Return type** -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. -* **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + `IBMJob` -### retrieve\_job + **Returns** - + The job with the given id. -`retrieve_job(job_id)` + **Raises** -Return a single job. - -**Parameters** - -**job\_id** (`str`) – The ID of the job to retrieve. - -**Return type** - -`IBMJob` - -**Returns** - -The job with the given id. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. -* **IBMJobNotFoundError** – If job cannot be found. -* **IBMInputValueError** – If job exists but was run from a different service. + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. + * **IBMJobNotFoundError** – If job cannot be found. + * **IBMInputValueError** – If job exists but was run from a different service. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendValueError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendValueError.mdx index a4744ab196f..05576e86170 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMBackendValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendValueError # IBMBackendValueError - + + Value errors raised by the backend modules. -`IBMBackendValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMError.mdx index 182017829e5..35a8c9193d8 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMError # IBMError - + + Base class for errors raised by the provider modules. -`IBMError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raised by the provider modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProvider.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProvider.mdx index a9621931eaf..b37967f39eb 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProvider.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProvider.mdx @@ -8,355 +8,333 @@ python_api_name: qiskit_ibm_provider.IBMProvider # IBMProvider - + + Provides access to the IBM Quantum services available to an account. -`IBMProvider(token=None, url=None, name=None, instance=None, proxies=None, verify=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/ibm_provider.py "view source code") + Authenticate against IBM Quantum for use from saved credentials or during session. -Provides access to the IBM Quantum services available to an account. + Credentials can be saved to disk by calling the save\_account() method: -Authenticate against IBM Quantum for use from saved credentials or during session. + ```python + from qiskit_ibm_provider import IBMProvider + IBMProvider.save_account(token=) + ``` -Credentials can be saved to disk by calling the save\_account() method: + You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: -```python -from qiskit_ibm_provider import IBMProvider -IBMProvider.save_account(token=) -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: + Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: + You can also enable an account just for the current session by instantiating the provider with the API token: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider(token=) + ``` -You can also enable an account just for the current session by instantiating the provider with the API token: + token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider(token=) -``` + + The hub/group/project is selected based on the below selection order, in decreasing order of priority. -token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. + * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. + * The hub/group/project required for the service. + * The default hub/group/project you set using save\_account(). + * A premium hub/group/project in your account. + * An open access hub/group/project. + - - The hub/group/project is selected based on the below selection order, in decreasing order of priority. + The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. - * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. - * The hub/group/project required for the service. - * The default hub/group/project you set using save\_account(). - * A premium hub/group/project in your account. - * An open access hub/group/project. - + You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: -The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. + ```python + backend_service = provider.backend + ``` -You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: + Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. -```python -backend_service = provider.backend -``` + The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: -Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. + ```python + backends = provider.backends() + ``` -The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: + The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: -```python -backends = provider.backends() -``` + ```python + simulator_backend = provider.get_backend('ibmq_qasm_simulator') + ``` -The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: + IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. -```python -simulator_backend = provider.get_backend('ibmq_qasm_simulator') -``` + It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: -IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. + ```python + simulator_backend = provider.backend.ibmq_qasm_simulator + ``` -It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: + + The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. + -```python -simulator_backend = provider.backend.ibmq_qasm_simulator -``` + IBMProvider constructor - - The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. - + **Parameters** -IBMProvider constructor + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). + * **name** (`Optional`\[`str`]) – Name of the account to load. + * **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. -**Parameters** + **Returns** -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). -* **name** (`Optional`\[`str`]) – Name of the account to load. -* **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. + An instance of IBMProvider -**Returns** + **Raises** -An instance of IBMProvider + **IBMInputValueError** – If an input is invalid. -**Raises** + ## Attributes -**IBMInputValueError** – If an input is invalid. + ### backend -## Attributes + + Return the backend service. - + **Return type** -### backend + [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") -Return the backend service. + **Returns** -**Return type** + The backend service instance. + -[`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") + ### version -**Returns** + -The backend service instance. + ## Methods - + ### active\_account -### version + + Return the IBM Quantum account currently in use for the session. -`= 1` + **Return type** -## Methods + `Optional`\[`Dict`\[`str`, `str`]] -### active\_account + **Returns** - + A dictionary with information about the account currently in the session. + -`active_account()` + ### backends -Return the IBM Quantum account currently in use for the session. + + Return all backends accessible via this account, subject to optional filtering. -**Return type** + **Parameters** -`Optional`\[`Dict`\[`str`, `str`]] + * **name** (`Optional`\[`str`]) – Backend name to filter by. -**Returns** + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -A dictionary with information about the account currently in the session. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -### backends + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – - + More complex filters, such as lambda functions. For example: -`backends(name=None, filters=None, min_num_qubits=None, instance=None, **kwargs)` + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -Return all backends accessible via this account, subject to optional filtering. + * **\*\*kwargs** – -**Parameters** + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: -* **name** (`Optional`\[`str`]) – Backend name to filter by. + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + **Return type** -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - More complex filters, such as lambda functions. For example: + **Returns** - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + The list of available backends that match the filter. + -* **\*\*kwargs** – + ### delete\_account - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: + + Delete a saved account from disk. - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Parameters** - For the full list of backend attributes, see the IBMBackend class documentation \<[providers\_models](/api/qiskit/providers_models)> + **name** (`Optional`\[`str`]) – Name of the saved account to delete. -**Return type** + **Return type** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + `bool` -**Returns** + **Returns** -The list of available backends that match the filter. + True if the account was deleted. False if no account was found. + -### delete\_account + ### get\_backend - + + Return a single backend matching the specified filtering. -`static delete_account(name=None)` + **Parameters** -Delete a saved account from disk. + * **name** (*str*) – Name of the backend. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **\*\*kwargs** – Dict used for filtering. -**Parameters** + **Returns** -**name** (`Optional`\[`str`]) – Name of the saved account to delete. + a backend matching the filtering. -**Return type** + **Return type** -`bool` + Backend -**Returns** + **Raises** -True if the account was deleted. False if no account was found. + * **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. + * [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + -### get\_backend + ### instances - + + Return the IBM Quantum instances list currently in use for the session. -`get_backend(name=None, instance=None, **kwargs)` + **Return type** -Return a single backend matching the specified filtering. + `List`\[`str`] -**Parameters** + **Returns** -* **name** (*str*) – Name of the backend. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **\*\*kwargs** – Dict used for filtering. + A list with instances currently in the session. + -**Returns** + ### jobs -a backend matching the filtering. + + Return a list of jobs, subject to optional filtering. -**Return type** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -Backend + **Parameters** -**Raises** + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – -* **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. -* [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + **Return type** -### instances + `List`\[`IBMJob`] - + **Returns** -`instances()` + A list of `IBMJob` instances. + -Return the IBM Quantum instances list currently in use for the session. + ### retrieve\_job -**Return type** + + Return a single job. -`List`\[`str`] + **Parameters** -**Returns** + **job\_id** (`str`) – The ID of the job to retrieve. -A list with instances currently in the session. + **Return type** -### jobs + `IBMJob` - + **Returns** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` + The job with the given id. + -Return a list of jobs, subject to optional filtering. + ### save\_account -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + + Save the account to disk for future use. -**Parameters** + **Parameters** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) + * **instance** (`Optional`\[`str`]) – The hub/group/project. + * **name** (`Optional`\[`str`]) – Name of the account to save. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. + * **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. -**Return type** + **Return type** -`List`\[`IBMJob`] + `None` + -**Returns** + ### saved\_accounts -A list of `IBMJob` instances. + + List the accounts saved on disk. -### retrieve\_job + **Parameters** - + * **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. + * **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. -`retrieve_job(job_id)` + **Return type** -Return a single job. + `dict` -**Parameters** + **Returns** -**job\_id** (`str`) – The ID of the job to retrieve. + A dictionary with information about the accounts saved on disk. -**Return type** + **Raises** -`IBMJob` - -**Returns** - -The job with the given id. - -### save\_account - - - -`static save_account(token=None, url=None, instance=None, name=None, proxies=None, verify=None, overwrite=False)` - -Save the account to disk for future use. - -**Parameters** - -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) -* **instance** (`Optional`\[`str`]) – The hub/group/project. -* **name** (`Optional`\[`str`]) – Name of the account to save. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. -* **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. - -**Return type** - -`None` - -### saved\_accounts - - - -`static saved_accounts(default=None, name=None)` - -List the accounts saved on disk. - -**Parameters** - -* **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. -* **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. - -**Return type** - -`dict` - -**Returns** - -A dictionary with information about the accounts saved on disk. - -**Raises** - -**ValueError** – If an invalid account is found on disk. + **ValueError** – If an invalid account is found on disk. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderError.mdx index 80905b796f1..211cd66d16c 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderError # IBMProviderError - + + Base class for errors raise by IBMProvider. -`IBMProviderError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Base class for errors raise by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderValueError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderValueError.mdx index d26360180d9..5ff68367323 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderValueError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.IBMProviderValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderValueError # IBMProviderValueError - + + Value errors raised by IBMProvider. -`IBMProviderValueError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/exceptions.py "view source code") - -Value errors raised by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.Session.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.Session.mdx index c4160b94f88..25324448a32 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.Session.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.Session.mdx @@ -8,85 +8,81 @@ python_api_name: qiskit_ibm_provider.Session # Session - + + Class for creating a flexible Qiskit Runtime session. -`Session(max_time=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/session.py "view source code") + A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. -Class for creating a flexible Qiskit Runtime session. + You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. -A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. + **For example::** -You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. + from qiskit\_ibm\_provider import IBMProvider -**For example::** + \# Bell Circuit qr = QuantumRegister(2, name=”qr”) cr = ClassicalRegister(2, name=”cr”) qc = QuantumCircuit(qr, cr, name=”bell”) qc.h(qr\[0]) qc.cx(qr\[0], qr\[1]) qc.measure(qr, cr) -from qiskit\_ibm\_provider import IBMProvider + backend = IBMProvider().get\_backend(“ibmq\_qasm\_simulator”) backend.open\_session() -\# Bell Circuit qr = QuantumRegister(2, name=”qr”) cr = ClassicalRegister(2, name=”cr”) qc = QuantumCircuit(qr, cr, name=”bell”) qc.h(qr\[0]) qc.cx(qr\[0], qr\[1]) qc.measure(qr, cr) + job = backend.run(qc) print(f”Job ID: \{job.job\_id()}”) print(f”Result: \{job.result()}”) # Close the session only if all jobs are finished and # you don’t need to run more in the session. backend.cancel\_session() -backend = IBMProvider().get\_backend(“ibmq\_qasm\_simulator”) backend.open\_session() + Session can also be used as a context manager: -job = backend.run(qc) print(f”Job ID: \{job.job\_id()}”) print(f”Result: \{job.result()}”) # Close the session only if all jobs are finished and # you don’t need to run more in the session. backend.cancel\_session() + ```python + with backend.open_session() as session: + job = backend.run(qc) + assert job.job_id() == session.session_id + ``` -Session can also be used as a context manager: + Session constructor. -```python -with backend.open_session() as session: - job = backend.run(qc) - assert job.job_id() == session.session_id -``` + **Parameters** -Session constructor. + **max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). -**Parameters** + **Raises** -**max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/faqs/max_execution_time.html). + **ValueError** – If an input value is invalid. -**Raises** + ## Attributes -**ValueError** – If an input value is invalid. + ### active -## Attributes + + Return the status of the session. - + **Return type** -### active + `bool` -Return the status of the session. + **Returns** -**Return type** + True if the session is active, False otherwise. + -`bool` + ### session\_id -**Returns** + + Return the session ID. -True if the session is active, False otherwise. + **Return type** - + `str` -### session\_id + **Returns** -Return the session ID. + Session ID. None until a job runs in the session. + -**Return type** + ## Methods -`str` + ### cancel -**Returns** + + Set the session.\_active status to False -Session ID. None until a job runs in the session. + **Return type** -## Methods - -### cancel - - - -`cancel()` - -Set the session.\_active status to False - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCircuitJob.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCircuitJob.mdx index f776c3c7a59..4180741fd19 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCircuitJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCircuitJob.mdx @@ -8,606 +8,550 @@ python_api_name: qiskit_ibm_provider.job.IBMCircuitJob # IBMCircuitJob - + + Representation of a job that executes on an IBM Quantum backend. -`IBMCircuitJob(backend, api_client, job_id, creation_date=None, status=None, runtime_client=None, kind=None, name=None, time_per_step=None, result=None, error=None, session_id=None, tags=None, run_mode=None, client_info=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/ibm_circuit_job.py "view source code") + The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. -Representation of a job that executes on an IBM Quantum backend. + If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") members. For example: -The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. - -If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") members. For example: - -```python -from qiskit.providers.jobstatus import JobStatus - -job = backend.run(...) - -try: - job_status = job.status() # Query the backend server for job status. - if job_status is JobStatus.RUNNING: - print("The job is still running") -except IBMJobApiError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - - - An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. - - -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: - -```python -job = backend.run(...) - -try: - job_result = job.result() # It will block until the job finishes. - print("The job finished with result {}".format(job_result)) -except JobError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - -Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. - -IBMCircuitJob constructor. - -**Parameters** - -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`str`) – Job ID. -* **creation\_date** (`Optional`\[`str`]) – Job creation date. -* **status** (`Optional`\[`str`]) – Job status returned by the server. -* **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server -* **kind** (`Optional`\[`str`]) – Job type. -* **name** (`Optional`\[`str`]) – Job name. -* **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. -* **result** (`Optional`\[`dict`]) – Job result. -* **error** (`Optional`\[`dict`]) – Job error. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. -* **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. -* **kwargs** (`Any`) – Additional job attributes. - -## Attributes - - - -### client\_version - -Return version of the client used for this job. - -**Return type** - -`Dict`\[`str`, `str`] - -**Returns** - -**Client version in dictionary format, where the key is the name** - -of the client and the value is the version. - - - -### usage\_estimation - -Return usage estimation information for this job. - -**Return type** - -`Dict`\[`str`, `Any`] - -**Returns** - -`quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. - - - -### version - -`= 1` - -## Methods - -### backend - - - -`backend()` - -Return the backend where this job was executed. - -**Return type** - -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") - -### backend\_options - - - -`backend_options()` - -Return the backend configuration options used for this job. - -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. - -**Return type** - -`Dict` - -**Returns** - -Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. - -### cancel - - - -`cancel()` - -Attempt to cancel the job. - - - Depending on the state the job is in, it might be impossible to cancel the job. - - -**Return type** - -`bool` - -**Returns** - -`True` if the job is cancelled, else `False`. - -**Raises** + ```python + from qiskit.providers.jobstatus import JobStatus -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. -* [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + job = backend.run(...) -### cancelled + try: + job_status = job.status() # Query the backend server for job status. + if job_status is JobStatus.RUNNING: + print("The job is still running") + except IBMJobApiError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` - + + An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. + -`cancelled()` + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: -Return whether the job has been cancelled. + ```python + job = backend.run(...) -**Return type** + try: + job_result = job.result() # It will block until the job finishes. + print("The job finished with result {}".format(job_result)) + except JobError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` -`bool` + Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. -### circuits + IBMCircuitJob constructor. - + **Parameters** -`circuits()` + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`str`) – Job ID. + * **creation\_date** (`Optional`\[`str`]) – Job creation date. + * **status** (`Optional`\[`str`]) – Job status returned by the server. + * **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server + * **kind** (`Optional`\[`str`]) – Job type. + * **name** (`Optional`\[`str`]) – Job name. + * **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. + * **result** (`Optional`\[`dict`]) – Job result. + * **error** (`Optional`\[`dict`]) – Job error. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. + * **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. + * **kwargs** (`Any`) – Additional job attributes. -Return the circuits for this job. + ## Attributes -**Return type** + ### client\_version -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")] + + Return version of the client used for this job. -**Returns** + **Return type** -The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + `Dict`\[`str`, `str`] -### creation\_date + **Returns** - + **Client version in dictionary format, where the key is the name** -`creation_date()` + of the client and the value is the version. + -Return job creation date, in local time. + ### usage\_estimation -**Return type** + + Return usage estimation information for this job. -`datetime` + **Return type** -**Returns** + `Dict`\[`str`, `Any`] -The job creation date as a datetime object, in local time. + **Returns** -### done + `quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. + - + ### version -`done()` + -Return whether the job has successfully run. + ## Methods -**Return type** + ### backend -`bool` + + Return the backend where this job was executed. -### error\_message + **Return type** - + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") + -`error_message()` + ### backend\_options -Provide details about the reason of failure. + + Return the backend configuration options used for this job. -**Return type** + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -`Optional`\[`str`] + **Return type** -**Returns** + `Dict` -An error report if the job failed or `None` otherwise. + **Returns** -### header + Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. + - + ### cancel -`header()` + + Attempt to cancel the job. -Return the user header specified for this job. + + Depending on the state the job is in, it might be impossible to cancel the job. + -**Return type** + **Return type** -`Dict` + `bool` -**Returns** + **Returns** -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + `True` if the job is cancelled, else `False`. -### in\_final\_state + **Raises** - + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. + * [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + -`in_final_state()` + ### cancelled -Return whether the job is in a final job state such as `DONE` or `ERROR`. + + Return whether the job has been cancelled. -**Return type** + **Return type** -`bool` + `bool` + -### job\_id + ### circuits - + + Return the circuits for this job. -`job_id()` + **Return type** -Return the job ID assigned by the server. + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")] -**Return type** + **Returns** -`str` + The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + -**Returns** + ### creation\_date -Job ID. + + Return job creation date, in local time. -### name + **Return type** - + `datetime` -`name()` + **Returns** -Return the name assigned to this job. + The job creation date as a datetime object, in local time. + -**Return type** + ### done -`Optional`\[`str`] + + Return whether the job has successfully run. -**Returns** + **Return type** -Job name or `None` if no name was assigned to this job. + `bool` + -### properties + ### error\_message - + + Provide details about the reason of failure. -`properties(refresh=False)` + **Return type** -Return the backend properties for this job. + `Optional`\[`str`] -**Parameters** + **Returns** -**refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + An error report if the job failed or `None` otherwise. + -**Return type** + ### header -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")] + + Return the user header specified for this job. -**Returns** + **Return type** -The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + `Dict` -### queue\_info + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`queue_info()` + ### in\_final\_state -Return queue information for this job. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + **Return type** - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + `bool` + -**Return type** + ### job\_id -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Return the job ID assigned by the server. -**Returns** + **Return type** -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + `str` -### queue\_position + **Returns** - + Job ID. + -`queue_position(refresh=False)` + ### name -Return the position of the job in the server queue. + + Return the name assigned to this job. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + `Optional`\[`str`] -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job name or `None` if no name was assigned to this job. + -`Optional`\[`int`] + ### properties -**Returns** + + Return the backend properties for this job. -Position in the queue or `None` if position is unknown or not applicable. + **Parameters** -### refresh + **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. - + **Return type** -`refresh()` + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")] -Obtain the latest job information from the server. + **Returns** -This method may add additional attributes to this job instance, if new information becomes available. + The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + -**Raises** + ### queue\_info -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return queue information for this job. -**Return type** + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`None` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -### result + **Return type** - + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`result(timeout=None, refresh=False)` + **Returns** -Return the result of the job. + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + ### queue\_position - The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + + Return the position of the job in the server queue. - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") instance can be used to verify whether it contains partial results. + + The position returned is within the scope of the provider and may differ from the global queue position. + - For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: + **Parameters** - ```python - try: - counts = result.get_counts("failed_experiment") - except QiskitError: - print("Experiment failed!") - ``` - + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + **Return type** -**Parameters** + `Optional`\[`int`] -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job result. + This method may add additional attributes to this job instance, if new information becomes available. -**Raises** + **Raises** -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -### running + **Return type** - + `None` + -`running()` + ### result -Return whether the job is actively running. + + Return the result of the job. -**Return type** + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -`bool` + The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -### scheduling\_mode + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") instance can be used to verify whether it contains partial results. - + For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: -`scheduling_mode()` + ```python + try: + counts = result.get_counts("failed_experiment") + except QiskitError: + print("Experiment failed!") + ``` + -Return the scheduling mode the job is in. + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. -**Return type** + **Parameters** -`Optional`\[`str`] + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. -**Returns** + **Return type** -The scheduling mode the job is in or `None` if the information is not available. + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") -### status + **Returns** - + Job result. -`status()` + **Raises** -Query the server for the latest job status. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. - + ### running - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. - + + Return whether the job is actively running. -**Return type** + **Return type** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") + `bool` + -**Returns** + ### scheduling\_mode -The status of the job. + + Return the scheduling mode the job is in. -**Raises** + **Return type** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `Optional`\[`str`] -### submit + **Returns** - + The scheduling mode the job is in or `None` if the information is not available. + -`submit()` + ### status -Unsupported method. + + Query the server for the latest job status. - - This method is not supported, please use `run()` to submit a job. - + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. + -**Raises** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + -**NotImplementedError** – Upon invocation. + **Return type** -**Return type** + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") -`None` + **Returns** -### tags + The status of the job. - + **Raises** -`tags()` + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Return the tags assigned to this job. + ### submit -**Return type** + + Unsupported method. -`List`\[`str`] + + This method is not supported, please use `run()` to submit a job. + -**Returns** + **Raises** -Tags assigned to this job. + **NotImplementedError** – Upon invocation. -### time\_per\_step + **Return type** - + `None` + -`time_per_step()` + ### tags -Return the date and time information on each step of the job processing. + + Return the tags assigned to this job. -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: + **Return type** -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` + `List`\[`str`] -**Return type** + **Returns** -`Optional`\[`Dict`] + Tags assigned to this job. + -**Returns** + ### time\_per\_step -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + + Return the date and time information on each step of the job processing. -### update\_name + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`update_name(name)` + **Return type** -Update the name associated with this job. + `Optional`\[`Dict`] -**Parameters** + **Returns** -**name** (`str`) – The new name for this job. + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + -**Return type** + ### update\_name -`str` + + Update the name associated with this job. -**Returns** + **Parameters** -The new name associated with this job. + **name** (`str`) – The new name for this job. -### update\_tags + **Return type** - + `str` -`update_tags(new_tags)` + **Returns** -Update the tags associated with this job. + The new name associated with this job. + -**Parameters** + ### update\_tags -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. + + Update the tags associated with this job. -**Return type** + **Parameters** -`List`\[`str`] + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -**Returns** + **Return type** -The new tags associated with this job. + `List`\[`str`] -**Raises** + **Returns** -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + The new tags associated with this job. -### wait\_for\_final\_state + **Raises** - + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -`wait_for_final_state(timeout=None, wait=3)` + ### wait\_for\_final\_state -**Use the websocket server to wait for the final the state of a job. The server** + + **Use the websocket server to wait for the final the state of a job. The server** -will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. + will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. -**Parameters** + **Parameters** -**timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. + **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. -**Raises** + **Raises** -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. -**Return type** + **Return type** -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCompositeJob.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCompositeJob.mdx index 36d7dabe2d7..4852739881e 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCompositeJob.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMCompositeJob.mdx @@ -8,746 +8,678 @@ python_api_name: qiskit_ibm_provider.job.IBMCompositeJob # IBMCompositeJob - + + Representation of a set of jobs that execute on an IBM Quantum backend. -`IBMCompositeJob(backend, api_client, job_id=None, creation_date=None, jobs=None, circuits_list=None, run_config=None, name=None, tags=None, client_version=None)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/ibm_composite_job.py "view source code") + An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. -Representation of a set of jobs that execute on an IBM Quantum backend. + This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. -An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. + You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. -This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. + `IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. -You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. -`IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + `IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. + IBMCompositeJob constructor. -`IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. + **Parameters** -IBMCompositeJob constructor. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **creation\_date** (`Optional`\[`datetime`]) – Job creation date. + * **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. + * **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")]]]) – Circuits for this job. + * **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. + * **name** (`Optional`\[`str`]) – Job name. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **client\_version** (`Optional`\[`Dict`]) – Client used for the job. -**Parameters** + **Raises** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **creation\_date** (`Optional`\[`datetime`]) – Job creation date. -* **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. -* **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")]]]) – Circuits for this job. -* **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. -* **name** (`Optional`\[`str`]) – Job name. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **client\_version** (`Optional`\[`Dict`]) – Client used for the job. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. -**Raises** + ## Attributes -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. + ### client\_version -## Attributes + + Return version of the client used for this job. - + **Return type** -### client\_version + `Dict`\[`str`, `str`] -Return version of the client used for this job. + **Returns** -**Return type** + **Client version in dictionary format, where the key is the name** -`Dict`\[`str`, `str`] + of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + -**Returns** + ### version -**Client version in dictionary format, where the key is the name** + -of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + ## Methods - + ### backend -### version + + Return the backend where this job was executed. -`= 1` + **Return type** -## Methods + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") + -### backend + ### backend\_options - + + Return the backend configuration options used for this job. -`backend()` + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -Return the backend where this job was executed. + **Return type** -**Return type** + `Dict`\[`str`, `Any`] -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") + **Returns** -### backend\_options + Backend options used for this job. + - + ### block\_for\_submit -`backend_options()` + + Block until all sub-jobs are submitted. -Return the backend configuration options used for this job. + **Return type** -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. + `None` + -**Return type** + ### cancel -`Dict`\[`str`, `Any`] + + Attempt to cancel the job. -**Returns** + + Depending on the state the job is in, it might be impossible to cancel the job. + -Backend options used for this job. + **Return type** -### block\_for\_submit + `bool` - + **Returns** -`block_for_submit()` + `True` if the job is cancelled, else `False`. -Block until all sub-jobs are submitted. + **Raises** -**Return type** + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -`None` + ### cancelled -### cancel + + Return whether the job has been cancelled. - + **Return type** -`cancel()` + `bool` + -Attempt to cancel the job. + ### circuits - - Depending on the state the job is in, it might be impossible to cancel the job. - + + Return the circuits for this job. -**Return type** + **Return type** -`bool` + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")] -**Returns** + **Returns** -`True` if the job is cancelled, else `False`. + The circuits for this job. + -**Raises** + ### creation\_date -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return job creation date, in local time. -### cancelled + **Return type** - + `Optional`\[`datetime`] -`cancelled()` + **Returns** -Return whether the job has been cancelled. + The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + -**Return type** + ### done -`bool` + + Return whether the job has successfully run. -### circuits + **Return type** - + `bool` + -`circuits()` + ### error\_message -Return the circuits for this job. + + Provide details about the reason of failure. -**Return type** + + This method blocks until the job finishes. + -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v0.46)")] + **Return type** -**Returns** + `Optional`\[`str`] -The circuits for this job. + **Returns** -### creation\_date + An error report if the job failed or `None` otherwise. + - + ### from\_jobs -`creation_date()` + + Return an instance of this class. -Return job creation date, in local time. + The input job ID is used to query for sub-job information from the server. -**Return type** + **Parameters** -`Optional`\[`datetime`] + * **job\_id** (`str`) – Job ID. + * **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. + * **api\_client** (`AccountClient`) – Client to use to communicate with the server. -**Returns** + **Return type** -The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + [`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") -### done + **Returns** - + An instance of this class. + -`done()` + ### header -Return whether the job has successfully run. + + Return the user header specified for this job. -**Return type** + **Return type** -`bool` + `Dict` -### error\_message + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`error_message()` + ### in\_final\_state -Provide details about the reason of failure. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. - - This method blocks until the job finishes. - + **Return type** -**Return type** + `bool` + -`Optional`\[`str`] + ### job\_id -**Returns** + + Return a unique id identifying the job. -An error report if the job failed or `None` otherwise. + **Return type** -### from\_jobs + `str` + - + ### name -`classmethod from_jobs(job_id, jobs, api_client)` + + Return the name assigned to this job. -Return an instance of this class. + **Return type** -The input job ID is used to query for sub-job information from the server. + `Optional`\[`str`] -**Parameters** + **Returns** -* **job\_id** (`str`) – Job ID. -* **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. -* **api\_client** (`AccountClient`) – Client to use to communicate with the server. + Job name or `None` if no name was assigned to this job. + -**Return type** + ### properties -[`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") + + Return the backend properties for this job. -**Returns** + > **Args:** + > + > **refresh: If `True`, re-query the server for the backend properties.** + > + > Otherwise, return a cached version. -An instance of this class. + + This method blocks until all sub-jobs are submitted. + -### header + **Return type** - + `Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)"), `None`] -`header()` + **Returns** -Return the user header specified for this job. + The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. -**Return type** + **Raises** -`Dict` + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Returns** + ### queue\_info -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + + Return queue information for this job. -### in\_final\_state + This method returns the queue information of the sub-job that is last in queue. - + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`in_final_state()` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -Return whether the job is in a final job state such as `DONE` or `ERROR`. + **Return type** -**Return type** + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`bool` + **Returns** -### job\_id + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - + ### queue\_position -`job_id()` + + Return the position of the job in the server queue. -Return a unique id identifying the job. + This method returns the queue position of the sub-job that is last in queue. -**Return type** + + The position returned is within the scope of the provider and may differ from the global queue position. + -`str` + **Parameters** -### name + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. - + **Return type** -`name()` + `Optional`\[`int`] -Return the name assigned to this job. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -`Optional`\[`str`] + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job name or `None` if no name was assigned to this job. + This method may add additional attributes to this job instance, if new information becomes available. -### properties + **Raises** - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -`properties(refresh=False)` + **Return type** -Return the backend properties for this job. + `None` + -> **Args:** -> -> **refresh: If `True`, re-query the server for the backend properties.** -> -> Otherwise, return a cached version. + ### report - - This method blocks until all sub-jobs are submitted. - + + Return a report on current sub-job statuses. -**Return type** + **Parameters** -`Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v0.46)"), `None`] + **detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. -**Returns** + **Return type** -The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. + `str` -**Raises** + **Returns** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + A report on sub-job statuses. + -### queue\_info + ### rerun\_failed - + + Re-submit all failed sub-jobs. -`queue_info()` + + All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + -Return queue information for this job. + **Return type** -This method returns the queue information of the sub-job that is last in queue. + `None` + -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + ### result - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + + Return the result of the job. -**Return type** + + This method blocks until all sub-jobs finish. + -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -**Returns** + The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") instance can be used to verify whether it contains partial results. -### queue\_position + For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: - + ```python + try: + counts = result.get_counts("failed_circuit") + except QiskitError: + print("Circuit execution failed!") + ``` + -`queue_position(refresh=False)` + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. -Return the position of the job in the server queue. + **Parameters** -This method returns the queue position of the sub-job that is last in queue. + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **wait** (`float`) – Time in seconds between queries. + * **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job result. -`Optional`\[`int`] + **Raises** -**Returns** + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Position in the queue or `None` if position is unknown or not applicable. + ### running -### refresh + + Return whether the job is actively running. - + **Return type** -`refresh()` + `bool` + -Obtain the latest job information from the server. + ### scheduling\_mode -This method may add additional attributes to this job instance, if new information becomes available. + + Return the scheduling mode the job is in. -**Raises** + The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. -**Return type** + This information is only available if the job status is `RUNNING` or `DONE`. -`None` + **Return type** -### report + `Optional`\[`str`] - + **Returns** -`report(detailed=True)` + The scheduling mode the job is in or `None` if the information is not available. + -Return a report on current sub-job statuses. + ### status -**Parameters** + + Query the server for the latest job status. -**detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. + -**Return type** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + -`str` + + Since this job contains multiple sub-jobs, the returned status is mapped in the following order: -**Returns** + > * INITIALIZING - if any sub-job is being initialized. + > * VALIDATING - if any sub-job is being validated. + > * QUEUED - if any sub-job is queued. + > * RUNNING - if any sub-job is still running. + > * ERROR - if any sub-job incurred an error. + > * CANCELLED - if any sub-job is cancelled. + > * DONE - if all sub-jobs finished. + -A report on sub-job statuses. + **Return type** -### rerun\_failed + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") - + **Returns** -`rerun_failed()` + The status of the job. -Re-submit all failed sub-jobs. + **Raises** - - All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Return type** + ### sub\_job -`None` + + Retrieve the job used to submit the specified circuit. -### result + **Parameters** - + **circuit\_index** (`int`) – Index of the circuit whose job is to be returned. -`result(timeout=None, wait=5, partial=False, refresh=False)` + **Return type** -Return the result of the job. + `Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] - - This method blocks until all sub-jobs finish. - + **Returns** - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. - The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + **Raises** - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") instance can be used to verify whether it contains partial results. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + - For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: + ### sub\_jobs - ```python - try: - counts = result.get_counts("failed_circuit") - except QiskitError: - print("Circuit execution failed!") - ``` - + + Return all submitted sub-jobs. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + **Parameters** -**Parameters** + **block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **wait** (`float`) – Time in seconds between queries. -* **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Return type** -**Return type** + `List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v0.46)") + **Returns** -**Returns** + All submitted sub-jobs. + -Job result. + ### submit -**Raises** + + Unsupported method. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + This method is not supported, please use `run()` to submit a job. + -### running + **Raises** - + **NotImplementedError** – Upon invocation. -`running()` + **Return type** -Return whether the job is actively running. + `None` + -**Return type** + ### tags -`bool` + + Return the tags assigned to this job. -### scheduling\_mode + **Return type** - + `List`\[`str`] -`scheduling_mode()` + **Returns** -Return the scheduling mode the job is in. + Tags assigned to this job. + -The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. + ### time\_per\_step -`fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. + + Return the date and time information on each step of the job processing. -This information is only available if the job status is `RUNNING` or `DONE`. + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: -**Return type** + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`Optional`\[`str`] + **Return type** -**Returns** + `Optional`\[`Dict`] -The scheduling mode the job is in or `None` if the information is not available. + **Returns** -### status + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + - + ### update\_name -`status()` + + Update the name associated with this job. -Query the server for the latest job status. + + This method blocks until all sub-jobs are submitted. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. - + **Parameters** - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. - + **name** (`str`) – The new name for this job. - - Since this job contains multiple sub-jobs, the returned status is mapped in the following order: + **Return type** - > * INITIALIZING - if any sub-job is being initialized. - > * VALIDATING - if any sub-job is being validated. - > * QUEUED - if any sub-job is queued. - > * RUNNING - if any sub-job is still running. - > * ERROR - if any sub-job incurred an error. - > * CANCELLED - if any sub-job is cancelled. - > * DONE - if all sub-jobs finished. - + `str` -**Return type** + **Returns** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v0.46)") + The new name associated with this job. -**Returns** + **Raises** -The status of the job. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. + -**Raises** + ### update\_tags -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Update the tags associated with this job. -### sub\_job + + This method blocks until all sub-jobs are submitted. + - + **Parameters** -`sub_job(circuit_index)` + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -Retrieve the job used to submit the specified circuit. + **Return type** -**Parameters** + `List`\[`str`] -**circuit\_index** (`int`) – Index of the circuit whose job is to be returned. + **Returns** -**Return type** + The new tags associated with this job. -`Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. + ### wait\_for\_final\_state -**Raises** + + Wait until the job progresses to a final state such as `DONE` or `ERROR`. -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + **Parameters** -### sub\_jobs + * **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - + * **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. -`sub_jobs(block_for_submit=True)` + * **callback** (`Optional`\[`Callable`]) – -Return all submitted sub-jobs. + Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: -**Parameters** + > * job\_id: Job ID + > * job\_status: Status of the job from the last query. + > * job: This `IBMCompositeJob` instance. -**block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. + In addition, the following keyword arguments are also provided: -**Return type** + > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. -`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. -All submitted sub-jobs. + **Return type** -### submit - - - -`submit()` - -Unsupported method. - - - This method is not supported, please use `run()` to submit a job. - - -**Raises** - -**NotImplementedError** – Upon invocation. - -**Return type** - -`None` - -### tags - - - -`tags()` - -Return the tags assigned to this job. - -**Return type** - -`List`\[`str`] - -**Returns** - -Tags assigned to this job. - -### time\_per\_step - - - -`time_per_step()` - -Return the date and time information on each step of the job processing. - -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` - -**Return type** - -`Optional`\[`Dict`] - -**Returns** - -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. - -### update\_name - - - -`update_name(name)` - -Update the name associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**name** (`str`) – The new name for this job. - -**Return type** - -`str` - -**Returns** - -The new name associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. - -### update\_tags - - - -`update_tags(new_tags)` - -Update the tags associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. - -**Return type** - -`List`\[`str`] - -**Returns** - -The new tags associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. - -### wait\_for\_final\_state - - - -`wait_for_final_state(timeout=None, wait=None, callback=None)` - -Wait until the job progresses to a final state such as `DONE` or `ERROR`. - -**Parameters** - -* **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - -* **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. - -* **callback** (`Optional`\[`Callable`]) – - - Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: - - > * job\_id: Job ID - > * job\_status: Status of the job from the last query. - > * job: This `IBMCompositeJob` instance. - - In addition, the following keyword arguments are also provided: - - > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. - -**Raises** - -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobApiError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobApiError.mdx index 06136810827..6d65fc3551f 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobApiError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobApiError # IBMJobApiError - + + Errors that occur unexpectedly when querying the server. -`IBMJobApiError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobError.mdx index 2e217306bb9..d193d4add3f 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobError # IBMJobError - + + Base class for errors raised by the job modules. -`IBMJobError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/exceptions.py "view source code") - -Base class for errors raised by the job modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobFailureError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobFailureError.mdx index 1cb58285202..cbb2ed27994 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobFailureError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobFailureError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobFailureError # IBMJobFailureError - + + Errors raised when a job failed. -`IBMJobFailureError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job failed. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx index 088d8ca19bd..05465e14fd9 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobInvalidStateError # IBMJobInvalidStateError - + + Errors raised when a job is not in a valid state for the operation. -`IBMJobInvalidStateError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job is not in a valid state for the operation. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx index 499c58d3bcb..c7f24aaf1e5 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobTimeoutError # IBMJobTimeoutError - + + Errors raised when a job operation times out. -`IBMJobTimeoutError(*message)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/exceptions.py "view source code") - -Errors raised when a job operation times out. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.QueueInfo.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.QueueInfo.mdx index 12d7cd93e04..cabd7befa33 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.QueueInfo.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.QueueInfo.mdx @@ -8,63 +8,59 @@ python_api_name: qiskit_ibm_provider.job.QueueInfo # QueueInfo - + + Queue information for a job. -`QueueInfo(position_in_queue=None, status=None, estimated_start_time=None, estimated_completion_time=None, hub_priority=None, group_priority=None, project_priority=None, job_id=None, **kwargs)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/queueinfo.py "view source code") + QueueInfo constructor. -Queue information for a job. + **Parameters** -QueueInfo constructor. + * **position** – Position in the queue. + * **status** (`Optional`\[`str`]) – Job status. + * **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. + * **estimated\_complete\_time** – Estimated complete time for the job, in UTC. + * **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. + * **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. + * **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **kwargs** (`Any`) – Additional attributes. -**Parameters** + ## Attributes -* **position** – Position in the queue. -* **status** (`Optional`\[`str`]) – Job status. -* **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. -* **estimated\_complete\_time** – Estimated complete time for the job, in UTC. -* **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. -* **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. -* **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **kwargs** (`Any`) – Additional attributes. + ### estimated\_complete\_time -## Attributes + + Return estimated complete time in local time. - + **Return type** -### estimated\_complete\_time + `Optional`\[`datetime`] + -Return estimated complete time in local time. + ### estimated\_start\_time -**Return type** + + Return estimated start time in local time. -`Optional`\[`datetime`] + **Return type** - + `Optional`\[`datetime`] + -### estimated\_start\_time + ## Methods -Return estimated start time in local time. + ### format -**Return type** + + Build a user-friendly report for the job queue information. -`Optional`\[`datetime`] + **Return type** -## Methods + `str` -### format + **Returns** - - -`format()` - -Build a user-friendly report for the job queue information. - -**Return type** - -`str` - -**Returns** - -The job queue information report. + The job queue information report. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.job_monitor.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.job_monitor.mdx index 8508cbdbe4b..53616609c74 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.job_monitor.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.job.job_monitor.mdx @@ -10,19 +10,17 @@ python_api_name: qiskit_ibm_provider.job.job_monitor # job\_monitor - + + Monitor the status of an `IBMJob` instance. -`job_monitor(job, interval=None, output=<_io.TextIOWrapper name='' mode='w' encoding='utf-8'>)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/job/job_monitor.py "view source code") + **Parameters** -Monitor the status of an `IBMJob` instance. + * **job** (`IBMJob`) – Job to monitor. + * **interval** (`Optional`\[`float`]) – Time interval between status queries. + * **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. -**Parameters** + **Return type** -* **job** (`IBMJob`) – Job to monitor. -* **interval** (`Optional`\[`float`]) – Time interval between status queries. -* **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.least_busy.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.least_busy.mdx index 9dfdedd050f..a7933e65658 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.least_busy.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.least_busy.mdx @@ -10,27 +10,25 @@ python_api_name: qiskit_ibm_provider.least_busy # least\_busy - + + Return the least busy backend from a list. -`least_busy(backends)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/__init__.py "view source code") + Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. -Return the least busy backend from a list. + **Parameters** -Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. + **backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)")]) – The backends to choose from. -**Parameters** + **Return type** -**backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)")]) – The backends to choose from. + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") -**Return type** + **Returns** -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)") + The backend with the fewest number of pending jobs. -**Returns** + **Raises** -The backend with the fewest number of pending jobs. - -**Raises** - -[**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + [**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx index c0e42ef0c40..8f646b9403b 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAn # ALAPScheduleAnalysis - + + Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. -`ALAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] + + Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + `None` -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` + **Return type** -Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -`None` - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx index 93cb8a932d2..265578d5f8e 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAn # ASAPScheduleAnalysis - + + Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. -`ASAPScheduleAnalysis(durations)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] + + Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` + **Return type** -Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -[`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)") - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx index 9a7b72fda0c..c0b983adf74 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx @@ -8,140 +8,128 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadde # BlockBasePadder - + + The base class of padding pass. -`BlockBasePadder(schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py "view source code") + This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. -The base class of padding pass. + This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. -This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. + Note that padding pass subclasses should define interleaving sequences satisfying: -This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. + > * Interleaved sequence does not change start time of other nodes + > * Interleaved sequence should have total duration of the provided `time_interval`. -Note that padding pass subclasses should define interleaving sequences satisfying: + Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. -> * Interleaved sequence does not change start time of other nodes -> * Interleaved sequence should have total duration of the provided `time_interval`. + ## Attributes -Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx index 93bc8b97e8b..c11efacfec7 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx @@ -8,137 +8,121 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuit # DynamicCircuitInstructionDurations - + + For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. -`DynamicCircuitInstructionDurations(instruction_durations=None, dt=None, enable_patching=True)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py "view source code") + Dynamic circuit instruction durations. -For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. + ## Attributes -Dynamic circuit instruction durations. + ### MEASURE\_PATCH\_CYCLES -## Attributes + - + ### MEASURE\_PATCH\_ODD\_OFFSET -### MEASURE\_PATCH\_CYCLES + -`= 160` + ## Methods - + ### from\_backend -### MEASURE\_PATCH\_ODD\_OFFSET + + Construct a `DynamicInstructionDurations` object from the backend. -`= 64` + **Parameters** -## Methods + **backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)")) – backend from which durations (gate lengths) and dt are extracted. -### from\_backend + **Returns** - + The InstructionDurations constructed from backend. -`classmethod from_backend(backend)` + **Return type** -Construct a `DynamicInstructionDurations` object from the backend. + DynamicInstructionDurations + -**Parameters** + ### from\_target -**backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v0.46)")) – backend from which durations (gate lengths) and dt are extracted. + + Construct a `DynamicInstructionDurations` object from the target. -**Returns** + **Parameters** -The InstructionDurations constructed from backend. + **target** ([`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)")) – target from which durations (gate lengths) and dt are extracted. -**Return type** + **Returns** -DynamicInstructionDurations + The InstructionDurations constructed from backend. -### from\_target + **Return type** - + DynamicInstructionDurations + -`classmethod from_target(target)` + ### get -Construct a `DynamicInstructionDurations` object from the target. + + Get the duration of the instruction with the name, qubits, and parameters. -**Parameters** + Some instructions may have a parameter dependent duration. -**target** ([`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v0.46)")) – target from which durations (gate lengths) and dt are extracted. + **Parameters** -**Returns** + * **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)")) – An instruction or its name to be queried. + * **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. + * **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. + * **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. -The InstructionDurations constructed from backend. + **Returns** -**Return type** + The duration of the instruction on the qubits. -DynamicInstructionDurations + **Return type** -### get + float|int - + **Raises** -`get(inst, qubits, unit='dt', parameters=None)` + **TranspilerError** – No duration is defined for the instruction. + -Get the duration of the instruction with the name, qubits, and parameters. + ### units\_used -Some instructions may have a parameter dependent duration. + + Get the set of all units used in this instruction durations. -**Parameters** + **Return type** -* **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v0.46)")) – An instruction or its name to be queried. -* **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. -* **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. -* **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. + `set`\[`str`] -**Returns** + **Returns** -The duration of the instruction on the qubits. + Set of units used in this instruction durations. + -**Return type** + ### update -float|int + + Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. -**Raises** + **Parameters** -**TranspilerError** – No duration is defined for the instruction. + * **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)"), `None`]) – Instruction durations to be merged into self (overwriting self). + * **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. -### units\_used + **Returns** - + The updated InstructionDurations. -`units_used()` + **Return type** -Get the set of all units used in this instruction durations. + InstructionDurations -**Return type** + **Raises** -`set`\[`str`] - -**Returns** - -Set of units used in this instruction durations. - -### update - - - -`update(inst_durations, dt=None)` - -Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. - -**Parameters** - -* **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)"), `None`]) – Instruction durations to be merged into self (overwriting self). -* **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. - -**Returns** - -The updated InstructionDurations. - -**Return type** - -InstructionDurations - -**Raises** - -**TranspilerError** – If the format of instruction\_durations is invalid. + **TranspilerError** – If the format of instruction\_durations is invalid. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx index b0bc27b1bac..df6a999aa29 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx @@ -8,152 +8,140 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay # PadDelay - + + Padding idle time with Delay instructions. -`PadDelay(fill_very_end=True, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/pad_delay.py "view source code") + Consecutive delays will be merged in the output of this pass. -Padding idle time with Delay instructions. + The ASAP-scheduled circuit output may become -Consecutive delays will be merged in the output of this pass. + ```python + ┌────────────────┐ + q_0: ┤ Delay(160[dt]) ├──■── + └─────┬───┬──────┘┌─┴─┐ + q_1: ──────┤ X ├───────┤ X ├ + └───┘ └───┘ + ``` -The ASAP-scheduled circuit output may become + Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. -```python - ┌────────────────┐ -q_0: ┤ Delay(160[dt]) ├──■── - └─────┬───┬──────┘┌─┴─┐ -q_1: ──────┤ X ├───────┤ X ├ - └───┘ └───┘ -``` + See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. -Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. + Create new padding delay pass. -See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. + **Parameters** -Create new padding delay pass. + * **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -**Parameters** + ## Attributes -* **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx index c5669e727b9..9297bdb8bab 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx @@ -8,287 +8,275 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDe # PadDynamicalDecoupling - - -`PadDynamicalDecoupling(durations, dd_sequences, qubits=None, spacings=None, skip_reset_qubits=True, pulse_alignment=16, extra_slack_distribution='middle', sequence_min_length_ratios=None, insert_multiple_cycles=False, coupling_map=None, alt_spacings=None, schedule_idle_qubits=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/transpiler/passes/scheduling/dynamical_decoupling.py "view source code") - -Dynamical decoupling insertion pass for IBM dynamic circuit backends. - -This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). - -```python -import numpy as np -from qiskit.circuit import QuantumCircuit -from qiskit.circuit.library import XGate -from qiskit.transpiler import PassManager, InstructionDurations -from qiskit.visualization import timeline_drawer - -from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis -from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling - -circ = QuantumCircuit(4) -circ.h(0) -circ.cx(0, 1) -circ.cx(1, 2) -circ.cx(2, 3) -circ.measure_all() -durations = InstructionDurations( - [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), - ("cx", [1, 2], 200), ("cx", [2, 3], 300), - ("x", None, 50), ("measure", None, 1000)] -) -``` - -```python -# balanced X-X sequence on all qubits -dd_sequence = [XGate(), XGate()] -pm = PassManager([ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence)]) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌───────────────┐ ┌───┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» - ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» - ├────────────────┤ └───┘ ┌─┴─┐ » - q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» - └────────────────┘ └───┘ » -meas: 4/═════════════════════════════════════════════════════════» - » -« ┌────────────────┐ ┌───┐ ┌───────────────┐ » -« q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» -« └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» -« q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» -« └───┘ └───────────────┘ └───┘ └───────────────┘» -« q_2: ─────────────────────────────────────────────────────────────────────» -« » -« q_3: ─────────────────────────────────────────────────────────────────────» -« » -«meas: 4/═════════════════════════════════════════════════════════════════════» -« » -« ░ ┌─┐ -« q_0: ─░─┤M├───────── -« ░ └╥┘┌─┐ -« q_1: ─░──╫─┤M├────── -« ░ ║ └╥┘┌─┐ -« q_2: ─░──╫──╫─┤M├─── -« ░ ║ ║ └╥┘┌─┐ -« q_3: ─░──╫──╫──╫─┤M├ -« ░ ║ ║ ║ └╥┘ -«meas: 4/════╩══╩══╩══╩═ -« 0 1 2 3 -``` - -```python -# Uhrig sequence on qubit 0 -n = 8 -dd_sequence = [XGate()] * n -def uhrig_pulse_location(k): - return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 -spacings = [] -for k in range(n): - spacings.append(uhrig_pulse_location(k) - sum(spacings)) -spacings.append(1 - sum(spacings)) -pm = PassManager( - [ - ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), - ] -) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌────────────────┐ ░ ┌─┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» - ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» - ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» - q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» - └────────────────┘ └───┘ ░ ║ ║ ║ » -meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» - 0 1 2 » -« -« q_0: ─── -« -« q_1: ─── -« -« q_2: ─── -« ┌─┐ -« q_3: ┤M├ -« └╥┘ -«meas: 4/═╩═ -« 3 -``` + + Dynamical decoupling insertion pass for IBM dynamic circuit backends. + + This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + + ```python + import numpy as np + from qiskit.circuit import QuantumCircuit + from qiskit.circuit.library import XGate + from qiskit.transpiler import PassManager, InstructionDurations + from qiskit.visualization import timeline_drawer + + from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis + from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling + + circ = QuantumCircuit(4) + circ.h(0) + circ.cx(0, 1) + circ.cx(1, 2) + circ.cx(2, 3) + circ.measure_all() + durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] + ) + ``` + + ```python + # balanced X-X sequence on all qubits + dd_sequence = [XGate(), XGate()] + pm = PassManager([ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence)]) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌───────────────┐ ┌───┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» + ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» + ├────────────────┤ └───┘ ┌─┴─┐ » + q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» + └────────────────┘ └───┘ » + meas: 4/═════════════════════════════════════════════════════════» + » + « ┌────────────────┐ ┌───┐ ┌───────────────┐ » + « q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» + « └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» + « q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» + « └───┘ └───────────────┘ └───┘ └───────────────┘» + « q_2: ─────────────────────────────────────────────────────────────────────» + « » + « q_3: ─────────────────────────────────────────────────────────────────────» + « » + «meas: 4/═════════════════════════════════════════════════════════════════════» + « » + « ░ ┌─┐ + « q_0: ─░─┤M├───────── + « ░ └╥┘┌─┐ + « q_1: ─░──╫─┤M├────── + « ░ ║ └╥┘┌─┐ + « q_2: ─░──╫──╫─┤M├─── + « ░ ║ ║ └╥┘┌─┐ + « q_3: ─░──╫──╫──╫─┤M├ + « ░ ║ ║ ║ └╥┘ + «meas: 4/════╩══╩══╩══╩═ + « 0 1 2 3 + ``` + + ```python + # Uhrig sequence on qubit 0 + n = 8 + dd_sequence = [XGate()] * n + def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 + spacings = [] + for k in range(n): + spacings.append(uhrig_pulse_location(k) - sum(spacings)) + spacings.append(1 - sum(spacings)) + pm = PassManager( + [ + ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), + ] + ) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌────────────────┐ ░ ┌─┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» + ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» + ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» + q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» + └────────────────┘ └───┘ ░ ║ ║ ║ » + meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» + 0 1 2 » + « + « q_0: ─── + « + « q_1: ─── + « + « q_2: ─── + « ┌─┐ + « q_3: ┤M├ + « └╥┘ + «meas: 4/═╩═ + « 3 + ``` + + + You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. + + + Dynamical decoupling initializer. + + **Parameters** - - You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. - + * **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. -Dynamical decoupling initializer. + * **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.46)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.46)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. -**Parameters** + * **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). -* **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v0.46)")) – Durations of instructions to be used in scheduling. + * **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified -* **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.46)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v0.46)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. + * **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). -* **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). + * **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. -* **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified + * **extra\_slack\_distribution** (`str`) – -* **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). + The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. -* **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. + > * ”middle”: Put the extra slack to the interval at the middle of the sequence. + > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. -* **extra\_slack\_distribution** (`str`) – + * **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. - The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. + * **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. - > * ”middle”: Put the extra slack to the interval at the middle of the sequence. - > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. + * **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.46)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. -* **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. + * **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. -* **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -* **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v0.46)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. + **Raises** -* **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. + * **TranspilerError** – When invalid DD sequence is specified. + * **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. + * **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ## Attributes -**Raises** + ### is\_analysis\_pass -* **TranspilerError** – When invalid DD sequence is specified. -* **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. -* **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) + + Check if the pass is an analysis pass. -## Attributes + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + - + ### is\_transformation\_pass -### is\_analysis\_pass + + Check if the pass is a transformation pass. -Check if the pass is an analysis pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ## Methods - + ### \_\_call\_\_ -### is\_transformation\_pass + + Runs the pass on circuit. -Check if the pass is a transformation pass. + **Parameters** -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -## Methods + **Return type** -### \_\_call\_\_ + QuantumCircuit - + **Returns** -`__call__(circuit, property_set=None)` + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -Runs the pass on circuit. + ### execute -**Parameters** + + Execute optimization task for input Qiskit IR. -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + **Parameters** -**Return type** + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -QuantumCircuit + **Return type** -**Returns** + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Returns** -### execute + Optimized Qiskit IR and state of the workflow. + - + ### name -`execute(passmanager_ir, state, callback=None)` + + Name of the pass. -Execute optimization task for input Qiskit IR. + **Return type** -**Parameters** + `str` + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### run -**Return type** + + Run the padding pass on `dag`. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")] + **Parameters** -**Returns** + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. -Optimized Qiskit IR and state of the workflow. + **Returns** -### name + DAG with idle time filled with instructions. - + **Return type** -`name()` + DAGCircuit -Name of the pass. + **Raises** -**Return type** + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`str` + ### update\_status -### run + + Update workflow status. - + **Parameters** -`run(dag)` + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -Run the padding pass on `dag`. + **Return type** -**Parameters** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v0.46)")) – DAG to be checked. + **Returns** -**Returns** - -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v0.46)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.seconds_to_duration.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.seconds_to_duration.mdx index 51ca3d6671f..1f69bc567e8 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.seconds_to_duration.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.seconds_to_duration.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.seconds_to_duration # seconds\_to\_duration - + + Converts seconds in a datetime delta to a duration. -`seconds_to_duration(seconds)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Converts seconds in a datetime delta to a duration. + **seconds** (`float`) – Number of seconds in time delta. -**Parameters** + **Return type** -**seconds** (`float`) – Number of seconds in time delta. + `Tuple`\[`int`, `int`, `int`, `int`, `int`] -**Return type** + **Returns** -`Tuple`\[`int`, `int`, `int`, `int`, `int`] - -**Returns** - -A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.to_python_identifier.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.to_python_identifier.mdx index abfd062d9ba..80136e38472 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.to_python_identifier.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.to_python_identifier.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.to_python_identifier # to\_python\_identifier - + + Convert a name to a valid Python identifier. -`to_python_identifier(name)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Convert a name to a valid Python identifier. + **name** (`str`) – Name to be converted. -**Parameters** + **Return type** -**name** (`str`) – Name to be converted. + `str` -**Return type** + **Returns** -`str` - -**Returns** - -Name that is a valid Python identifier. + Name that is a valid Python identifier. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.utc_to_local.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.utc_to_local.mdx index e76fefa9e75..f06eb147ccb 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.utc_to_local.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.utc_to_local.mdx @@ -10,25 +10,23 @@ python_api_name: qiskit_ibm_provider.utils.utc_to_local # utc\_to\_local - + + Convert a UTC `datetime` object or string to a local timezone `datetime`. -`utc_to_local(utc_dt)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/converters.py "view source code") + **Parameters** -Convert a UTC `datetime` object or string to a local timezone `datetime`. + **utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. -**Parameters** + **Return type** -**utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. + `datetime` -**Return type** + **Returns** -`datetime` + A `datetime` with the local timezone. -**Returns** + **Raises** -A `datetime` with the local timezone. - -**Raises** - -**TypeError** – If the input parameter value is not valid. + **TypeError** – If the input parameter value is not valid. + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.validate_job_tags.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.validate_job_tags.mdx index 1a2f894ba42..ec31c2b8afe 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.validate_job_tags.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.utils.validate_job_tags.mdx @@ -10,22 +10,20 @@ python_api_name: qiskit_ibm_provider.utils.validate_job_tags # validate\_job\_tags - + + Validates input job tags. -`validate_job_tags(job_tags, exception)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/utils/utils.py "view source code") + **Parameters** -Validates input job tags. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. + * **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. -**Parameters** + **Raises** -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. -* **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. + **Exception** – If the job tags are invalid. -**Raises** + **Return type** -**Exception** – If the job tags are invalid. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_error_map.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_error_map.mdx index ab33cd20e41..3c0d6110451 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_error_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_error_map.mdx @@ -10,45 +10,43 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_error_map # iplot\_error\_map - + + Plot the error map of a device. -`iplot_error_map(backend, figsize=(800, 500), show_title=True, remove_badcal_edges=True, background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/visualization/interactive/error_map.py "view source code") + **Parameters** -Plot the error map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. + * **figsize** (`Tuple`\[`int`]) – Figure size in pixels. + * **show\_title** (`bool`) – Whether to show figure title. + * **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. + * **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. -* **figsize** (`Tuple`\[`int`]) – Figure size in pixels. -* **show\_title** (`bool`) – Whether to show figure title. -* **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. -* **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The error map figure. -**Returns** + **Raises** -The error map figure. + * **VisualizationValueError** – If an invalid input is received. + * **VisualizationTypeError** – If the specified backend is a simulator. -**Raises** + **Example** -* **VisualizationValueError** – If an invalid input is received. -* **VisualizationTypeError** – If the specified backend is a simulator. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_error_map -**Example** + provider = IBMProvider(group='open', project='main') + # Note that this is a mock provider, replace ``FakeOpenPulse2Q`` + # with any of the currently available IBM devices. + backend = provider.get_backend('FakeOpenPulse2Q') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_error_map - -provider = IBMProvider(group='open', project='main') -# Note that this is a mock provider, replace ``FakeOpenPulse2Q`` -# with any of the currently available IBM devices. -backend = provider.get_backend('FakeOpenPulse2Q') - -iplot_error_map(backend, as_widget=True) -``` + iplot_error_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_gate_map.mdx b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_gate_map.mdx index 6b9d2aeed28..0d7f30c3e0e 100644 --- a/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_gate_map.mdx +++ b/docs/api/qiskit-ibm-provider/0.9/qiskit_ibm_provider.visualization.iplot_gate_map.mdx @@ -10,46 +10,44 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_gate_map # iplot\_gate\_map - + + Plots an interactive gate map of a device. -`iplot_gate_map(backend, figsize=(None, None), label_qubits=True, qubit_size=None, line_width=None, font_size=None, qubit_color='#2f4b7c', qubit_labels=None, line_color='#2f4b7c', font_color='white', background_color='white', as_widget=False)` [GitHub](https://github.com/qiskit/qiskit-ibm-provider/tree/stable/0.9/qiskit_ibm_provider/visualization/interactive/gate_map.py "view source code") + **Parameters** -Plots an interactive gate map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. + * **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. + * **label\_qubits** (`bool`) – Labels for the qubits. + * **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. + * **line\_width** (`Optional`\[`float`]) – Width of lines. + * **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. + * **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. + * **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels + * **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. + * **font\_color** (`str`) – The font color for the qubit labels. + * **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. -* **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. -* **label\_qubits** (`bool`) – Labels for the qubits. -* **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. -* **line\_width** (`Optional`\[`float`]) – Width of lines. -* **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. -* **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. -* **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels -* **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. -* **font\_color** (`str`) – The font color for the qubit labels. -* **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The gate map figure. -**Returns** + **Example** -The gate map figure. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_gate_map -**Example** + provider = IBMProvider(group='open', project='main') + # Note that this is a mock provider, replace ``FakeOpenPulse2Q`` + # with any of the currently available IBM devices. + backend = provider.get_backend('FakeOpenPulse2Q') -```python - from qiskit_ibm_provider import IBMProvider - from qiskit_ibm_provider.visualization import iplot_gate_map - -provider = IBMProvider(group='open', project='main') -# Note that this is a mock provider, replace ``FakeOpenPulse2Q`` -# with any of the currently available IBM devices. -backend = provider.get_backend('FakeOpenPulse2Q') - - iplot_gate_map(backend, as_widget=True) -``` + iplot_gate_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/ibm_utils.mdx b/docs/api/qiskit-ibm-provider/ibm_utils.mdx index f999edc9102..98295f4919e 100644 --- a/docs/api/qiskit-ibm-provider/ibm_utils.mdx +++ b/docs/api/qiskit-ibm-provider/ibm_utils.mdx @@ -42,73 +42,61 @@ Utility functions related to the IBM Quantum Provider. Message broker for the Publisher / Subscriber mechanism - + + Represents a “publisher”. -`Publisher` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L140-L155 "view source code") + Every component (class) can become a [`Publisher`](#qiskit_ibm_provider.utils.pubsub.Publisher "qiskit_ibm_provider.utils.pubsub.Publisher") and send events by inheriting this class. Functions can call this class like: -Represents a “publisher”. + ```python + Publisher().publish("event", args, ... ) + ``` -Every component (class) can become a [`Publisher`](#qiskit_ibm_provider.utils.pubsub.Publisher "qiskit_ibm_provider.utils.pubsub.Publisher") and send events by inheriting this class. Functions can call this class like: + ### publish -```python -Publisher().publish("event", args, ... ) -``` + + Triggers an event, and associates some data to it, so if there are any subscribers, their callback will be called synchronously. -### publish + **Return type** - + `None` + + -`publish(event, *args, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L152-L155 "view source code") + + Represents a “subscriber”. -Triggers an event, and associates some data to it, so if there are any subscribers, their callback will be called synchronously. + Every component (class) can become a [`Subscriber`](#qiskit_ibm_provider.utils.pubsub.Subscriber "qiskit_ibm_provider.utils.pubsub.Subscriber") and subscribe to events, that will call callback functions when they are emitted. -**Return type** + ### clear -`None` + + Unsubscribe everything - + **Return type** -`Subscriber` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L158-L182 "view source code") + `None` + -Represents a “subscriber”. + ### subscribe -Every component (class) can become a [`Subscriber`](#qiskit_ibm_provider.utils.pubsub.Subscriber "qiskit_ibm_provider.utils.pubsub.Subscriber") and subscribe to events, that will call callback functions when they are emitted. + + Subscribes to an event, associating a callback function to that event, so when the event occurs, the callback will be called. -### clear + This is a blocking call, so try to keep callbacks as lightweight as possible. - + **Return type** -`clear()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L180-L182 "view source code") + `bool` + -Unsubscribe everything + ### unsubscribe -**Return type** + + Unsubscribe a pair event-callback, so the callback will not be called anymore when the event occurs. -`None` + **Return type** -### subscribe - - - -`subscribe(event, callback)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L168-L173 "view source code") - -Subscribes to an event, associating a callback function to that event, so when the event occurs, the callback will be called. - -This is a blocking call, so try to keep callbacks as lightweight as possible. - -**Return type** - -`bool` - -### unsubscribe - - - -`unsubscribe(event, callback)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/pubsub.py#L175-L178 "view source code") - -Unsubscribe a pair event-callback, so the callback will not be called anymore when the event occurs. - -**Return type** - -`bool` + `bool` + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackend.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackend.mdx index aff854ceabf..4b30d440e28 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackend.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackend.mdx @@ -8,657 +8,619 @@ python_api_name: qiskit_ibm_provider.IBMBackend # IBMBackend - + + Backend class interfacing with an IBM Quantum device. -`IBMBackend(configuration, provider, api_client, instance=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L79-L895 "view source code") + You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: -Backend class interfacing with an IBM Quantum device. + ```python + from qiskit import transpile + from qiskit_ibm_provider import IBMProvider + from qiskit.circuit.random import random_circuit -You can run experiments on a backend using the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. The [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method takes one or more [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)") and returns an `IBMJob` instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow: + provider = IBMProvider() + backend = provider.backend.ibmq_vigo + qx = random_circuit(n_qubits=5, depth=4) + transpiled = transpile(qx, backend=backend) + job = backend.run(transpiled) + retrieved_job = provider.backend.retrieve_job(job.job_id()) + ``` -```python -from qiskit import transpile -from qiskit_ibm_provider import IBMProvider -from qiskit.circuit.random import random_circuit + + * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. + * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. + -provider = IBMProvider() -backend = provider.backend.ibmq_vigo -qx = random_circuit(n_qubits=5, depth=4) -transpiled = transpile(qx, backend=backend) -job = backend.run(transpiled) -retrieved_job = provider.backend.retrieve_job(job.job_id()) -``` + Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: - - * Unlike `qiskit.execute()`, the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method does not transpile the circuits for you, so be sure to do so before submitting them. - * You should not instantiate the `IBMBackend` class directly. Instead, use the methods provided by an [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") instance to retrieve and handle backends. - + ```python + status = backend.status() + is_operational = status.operational + jobs_in_queue = status.pending_jobs + ``` -Other methods return information about the backend. For example, the [`status()`](#qiskit_ibm_provider.IBMBackend.status "qiskit_ibm_provider.IBMBackend.status") method returns a [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") instance. The instance contains the `operational` and `pending_jobs` attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively: + **Here is list of attributes available on the `IBMBackend` class:** -```python -status = backend.status() -is_operational = status.operational -jobs_in_queue = status.pending_jobs -``` + * name: backend name. -**Here is list of attributes available on the `IBMBackend` class:** + * backend\_version: backend version in the form X.Y.Z. -* name: backend name. + * num\_qubits: number of qubits. -* backend\_version: backend version in the form X.Y.Z. + * target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. -* num\_qubits: number of qubits. + * basis\_gates: list of basis gates names on the backend. -* target: A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. + * gates: list of basis gates on the backend. -* basis\_gates: list of basis gates names on the backend. + * local: backend is local or remote. -* gates: list of basis gates on the backend. + * simulator: backend is a simulator. -* local: backend is local or remote. + * conditional: backend supports conditional operations. -* simulator: backend is a simulator. + * open\_pulse: backend supports open pulse. -* conditional: backend supports conditional operations. + * memory: backend supports memory. -* open\_pulse: backend supports open pulse. + * max\_shots: maximum number of shots supported. -* memory: backend supports memory. + * coupling\_map (list): The coupling map for the device -* max\_shots: maximum number of shots supported. + * supported\_instructions (List\[str]): Instructions supported by the backend. -* coupling\_map (list): The coupling map for the device + * dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. -* supported\_instructions (List\[str]): Instructions supported by the backend. + * rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. -* dynamic\_reprate\_enabled (bool): whether delay between programs can be set dynamically (ie via `rep_delay`). Defaults to False. + * default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. -* rep\_delay\_range (List\[float]): 2d list defining supported range of repetition delays for backend in μs. First entry is lower end of the range, second entry is higher end of the range. Optional, but will be specified when `dynamic_reprate_enabled=True`. + * n\_uchannels: Number of u-channels. -* default\_rep\_delay (float): Value of `rep_delay` if not specified by user and `dynamic_reprate_enabled=True`. + * u\_channel\_lo: U-channel relationship on device los. -* n\_uchannels: Number of u-channels. + * meas\_levels: Supported measurement levels. -* u\_channel\_lo: U-channel relationship on device los. + * qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. -* meas\_levels: Supported measurement levels. + * meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. -* qubit\_lo\_range: Qubit lo ranges for each qubit with form (min, max) in GHz. + * dt: Qubit drive channel timestep in nanoseconds. -* meas\_lo\_range: Measurement lo ranges for each qubit with form (min, max) in GHz. + * dtm: Measurement drive channel timestep in nanoseconds. -* dt: Qubit drive channel timestep in nanoseconds. + * rep\_times: Supported repetition times (program execution time) for backend in μs. -* dtm: Measurement drive channel timestep in nanoseconds. + * meas\_kernels: Supported measurement kernels. -* rep\_times: Supported repetition times (program execution time) for backend in μs. + * discriminators: Supported discriminators. -* meas\_kernels: Supported measurement kernels. + * hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. -* discriminators: Supported discriminators. + * channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) -* hamiltonian: An optional dictionary with fields characterizing the system hamiltonian. + * acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. -* channel\_bandwidth (list): Bandwidth of all channels (qubit, measurement, and U) + * conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m -* acquisition\_latency (list): Array of dimension n\_qubits x n\_registers. Latency (in units of dt) to write a measurement result from qubit n into register slot m. + * meas\_map (list): Grouping of measurement which are multiplexed -* conditional\_latency (list): Array of dimension n\_channels \[d->u->m] x n\_registers. Latency (in units of dt) to do a conditional operation on channel n from register slot m + * max\_circuits (int): The maximum number of experiments per job -* meas\_map (list): Grouping of measurement which are multiplexed + * sample\_name (str): Sample name for the backend -* max\_circuits (int): The maximum number of experiments per job + * n\_registers (int): Number of register slots available for feedback (if conditional is True) -* sample\_name (str): Sample name for the backend + * register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. -* n\_registers (int): Number of register slots available for feedback (if conditional is True) + * configurable (bool): True if the backend is configurable, if the backend is a simulator -* register\_map (list): An array of dimension n\_qubits X n\_registers that specifies whether a qubit can store a measurement in a certain register slot. + * credits\_required (bool): True if backend requires credits to run a job. -* configurable (bool): True if the backend is configurable, if the backend is a simulator + * online\_date (datetime): The date that the device went online -* credits\_required (bool): True if backend requires credits to run a job. + * display\_name (str): Alternate name field for the backend -* online\_date (datetime): The date that the device went online + * description (str): A description for the backend -* display\_name (str): Alternate name field for the backend + * tags (list): A list of string tags to describe the backend -* description (str): A description for the backend + * version: version of `Backend` class (Ex: 1, 2) -* tags (list): A list of string tags to describe the backend + * channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. -* version: version of `Backend` class (Ex: 1, 2) + * parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` -* channels: An optional dictionary containing information of each channel – their purpose, type, and qubits operated on. + * processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. -* parametric\_pulses (list): A list of pulse shapes which are supported on the backend. For example: `['gaussian', 'constant']` + > * family: Processor family of this backend. + > * revision: Revision version of this processor. + > * segment: Segment this processor belongs to within a larger chip. -* processor\_type (dict): Processor type for this backend. A dictionary of the form `{"family": , "revision": , segment: }` such as `{"family": "Canary", "revision": "1.0", segment: "A"}`. + IBMBackend constructor. - > * family: Processor family of this backend. - > * revision: Revision version of this processor. - > * segment: Segment this processor belongs to within a larger chip. + **Parameters** -IBMBackend constructor. + * **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v1.0)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v1.0)")]) – Backend configuration. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. -**Parameters** + ## Attributes -* **configuration** (`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v1.0)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v1.0)")]) – Backend configuration. -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **api\_client** (`AccountClient`) – IBM Quantum client used to communicate with the server. + ### coupling\_map -## Attributes + + Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.0)") object + - + ### dt -### coupling\_map + + Return the system time resolution of input signals -Return the [`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.0)") object + This is required to be implemented if the backend supports Pulse scheduling. - + **Return type** -### dt + `Optional`\[`float`] -Return the system time resolution of input signals + **Returns** -This is required to be implemented if the backend supports Pulse scheduling. + The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + -**Return type** + ### dtm -`Optional`\[`float`] + + Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + -**Returns** + ### id\_warning\_issued -The input signal timestep in seconds. If the backend doesn’t define `dt`, `None` will be returned. + - + ### instruction\_durations -### dtm + + Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)") object. + -Return the system time resolution of output signals :returns: The output signal timestep in seconds. :rtype: dtm + ### instruction\_schedule\_map - + + Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v1.0)") for the instructions defined in this backend’s target. + -### id\_warning\_issued + ### instructions -`= False` + + A list of Instruction tuples on the backend of the form `(instruction, (qubits)` - + **Return type** -### instruction\_durations + `List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)"), `Tuple`\[`int`]]] + -Return the [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)") object. + ### max\_circuits - + + The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. -### instruction\_schedule\_map + **Return type** -Return the [`InstructionScheduleMap`](/api/qiskit/qiskit.pulse.InstructionScheduleMap "(in Qiskit v1.0)") for the instructions defined in this backend’s target. + `int` + - + ### meas\_map -### instructions + + Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + -A list of Instruction tuples on the backend of the form `(instruction, (qubits)` + ### num\_qubits -**Return type** + + Return the number of qubits the backend has. -`List`\[`Tuple`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)"), `Tuple`\[`int`]]] + **Return type** - + `int` + -### max\_circuits + ### operation\_names -The maximum number of circuits The maximum number of circuits that can be run in a single job. If there is no limit this will return None. + + A list of instruction names that the backend supports. -**Return type** + **Return type** -`int` + `List`\[`str`] + - + ### operations -### meas\_map + + A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)") instances that the backend supports. -Return the grouping of measurements which are multiplexed This is required to be implemented if the backend supports Pulse scheduling. :returns: The grouping of measurements which are multiplexed :rtype: meas\_map + **Return type** - + `List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)")] + -### num\_qubits + ### options -Return the number of qubits the backend has. + + Return the options for the backend -**Return type** + The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + -`int` + ### provider - + + Return the backend Provider. -### operation\_names + **Returns** -A list of instruction names that the backend supports. + the Provider responsible for the backend. -**Return type** + **Return type** -`List`\[`str`] + Provider + - + ### session -### operations + + Return session -A list of [`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)") instances that the backend supports. + **Return type** -**Return type** + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -`List`\[[`Instruction`](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)")] + ### target - + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") :returns: Target + -### options + ### version -Return the options for the backend + -The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the [`run()`](#qiskit_ibm_provider.IBMBackend.run "qiskit_ibm_provider.IBMBackend.run") method. + ### name - + + Name of the backend. + -### provider + ### description -Return the backend Provider. + + Optional human-readable description. + -**Returns** + ### online\_date -the Provider responsible for the backend. + + Date that the backend came online. + -**Return type** + ### backend\_version -Provider + + Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + - + ## Methods -### session + ### acquire\_channel -Return session + + Return the acquisition channel for the given qubit. -**Return type** + **Returns** -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + The Qubit measurement acquisition line. - + **Return type** -### target + AcquireChannel + -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") :returns: Target + ### cancel\_session - + + Cancel session. All pending jobs will be cancelled. -### version + **Return type** -`= 2` + `None` + - + ### close\_session -### name + + Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. -Name of the backend. + **Return type** - + `None` + -### description + ### configuration -Optional human-readable description. + + Return the backend configuration. - + Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. -### online\_date + The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). -Date that the backend came online. + **Return type** - + `Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v1.0)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v1.0)")] -### backend\_version + **Returns** -Version of the backend being provided. This is not the same as `BackendV2.version`, which is the version of the `Backend` abstract interface. + The configuration for the backend. + -## Methods + ### control\_channel -### acquire\_channel + + Return the secondary drive channel for the given qubit. - + This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. -`acquire_channel(qubit)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L710-L716 "view source code") + **Parameters** -Return the acquisition channel for the given qubit. + **qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. -**Returns** + **Returns** -The Qubit measurement acquisition line. + The Qubit measurement acquisition line. -**Return type** + **Return type** -AcquireChannel + List\[ControlChannel] + -### cancel\_session + ### defaults - + + Return the pulse defaults for the backend. -`cancel_session()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L879-L885 "view source code") + The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). -Cancel session. All pending jobs will be cancelled. + **Parameters** -**Return type** + **refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. -`None` + **Return type** -### close\_session + `Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v1.0)")] - + **Returns** -`close_session()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L887-L895 "view source code") + The backend pulse defaults or `None` if the backend does not support pulse. + -Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs. + ### drive\_channel -**Return type** + + Return the drive channel for the given qubit. -`None` + **Returns** -### configuration + The Qubit drive channel - + **Return type** -`configuration()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L677-L692 "view source code") + DriveChannel + -Return the backend configuration. + ### get\_translation\_stage\_plugin -Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc. + + Return the default translation stage plugin name for IBM backends. -The schema for backend configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_configuration_schema.json). + **Return type** -**Return type** + `str` + -`Union`\[[`QasmBackendConfiguration`](/api/qiskit/qiskit.providers.models.QasmBackendConfiguration "(in Qiskit v1.0)"), [`PulseBackendConfiguration`](/api/qiskit/qiskit.providers.models.PulseBackendConfiguration "(in Qiskit v1.0)")] + ### measure\_channel -**Returns** + + Return the measure stimulus channel for the given qubit. -The configuration for the backend. + **Returns** -### control\_channel + The Qubit measurement stimulus line - + **Return type** -`control_channel(qubits)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L718-L731 "view source code") + MeasureChannel + -Return the secondary drive channel for the given qubit. + ### open\_session -This is typically utilized for controlling multiqubit interactions. This channel is derived from other channels. + + Open session -**Parameters** + **Return type** -**qubits** (`Iterable`\[`int`]) – Tuple or list of qubits of the form `(control_qubit, target_qubit)`. + [`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + -**Returns** + ### properties -The Qubit measurement acquisition line. + + Return the backend properties, subject to optional filtering. -**Return type** + This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. -List\[ControlChannel] + The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). -### defaults + **Parameters** - + * **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + * **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)") whose timestamp is closest to, but older than, the specified datetime. -`defaults(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L652-L675 "view source code") + **Return type** -Return the pulse defaults for the backend. + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")] -The schema for default pulse configuration can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json). + **Returns** -**Parameters** + The backend properties or `None` if the backend properties are not currently available. -**refresh** (`bool`) – If `True`, re-query the server for the backend pulse defaults. Otherwise, return a cached version. + **Raises** -**Return type** + **TypeError** – If an input argument is not of the correct type. + -`Optional`\[[`PulseDefaults`](/api/qiskit/qiskit.providers.models.PulseDefaults "(in Qiskit v1.0)")] + ### qubit\_properties -**Returns** + + Return QubitProperties for a given qubit. -The backend pulse defaults or `None` if the backend does not support pulse. + If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. -### drive\_channel + **Parameters** - + **qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order -`drive_channel(qubit)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L694-L700 "view source code") + **Return type** -Return the drive channel for the given qubit. + `Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v1.0)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v1.0)")]] -**Returns** + **Returns** -The Qubit drive channel + The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. -**Return type** + **Raises** -DriveChannel + **NotImplementedError** – if the backend doesn’t support querying the qubit properties + -### get\_translation\_stage\_plugin + ### run - + + Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. -`classmethod get_translation_stage_plugin()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L802-L805 "view source code") + **Parameters** -Return the default translation stage plugin name for IBM backends. + * **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)"), `str`]]]) – An individual or a list of `QuantumCircuit`. -**Return type** + * **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) -`str` + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. -### measure\_channel + * **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - + * **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. -`measure_channel(qubit)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L702-L708 "view source code") + * **or** (*The following parameters are applicable only if dynamic=False is specified*) – -Return the measure stimulus channel for the given qubit. + * **to.** (*defaulted*) – -**Returns** + * **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. -The Qubit measurement stimulus line + * **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. -**Return type** + * **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. -MeasureChannel + * **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – -### open\_session + Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - + * `0`, measurements of the raw signal (the measurement output pulse envelope) + * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) + * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) -`open_session(max_time=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L863-L872 "view source code") + * **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – -Open session + Level of measurement data for the backend to return. For `meas_level` 0 and 1: -**Return type** + * `single` returns information from every shot. + * `avg` returns average measurement output (averaged over number of shots). -[`Session`](qiskit_ibm_provider.Session "qiskit_ibm_provider.session.Session") + * **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. -### properties + * **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - + * **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. -`properties(refresh=False, datetime=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L574-L626 "view source code") + * **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) -Return the backend properties, subject to optional filtering. + * **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) -This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend. + * **\*\*run\_config** – Extra arguments used to configure the run. -The schema for backend properties can be found in [Qiskit/ibm-quantum-schemas](https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_properties_schema.json). + **Return type** -**Parameters** + `IBMJob` -* **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. -* **datetime** (`Optional`\[`datetime`]) – By specifying datetime, this function returns an instance of the [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)") whose timestamp is closest to, but older than, the specified datetime. + **Returns** -**Return type** + The job to be executed. -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")] + **Raises** -**Returns** + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. -The backend properties or `None` if the backend properties are not currently available. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. -**Raises** + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – -**TypeError** – If an input argument is not of the correct type. + * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. + -### qubit\_properties + ### set\_options - + + Set the options fields for the backend -`qubit_properties(qubit)` + This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. -Return QubitProperties for a given qubit. + **Parameters** -If there are no defined or the backend doesn’t support querying these details this method does not need to be implemented. + **fields** – The fields to update the options -**Parameters** + **Raises** -**qubit** (`Union`\[`int`, `List`\[`int`]]) – The qubit to get the `QubitProperties` object for. This can be a single integer for 1 qubit or a list of qubits and a list of `QubitProperties` objects will be returned in the same order + **AttributeError** – If the field passed in is not part of the options + -**Return type** + ### status -`Union`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v1.0)"), `List`\[[`QubitProperties`](/api/qiskit/qiskit.providers.QubitProperties "(in Qiskit v1.0)")]] + + Return the backend status. -**Returns** + + If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. + -The `QubitProperties` object for the specified qubit. If a list of qubits is provided a list will be returned. If properties are missing for a qubit this can be `None`. + **Return type** -**Raises** + [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") -**NotImplementedError** – if the backend doesn’t support querying the qubit properties + **Returns** -### run + The status of the backend. - + **Raises** -`run(circuits, dynamic=None, job_tags=None, init_circuit=None, init_num_resets=None, header=None, shots=None, memory=None, meas_level=None, meas_return=None, rep_delay=None, init_qubits=None, use_measure_esp=None, noise_model=None, seed_simulator=None, **run_config)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L331-L501 "view source code") + [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. + -Run on the backend. If a keyword specified here is also present in the `options` attribute/object, the value specified here will be used for this run. + ### target\_history -**Parameters** - -* **circuits** (`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)"), `str`, `List`\[`Union`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)"), `str`]]]) – An individual or a list of `QuantumCircuit`. - -* **dynamic** (`Optional`\[`bool`]) – Whether the circuit is dynamic (uses in-circuit conditionals) - -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in the `jobs()` function call. - -* **init\_circuit** (`Optional`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")]) – A quantum circuit to execute for initializing qubits before each circuit. If specified, `init_num_resets` is ignored. Applicable only if `dynamic=True` is specified. - -* **init\_num\_resets** (`Optional`\[`int`]) – The number of qubit resets to insert before each circuit execution. - -* **or** (*The following parameters are applicable only if dynamic=False is specified*) – - -* **to.** (*defaulted*) – - -* **header** (`Optional`\[`Dict`]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the old `Qobj` header. - -* **shots** (`Union`\[`int`, `float`, `None`]) – Number of repetitions of each circuit, for sampling. Default: 4000 or `max_shots` from the backend configuration, whichever is smaller. - -* **memory** (`Optional`\[`bool`]) – If `True`, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. - -* **meas\_level** (`Union`\[`int`, `MeasLevel`, `None`]) – - - Level of the measurement output for pulse experiments. See [OpenPulse specification](https://arxiv.org/pdf/1809.03452.pdf) for details: - - * `0`, measurements of the raw signal (the measurement output pulse envelope) - * `1`, measurement kernel is selected (a complex number obtained after applying the measurement kernel to the measurement output signal) - * `2` (default), a discriminator is selected and the qubit state is stored (0 or 1) - -* **meas\_return** (`Union`\[`str`, `MeasReturnType`, `None`]) – - - Level of measurement data for the backend to return. For `meas_level` 0 and 1: - - * `single` returns information from every shot. - * `avg` returns average measurement output (averaged over number of shots). - -* **rep\_delay** (`Optional`\[`float`]) – Delay between programs in seconds. Only supported on certain backends (if `backend.configuration().dynamic_reprate_enabled=True`). If supported, `rep_delay` must be from the range supplied by the backend (`backend.configuration().rep_delay_range`). Default is given by `backend.configuration().default_rep_delay`. - -* **init\_qubits** (`Optional`\[`bool`]) – Whether to reset the qubits to the ground state for each shot. Default: `True`. - -* **use\_measure\_esp** (`Optional`\[`bool`]) – Whether to use excited state promoted (ESP) readout for measurements which are the terminal instruction to a qubit. ESP readout can offer higher fidelity than standard measurement sequences. See [here](https://arxiv.org/pdf/2008.08571.pdf). Default: `True` if backend supports ESP readout, else `False`. Backend support for ESP readout is determined by the flag `measure_esp_enabled` in `backend.configuration()`. - -* **noise\_model** (`Optional`\[`Any`]) – Noise model. (Simulators only) - -* **seed\_simulator** (`Optional`\[`int`]) – Random seed to control sampling. (Simulators only) - -* **\*\*run\_config** – Extra arguments used to configure the run. - -**Return type** - -`IBMJob` - -**Returns** - -The job to be executed. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred while submitting the job. - -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If an unexpected value received from the server. - -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – - - * If an input parameter value is not valid. - If ESP readout is used and the backend does not support this. - -### set\_options - - - -`set_options(**fields)` - -Set the options fields for the backend - -This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options. - -**Parameters** - -**fields** – The fields to update the options - -**Raises** - -**AttributeError** – If the field passed in is not part of the options - -### status - - - -`status()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L628-L650 "view source code") - -Return the backend status. - - - If the returned [`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") instance has `operational=True` but `status_msg="internal"`, then the backend is accepting jobs but not processing them. - - -**Return type** - -[`BackendStatus`](/api/qiskit/qiskit.providers.models.BackendStatus "(in Qiskit v1.0)") - -**Returns** - -The status of the backend. - -**Raises** - -[**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If the status for the backend cannot be formatted properly. - -### target\_history - - - -`target_history(datetime=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend.py#L324-L329 "view source code") - -A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") :returns: Target with properties found on datetime + + A [`qiskit.transpiler.Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") object for the backend. :rtype: [`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)") :returns: Target with properties found on datetime + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiError.mdx index b04ec21d518..e6d966f626c 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiError # IBMBackendApiError - + + Errors that occur unexpectedly when querying the server. -`IBMBackendApiError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L78-L81 "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx index fe11f43b8d6..1852d84849c 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendApiProtocolError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendApiProtocolError # IBMBackendApiProtocolError - + + Errors raised when an unexpected value is received from the server. -`IBMBackendApiProtocolError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L84-L87 "view source code") - -Errors raised when an unexpected value is received from the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendError.mdx index 39ec538c3fa..1ba2cae9ee5 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendError # IBMBackendError - + + Base class for errors raised by the backend modules. -`IBMBackendError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L72-L75 "view source code") - -Base class for errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendService.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendService.mdx index f8ede9715f3..d8f11435dc5 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendService.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendService.mdx @@ -8,161 +8,153 @@ python_api_name: qiskit_ibm_provider.IBMBackendService # IBMBackendService - + + Backend namespace for an IBM Quantum account. -`IBMBackendService(provider, hgp)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend_service.py#L61-L741 "view source code") + Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: -Backend namespace for an IBM Quantum account. + ```python + backends = provider.backends() # Invoke backends() to get the backends. + sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. + ``` -Represent a namespace that provides backend related services for the IBM Quantum backends available to this account. An instance of this class is used as a callable attribute to the [`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.IBMProvider") class. This allows a convenient way to query for all backends or to access a specific backend: + Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: -```python -backends = provider.backends() # Invoke backends() to get the backends. -sim_backend = provider.backend.ibmq_qasm_simulator # Get a specific backend instance. -``` + ```python + most_recent_jobs = provider.backend.jobs(limit=10) + ``` -Also, you are able to retrieve jobs from an account without specifying the backend name. For example, to retrieve the ten most recent jobs you have submitted, regardless of the backend they were submitted to, you could do: + It is also possible to retrieve a single job without specifying the backend name: -```python -most_recent_jobs = provider.backend.jobs(limit=10) -``` + ```python + job = provider.backend.retrieve_job() + ``` -It is also possible to retrieve a single job without specifying the backend name: + IBMBackendService constructor. -```python -job = provider.backend.retrieve_job() -``` + **Parameters** -IBMBackendService constructor. + * **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. + * **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. -**Parameters** + ## Methods -* **provider** ([`IBMProvider`](qiskit_ibm_provider.IBMProvider "qiskit_ibm_provider.ibm_provider.IBMProvider")) – IBM Quantum account provider. -* **hgp** (`HubGroupProject`) – default hub/group/project to use for the service. + ### backends -## Methods + + Return all backends accessible via this account, subject to optional filtering. -### backends + **Parameters** - + * **name** (`Optional`\[`str`]) – Backend name to filter by. -`backends(name=None, filters=None, min_num_qubits=None, instance=None, dynamic_circuits=None, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend_service.py#L118-L218 "view source code") + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -Return all backends accessible via this account, subject to optional filtering. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -**Parameters** + * **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. -* **name** (`Optional`\[`str`]) – Backend name to filter by. + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + More complex filters, such as lambda functions. For example: -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -* **dynamic\_circuits** (`Optional`\[`bool`]) – Filter by whether the backend supports dynamic circuits. + * **\*\*kwargs** – -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. - More complex filters, such as lambda functions. For example: + Examples: - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **\*\*kwargs** – + For the full list of backend attributes, see the IBMBackend class documentation \<[api/qiskit/providers\_models](/api/qiskit/providers_models)> - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. + **Return type** - Examples: + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Returns** - For the full list of backend attributes, see the IBMBackend class documentation \<[api/qiskit/providers\_models](/api/qiskit/providers_models)> + The list of available backends that match the filter. -**Return type** + **Raises** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. + * **QiskitBackendNotFoundError** – If the backend is not found in any instance. + -**Returns** + ### jobs -The list of available backends that match the filter. + + Return a list of jobs, subject to optional filtering. -**Raises** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If only one or two parameters from hub, group, project are specified. -* **QiskitBackendNotFoundError** – If the backend is not found in any instance. + **Parameters** -### jobs + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by + * **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. + * **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – - + **Return type** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend_service.py#L220-L368 "view source code") + `List`\[`IBMJob`] -Return a list of jobs, subject to optional filtering. + **Returns** -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + A list of `IBMJob` instances. -**Parameters** + **Raises** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Union`\[`Literal`\[‘pending’, ‘completed’], `List`\[`Union`\[[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)"), `str`]], [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)"), `str`, `None`]) – Filter jobs with either “pending” or “completed” status. You can also specify by -* **example** (*exact status. For*) – or status=\[“RUNNING”, “ERROR”]. -* **status="RUNNING"** (*status=JobStatus.RUNNING or*) – or status=\[“RUNNING”, “ERROR”]. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the archived `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. + * **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + -**Return type** + ### retrieve\_job -`List`\[`IBMJob`] + + Return a single job. -**Returns** + **Parameters** -A list of `IBMJob` instances. + **job\_id** (`str`) – The ID of the job to retrieve. -**Raises** + **Return type** -* [**IBMBackendValueError**](qiskit_ibm_provider.IBMBackendValueError "qiskit_ibm_provider.IBMBackendValueError") – If a keyword value is not recognized. -* **TypeError** – If the input start\_datetime or end\_datetime parameter value is not valid. + `IBMJob` -### retrieve\_job + **Returns** - + The job with the given id. -`retrieve_job(job_id)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_backend_service.py#L621-L662 "view source code") + **Raises** -Return a single job. - -**Parameters** - -**job\_id** (`str`) – The ID of the job to retrieve. - -**Return type** - -`IBMJob` - -**Returns** - -The job with the given id. - -**Raises** - -* [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. -* [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. -* **IBMJobNotFoundError** – If job cannot be found. -* **IBMInputValueError** – If job exists but was run from a different service. + * [**IBMBackendApiError**](qiskit_ibm_provider.IBMBackendApiError "qiskit_ibm_provider.IBMBackendApiError") – If an unexpected error occurred when retrieving the job. + * [**IBMBackendApiProtocolError**](qiskit_ibm_provider.IBMBackendApiProtocolError "qiskit_ibm_provider.IBMBackendApiProtocolError") – If unexpected return value received from the server. + * **IBMJobNotFoundError** – If job cannot be found. + * **IBMInputValueError** – If job exists but was run from a different service. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendValueError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendValueError.mdx index 1d9868ebf5b..c5584577e74 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendValueError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMBackendValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMBackendValueError # IBMBackendValueError - + + Value errors raised by the backend modules. -`IBMBackendValueError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L90-L93 "view source code") - -Value errors raised by the backend modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMError.mdx index 0e5c2635f8e..9d68fa9ae35 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMError # IBMError - + + Base class for errors raised by the provider modules. -`IBMError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L18-L21 "view source code") - -Base class for errors raised by the provider modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProvider.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProvider.mdx index febfb2a22ca..8787524a16b 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProvider.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProvider.mdx @@ -8,355 +8,333 @@ python_api_name: qiskit_ibm_provider.IBMProvider # IBMProvider - + + Provides access to the IBM Quantum services available to an account. -`IBMProvider(token=None, url=None, name=None, instance=None, proxies=None, verify=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L46-L671 "view source code") + Authenticate against IBM Quantum for use from saved credentials or during session. -Provides access to the IBM Quantum services available to an account. + Credentials can be saved to disk by calling the save\_account() method: -Authenticate against IBM Quantum for use from saved credentials or during session. + ```python + from qiskit_ibm_provider import IBMProvider + IBMProvider.save_account(token=) + ``` -Credentials can be saved to disk by calling the save\_account() method: + You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: -```python -from qiskit_ibm_provider import IBMProvider -IBMProvider.save_account(token=) -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -You can set the default project using the hub, group, and project keywords in save\_account(). Once credentials are saved you can simply instantiate the provider like below to load the saved account and default project: + Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + ``` -Instead of saving credentials to disk, you can also set the environment variables QISKIT\_IBM\_TOKEN, QISKIT\_IBM\_URL and QISKIT\_IBM\_INSTANCE and then instantiate the provider as below: + You can also enable an account just for the current session by instantiating the provider with the API token: -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider() -``` + ```python + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider(token=) + ``` -You can also enable an account just for the current session by instantiating the provider with the API token: + token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. -```python -from qiskit_ibm_provider import IBMProvider -provider = IBMProvider(token=) -``` + + The hub/group/project is selected based on the below selection order, in decreasing order of priority. -token is the only required attribute that needs to be set using one of the above methods. If no url is set, it defaults to ‘[https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api)’. + * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. + * The hub/group/project required for the service. + * The default hub/group/project you set using save\_account(). + * A premium hub/group/project in your account. + * An open access hub/group/project. + - - The hub/group/project is selected based on the below selection order, in decreasing order of priority. + The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. - * The hub/group/project you explicity specify when calling a service. Ex: provider.get\_backend(), etc. - * The hub/group/project required for the service. - * The default hub/group/project you set using save\_account(). - * A premium hub/group/project in your account. - * An open access hub/group/project. - + You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: -The IBMProvider offers the [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") which gives access to the IBM Quantum devices and simulators. + ```python + backend_service = provider.backend + ``` -You can obtain an instance of the service as an attribute of the `IBMProvider` instance. For example: + Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. -```python -backend_service = provider.backend -``` + The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: -Since [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") is the main service, some of the backend-related methods are available through this class for convenience. + ```python + backends = provider.backends() + ``` -The [`backends()`](#qiskit_ibm_provider.IBMProvider.backends "qiskit_ibm_provider.IBMProvider.backends") method returns all the backends available to this account: + The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: -```python -backends = provider.backends() -``` + ```python + simulator_backend = provider.get_backend('ibmq_qasm_simulator') + ``` -The [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") method returns a backend that matches the filters passed as argument. An example of retrieving a backend that matches a specified name: + IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. -```python -simulator_backend = provider.get_backend('ibmq_qasm_simulator') -``` + It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: -IBMBackend’s are uniquely identified by their name. If you invoke [`get_backend()`](#qiskit_ibm_provider.IBMProvider.get_backend "qiskit_ibm_provider.IBMProvider.get_backend") twice, you will get the same IBMBackend instance, and any previously updated options will be reset to the default values. + ```python + simulator_backend = provider.backend.ibmq_qasm_simulator + ``` -It is also possible to use the `backend` attribute to reference a backend. As an example, to retrieve the same backend from the example above: + + The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. + -```python -simulator_backend = provider.backend.ibmq_qasm_simulator -``` + IBMProvider constructor - - The `backend` attribute can be used to autocomplete the names of backends available to this account. To autocomplete, press `tab` after `provider.backend.`. This feature may not be available if an error occurs during backend discovery. Also note that this feature is only available in interactive sessions, such as in Jupyter Notebook and the Python interpreter. - + **Parameters** -IBMProvider constructor + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). + * **name** (`Optional`\[`str`]) – Name of the account to load. + * **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. -**Parameters** + **Returns** -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api). -* **name** (`Optional`\[`str`]) – Name of the account to load. -* **instance** (`Optional`\[`str`]) – Provider in the hub/group/project format. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Whether to verify the server’s TLS certificate. + An instance of IBMProvider -**Returns** + **Raises** -An instance of IBMProvider + **IBMInputValueError** – If an input is invalid. -**Raises** + ## Attributes -**IBMInputValueError** – If an input is invalid. + ### backend -## Attributes + + Return the backend service. - + **Return type** -### backend + [`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") -Return the backend service. + **Returns** -**Return type** + The backend service instance. + -[`IBMBackendService`](qiskit_ibm_provider.IBMBackendService "qiskit_ibm_provider.ibm_backend_service.IBMBackendService") + ### version -**Returns** + -The backend service instance. + ## Methods - + ### active\_account -### version + + Return the IBM Quantum account currently in use for the session. -`= 1` + **Return type** -## Methods + `Optional`\[`Dict`\[`str`, `str`]] -### active\_account + **Returns** - + A dictionary with information about the account currently in the session. + -`active_account()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L426-L435 "view source code") + ### backends -Return the IBM Quantum account currently in use for the session. + + Return all backends accessible via this account, subject to optional filtering. -**Return type** + **Parameters** -`Optional`\[`Dict`\[`str`, `str`]] + * **name** (`Optional`\[`str`]) – Backend name to filter by. -**Returns** + * **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. -A dictionary with information about the account currently in the session. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -### backends + * **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – - + More complex filters, such as lambda functions. For example: -`backends(name=None, filters=None, min_num_qubits=None, instance=None, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L523-L567 "view source code") + ```python + IBMProvider.backends(filters=lambda b: b.max_shots > 50000) + IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) + ``` -Return all backends accessible via this account, subject to optional filtering. + * **\*\*kwargs** – -**Parameters** + Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: -* **name** (`Optional`\[`str`]) – Backend name to filter by. + ```python + # Get the operational real backends + IBMProvider.backends(simulator=False, operational=True) + # Get the backends with at least 127 qubits + IBMProvider.backends(min_num_qubits=127) + # Get the backends that support OpenPulse + IBMProvider.backends(open_pulse=True) + ``` -* **min\_num\_qubits** (`Optional`\[`int`]) – Minimum number of qubits the backend must have. + For the full list of backend attributes, see the IBMBackend class documentation \<[api/qiskit/providers\_models](/api/qiskit/providers_models)> -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + **Return type** -* **filters** (`Optional`\[`Callable`\[\[`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")]], `bool`]]) – + `List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] - More complex filters, such as lambda functions. For example: + **Returns** - ```python - IBMProvider.backends(filters=lambda b: b.max_shots > 50000) - IBMProvider.backends(filters=lambda x: ("rz" in x.basis_gates ) - ``` + The list of available backends that match the filter. + -* **\*\*kwargs** – + ### delete\_account - Simple filters that require a specific value for an attribute in backend configuration, backend status, or provider credentials. Examples: + + Delete a saved account from disk. - ```python - # Get the operational real backends - IBMProvider.backends(simulator=False, operational=True) - # Get the backends with at least 127 qubits - IBMProvider.backends(min_num_qubits=127) - # Get the backends that support OpenPulse - IBMProvider.backends(open_pulse=True) - ``` + **Parameters** - For the full list of backend attributes, see the IBMBackend class documentation \<[api/qiskit/providers\_models](/api/qiskit/providers_models)> + **name** (`Optional`\[`str`]) – Name of the saved account to delete. -**Return type** + **Return type** -`List`\[[`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")] + `bool` -**Returns** + **Returns** -The list of available backends that match the filter. + True if the account was deleted. False if no account was found. + -### delete\_account + ### get\_backend - + + Return a single backend matching the specified filtering. -`static delete_account(name=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L445-L456 "view source code") + **Parameters** -Delete a saved account from disk. + * **name** (*str*) – Name of the backend. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **\*\*kwargs** – Dict used for filtering. -**Parameters** + **Returns** -**name** (`Optional`\[`str`]) – Name of the saved account to delete. + a backend matching the filtering. -**Return type** + **Return type** -`bool` + Backend -**Returns** + **Raises** -True if the account was deleted. False if no account was found. + * **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. + * [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + -### get\_backend + ### instances - + + Return the IBM Quantum instances list currently in use for the session. -`get_backend(name=None, instance=None, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L637-L668 "view source code") + **Return type** -Return a single backend matching the specified filtering. + `List`\[`str`] -**Parameters** + **Returns** -* **name** (*str*) – Name of the backend. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **\*\*kwargs** – Dict used for filtering. + A list with instances currently in the session. + -**Returns** + ### jobs -a backend matching the filtering. + + Return a list of jobs, subject to optional filtering. -**Return type** + Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. -Backend + **Parameters** -**Raises** + * **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. + * **skip** (`int`) – Starting index for the job retrieval. + * **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. + * **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. + * **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. + * **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. + * **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. + * **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. + * **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. + * **Otherwise** – + * **qiskit-ibm-provider.** (*only retrieve jobs run from*) – -* **QiskitBackendNotFoundError** – if no backend could be found or more than one backend matches the filtering criteria. -* [**IBMProviderValueError**](qiskit_ibm_provider.IBMProviderValueError "qiskit_ibm_provider.IBMProviderValueError") – If only one or two parameters from hub, group, project are specified. + **Return type** -### instances + `List`\[`IBMJob`] - + **Returns** -`instances()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L437-L443 "view source code") + A list of `IBMJob` instances. + -Return the IBM Quantum instances list currently in use for the session. + ### retrieve\_job -**Return type** + + Return a single job. -`List`\[`str`] + **Parameters** -**Returns** + **job\_id** (`str`) – The ID of the job to retrieve. -A list with instances currently in the session. + **Return type** -### jobs + `IBMJob` - + **Returns** -`jobs(limit=10, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L569-L624 "view source code") + The job with the given id. + -Return a list of jobs, subject to optional filtering. + ### save\_account -Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. + + Save the account to disk for future use. -**Parameters** + **Parameters** -* **limit** (`Optional`\[`int`]) – Number of jobs to retrieve. `None` means no limit. Note that the number of sub-jobs within a composite job count towards the limit. -* **skip** (`int`) – Starting index for the job retrieval. -* **backend\_name** (`Optional`\[`str`]) – Name of the backend to retrieve jobs from. -* **status** (`Optional`\[`Literal`\[‘pending’, ‘completed’]]) – Filter jobs with either “pending” or “completed” status. -* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to jobs. Matched jobs are associated with all tags. -* **descending** (`bool`) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached. -* **instance** (`Optional`\[`str`]) – The provider in the hub/group/project format. -* **legacy** (`bool`) – If `True`, only retrieve jobs run from the deprecated `qiskit-ibmq-provider`. -* **Otherwise** – -* **qiskit-ibm-provider.** (*only retrieve jobs run from*) – + * **token** (`Optional`\[`str`]) – IBM Quantum API token. + * **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) + * **instance** (`Optional`\[`str`]) – The hub/group/project. + * **name** (`Optional`\[`str`]) – Name of the account to save. + * **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) + * **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. + * **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. -**Return type** + **Return type** -`List`\[`IBMJob`] + `None` + -**Returns** + ### saved\_accounts -A list of `IBMJob` instances. + + List the accounts saved on disk. -### retrieve\_job + **Parameters** - + * **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. + * **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. -`retrieve_job(job_id)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L626-L635 "view source code") + **Return type** -Return a single job. + `dict` -**Parameters** + **Returns** -**job\_id** (`str`) – The ID of the job to retrieve. + A dictionary with information about the accounts saved on disk. -**Return type** + **Raises** -`IBMJob` - -**Returns** - -The job with the given id. - -### save\_account - - - -`static save_account(token=None, url=None, instance=None, name=None, proxies=None, verify=None, overwrite=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L458-L494 "view source code") - -Save the account to disk for future use. - -**Parameters** - -* **token** (`Optional`\[`str`]) – IBM Quantum API token. -* **url** (`Optional`\[`str`]) – The API URL. Defaults to [https://auth.quantum-computing.ibm.com/api](https://auth.quantum-computing.ibm.com/api) -* **instance** (`Optional`\[`str`]) – The hub/group/project. -* **name** (`Optional`\[`str`]) – Name of the account to save. -* **proxies** (`Optional`\[`dict`]) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://docs.python-requests.org/en/latest/api/#requests.Session.proxies](https://docs.python-requests.org/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication) -* **verify** (`Optional`\[`bool`]) – Verify the server’s TLS certificate. -* **overwrite** (`Optional`\[`bool`]) – `True` if the existing account is to be overwritten. - -**Return type** - -`None` - -### saved\_accounts - - - -`static saved_accounts(default=None, name=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/ibm_provider.py#L496-L521 "view source code") - -List the accounts saved on disk. - -**Parameters** - -* **default** (`Optional`\[`bool`]) – If set to True, only default accounts are returned. -* **name** (`Optional`\[`str`]) – If set, only accounts with the given name are returned. - -**Return type** - -`dict` - -**Returns** - -A dictionary with information about the accounts saved on disk. - -**Raises** - -**ValueError** – If an invalid account is found on disk. + **ValueError** – If an invalid account is found on disk. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderError.mdx index a8fd282c17b..88c672229b4 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderError # IBMProviderError - + + Base class for errors raise by IBMProvider. -`IBMProviderError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L30-L33 "view source code") - -Base class for errors raise by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderValueError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderValueError.mdx index 5822b0f8511..465806a90ce 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderValueError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.IBMProviderValueError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.IBMProviderValueError # IBMProviderValueError - + + Value errors raised by IBMProvider. -`IBMProviderValueError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/exceptions.py#L36-L39 "view source code") - -Value errors raised by IBMProvider. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.Session.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.Session.mdx index 6e4dbf3dcdc..9afb796f6fe 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.Session.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.Session.mdx @@ -8,85 +8,81 @@ python_api_name: qiskit_ibm_provider.Session # Session - + + Class for creating a flexible Qiskit Runtime session. -`Session(max_time=None, session_id=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/session.py#L22-L123 "view source code") + A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. -Class for creating a flexible Qiskit Runtime session. + You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. -A Qiskit Runtime `session` allows you to group a collection of iterative calls to the quantum computer. A session is started when the first job within the session is started. Subsequent jobs within the session are prioritized by the scheduler. Data used within a session, such as transpiled circuits, is also cached to avoid unnecessary overhead. + **For example::** -You can open a Qiskit Runtime session using this `Session` class and submit one or more jobs. + from qiskit\_ibm\_provider import IBMProvider -**For example::** + \# Bell Circuit qr = QuantumRegister(2, name=”qr”) cr = ClassicalRegister(2, name=”cr”) qc = QuantumCircuit(qr, cr, name=”bell”) qc.h(qr\[0]) qc.cx(qr\[0], qr\[1]) qc.measure(qr, cr) -from qiskit\_ibm\_provider import IBMProvider + backend = IBMProvider().get\_backend(“ibmq\_qasm\_simulator”) backend.open\_session() -\# Bell Circuit qr = QuantumRegister(2, name=”qr”) cr = ClassicalRegister(2, name=”cr”) qc = QuantumCircuit(qr, cr, name=”bell”) qc.h(qr\[0]) qc.cx(qr\[0], qr\[1]) qc.measure(qr, cr) + job = backend.run(qc) print(f”Job ID: \{job.job\_id()}”) print(f”Result: \{job.result()}”) # Close the session only if all jobs are finished and # you don’t need to run more in the session. backend.cancel\_session() -backend = IBMProvider().get\_backend(“ibmq\_qasm\_simulator”) backend.open\_session() + Session can also be used as a context manager: -job = backend.run(qc) print(f”Job ID: \{job.job\_id()}”) print(f”Result: \{job.result()}”) # Close the session only if all jobs are finished and # you don’t need to run more in the session. backend.cancel\_session() + ```python + with backend.open_session() as session: + job = backend.run(qc) + assert job.job_id() == session.session_id + ``` -Session can also be used as a context manager: + Session constructor. -```python -with backend.open_session() as session: - job = backend.run(qc) - assert job.job_id() == session.session_id -``` + **Parameters** -Session constructor. + **max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](/run/max-execution-time). -**Parameters** + **Raises** -**max\_time** (`Union`\[`int`, `str`, `None`]) – (EXPERIMENTAL setting, can break between releases without warning) Maximum amount of time, a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be in between 300 seconds and the [system imposed maximum](/run/max-execution-time). + **ValueError** – If an input value is invalid. -**Raises** + ## Attributes -**ValueError** – If an input value is invalid. + ### active -## Attributes + + Return the status of the session. - + **Return type** -### active + `bool` -Return the status of the session. + **Returns** -**Return type** + True if the session is active, False otherwise. + -`bool` + ### session\_id -**Returns** + + Return the session ID. -True if the session is active, False otherwise. + **Return type** - + `str` -### session\_id + **Returns** -Return the session ID. + Session ID. None until a job runs in the session. + -**Return type** + ## Methods -`str` + ### cancel -**Returns** + + Set the session.\_active status to False -Session ID. None until a job runs in the session. + **Return type** -## Methods - -### cancel - - - -`cancel()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/session.py#L109-L111 "view source code") - -Set the session.\_active status to False - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCircuitJob.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCircuitJob.mdx index f22d801eded..54763b88421 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCircuitJob.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCircuitJob.mdx @@ -8,606 +8,550 @@ python_api_name: qiskit_ibm_provider.job.IBMCircuitJob # IBMCircuitJob - + + Representation of a job that executes on an IBM Quantum backend. -`IBMCircuitJob(backend, api_client, job_id, creation_date=None, status=None, runtime_client=None, kind=None, name=None, time_per_step=None, result=None, error=None, session_id=None, tags=None, run_mode=None, client_info=None, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L59-L860 "view source code") + The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. -Representation of a job that executes on an IBM Quantum backend. + If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") members. For example: -The job may be executed on a simulator or a real device. A new `IBMCircuitJob` instance is returned when you call `IBMBackend.run()` to submit a job to a particular backend. - -If the job is successfully submitted, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_provider.job.IBMCircuitJob.status "qiskit_ibm_provider.job.IBMCircuitJob.status"). Job status can be one of the [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") members. For example: - -```python -from qiskit.providers.jobstatus import JobStatus - -job = backend.run(...) - -try: - job_status = job.status() # Query the backend server for job status. - if job_status is JobStatus.RUNNING: - print("The job is still running") -except IBMJobApiError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - - - An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. - - -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: - -```python -job = backend.run(...) - -try: - job_result = job.result() # It will block until the job finishes. - print("The job finished with result {}".format(job_result)) -except JobError as ex: - print("Something wrong happened!: {}".format(ex)) -``` - -Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. - -IBMCircuitJob constructor. - -**Parameters** - -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`str`) – Job ID. -* **creation\_date** (`Optional`\[`str`]) – Job creation date. -* **status** (`Optional`\[`str`]) – Job status returned by the server. -* **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server -* **kind** (`Optional`\[`str`]) – Job type. -* **name** (`Optional`\[`str`]) – Job name. -* **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. -* **result** (`Optional`\[`dict`]) – Job result. -* **error** (`Optional`\[`dict`]) – Job error. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. -* **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. -* **kwargs** (`Any`) – Additional job attributes. - -## Attributes - - - -### client\_version - -Return version of the client used for this job. - -**Return type** - -`Dict`\[`str`, `str`] - -**Returns** - -**Client version in dictionary format, where the key is the name** - -of the client and the value is the version. - - - -### usage\_estimation - -Return usage estimation information for this job. - -**Return type** - -`Dict`\[`str`, `Any`] - -**Returns** - -`quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. - - - -### version - -`= 1` - -## Methods - -### backend - - - -`backend()` - -Return the backend where this job was executed. - -**Return type** - -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") - -### backend\_options - - - -`backend_options()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L580-L599 "view source code") - -Return the backend configuration options used for this job. - -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. - -**Return type** - -`Dict` - -**Returns** - -Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. - -### cancel - - - -`cancel()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L260-L290 "view source code") - -Attempt to cancel the job. - - - Depending on the state the job is in, it might be impossible to cancel the job. - - -**Return type** - -`bool` - -**Returns** - -`True` if the job is cancelled, else `False`. - -**Raises** + ```python + from qiskit.providers.jobstatus import JobStatus -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. -* [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + job = backend.run(...) -### cancelled + try: + job_status = job.status() # Query the backend server for job status. + if job_status is JobStatus.RUNNING: + print("The job is still running") + except IBMJobApiError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` - + + An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an [`IBMJobApiError`](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") is raised. These errors usually clear quickly, so retrying the operation is likely to succeed. + -`cancelled()` + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCircuitJob.result "qiskit_ibm_provider.job.IBMCircuitJob.result") is an example of a blocking method: -Return whether the job has been cancelled. + ```python + job = backend.run(...) -**Return type** + try: + job_result = job.result() # It will block until the job finishes. + print("The job finished with result {}".format(job_result)) + except JobError as ex: + print("Something wrong happened!: {}".format(ex)) + ``` -`bool` + Job information retrieved from the server is attached to the `IBMCircuitJob` instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use [`creation_date()`](#qiskit_ibm_provider.job.IBMCircuitJob.creation_date "qiskit_ibm_provider.job.IBMCircuitJob.creation_date") to retrieve the job creation date, which is a supported attribute. -### circuits + IBMCircuitJob constructor. - + **Parameters** -`circuits()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L613-L627 "view source code") + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`str`) – Job ID. + * **creation\_date** (`Optional`\[`str`]) – Job creation date. + * **status** (`Optional`\[`str`]) – Job status returned by the server. + * **runtime\_client** (`Optional`\[`RuntimeClient`]) – Object for connecting to the runtime server + * **kind** (`Optional`\[`str`]) – Job type. + * **name** (`Optional`\[`str`]) – Job name. + * **time\_per\_step** (`Optional`\[`dict`]) – Time spent for each processing step. + * **result** (`Optional`\[`dict`]) – Job result. + * **error** (`Optional`\[`dict`]) – Job error. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **run\_mode** (`Optional`\[`str`]) – Scheduling mode the job runs in. + * **client\_info** (`Optional`\[`Dict`\[`str`, `str`]]) – Client information from the API. + * **kwargs** (`Any`) – Additional job attributes. -Return the circuits for this job. + ## Attributes -**Return type** + ### client\_version -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")] + + Return version of the client used for this job. -**Returns** + **Return type** -The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + `Dict`\[`str`, `str`] -### creation\_date + **Returns** - + **Client version in dictionary format, where the key is the name** -`creation_date()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L464-L473 "view source code") + of the client and the value is the version. + -Return job creation date, in local time. + ### usage\_estimation -**Return type** + + Return usage estimation information for this job. -`datetime` + **Return type** -**Returns** + `Dict`\[`str`, `Any`] -The job creation date as a datetime object, in local time. + **Returns** -### done + `quantum_seconds` which is the estimated quantum time of the job in seconds. Quantum time represents the time that the QPU complex is occupied exclusively by the job. + - + ### version -`done()` + -Return whether the job has successfully run. + ## Methods -**Return type** + ### backend -`bool` + + Return the backend where this job was executed. -### error\_message + **Return type** - + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") + -`error_message()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L364-L401 "view source code") + ### backend\_options -Provide details about the reason of failure. + + Return the backend configuration options used for this job. -**Return type** + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -`Optional`\[`str`] + **Return type** -**Returns** + `Dict` -An error report if the job failed or `None` otherwise. + **Returns** -### header + Backend options used for this job. An empty dictionary is returned if the options cannot be retrieved. + - + ### cancel -`header()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L601-L611 "view source code") + + Attempt to cancel the job. -Return the user header specified for this job. + + Depending on the state the job is in, it might be impossible to cancel the job. + -**Return type** + **Return type** -`Dict` + `bool` -**Returns** + **Returns** -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + `True` if the job is cancelled, else `False`. -### in\_final\_state + **Raises** - + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job is in a state that cannot be cancelled. + * [**IBMJobError**](qiskit_ibm_provider.job.IBMJobError "qiskit_ibm_provider.job.IBMJobError") – If unable to cancel job. + -`in_final_state()` + ### cancelled -Return whether the job is in a final job state such as `DONE` or `ERROR`. + + Return whether the job has been cancelled. -**Return type** + **Return type** -`bool` + `bool` + -### job\_id + ### circuits - + + Return the circuits for this job. -`job_id()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L475-L481 "view source code") + **Return type** -Return the job ID assigned by the server. + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")] -**Return type** + **Returns** -`str` + The circuits or for this job. An empty list is returned if the circuits cannot be retrieved (for example, if the job uses an old format that is no longer supported). + -**Returns** + ### creation\_date -Job ID. + + Return job creation date, in local time. -### name + **Return type** - + `datetime` -`name()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L232-L238 "view source code") + **Returns** -Return the name assigned to this job. + The job creation date as a datetime object, in local time. + -**Return type** + ### done -`Optional`\[`str`] + + Return whether the job has successfully run. -**Returns** + **Return type** -Job name or `None` if no name was assigned to this job. + `bool` + -### properties + ### error\_message - + + Provide details about the reason of failure. -`properties(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L71-L82 "view source code") + **Return type** -Return the backend properties for this job. + `Optional`\[`str`] -**Parameters** + **Returns** -**refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. + An error report if the job failed or `None` otherwise. + -**Return type** + ### header -`Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")] + + Return the user header specified for this job. -**Returns** + **Return type** -The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + `Dict` -### queue\_info + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`queue_info()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L430-L462 "view source code") + ### in\_final\_state -Return queue information for this job. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + **Return type** - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + `bool` + -**Return type** + ### job\_id -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Return the job ID assigned by the server. -**Returns** + **Return type** -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + `str` -### queue\_position + **Returns** - + Job ID. + -`queue_position(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L403-L428 "view source code") + ### name -Return the position of the job in the server queue. + + Return the name assigned to this job. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + `Optional`\[`str`] -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job name or `None` if no name was assigned to this job. + -`Optional`\[`int`] + ### properties -**Returns** + + Return the backend properties for this job. -Position in the queue or `None` if position is unknown or not applicable. + **Parameters** -### refresh + **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. - + **Return type** -`refresh()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L540-L578 "view source code") + `Optional`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")] -Obtain the latest job information from the server. + **Returns** -This method may add additional attributes to this job instance, if new information becomes available. + The backend properties used for this job, at the time the job was run, or `None` if properties are not available. + -**Raises** + ### queue\_info -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return queue information for this job. -**Return type** + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`None` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -### result + **Return type** - + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`result(timeout=None, refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L194-L258 "view source code") + **Returns** -Return the result of the job. + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + ### queue\_position - The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + + Return the position of the job in the server queue. - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") instance can be used to verify whether it contains partial results. + + The position returned is within the scope of the provider and may differ from the global queue position. + - For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: + **Parameters** - ```python - try: - counts = result.get_counts("failed_experiment") - except QiskitError: - print("Experiment failed!") - ``` - + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + **Return type** -**Parameters** + `Optional`\[`int`] -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job result. + This method may add additional attributes to this job instance, if new information becomes available. -**Raises** + **Raises** -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -### running + **Return type** - + `None` + -`running()` + ### result -Return whether the job is actively running. + + Return the result of the job. -**Return type** + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -`bool` + The first call to this method in an `IBMCircuitJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -### scheduling\_mode + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") instance can be used to verify whether it contains partial results. - + For example, if one of the experiments in the job failed, trying to get the counts of the unsuccessful experiment would raise an exception since there are no counts to return: -`scheduling_mode()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L190-L197 "view source code") + ```python + try: + counts = result.get_counts("failed_experiment") + except QiskitError: + print("Experiment failed!") + ``` + -Return the scheduling mode the job is in. + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. -**Return type** + **Parameters** -`Optional`\[`str`] + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. -**Returns** + **Return type** -The scheduling mode the job is in or `None` if the information is not available. + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") -### status + **Returns** - + Job result. -`status()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L332-L362 "view source code") + **Raises** -Query the server for the latest job status. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. - + ### running - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. - + + Return whether the job is actively running. -**Return type** + **Return type** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") + `bool` + -**Returns** + ### scheduling\_mode -The status of the job. + + Return the scheduling mode the job is in. -**Raises** + **Return type** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `Optional`\[`str`] -### submit + **Returns** - + The scheduling mode the job is in or `None` if the information is not available. + -`submit()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L846-L860 "view source code") + ### status -Unsupported method. + + Query the server for the latest job status. - - This method is not supported, please use `run()` to submit a job. - + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCircuitJob.wait_for_final_state") if you want to wait for the job to finish. + -**Raises** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCircuitJob.error_message "qiskit_ibm_provider.job.IBMCircuitJob.error_message") to get more information. + -**NotImplementedError** – Upon invocation. + **Return type** -**Return type** + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") -`None` + **Returns** -### tags + The status of the job. - + **Raises** -`tags()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L240-L246 "view source code") + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Return the tags assigned to this job. + ### submit -**Return type** + + Unsupported method. -`List`\[`str`] + + This method is not supported, please use `run()` to submit a job. + -**Returns** + **Raises** -Tags assigned to this job. + **NotImplementedError** – Upon invocation. -### time\_per\_step + **Return type** - + `None` + -`time_per_step()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L483-L512 "view source code") + ### tags -Return the date and time information on each step of the job processing. + + Return the tags assigned to this job. -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: + **Return type** -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` + `List`\[`str`] -**Return type** + **Returns** -`Optional`\[`Dict`] + Tags assigned to this job. + -**Returns** + ### time\_per\_step -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + + Return the date and time information on each step of the job processing. -### update\_name + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`update_name(name)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L116-L125 "view source code") + **Return type** -Update the name associated with this job. + `Optional`\[`Dict`] -**Parameters** + **Returns** -**name** (`str`) – The new name for this job. + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + -**Return type** + ### update\_name -`str` + + Update the name associated with this job. -**Returns** + **Parameters** -The new name associated with this job. + **name** (`str`) – The new name for this job. -### update\_tags + **Return type** - + `str` -`update_tags(new_tags)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L292-L330 "view source code") + **Returns** -Update the tags associated with this job. + The new name associated with this job. + -**Parameters** + ### update\_tags -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. + + Update the tags associated with this job. -**Return type** + **Parameters** -`List`\[`str`] + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -**Returns** + **Return type** -The new tags associated with this job. + `List`\[`str`] -**Raises** + **Returns** -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + The new tags associated with this job. -### wait\_for\_final\_state + **Raises** - + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -`wait_for_final_state(timeout=None, wait=3)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_circuit_job.py#L641-L674 "view source code") + ### wait\_for\_final\_state -**Use the websocket server to wait for the final the state of a job. The server** + + **Use the websocket server to wait for the final the state of a job. The server** -will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. + will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job. -**Parameters** + **Parameters** -**timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. + **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. -**Raises** + **Raises** -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – If the job does not complete within given timeout. -**Return type** + **Return type** -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCompositeJob.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCompositeJob.mdx index 57327eb149b..2f520b2af14 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCompositeJob.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMCompositeJob.mdx @@ -8,746 +8,678 @@ python_api_name: qiskit_ibm_provider.job.IBMCompositeJob # IBMCompositeJob - + + Representation of a set of jobs that execute on an IBM Quantum backend. -`IBMCompositeJob(backend, api_client, job_id=None, creation_date=None, jobs=None, circuits_list=None, run_config=None, name=None, tags=None, client_version=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L72-L1317 "view source code") + An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. -Representation of a set of jobs that execute on an IBM Quantum backend. + This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. -An `IBMCompositeJob` instance is returned when you call `IBMBackend.run()` to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the `max_circuits_per_job` parameter. + You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. -This `IBMCompositeJob` instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like [`status()`](#qiskit_ibm_provider.job.IBMCompositeJob.status "qiskit_ibm_provider.job.IBMCompositeJob.status") and [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") to get the job status and result, respectively. + `IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. -You can also retrieve a previously executed `IBMCompositeJob` using the `job()` and [`jobs()`](qiskit_ibm_provider.IBMBackendService#jobs "qiskit_ibm_provider.IBMBackendService.jobs") methods, like you would with traditional jobs. + Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. -`IBMCompositeJob` also allows you to re-run failed jobs, using the [`rerun_failed()`](#qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed "qiskit_ibm_provider.job.IBMCompositeJob.rerun_failed") method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + `IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. -Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_provider.job.IBMCompositeJob.result "qiskit_ibm_provider.job.IBMCompositeJob.result") is an example of a blocking method, and control will return only after all sub-jobs finish. + IBMCompositeJob constructor. -`IBMCompositeJob` uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by `IBMCompositeJob` start with `ibm_composite_job_`. + **Parameters** -IBMCompositeJob constructor. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. + * **api\_client** (`AccountClient`) – Object for connecting to the server. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **creation\_date** (`Optional`\[`datetime`]) – Job creation date. + * **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. + * **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")]]]) – Circuits for this job. + * **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. + * **name** (`Optional`\[`str`]) – Job name. + * **tags** (`Optional`\[`List`\[`str`]]) – Job tags. + * **client\_version** (`Optional`\[`Dict`]) – Client used for the job. -**Parameters** + **Raises** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – The backend instance used to run this job. -* **api\_client** (`AccountClient`) – Object for connecting to the server. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **creation\_date** (`Optional`\[`datetime`]) – Job creation date. -* **jobs** (`Optional`\[`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]]) – A list of sub-jobs. -* **circuits\_list** (`Optional`\[`List`\[`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")]]]) – Circuits for this job. -* **run\_config** (`Optional`\[`Dict`]) – Runtime configuration for this job. -* **name** (`Optional`\[`str`]) – Job name. -* **tags** (`Optional`\[`List`\[`str`]]) – Job tags. -* **client\_version** (`Optional`\[`Dict`]) – Client used for the job. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. -**Raises** + ## Attributes -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If one or more subjobs is missing. + ### client\_version -## Attributes + + Return version of the client used for this job. - + **Return type** -### client\_version + `Dict`\[`str`, `str`] -Return version of the client used for this job. + **Returns** -**Return type** + **Client version in dictionary format, where the key is the name** -`Dict`\[`str`, `str`] + of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + -**Returns** + ### version -**Client version in dictionary format, where the key is the name** + -of the client and the value is the version. An empty dictionary is returned if the information is not yet known. + ## Methods - + ### backend -### version + + Return the backend where this job was executed. -`= 1` + **Return type** -## Methods + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") + -### backend + ### backend\_options - + + Return the backend configuration options used for this job. -`backend()` + Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. -Return the backend where this job was executed. + **Return type** -**Return type** + `Dict`\[`str`, `Any`] -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") + **Returns** -### backend\_options + Backend options used for this job. + - + ### block\_for\_submit -`backend_options()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L891-L904 "view source code") + + Block until all sub-jobs are submitted. -Return the backend configuration options used for this job. + **Return type** -Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use [`qiskit_ibm_provider.IBMBackend.options`](qiskit_ibm_provider.IBMBackend#options "qiskit_ibm_provider.IBMBackend.options") to see all backend options. + `None` + -**Return type** + ### cancel -`Dict`\[`str`, `Any`] + + Attempt to cancel the job. -**Returns** + + Depending on the state the job is in, it might be impossible to cancel the job. + -Backend options used for this job. + **Return type** -### block\_for\_submit + `bool` - + **Returns** -`block_for_submit()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L1050-L1054 "view source code") + `True` if the job is cancelled, else `False`. -Block until all sub-jobs are submitted. + **Raises** -**Return type** + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -`None` + ### cancelled -### cancel + + Return whether the job has been cancelled. - + **Return type** -`cancel()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L497-L524 "view source code") + `bool` + -Attempt to cancel the job. + ### circuits - - Depending on the state the job is in, it might be impossible to cancel the job. - + + Return the circuits for this job. -**Return type** + **Return type** -`bool` + `List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")] -**Returns** + **Returns** -`True` if the job is cancelled, else `False`. + The circuits for this job. + -**Raises** + ### creation\_date -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Return job creation date, in local time. -### cancelled + **Return type** - + `Optional`\[`datetime`] -`cancelled()` + **Returns** -Return whether the job has been cancelled. + The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + -**Return type** + ### done -`bool` + + Return whether the job has successfully run. -### circuits + **Return type** - + `bool` + -`circuits()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L879-L889 "view source code") + ### error\_message -Return the circuits for this job. + + Provide details about the reason of failure. -**Return type** + + This method blocks until the job finishes. + -`List`\[[`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit "(in Qiskit v1.0)")] + **Return type** -**Returns** + `Optional`\[`str`] -The circuits for this job. + **Returns** -### creation\_date + An error report if the job failed or `None` otherwise. + - + ### from\_jobs -`creation_date()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L761-L773 "view source code") + + Return an instance of this class. -Return job creation date, in local time. + The input job ID is used to query for sub-job information from the server. -**Return type** + **Parameters** -`Optional`\[`datetime`] + * **job\_id** (`str`) – Job ID. + * **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. + * **api\_client** (`AccountClient`) – Client to use to communicate with the server. -**Returns** + **Return type** -The job creation date as a datetime object, in local time, or `None` if job submission hasn’t finished or failed. + [`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") -### done + **Returns** - + An instance of this class. + -`done()` + ### header -Return whether the job has successfully run. + + Return the user header specified for this job. -**Return type** + **Return type** -`bool` + `Dict` -### error\_message + **Returns** - + User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + -`error_message()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L694-L710 "view source code") + ### in\_final\_state -Provide details about the reason of failure. + + Return whether the job is in a final job state such as `DONE` or `ERROR`. - - This method blocks until the job finishes. - + **Return type** -**Return type** + `bool` + -`Optional`\[`str`] + ### job\_id -**Returns** + + Return a unique id identifying the job. -An error report if the job failed or `None` otherwise. + **Return type** -### from\_jobs + `str` + - + ### name -`classmethod from_jobs(job_id, jobs, api_client)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L224-L255 "view source code") + + Return the name assigned to this job. -Return an instance of this class. + **Return type** -The input job ID is used to query for sub-job information from the server. + `Optional`\[`str`] -**Parameters** + **Returns** -* **job\_id** (`str`) – Job ID. -* **jobs** (`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")]) – A list of circuit jobs that belong to this composite job. -* **api\_client** (`AccountClient`) – Client to use to communicate with the server. + Job name or `None` if no name was assigned to this job. + -**Return type** + ### properties -[`IBMCompositeJob`](#qiskit_ibm_provider.job.IBMCompositeJob "qiskit_ibm_provider.job.ibm_composite_job.IBMCompositeJob") + + Return the backend properties for this job. -**Returns** + > **Args:** + > + > **refresh: If `True`, re-query the server for the backend properties.** + > + > Otherwise, return a cached version. -An instance of this class. + + This method blocks until all sub-jobs are submitted. + -### header + **Return type** - + `Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)"), `None`] -`header()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L906-L915 "view source code") + **Returns** -Return the user header specified for this job. + The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. -**Return type** + **Raises** -`Dict` + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Returns** + ### queue\_info -User header specified for this job. An empty dictionary is returned if the header cannot be retrieved. + + Return queue information for this job. -### in\_final\_state + This method returns the queue information of the sub-job that is last in queue. - + The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. -`in_final_state()` + + The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. + -Return whether the job is in a final job state such as `DONE` or `ERROR`. + **Return type** -**Return type** + `Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] -`bool` + **Returns** -### job\_id + A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + - + ### queue\_position -`job_id()` + + Return the position of the job in the server queue. -Return a unique id identifying the job. + This method returns the queue position of the sub-job that is last in queue. -**Return type** + + The position returned is within the scope of the provider and may differ from the global queue position. + -`str` + **Parameters** -### name + **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. - + **Return type** -`name()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L232-L238 "view source code") + `Optional`\[`int`] -Return the name assigned to this job. + **Returns** -**Return type** + Position in the queue or `None` if position is unknown or not applicable. + -`Optional`\[`str`] + ### refresh -**Returns** + + Obtain the latest job information from the server. -Job name or `None` if no name was assigned to this job. + This method may add additional attributes to this job instance, if new information becomes available. -### properties + **Raises** - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. -`properties(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L375-L410 "view source code") + **Return type** -Return the backend properties for this job. + `None` + -> **Args:** -> -> **refresh: If `True`, re-query the server for the backend properties.** -> -> Otherwise, return a cached version. + ### report - - This method blocks until all sub-jobs are submitted. - + + Return a report on current sub-job statuses. -**Return type** + **Parameters** -`Union`\[`List`\[[`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)")], [`BackendProperties`](/api/qiskit/qiskit.providers.models.BackendProperties "(in Qiskit v1.0)"), `None`] + **detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. -**Returns** + **Return type** -The backend properties used for this job, or `None` if properties are not available. A list of backend properties is returned if the sub-jobs used different properties. + `str` -**Raises** + **Returns** -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + A report on sub-job statuses. + -### queue\_info + ### rerun\_failed - + + Re-submit all failed sub-jobs. -`queue_info()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L736-L759 "view source code") + + All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. + -Return queue information for this job. + **Return type** -This method returns the queue information of the sub-job that is last in queue. + `None` + -The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") for more information. + ### result - - The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. - + + Return the result of the job. -**Return type** + + This method blocks until all sub-jobs finish. + -`Optional`\[[`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.queueinfo.QueueInfo")] + + Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. -**Returns** + The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. + -A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. + + When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") instance can be used to verify whether it contains partial results. -### queue\_position + For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: - + ```python + try: + counts = result.get_counts("failed_circuit") + except QiskitError: + print("Circuit execution failed!") + ``` + -`queue_position(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L712-L734 "view source code") + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. -Return the position of the job in the server queue. + **Parameters** -This method returns the queue position of the sub-job that is last in queue. + * **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. + * **wait** (`float`) – Time in seconds between queries. + * **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. + * **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. - - The position returned is within the scope of the provider and may differ from the global queue position. - + **Return type** -**Parameters** + [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") -**refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. + **Returns** -**Return type** + Job result. -`Optional`\[`int`] + **Raises** -**Returns** + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. + * [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -Position in the queue or `None` if position is unknown or not applicable. + ### running -### refresh + + Return whether the job is actively running. - + **Return type** -`refresh()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L865-L877 "view source code") + `bool` + -Obtain the latest job information from the server. + ### scheduling\_mode -This method may add additional attributes to this job instance, if new information becomes available. + + Return the scheduling mode the job is in. -**Raises** + The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + `fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. -**Return type** + This information is only available if the job status is `RUNNING` or `DONE`. -`None` + **Return type** -### report + `Optional`\[`str`] - + **Returns** -`report(detailed=True)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L625-L692 "view source code") + The scheduling mode the job is in or `None` if the information is not available. + -Return a report on current sub-job statuses. + ### status -**Parameters** + + Query the server for the latest job status. -**detailed** (`bool`) – If `True`, return a detailed report. Otherwise return a summary report. + + This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. + -**Return type** + + If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + -`str` + + Since this job contains multiple sub-jobs, the returned status is mapped in the following order: -**Returns** + > * INITIALIZING - if any sub-job is being initialized. + > * VALIDATING - if any sub-job is being validated. + > * QUEUED - if any sub-job is queued. + > * RUNNING - if any sub-job is still running. + > * ERROR - if any sub-job incurred an error. + > * CANCELLED - if any sub-job is cancelled. + > * DONE - if all sub-jobs finished. + -A report on sub-job statuses. + **Return type** -### rerun\_failed + [`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") - + **Returns** -`rerun_failed()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L1020-L1048 "view source code") + The status of the job. -Re-submit all failed sub-jobs. + **Raises** - - All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this `IBMCompositeJob` was returned by [`qiskit_ibm_provider.IBMBackend.run()`](qiskit_ibm_provider.IBMBackend#run "qiskit_ibm_provider.IBMBackend.run") and not retrieved from the server. - + [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + -**Return type** + ### sub\_job -`None` + + Retrieve the job used to submit the specified circuit. -### result + **Parameters** - + **circuit\_index** (`int`) – Index of the circuit whose job is to be returned. -`result(timeout=None, wait=5, partial=False, refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L412-L495 "view source code") + **Return type** -Return the result of the job. + `Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] - - This method blocks until all sub-jobs finish. - + **Returns** - - Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”. + The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. - The first call to this method in an `IBMCompositeJob` instance will query the server and consume any available job results. Subsequent calls to that instance’s `result()` will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed. - + **Raises** - - When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The `success` attribute of the returned [`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") instance can be used to verify whether it contains partial results. + [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + - For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return: + ### sub\_jobs - ```python - try: - counts = result.get_counts("failed_circuit") - except QiskitError: - print("Circuit execution failed!") - ``` - + + Return all submitted sub-jobs. -If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. + **Parameters** -**Parameters** + **block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. -* **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. -* **wait** (`float`) – Time in seconds between queries. -* **partial** (`bool`) – If `True`, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to `True`. -* **refresh** (`bool`) – If `True`, re-query the server for the result. Otherwise return the cached value. + **Return type** -**Return type** + `List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] -[`Result`](/api/qiskit/qiskit.result.Result "(in Qiskit v1.0)") + **Returns** -**Returns** + All submitted sub-jobs. + -Job result. + ### submit -**Raises** + + Unsupported method. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the job was cancelled. -* [**IBMJobFailureError**](qiskit_ibm_provider.job.IBMJobFailureError "qiskit_ibm_provider.job.IBMJobFailureError") – If the job failed. -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + This method is not supported, please use `run()` to submit a job. + -### running + **Raises** - + **NotImplementedError** – Upon invocation. -`running()` + **Return type** -Return whether the job is actively running. + `None` + -**Return type** + ### tags -`bool` + + Return the tags assigned to this job. -### scheduling\_mode + **Return type** - + `List`\[`str`] -`scheduling_mode()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L823-L848 "view source code") + **Returns** -Return the scheduling mode the job is in. + Tags assigned to this job. + -The scheduling mode indicates how the job is scheduled to run. For example, `fairshare` indicates the job is scheduled using a fairshare algorithm. + ### time\_per\_step -`fairshare` is returned if any of the sub-jobs has scheduling mode of `fairshare`. + + Return the date and time information on each step of the job processing. -This information is only available if the job status is `RUNNING` or `DONE`. + The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: -**Return type** + ```python + {'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), + 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), + 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} + ``` -`Optional`\[`str`] + **Return type** -**Returns** + `Optional`\[`Dict`] -The scheduling mode the job is in or `None` if the information is not available. + **Returns** -### status + Date and time information on job processing steps, in local time, or `None` if the information is not yet available. + - + ### update\_name -`status()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L590-L623 "view source code") + + Update the name associated with this job. -Query the server for the latest job status. + + This method blocks until all sub-jobs are submitted. + - - This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use [`wait_for_final_state()`](#qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state "qiskit_ibm_provider.job.IBMCompositeJob.wait_for_final_state") if you want to wait for the job to finish. - + **Parameters** - - If the job failed, you can use [`error_message()`](#qiskit_ibm_provider.job.IBMCompositeJob.error_message "qiskit_ibm_provider.job.IBMCompositeJob.error_message") to get more information. - + **name** (`str`) – The new name for this job. - - Since this job contains multiple sub-jobs, the returned status is mapped in the following order: + **Return type** - > * INITIALIZING - if any sub-job is being initialized. - > * VALIDATING - if any sub-job is being validated. - > * QUEUED - if any sub-job is queued. - > * RUNNING - if any sub-job is still running. - > * ERROR - if any sub-job incurred an error. - > * CANCELLED - if any sub-job is cancelled. - > * DONE - if all sub-jobs finished. - + `str` -**Return type** + **Returns** -[`JobStatus`](/api/qiskit/qiskit.providers.JobStatus "(in Qiskit v1.0)") + The new name associated with this job. -**Returns** + **Raises** -The status of the job. + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. + -**Raises** + ### update\_tags -[**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server. + + Update the tags associated with this job. -### sub\_job + + This method blocks until all sub-jobs are submitted. + - + **Parameters** -`sub_job(circuit_index)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L995-L1018 "view source code") + **new\_tags** (`List`\[`str`]) – New tags to assign to the job. -Retrieve the job used to submit the specified circuit. + **Return type** -**Parameters** + `List`\[`str`] -**circuit\_index** (`int`) – Index of the circuit whose job is to be returned. + **Returns** -**Return type** + The new tags associated with this job. -`Optional`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + * [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. + * [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. + -The Job submitted for the circuit, or `None` if the job has not been submitted or the submit failed. + ### wait\_for\_final\_state -**Raises** + + Wait until the job progresses to a final state such as `DONE` or `ERROR`. -[**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the circuit index is out of range. + **Parameters** -### sub\_jobs + * **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - + * **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. -`sub_jobs(block_for_submit=True)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L980-L993 "view source code") + * **callback** (`Optional`\[`Callable`]) – -Return all submitted sub-jobs. + Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: -**Parameters** + > * job\_id: Job ID + > * job\_status: Status of the job from the last query. + > * job: This `IBMCompositeJob` instance. -**block\_for\_submit** (`bool`) – `True` if this method should block until all sub-jobs are submitted. `False` if the method should return immediately with submitted sub-jobs, if any. + In addition, the following keyword arguments are also provided: -**Return type** + > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. -`List`\[[`IBMCircuitJob`](qiskit_ibm_provider.job.IBMCircuitJob "qiskit_ibm_provider.job.ibm_circuit_job.IBMCircuitJob")] + **Raises** -**Returns** + [**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. -All submitted sub-jobs. + **Return type** -### submit - - - -`submit()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L1303-L1317 "view source code") - -Unsupported method. - - - This method is not supported, please use `run()` to submit a job. - - -**Raises** - -**NotImplementedError** – Upon invocation. - -**Return type** - -`None` - -### tags - - - -`tags()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_job.py#L240-L246 "view source code") - -Return the tags assigned to this job. - -**Return type** - -`List`\[`str`] - -**Returns** - -Tags assigned to this job. - -### time\_per\_step - - - -`time_per_step()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L775-L821 "view source code") - -Return the date and time information on each step of the job processing. - -The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example: - -```python -{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(), - 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(), - 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()} -``` - -**Return type** - -`Optional`\[`Dict`] - -**Returns** - -Date and time information on job processing steps, in local time, or `None` if the information is not yet available. - -### update\_name - - - -`update_name(name)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L526-L554 "view source code") - -Update the name associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**name** (`str`) – The new name for this job. - -**Return type** - -`str` - -**Returns** - -The new name associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job name. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If the input job name is not a string. - -### update\_tags - - - -`update_tags(new_tags)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L556-L588 "view source code") - -Update the tags associated with this job. - - - This method blocks until all sub-jobs are submitted. - - -**Parameters** - -**new\_tags** (`List`\[`str`]) – New tags to assign to the job. - -**Return type** - -`List`\[`str`] - -**Returns** - -The new tags associated with this job. - -**Raises** - -* [**IBMJobApiError**](qiskit_ibm_provider.job.IBMJobApiError "qiskit_ibm_provider.job.IBMJobApiError") – If an unexpected error occurred when communicating with the server or updating the job tags. -* [**IBMJobInvalidStateError**](qiskit_ibm_provider.job.IBMJobInvalidStateError "qiskit_ibm_provider.job.IBMJobInvalidStateError") – If none of the input parameters are specified or if any of the input parameters are invalid. - -### wait\_for\_final\_state - - - -`wait_for_final_state(timeout=None, wait=None, callback=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/ibm_composite_job.py#L917-L978 "view source code") - -Wait until the job progresses to a final state such as `DONE` or `ERROR`. - -**Parameters** - -* **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. - -* **wait** (`Optional`\[`float`]) – Seconds to wait between invoking the callback function. If `None`, the callback function is invoked only if job status or queue position has changed. - -* **callback** (`Optional`\[`Callable`]) – - - Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function: - - > * job\_id: Job ID - > * job\_status: Status of the job from the last query. - > * job: This `IBMCompositeJob` instance. - - In addition, the following keyword arguments are also provided: - - > * queue\_info: A [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance with job queue information, or `None` if queue information is unknown or not applicable. You can use the `to_dict()` method to convert the [`QueueInfo`](qiskit_ibm_provider.job.QueueInfo "qiskit_ibm_provider.job.QueueInfo") instance to a dictionary, if desired. - -**Raises** - -[**IBMJobTimeoutError**](qiskit_ibm_provider.job.IBMJobTimeoutError "qiskit_ibm_provider.job.IBMJobTimeoutError") – if the job does not reach a final state before the specified timeout. - -**Return type** - -`None` + `None` + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobApiError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobApiError.mdx index 8eeacca32f4..6bd18edd0a7 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobApiError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobApiError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobApiError # IBMJobApiError - + + Errors that occur unexpectedly when querying the server. -`IBMJobApiError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/exceptions.py#L26-L29 "view source code") - -Errors that occur unexpectedly when querying the server. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobError.mdx index 07398f80525..d74af418e7d 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobError # IBMJobError - + + Base class for errors raised by the job modules. -`IBMJobError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/exceptions.py#L20-L23 "view source code") - -Base class for errors raised by the job modules. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobFailureError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobFailureError.mdx index 6ab41ec52fe..97a26493799 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobFailureError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobFailureError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobFailureError # IBMJobFailureError - + + Errors raised when a job failed. -`IBMJobFailureError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/exceptions.py#L32-L35 "view source code") - -Errors raised when a job failed. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx index d5f9d5c7608..8d565dd0d68 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobInvalidStateError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobInvalidStateError # IBMJobInvalidStateError - + + Errors raised when a job is not in a valid state for the operation. -`IBMJobInvalidStateError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/exceptions.py#L38-L41 "view source code") - -Errors raised when a job is not in a valid state for the operation. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx index 8fa1e95b532..3098f64e6d4 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.IBMJobTimeoutError.mdx @@ -8,11 +8,9 @@ python_api_name: qiskit_ibm_provider.job.IBMJobTimeoutError # IBMJobTimeoutError - + + Errors raised when a job operation times out. -`IBMJobTimeoutError(*message)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/exceptions.py#L44-L47 "view source code") - -Errors raised when a job operation times out. - -Set the error message. + Set the error message. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.QueueInfo.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.QueueInfo.mdx index 88bfd1a7e36..deb265cc4fc 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.QueueInfo.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.QueueInfo.mdx @@ -8,63 +8,59 @@ python_api_name: qiskit_ibm_provider.job.QueueInfo # QueueInfo - + + Queue information for a job. -`QueueInfo(position_in_queue=None, status=None, estimated_start_time=None, estimated_completion_time=None, hub_priority=None, group_priority=None, project_priority=None, job_id=None, **kwargs)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/queueinfo.py#L25-L183 "view source code") + QueueInfo constructor. -Queue information for a job. + **Parameters** -QueueInfo constructor. + * **position** – Position in the queue. + * **status** (`Optional`\[`str`]) – Job status. + * **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. + * **estimated\_complete\_time** – Estimated complete time for the job, in UTC. + * **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. + * **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. + * **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. + * **job\_id** (`Optional`\[`str`]) – Job ID. + * **kwargs** (`Any`) – Additional attributes. -**Parameters** + ## Attributes -* **position** – Position in the queue. -* **status** (`Optional`\[`str`]) – Job status. -* **estimated\_start\_time** (`Union`\[`str`, `datetime`, `None`]) – Estimated start time for the job, in UTC. -* **estimated\_complete\_time** – Estimated complete time for the job, in UTC. -* **hub\_priority** (`Optional`\[`float`]) – Dynamic priority for the hub. -* **group\_priority** (`Optional`\[`float`]) – Dynamic priority for the group. -* **project\_priority** (`Optional`\[`float`]) – Dynamic priority for the project. -* **job\_id** (`Optional`\[`str`]) – Job ID. -* **kwargs** (`Any`) – Additional attributes. + ### estimated\_complete\_time -## Attributes + + Return estimated complete time in local time. - + **Return type** -### estimated\_complete\_time + `Optional`\[`datetime`] + -Return estimated complete time in local time. + ### estimated\_start\_time -**Return type** + + Return estimated start time in local time. -`Optional`\[`datetime`] + **Return type** - + `Optional`\[`datetime`] + -### estimated\_start\_time + ## Methods -Return estimated start time in local time. + ### format -**Return type** + + Build a user-friendly report for the job queue information. -`Optional`\[`datetime`] + **Return type** -## Methods + `str` -### format + **Returns** - - -`format()` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/queueinfo.py#L123-L159 "view source code") - -Build a user-friendly report for the job queue information. - -**Return type** - -`str` - -**Returns** - -The job queue information report. + The job queue information report. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.job_monitor.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.job_monitor.mdx index ec436c8991f..bba6b476d4e 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.job_monitor.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.job.job_monitor.mdx @@ -10,19 +10,17 @@ python_api_name: qiskit_ibm_provider.job.job_monitor # job\_monitor - + + Monitor the status of an `IBMJob` instance. -`job_monitor(job, interval=None, output=<_io.TextIOWrapper name='' mode='w' encoding='utf-8'>)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/job/job_monitor.py#L99-L116 "view source code") + **Parameters** -Monitor the status of an `IBMJob` instance. + * **job** (`IBMJob`) – Job to monitor. + * **interval** (`Optional`\[`float`]) – Time interval between status queries. + * **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. -**Parameters** + **Return type** -* **job** (`IBMJob`) – Job to monitor. -* **interval** (`Optional`\[`float`]) – Time interval between status queries. -* **output** (`TextIO`) – The file like object to write status messages to. By default this is sys.stdout. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy.mdx index a96816421cc..d91b25ef9b7 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy.mdx @@ -10,27 +10,25 @@ python_api_name: qiskit_ibm_provider.least_busy # least\_busy - + + Return the least busy backend from a list. -`least_busy(backends)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/__init__.py#L104-L140 "view source code") + Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. -Return the least busy backend from a list. + **Parameters** -Return the least busy available backend for those that have a `pending_jobs` in their `status`. Note that local backends may not have this attribute. + **backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)")]) – The backends to choose from. -**Parameters** + **Return type** -**backends** (`List`\[[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)")]) – The backends to choose from. + [`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") -**Return type** + **Returns** -[`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)") + The backend with the fewest number of pending jobs. -**Returns** + **Raises** -The backend with the fewest number of pending jobs. - -**Raises** - -[**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + [**IBMError**](qiskit_ibm_provider.IBMError "qiskit_ibm_provider.IBMError") – If the backends list is empty, or if none of the backends is available, or if a backend in the list does not have the `pending_jobs` attribute in its status. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx index 2a207682d83..7ea503eff1b 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAn # ALAPScheduleAnalysis - + + Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. -`ALAPScheduleAnalysis(durations)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py#L437-L665 "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-late-as-possible (ALAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ALAP scheduler in which instructions start as late as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] + + Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + `None` -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py#L458-L477 "view source code") + **Return type** -Run the ASAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -`None` - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx index a9d3c7cc230..88f645ff5c0 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAnalysis.mdx @@ -8,146 +8,134 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.ASAPScheduleAn # ASAPScheduleAnalysis - + + Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. -`ASAPScheduleAnalysis(durations)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py#L304-L434 "view source code") + This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. -Dynamic circuits as-soon-as-possible (ASAP) scheduling analysis pass. + In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. -This is a scheduler designed to work for the unique scheduling constraints of the dynamic circuits backends due to the limitations imposed by hardware. This is expected to evolve over time as the dynamic circuit backends also change. + The primary differences are that: -In its current form this is similar to Qiskit’s ASAP scheduler in which instructions start as early as possible. + * **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** -The primary differences are that: + of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. -* **Resets and control-flow currently trigger the end of a “quantum block”. The period between the end** + * During a measurement it is possible to apply gates in parallel on disjoint qubits. - of the block and the next is *nondeterministic* ie., we do not know when the next block will begin (as we could be evaluating a classical function of nondeterministic length) and therefore the next block starts at a *relative* t=0. + * Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. -* During a measurement it is possible to apply gates in parallel on disjoint qubits. + Scheduler for dynamic circuit backends. -* Measurements and resets on disjoint qubits happen simultaneously and are part of the same block. + **Parameters** -Scheduler for dynamic circuit backends. + **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. -**Parameters** + ## Attributes -**durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] + + Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") :param dag: DAG to schedule. :type dag: DAGCircuit -**Returns** + **Raises** -Optimized Qiskit IR and state of the workflow. + * **TranspilerError** – if the circuit is not mapped on physical qubits. + * **TranspilerError** – if conditional bit is added to non-supported instruction. -### name + **Return type** - + [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") -`name()` + **Returns** -Name of the pass. + The scheduled DAGCircuit. + -**Return type** + ### update\_status -`str` + + Update workflow status. -### run + **Parameters** - + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -`run(dag)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/scheduler.py#L325-L344 "view source code") + **Return type** -Run the ALAPSchedule pass on dag. :type dag: [`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") :param dag: DAG to schedule. :type dag: DAGCircuit + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") -**Raises** + **Returns** -* **TranspilerError** – if the circuit is not mapped on physical qubits. -* **TranspilerError** – if conditional bit is added to non-supported instruction. - -**Return type** - -[`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)") - -**Returns** - -The scheduled DAGCircuit. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx index 0722270fc9d..642ebefca36 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder.mdx @@ -8,140 +8,128 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadde # BlockBasePadder - + + The base class of padding pass. -`BlockBasePadder(schedule_idle_qubits=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py#L38-L641 "view source code") + This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. -The base class of padding pass. + This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. -This pass requires one of scheduling passes to be executed before itself. Since there are multiple scheduling strategies, the selection of scheduling pass is left in the hands of the pass manager designer. Once a scheduling analysis pass is run, `node_start_time` is generated in the `property_set`. This information is represented by a python dictionary of the expected instruction execution times keyed on the node instances. The padding pass expects all `DAGOpNode` in the circuit to be scheduled. + Note that padding pass subclasses should define interleaving sequences satisfying: -This base class doesn’t define any sequence to interleave, but it manages the location where the sequence is inserted, and provides a set of information necessary to construct the proper sequence. Thus, a subclass of this pass just needs to implement `_pad()` method, in which the subclass constructs a circuit block to insert. This mechanism removes lots of boilerplate logic to manage whole DAG circuits. + > * Interleaved sequence does not change start time of other nodes + > * Interleaved sequence should have total duration of the provided `time_interval`. -Note that padding pass subclasses should define interleaving sequences satisfying: + Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. -> * Interleaved sequence does not change start time of other nodes -> * Interleaved sequence should have total duration of the provided `time_interval`. + ## Attributes -Any manipulation violating these constraints may prevent this base pass from correctly tracking the start time of each instruction, which may result in violation of hardware alignment constraints. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py#L91-L117 "view source code") + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx index 66200749f3f..d62ba538038 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitInstructionDurations.mdx @@ -8,137 +8,121 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuit # DynamicCircuitInstructionDurations - + + For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. -`DynamicCircuitInstructionDurations(instruction_durations=None, dt=None, enable_patching=True)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py#L133-L367 "view source code") + Dynamic circuit instruction durations. -For dynamic circuits the IBM Qiskit backend currently reports instruction durations that differ compared with those required for the legacy Qobj-based path. For now we use this class to report updated InstructionDurations. TODO: This would be mitigated by a specialized Backend/Target for dynamic circuit backends. + ## Attributes -Dynamic circuit instruction durations. + ### MEASURE\_PATCH\_CYCLES -## Attributes + - + ### MEASURE\_PATCH\_ODD\_OFFSET -### MEASURE\_PATCH\_CYCLES + -`= 160` + ## Methods - + ### from\_backend -### MEASURE\_PATCH\_ODD\_OFFSET + + Construct a `DynamicInstructionDurations` object from the backend. -`= 64` + **Parameters** -## Methods + **backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)")) – backend from which durations (gate lengths) and dt are extracted. -### from\_backend + **Returns** - + The InstructionDurations constructed from backend. -`classmethod from_backend(backend)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py#L155-L209 "view source code") + **Return type** -Construct a `DynamicInstructionDurations` object from the backend. + DynamicInstructionDurations + -**Parameters** + ### from\_target -**backend** ([`Backend`](/api/qiskit/qiskit.providers.Backend "(in Qiskit v1.0)")) – backend from which durations (gate lengths) and dt are extracted. + + Construct a `DynamicInstructionDurations` object from the target. -**Returns** + **Parameters** -The InstructionDurations constructed from backend. + **target** ([`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)")) – target from which durations (gate lengths) and dt are extracted. -**Return type** + **Returns** -DynamicInstructionDurations + The InstructionDurations constructed from backend. -### from\_target + **Return type** - + DynamicInstructionDurations + -`classmethod from_target(target)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py#L211-L230 "view source code") + ### get -Construct a `DynamicInstructionDurations` object from the target. + + Get the duration of the instruction with the name, qubits, and parameters. -**Parameters** + Some instructions may have a parameter dependent duration. -**target** ([`Target`](/api/qiskit/qiskit.transpiler.Target "(in Qiskit v1.0)")) – target from which durations (gate lengths) and dt are extracted. + **Parameters** -**Returns** + * **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)")) – An instruction or its name to be queried. + * **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. + * **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. + * **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. -The InstructionDurations constructed from backend. + **Returns** -**Return type** + The duration of the instruction on the qubits. -DynamicInstructionDurations + **Return type** -### get + float|int - + **Raises** -`get(inst, qubits, unit='dt', parameters=None)` + **TranspilerError** – No duration is defined for the instruction. + -Get the duration of the instruction with the name, qubits, and parameters. + ### units\_used -Some instructions may have a parameter dependent duration. + + Get the set of all units used in this instruction durations. -**Parameters** + **Return type** -* **inst** (*str |* [*qiskit.circuit.Instruction*](/api/qiskit/qiskit.circuit.Instruction "(in Qiskit v1.0)")) – An instruction or its name to be queried. -* **qubits** (*int | list\[int]*) – Qubit indices that the instruction acts on. -* **unit** (*str*) – The unit of duration to be returned. It must be ‘s’ or ‘dt’. -* **parameters** (*list\[float] | None*) – The value of the parameters of the desired instruction. + `set`\[`str`] -**Returns** + **Returns** -The duration of the instruction on the qubits. + Set of units used in this instruction durations. + -**Return type** + ### update -float|int + + Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. -**Raises** + **Parameters** -**TranspilerError** – No duration is defined for the instruction. + * **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)"), `None`]) – Instruction durations to be merged into self (overwriting self). + * **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. -### units\_used + **Returns** - + The updated InstructionDurations. -`units_used()` + **Return type** -Get the set of all units used in this instruction durations. + InstructionDurations -**Return type** + **Raises** -`set`\[`str`] - -**Returns** - -Set of units used in this instruction durations. - -### update - - - -`update(inst_durations, dt=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/utils.py#L232-L278 "view source code") - -Update self with inst\_durations (inst\_durations overwrite self). Overrides the default durations for certain hardcoded instructions. - -**Parameters** - -* **inst\_durations** (`Union`\[`List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]], `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `Optional`\[`Iterable`\[`float`]]]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`, `str`]], `List`\[`Tuple`\[`str`, `Optional`\[`Iterable`\[`int`]], `float`]], [`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)"), `None`]) – Instruction durations to be merged into self (overwriting self). -* **dt** (`Optional`\[`float`]) – Sampling duration in seconds of the target backend. - -**Returns** - -The updated InstructionDurations. - -**Return type** - -InstructionDurations - -**Raises** - -**TranspilerError** – If the format of instruction\_durations is invalid. + **TranspilerError** – If the format of instruction\_durations is invalid. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx index 8eb4551145d..4b18d79b217 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay.mdx @@ -8,152 +8,140 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDelay # PadDelay - + + Padding idle time with Delay instructions. -`PadDelay(fill_very_end=True, schedule_idle_qubits=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/pad_delay.py#L22-L78 "view source code") + Consecutive delays will be merged in the output of this pass. -Padding idle time with Delay instructions. + The ASAP-scheduled circuit output may become -Consecutive delays will be merged in the output of this pass. + ```python + ┌────────────────┐ + q_0: ┤ Delay(160[dt]) ├──■── + └─────┬───┬──────┘┌─┴─┐ + q_1: ──────┤ X ├───────┤ X ├ + └───┘ └───┘ + ``` -The ASAP-scheduled circuit output may become + Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. -```python - ┌────────────────┐ -q_0: ┤ Delay(160[dt]) ├──■── - └─────┬───┬──────┘┌─┴─┐ -q_1: ──────┤ X ├───────┤ X ├ - └───┘ └───┘ -``` + See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. -Note that the additional idle time of 60dt on the `q_0` wire coming from the duration difference between `Delay` of 100dt (`q_0`) and `XGate` of 160 dt (`q_1`) is absorbed in the delay instruction on the `q_0` wire, i.e. in total 160 dt. + Create new padding delay pass. -See [`BlockBasePadder`](qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder "qiskit_ibm_provider.transpiler.passes.scheduling.BlockBasePadder") pass for details. + **Parameters** -Create new padding delay pass. + * **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -**Parameters** + ## Attributes -* **fill\_very\_end** (`bool`) – Set `True` to fill the end of circuit with delay. -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ### is\_analysis\_pass -## Attributes + + Check if the pass is an analysis pass. - + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + -### is\_analysis\_pass + ### is\_transformation\_pass -Check if the pass is an analysis pass. + + Check if the pass is a transformation pass. -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + - + ## Methods -### is\_transformation\_pass + ### \_\_call\_\_ -Check if the pass is a transformation pass. + + Runs the pass on circuit. -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + **Parameters** -## Methods + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -### \_\_call\_\_ + **Return type** - + QuantumCircuit -`__call__(circuit, property_set=None)` + **Returns** -Runs the pass on circuit. + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -**Parameters** + ### execute -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + + Execute optimization task for input Qiskit IR. -**Return type** + **Parameters** -QuantumCircuit + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -**Returns** + **Return type** -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] -### execute + **Returns** - + Optimized Qiskit IR and state of the workflow. + -`execute(passmanager_ir, state, callback=None)` + ### name -Execute optimization task for input Qiskit IR. + + Name of the pass. -**Parameters** + **Return type** -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + `str` + -**Return type** + ### run -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] + + Run the padding pass on `dag`. -**Returns** + **Parameters** -Optimized Qiskit IR and state of the workflow. + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. -### name + **Returns** - + DAG with idle time filled with instructions. -`name()` + **Return type** -Name of the pass. + DAGCircuit -**Return type** + **Raises** -`str` + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -### run + ### update\_status - + + Update workflow status. -`run(dag)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py#L91-L117 "view source code") + **Parameters** -Run the padding pass on `dag`. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -**Parameters** + **Return type** -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") -**Returns** + **Returns** -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx index 9f09b97195d..34cbffd5169 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDecoupling.mdx @@ -8,287 +8,275 @@ python_api_name: qiskit_ibm_provider.transpiler.passes.scheduling.PadDynamicalDe # PadDynamicalDecoupling - - -`PadDynamicalDecoupling(durations, dd_sequences, qubits=None, spacings=None, skip_reset_qubits=True, pulse_alignment=16, extra_slack_distribution='middle', sequence_min_length_ratios=None, insert_multiple_cycles=False, coupling_map=None, alt_spacings=None, schedule_idle_qubits=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/dynamical_decoupling.py#L39-L583 "view source code") - -Dynamical decoupling insertion pass for IBM dynamic circuit backends. - -This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). - -```python -import numpy as np -from qiskit.circuit import QuantumCircuit -from qiskit.circuit.library import XGate -from qiskit.transpiler import PassManager, InstructionDurations -from qiskit.visualization import timeline_drawer - -from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis -from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling - -circ = QuantumCircuit(4) -circ.h(0) -circ.cx(0, 1) -circ.cx(1, 2) -circ.cx(2, 3) -circ.measure_all() -durations = InstructionDurations( - [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), - ("cx", [1, 2], 200), ("cx", [2, 3], 300), - ("x", None, 50), ("measure", None, 1000)] -) -``` - -```python -# balanced X-X sequence on all qubits -dd_sequence = [XGate(), XGate()] -pm = PassManager([ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence)]) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌───────────────┐ ┌───┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» - ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» - ├────────────────┤ └───┘ ┌─┴─┐ » - q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» - └────────────────┘ └───┘ » -meas: 4/═════════════════════════════════════════════════════════» - » -« ┌────────────────┐ ┌───┐ ┌───────────────┐ » -« q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» -« └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» -« q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» -« └───┘ └───────────────┘ └───┘ └───────────────┘» -« q_2: ─────────────────────────────────────────────────────────────────────» -« » -« q_3: ─────────────────────────────────────────────────────────────────────» -« » -«meas: 4/═════════════════════════════════════════════════════════════════════» -« » -« ░ ┌─┐ -« q_0: ─░─┤M├───────── -« ░ └╥┘┌─┐ -« q_1: ─░──╫─┤M├────── -« ░ ║ └╥┘┌─┐ -« q_2: ─░──╫──╫─┤M├─── -« ░ ║ ║ └╥┘┌─┐ -« q_3: ─░──╫──╫──╫─┤M├ -« ░ ║ ║ ║ └╥┘ -«meas: 4/════╩══╩══╩══╩═ -« 0 1 2 3 -``` - -```python -# Uhrig sequence on qubit 0 -n = 8 -dd_sequence = [XGate()] * n -def uhrig_pulse_location(k): - return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 -spacings = [] -for k in range(n): - spacings.append(uhrig_pulse_location(k) - sum(spacings)) -spacings.append(1 - sum(spacings)) -pm = PassManager( - [ - ALAPScheduleAnalysis(durations), - PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), - ] -) -circ_dd = pm.run(circ) -circ_dd.draw() -``` - -```python - ┌───┐ ┌────────────────┐ ░ ┌─┐ » - q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» - ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » - q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» - ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» - q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» - ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» - q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» - └────────────────┘ └───┘ ░ ║ ║ ║ » -meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» - 0 1 2 » -« -« q_0: ─── -« -« q_1: ─── -« -« q_2: ─── -« ┌─┐ -« q_3: ┤M├ -« └╥┘ -«meas: 4/═╩═ -« 3 -``` + + Dynamical decoupling insertion pass for IBM dynamic circuit backends. + + This pass works on a scheduled, physical circuit. It scans the circuit for idle periods of time (i.e. those containing delay instructions) and inserts a DD sequence of gates in those spots. These gates amount to the identity, so do not alter the logical action of the circuit, but have the effect of mitigating decoherence in those idle periods. As a special case, the pass allows a length-1 sequence (e.g. \[XGate()]). In this case the DD insertion happens only when the gate inverse can be absorbed into a neighboring gate in the circuit (so we would still be replacing Delay with something that is equivalent to the identity). This can be used, for instance, as a Hahn echo. This pass ensures that the inserted sequence preserves the circuit exactly (including global phase). + + ```python + import numpy as np + from qiskit.circuit import QuantumCircuit + from qiskit.circuit.library import XGate + from qiskit.transpiler import PassManager, InstructionDurations + from qiskit.visualization import timeline_drawer + + from qiskit_ibm_provider.transpiler.passes.scheduling import ALAPScheduleAnalysis + from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling + + circ = QuantumCircuit(4) + circ.h(0) + circ.cx(0, 1) + circ.cx(1, 2) + circ.cx(2, 3) + circ.measure_all() + durations = InstructionDurations( + [("h", 0, 50), ("cx", [0, 1], 700), ("reset", None, 10), + ("cx", [1, 2], 200), ("cx", [2, 3], 300), + ("x", None, 50), ("measure", None, 1000)] + ) + ``` + + ```python + # balanced X-X sequence on all qubits + dd_sequence = [XGate(), XGate()] + pm = PassManager([ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence)]) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌───────────────┐ ┌───┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(96[dt]) ├──────┤ X ├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└───────────────┘┌─────┴───┴─────┐» + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■────────┤ Delay(48[dt]) ├» + ├───────────────┴┐└───┘ ┌─┴─┐ └───────────────┘» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├──────────────■────────» + ├────────────────┤ └───┘ ┌─┴─┐ » + q_3: ┤ Delay(950[dt]) ├────────────────────────────┤ X ├──────» + └────────────────┘ └───┘ » + meas: 4/═════════════════════════════════════════════════════════» + » + « ┌────────────────┐ ┌───┐ ┌───────────────┐ » + « q_0: ┤ Delay(208[dt]) ├──────┤ X ├──────┤ Delay(96[dt]) ├─────────────────» + « └─────┬───┬──────┘┌─────┴───┴─────┐└─────┬───┬─────┘┌───────────────┐» + « q_1: ──────┤ X ├───────┤ Delay(96[dt]) ├──────┤ X ├──────┤ Delay(56[dt]) ├» + « └───┘ └───────────────┘ └───┘ └───────────────┘» + « q_2: ─────────────────────────────────────────────────────────────────────» + « » + « q_3: ─────────────────────────────────────────────────────────────────────» + « » + «meas: 4/═════════════════════════════════════════════════════════════════════» + « » + « ░ ┌─┐ + « q_0: ─░─┤M├───────── + « ░ └╥┘┌─┐ + « q_1: ─░──╫─┤M├────── + « ░ ║ └╥┘┌─┐ + « q_2: ─░──╫──╫─┤M├─── + « ░ ║ ║ └╥┘┌─┐ + « q_3: ─░──╫──╫──╫─┤M├ + « ░ ║ ║ ║ └╥┘ + «meas: 4/════╩══╩══╩══╩═ + « 0 1 2 3 + ``` + + ```python + # Uhrig sequence on qubit 0 + n = 8 + dd_sequence = [XGate()] * n + def uhrig_pulse_location(k): + return np.sin(np.pi * (k + 1) / (2 * n + 2)) ** 2 + spacings = [] + for k in range(n): + spacings.append(uhrig_pulse_location(k) - sum(spacings)) + spacings.append(1 - sum(spacings)) + pm = PassManager( + [ + ALAPScheduleAnalysis(durations), + PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacings=spacings), + ] + ) + circ_dd = pm.run(circ) + circ_dd.draw() + ``` + + ```python + ┌───┐ ┌────────────────┐ ░ ┌─┐ » + q_0: ──────┤ H ├─────────■──┤ Delay(500[dt]) ├───────────────────░─┤M├──────» + ┌─────┴───┴─────┐ ┌─┴─┐└────────────────┘┌────────────────┐ ░ └╥┘┌─┐ » + q_1: ┤ Delay(50[dt]) ├─┤ X ├────────■─────────┤ Delay(300[dt]) ├─░──╫─┤M├───» + ├───────────────┴┐└───┘ ┌─┴─┐ └────────────────┘ ░ ║ └╥┘┌─┐» + q_2: ┤ Delay(750[dt]) ├───────────┤ X ├───────────────■──────────░──╫──╫─┤M├» + ├────────────────┤ └───┘ ┌─┴─┐ ░ ║ ║ └╥┘» + q_3: ┤ Delay(950[dt]) ├─────────────────────────────┤ X ├────────░──╫──╫──╫─» + └────────────────┘ └───┘ ░ ║ ║ ║ » + meas: 4/═══════════════════════════════════════════════════════════════╩══╩══╩═» + 0 1 2 » + « + « q_0: ─── + « + « q_1: ─── + « + « q_2: ─── + « ┌─┐ + « q_3: ┤M├ + « └╥┘ + «meas: 4/═╩═ + « 3 + ``` + + + You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. + + + Dynamical decoupling initializer. + + **Parameters** - - You need to call [`ALAPScheduleAnalysis`](qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis "qiskit_ibm_provider.transpiler.passes.scheduling.ALAPScheduleAnalysis") before running dynamical decoupling to guarantee your circuit satisfies acquisition alignment constraints for dynamic circuit backends. - + * **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. -Dynamical decoupling initializer. + * **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v1.0)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v1.0)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. -**Parameters** + * **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). -* **durations** ([`InstructionDurations`](/api/qiskit/qiskit.transpiler.InstructionDurations "(in Qiskit v1.0)")) – Durations of instructions to be used in scheduling. + * **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified -* **dd\_sequences** (`Union`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v1.0)")], `List`\[`List`\[[`Gate`](/api/qiskit/qiskit.circuit.Gate "(in Qiskit v1.0)")]]]) – Sequence of gates to apply in idle spots. Alternatively a list of gate sequences may be supplied that will preferentially be inserted if there is a delay of sufficient duration. This may be tuned by the optionally supplied `sequence_min_length_ratios`. + * **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). -* **qubits** (`Optional`\[`List`\[`int`]]) – Physical qubits on which to apply DD. If None, all qubits will undergo DD (when possible). + * **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. -* **spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates. The available slack will be divided according to this. The list length must be one more than the length of dd\_sequence, and the elements must sum to 1. If None, a balanced spacing will be used \[d/2, d, d, …, d, d, d/2]. This spacing only applies to the first subcircuit, if a `coupling_map` is specified + * **extra\_slack\_distribution** (`str`) – -* **skip\_reset\_qubits** (`bool`) – If True, does not insert DD on idle periods that immediately follow initialized/reset qubits (as qubits in the ground state are less susceptible to decoherence). + The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. -* **pulse\_alignment** (`int`) – The hardware constraints for gate timing allocation. This is usually provided from `backend.configuration().timing_constraints`. If provided, the delay length, i.e. `spacing`, is implicitly adjusted to satisfy this constraint. + > * ”middle”: Put the extra slack to the interval at the middle of the sequence. + > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. -* **extra\_slack\_distribution** (`str`) – + * **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. - The option to control the behavior of DD sequence generation. The duration of the DD sequence should be identical to an idle time in the scheduled quantum circuit, however, the delay in between gates comprising the sequence should be integer number in units of dt, and it might be further truncated when `pulse_alignment` is specified. This sometimes results in the duration of the created sequence being shorter than the idle time that you want to fill with the sequence, i.e. extra slack. This option takes following values. + * **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. - > * ”middle”: Put the extra slack to the interval at the middle of the sequence. - > * ”edges”: Divide the extra slack as evenly as possible into intervals at beginning and end of the sequence. + * **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.0)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. -* **sequence\_min\_length\_ratios** (`Union`\[`int`, `List`\[`int`], `None`]) – List of minimum delay length to DD sequence ratio to satisfy in order to insert the DD sequence. For example if the X-X dynamical decoupling sequence is 320dt samples long and the available delay is 384dt it has a ratio of 384dt/320dt=1.2. From the perspective of dynamical decoupling this is likely to add more control noise than decoupling error rate reductions. The defaults value is 2.0. + * **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. -* **insert\_multiple\_cycles** (`bool`) – If the available duration exceeds 2\*sequence\_min\_length\_ratio\*duration(dd\_sequence) enable the insertion of multiple rounds of the dynamical decoupling sequence in that delay. + * **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. -* **coupling\_map** (`Optional`\[[`CouplingMap`](/api/qiskit/qiskit.transpiler.CouplingMap "(in Qiskit v1.0)")]) – directed graph representing the coupling map for the device. Specifying a coupling map partitions the device into subcircuits, in order to apply DD sequences with different pulse spacings within each. Currently support 2 subcircuits. + **Raises** -* **alt\_spacings** (`Union`\[`List`\[`List`\[`float`]], `List`\[`float`], `None`]) – A list of lists of spacings between the DD gates, for the second subcircuit, as determined by the coupling map. If None, a balanced spacing that is staggered with respect to the first subcircuit will be used \[d, d, d, …, d, d, 0]. + * **TranspilerError** – When invalid DD sequence is specified. + * **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. + * **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) -* **schedule\_idle\_qubits** (`bool`) – Set to true if you’d like a delay inserted on idle qubits. This is useful for timeline visualizations, but may cause issues for execution on large backends. + ## Attributes -**Raises** + ### is\_analysis\_pass -* **TranspilerError** – When invalid DD sequence is specified. -* **TranspilerError** – When pulse gate with the duration which is non-multiple of the alignment constraint value is found. -* **TranspilerError** – When the coupling map is not supported (i.e., if degree > 3) + + Check if the pass is an analysis pass. -## Attributes + If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + - + ### is\_transformation\_pass -### is\_analysis\_pass + + Check if the pass is a transformation pass. -Check if the pass is an analysis pass. + If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + -If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass. + ## Methods - + ### \_\_call\_\_ -### is\_transformation\_pass + + Runs the pass on circuit. -Check if the pass is a transformation pass. + **Parameters** -If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read). + * **circuit** (*QuantumCircuit*) – The dag on which the pass is run. + * **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. -## Methods + **Return type** -### \_\_call\_\_ + QuantumCircuit - + **Returns** -`__call__(circuit, property_set=None)` + If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + -Runs the pass on circuit. + ### execute -**Parameters** + + Execute optimization task for input Qiskit IR. -* **circuit** (*QuantumCircuit*) – The dag on which the pass is run. -* **property\_set** (*PropertySet | dict | None*) – Input/output property set. An analysis pass might change the property set in-place. + **Parameters** -**Return type** + * **passmanager\_ir** (`Any`) – Qiskit IR to optimize. + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. + * **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. -QuantumCircuit + **Return type** -**Returns** + `tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] -If on transformation pass, the resulting QuantumCircuit. If analysis pass, the input circuit. + **Returns** -### execute + Optimized Qiskit IR and state of the workflow. + - + ### name -`execute(passmanager_ir, state, callback=None)` + + Name of the pass. -Execute optimization task for input Qiskit IR. + **Return type** -**Parameters** + `str` + -* **passmanager\_ir** (`Any`) – Qiskit IR to optimize. -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – State associated with workflow execution by the pass manager itself. -* **callback** (`Optional`\[`Callable`]) – A callback function which is caller per execution of optimization task. + ### run -**Return type** + + Run the padding pass on `dag`. -`tuple`\[`Any`, [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")] + **Parameters** -**Returns** + **dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. -Optimized Qiskit IR and state of the workflow. + **Returns** -### name + DAG with idle time filled with instructions. - + **Return type** -`name()` + DAGCircuit -Name of the pass. + **Raises** -**Return type** + **TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. + -`str` + ### update\_status -### run + + Update workflow status. - + **Parameters** -`run(dag)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/transpiler/passes/scheduling/block_base_padder.py#L91-L117 "view source code") + * **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. + * **run\_state** (`RunState`) – Completion status of current task. -Run the padding pass on `dag`. + **Return type** -**Parameters** + [`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") -**dag** ([`DAGCircuit`](/api/qiskit/qiskit.dagcircuit.DAGCircuit "(in Qiskit v1.0)")) – DAG to be checked. + **Returns** -**Returns** - -DAG with idle time filled with instructions. - -**Return type** - -DAGCircuit - -**Raises** - -**TranspilerError** – When a particular node is not scheduled, likely some transform pass is inserted before this node is called. - -### update\_status - - - -`update_status(state, run_state)` - -Update workflow status. - -**Parameters** - -* **state** ([`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)")) – Pass manager state to update. -* **run\_state** (`RunState`) – Completion status of current task. - -**Return type** - -[`PassManagerState`](/api/qiskit/qiskit.passmanager.PassManagerState "(in Qiskit v1.0)") - -**Returns** - -Updated pass manager state. + Updated pass manager state. + + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.seconds_to_duration.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.seconds_to_duration.mdx index 8d463936931..59993069f8e 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.seconds_to_duration.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.seconds_to_duration.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.seconds_to_duration # seconds\_to\_duration - + + Converts seconds in a datetime delta to a duration. -`seconds_to_duration(seconds)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/converters.py#L140-L160 "view source code") + **Parameters** -Converts seconds in a datetime delta to a duration. + **seconds** (`float`) – Number of seconds in time delta. -**Parameters** + **Return type** -**seconds** (`float`) – Number of seconds in time delta. + `Tuple`\[`int`, `int`, `int`, `int`, `int`] -**Return type** + **Returns** -`Tuple`\[`int`, `int`, `int`, `int`, `int`] - -**Returns** - -A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + A tuple containing the duration in terms of days, hours, minutes, seconds, and milliseconds. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.to_python_identifier.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.to_python_identifier.mdx index 98313947d2e..86f85ff371a 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.to_python_identifier.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.to_python_identifier.mdx @@ -10,21 +10,19 @@ python_api_name: qiskit_ibm_provider.utils.to_python_identifier # to\_python\_identifier - + + Convert a name to a valid Python identifier. -`to_python_identifier(name)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/utils.py#L66-L89 "view source code") + **Parameters** -Convert a name to a valid Python identifier. + **name** (`str`) – Name to be converted. -**Parameters** + **Return type** -**name** (`str`) – Name to be converted. + `str` -**Return type** + **Returns** -`str` - -**Returns** - -Name that is a valid Python identifier. + Name that is a valid Python identifier. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.utc_to_local.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.utc_to_local.mdx index 24beab5b888..2d1cb35acfe 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.utc_to_local.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.utc_to_local.mdx @@ -10,25 +10,23 @@ python_api_name: qiskit_ibm_provider.utils.utc_to_local # utc\_to\_local - + + Convert a UTC `datetime` object or string to a local timezone `datetime`. -`utc_to_local(utc_dt)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/converters.py#L25-L43 "view source code") + **Parameters** -Convert a UTC `datetime` object or string to a local timezone `datetime`. + **utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. -**Parameters** + **Return type** -**utc\_dt** (`Union`\[`datetime`, `str`]) – Input UTC datetime or string. + `datetime` -**Return type** + **Returns** -`datetime` + A `datetime` with the local timezone. -**Returns** + **Raises** -A `datetime` with the local timezone. - -**Raises** - -**TypeError** – If the input parameter value is not valid. + **TypeError** – If the input parameter value is not valid. + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.validate_job_tags.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.validate_job_tags.mdx index 6f70459bee4..a3614b487c2 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.validate_job_tags.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.utils.validate_job_tags.mdx @@ -10,22 +10,20 @@ python_api_name: qiskit_ibm_provider.utils.validate_job_tags # validate\_job\_tags - + + Validates input job tags. -`validate_job_tags(job_tags, exception)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/utils/utils.py#L92-L108 "view source code") + **Parameters** -Validates input job tags. + * **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. + * **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. -**Parameters** + **Raises** -* **job\_tags** (`Optional`\[`List`\[`str`]]) – Job tags to be validated. -* **exception** (`Type`\[`Exception`]) – Exception to raise if the tags are invalid. + **Exception** – If the job tags are invalid. -**Raises** + **Return type** -**Exception** – If the job tags are invalid. - -**Return type** - -`None` + `None` + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_error_map.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_error_map.mdx index d9066e38e13..f9f93b50bc1 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_error_map.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_error_map.mdx @@ -10,45 +10,43 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_error_map # iplot\_error\_map - + + Plot the error map of a device. -`iplot_error_map(backend, figsize=(800, 500), show_title=True, remove_badcal_edges=True, background_color='white', as_widget=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/visualization/interactive/error_map.py#L31-L556 "view source code") + **Parameters** -Plot the error map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. + * **figsize** (`Tuple`\[`int`]) – Figure size in pixels. + * **show\_title** (`bool`) – Whether to show figure title. + * **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. + * **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the error map for this backend. -* **figsize** (`Tuple`\[`int`]) – Figure size in pixels. -* **show\_title** (`bool`) – Whether to show figure title. -* **remove\_badcal\_edges** (`bool`) – Whether to remove bad CX gate calibration data. -* **background\_color** (`str`) – Background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The error map figure. -**Returns** + **Raises** -The error map figure. + * **VisualizationValueError** – If an invalid input is received. + * **VisualizationTypeError** – If the specified backend is a simulator. -**Raises** + **Example** -* **VisualizationValueError** – If an invalid input is received. -* **VisualizationTypeError** – If the specified backend is a simulator. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_error_map -**Example** + provider = IBMProvider(group='open', project='main') + # Note that this is a mock provider, replace ``FakeOpenPulse2Q`` + # with any of the currently available IBM devices. + backend = provider.get_backend('FakeOpenPulse2Q') -```python -from qiskit_ibm_provider import IBMProvider -from qiskit_ibm_provider.visualization import iplot_error_map - -provider = IBMProvider(group='open', project='main') -# Note that this is a mock provider, replace ``FakeOpenPulse2Q`` -# with any of the currently available IBM devices. -backend = provider.get_backend('FakeOpenPulse2Q') - -iplot_error_map(backend, as_widget=True) -``` + iplot_error_map(backend, as_widget=True) + ``` + diff --git a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_gate_map.mdx b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_gate_map.mdx index 9090ec8479b..0f405549260 100644 --- a/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_gate_map.mdx +++ b/docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_gate_map.mdx @@ -10,46 +10,44 @@ python_api_name: qiskit_ibm_provider.visualization.iplot_gate_map # iplot\_gate\_map - + + Plots an interactive gate map of a device. -`iplot_gate_map(backend, figsize=(None, None), label_qubits=True, qubit_size=None, line_width=None, font_size=None, qubit_color='#2f4b7c', qubit_labels=None, line_color='#2f4b7c', font_color='white', background_color='white', as_widget=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.10/qiskit_ibm_provider/visualization/interactive/gate_map.py#L24-L244 "view source code") + **Parameters** -Plots an interactive gate map of a device. + * **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. + * **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. + * **label\_qubits** (`bool`) – Labels for the qubits. + * **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. + * **line\_width** (`Optional`\[`float`]) – Width of lines. + * **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. + * **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. + * **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels + * **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. + * **font\_color** (`str`) – The font color for the qubit labels. + * **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. + * **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. -**Parameters** + **Return type** -* **backend** ([`IBMBackend`](qiskit_ibm_provider.IBMBackend "qiskit_ibm_provider.ibm_backend.IBMBackend")) – Plot the gate map for this backend. -* **figsize** (`Tuple`\[`Optional`\[`int`], `Optional`\[`int`]]) – Output figure size (wxh) in inches. -* **label\_qubits** (`bool`) – Labels for the qubits. -* **qubit\_size** (`Optional`\[`float`]) – Size of qubit marker. -* **line\_width** (`Optional`\[`float`]) – Width of lines. -* **font\_size** (`Optional`\[`int`]) – Font size of qubit labels. -* **qubit\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for the qubits. If a single color is given, it’s used for all qubits. -* **qubit\_labels** (`Optional`\[`List`\[`str`]]) – A list of qubit labels -* **line\_color** (`Union`\[`List`\[`str`], `str`]) – A list of colors for each line from the coupling map. If a single color is given, it’s used for all lines. -* **font\_color** (`str`) – The font color for the qubit labels. -* **background\_color** (`str`) – The background color, either ‘white’ or ‘black’. -* **as\_widget** (`bool`) – `True` if the figure is to be returned as a `PlotlyWidget`. Otherwise the figure is to be returned as a `PlotlyFigure`. + `Union`\[`PlotlyFigure`, `PlotlyWidget`] -**Return type** + **Returns** -`Union`\[`PlotlyFigure`, `PlotlyWidget`] + The gate map figure. -**Returns** + **Example** -The gate map figure. + ```python + from qiskit_ibm_provider import IBMProvider + from qiskit_ibm_provider.visualization import iplot_gate_map -**Example** + provider = IBMProvider(group='open', project='main') + # Note that this is a mock provider, replace ``FakeOpenPulse2Q`` + # with any of the currently available IBM devices. + backend = provider.get_backend('FakeOpenPulse2Q') -```python - from qiskit_ibm_provider import IBMProvider - from qiskit_ibm_provider.visualization import iplot_gate_map - -provider = IBMProvider(group='open', project='main') -# Note that this is a mock provider, replace ``FakeOpenPulse2Q`` -# with any of the currently available IBM devices. -backend = provider.get_backend('FakeOpenPulse2Q') - - iplot_gate_map(backend, as_widget=True) -``` + iplot_gate_map(backend, as_widget=True) + ``` +