Skip to content

Commit

Permalink
Generation qiskit-ibm-runtime v0.16.1 API docs (Qiskit#499)
Browse files Browse the repository at this point in the history 
This PR adds the API docs for qiskit-ibm-runtime 0.16.1 and converts
version 0.15 into a historical one.

Commands used:

```
npm run make-historical -- -p qiskit-ibm-runtime
npm run gen-api -- -p qiskit-ibm-runtime -v 0.16.1 -a https://github.com/Qiskit/qiskit-ibm-runtime/suites/18545595602/artifacts/1076853761
```

The CI run used to build the current version: 
https://github.com/Qiskit/qiskit-ibm-runtime/actions/runs/7013376928
  • Loading branch information
@arnaucasau
arnaucasau authored Dec 8, 2023
1 parent d114029 commit 0b60acf
Show file tree
Hide file tree
Showing 28 changed files with 3,601 additions and 282 deletions.
4 changes: 4 additions & 0 deletions docs/api/qiskit-ibm-runtime/0.15/_package.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"name": "qiskit-ibm-runtime",
"version": "0.15.0"
}
96 changes: 96 additions & 0 deletions docs/api/qiskit-ibm-runtime/0.15/_toc.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
{
"title": "Qiskit Runtime IBM Client",
"children": [
{
"title": "qiskit_ibm_runtime",
"children": [
{
"title": "Overview",
"url": "/api/qiskit-ibm-runtime/0.15/index"
},
{
"title": "Estimator",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.Estimator"
},
{
"title": "IBMBackend",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.IBMBackend"
},
{
"title": "ParameterNamespace",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.ParameterNamespace"
},
{
"title": "QiskitRuntimeService",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.QiskitRuntimeService"
},
{
"title": "RuntimeDecoder",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.RuntimeDecoder"
},
{
"title": "RuntimeEncoder",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.RuntimeEncoder"
},
{
"title": "RuntimeJob",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.RuntimeJob"
},
{
"title": "RuntimeOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.RuntimeOptions"
},
{
"title": "RuntimeProgram",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.RuntimeProgram"
},
{
"title": "Sampler",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.Sampler"
},
{
"title": "Session",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.Session"
},
{
"title": "qiskit_ibm_runtime.options",
"children": [
{
"title": "Overview",
"url": "/api/qiskit-ibm-runtime/0.15/options"
},
{
"title": "EnvironmentOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.EnvironmentOptions"
},
{
"title": "ExecutionOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.ExecutionOptions"
},
{
"title": "Options",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.Options"
},
{
"title": "ResilienceOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.ResilienceOptions"
},
{
"title": "SimulatorOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.SimulatorOptions"
},
{
"title": "TranspilationOptions",
"url": "/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.options.TranspilationOptions"
}
]
}
]
},
{
"title": "Release notes",
"url": "/api/qiskit-ibm-runtime/release-notes"
}
]
}

4 changes: 4 additions & 0 deletions docs/api/qiskit-ibm-runtime/0.15/ibm-runtime.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# qiskit-ibm-runtime API reference

* [Qiskit Runtime (`qiskit_ibm_runtime`)](runtime_service)
* [Primitive options (`qiskit_ibm_runtime.options`)](options)
135 changes: 135 additions & 0 deletions docs/api/qiskit-ibm-runtime/0.15/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
---
title: qiskit_ibm_runtime
description: API reference for qiskit_ibm_runtime
in_page_toc_min_heading_level: 1
python_api_type: module
python_api_name: qiskit_ibm_runtime
---

<span id="qiskit-runtime-qiskit-ibm-runtime" />

<span id="module-qiskit_ibm_runtime" />

# Qiskit Runtime

<span id="module-qiskit_ibm_runtime" />

`qiskit_ibm_runtime`

Modules related to Qiskit Runtime IBM Client.

Qiskit Runtime is a new architecture that streamlines computations requiring many iterations. These experiments will execute significantly faster within its improved hybrid quantum/classical process.

## Primitives and sessions

Qiskit Runtime has two predefined primitives: `Sampler` and `Estimator`. These primitives provide a simplified interface for performing foundational quantum computing tasks while also accounting for the latest developments in quantum hardware and software.

Qiskit Runtime also has the concept of a session. Jobs submitted within a session are prioritized by the scheduler. A session allows you to make iterative calls to the quantum computer more efficiently.

Below is an example of using primitives within a session:

```python
from qiskit_ibm_runtime import QiskitRuntimeService, Session, Sampler, Estimator, Options
from qiskit.test.reference_circuits import ReferenceCircuits
from qiskit.circuit.library import RealAmplitudes
from qiskit.quantum_info import SparsePauliOp

# Initialize account.
service = QiskitRuntimeService()

# Set options, which can be overwritten at job level.
options = Options(optimization_level=3)

# Prepare inputs.
bell = ReferenceCircuits.bell()
psi = RealAmplitudes(num_qubits=2, reps=2)
H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
theta = [0, 1, 1, 2, 3, 5]

with Session(service=service, backend="ibmq_qasm_simulator") as session:
# Submit a request to the Sampler primitive within the session.
sampler = Sampler(session=session, options=options)
job = sampler.run(circuits=bell)
print(f"Sampler results: {job.result()}")

# Submit a request to the Estimator primitive within the session.
estimator = Estimator(session=session, options=options)
job = estimator.run(
circuits=[psi], observables=[H1], parameter_values=[theta]
)
print(f"Estimator results: {job.result()}")
```

## Backend data

[`QiskitRuntimeService`](qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService") also has methods, such as `backend()`, `backends()`, and `least_busy()`, that allow you to query for a target backend to use. These methods return one or more [`IBMBackend`](qiskit_ibm_runtime.IBMBackend "qiskit_ibm_runtime.IBMBackend") instances that contains methods and attributes describing the backend.

## Supplementary Information

### Account initialization

You need to initialize your account before you can start using the Qiskit Runtime service. This is done by initializing a [`QiskitRuntimeService`](qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService") instance with your account credentials. If you don’t want to pass in the credentials each time, you can use the [`QiskitRuntimeService.save_account()`](qiskit_ibm_runtime.QiskitRuntimeService#save_account "qiskit_ibm_runtime.QiskitRuntimeService.save_account") method to save the credentials on disk.

Qiskit Runtime is available on both IBM Cloud and IBM Quantum, and you can specify `channel="ibm_cloud"` for IBM Cloud and `channel="ibm_quantum"` for IBM Quantum. The default is IBM Cloud.

### Runtime Jobs

When you use the `run()` method of the [`Sampler`](qiskit_ibm_runtime.Sampler "qiskit_ibm_runtime.Sampler") or [`Estimator`](qiskit_ibm_runtime.Estimator "qiskit_ibm_runtime.Estimator") to invoke the primitive, a [`RuntimeJob`](qiskit_ibm_runtime.RuntimeJob "qiskit_ibm_runtime.RuntimeJob") instance is returned. This class has all the basic job methods, such as [`RuntimeJob.status()`](qiskit_ibm_runtime.RuntimeJob#status "qiskit_ibm_runtime.RuntimeJob.status"), [`RuntimeJob.result()`](qiskit_ibm_runtime.RuntimeJob#result "qiskit_ibm_runtime.RuntimeJob.result"), and [`RuntimeJob.cancel()`](qiskit_ibm_runtime.RuntimeJob#cancel "qiskit_ibm_runtime.RuntimeJob.cancel").

### Logging

`qiskit-ibm-runtime` uses the `qiskit_ibm_runtime` logger.

Two environment variables can be used to control the logging:

* `QISKIT_IBM_RUNTIME_LOG_LEVEL`: Specifies the log level to use. If an invalid level is set, the log level defaults to `WARNING`. The valid log levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL` (case-insensitive). If the environment variable is not set, then the parent logger’s level is used, which also defaults to `WARNING`.
* `QISKIT_IBM_RUNTIME_LOG_FILE`: Specifies the name of the log file to use. If specified, messages will be logged to the file only. Otherwise messages will be logged to the standard error (usually the screen).

For more advanced use, you can modify the logger itself. For example, to manually set the level to `WARNING`:

```python
import logging
logging.getLogger('qiskit_ibm_runtime').setLevel(logging.WARNING)
```

### Interim and final results

Some runtime programs provide interim results that inform you about program progress. You can choose to stream the interim results and final result when you run the program by passing in the `callback` parameter, or at a later time using the [`RuntimeJob.stream_results()`](qiskit_ibm_runtime.RuntimeJob#stream_results "qiskit_ibm_runtime.RuntimeJob.stream_results") method. For example:

```python
from qiskit.test.reference_circuits import ReferenceCircuits
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler

service = QiskitRuntimeService()
backend = service.backend("ibmq_qasm_simulator")

def result_callback(job_id, result):
print(result)

# Stream results as soon as the job starts running.
job = Sampler(backend).run(ReferenceCircuits.bell(), callback=result_callback)
print(job.result())
```

### Uploading a program

Authorized users can upload their custom Qiskit Runtime programs. A Qiskit Runtime program is a piece of Python code and its metadata that takes certain inputs, performs quantum and maybe classical processing, and returns the results.

Files related to writing a runtime program are in the `qiskit_ibm_runtime/program` directory.

### Classes

| | |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`QiskitRuntimeService`](qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService")(\[channel, token, url, ...]) | Class for interacting with the Qiskit Runtime service. |
| [`Estimator`](qiskit_ibm_runtime.Estimator "qiskit_ibm_runtime.Estimator")(\[backend, session, options]) | Class for interacting with Qiskit Runtime Estimator primitive service. |
| [`Sampler`](qiskit_ibm_runtime.Sampler "qiskit_ibm_runtime.Sampler")(\[backend, session, options]) | Class for interacting with Qiskit Runtime Sampler primitive service. |
| [`Session`](qiskit_ibm_runtime.Session "qiskit_ibm_runtime.Session")(\[service, backend, max\_time]) | Class for creating a flexible Qiskit Runtime session. |
| [`IBMBackend`](qiskit_ibm_runtime.IBMBackend "qiskit_ibm_runtime.IBMBackend")(configuration, service, api\_client) | Backend class interfacing with an IBM Quantum backend. |
| [`RuntimeJob`](qiskit_ibm_runtime.RuntimeJob "qiskit_ibm_runtime.RuntimeJob")(backend, api\_client, ...\[, ...]) | Representation of a runtime program execution. |
| [`RuntimeProgram`](qiskit_ibm_runtime.RuntimeProgram "qiskit_ibm_runtime.RuntimeProgram")(program\_name, program\_id, ...) | Class representing program metadata. |
| [`ParameterNamespace`](qiskit_ibm_runtime.ParameterNamespace "qiskit_ibm_runtime.ParameterNamespace")(parameters) | A namespace for program parameters with validation. |
| [`RuntimeOptions`](qiskit_ibm_runtime.RuntimeOptions "qiskit_ibm_runtime.RuntimeOptions")(\[backend, image, log\_level, ...]) | Class for representing generic runtime execution options. |
| [`RuntimeEncoder`](qiskit_ibm_runtime.RuntimeEncoder "qiskit_ibm_runtime.RuntimeEncoder")(\*\[, skipkeys, ensure\_ascii, ...]) | JSON Encoder used by runtime service. |
| [`RuntimeDecoder`](qiskit_ibm_runtime.RuntimeDecoder "qiskit_ibm_runtime.RuntimeDecoder")(\*args, \*\*kwargs) | JSON Decoder used by runtime service. |

48 changes: 48 additions & 0 deletions docs/api/qiskit-ibm-runtime/0.15/options.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
title: options
description: API reference for qiskit_ibm_runtime.options
in_page_toc_min_heading_level: 1
python_api_type: module
python_api_name: qiskit_ibm_runtime.options
---

<span id="primitive-options-qiskit-ibm-runtime-options" />

<span id="module-qiskit_ibm_runtime.options" />

# Primitive options

<span id="module-qiskit_ibm_runtime.options" />

`qiskit_ibm_runtime.options`

Options that can be passed to the primitives.

The [`Options`](qiskit_ibm_runtime.options.Options "qiskit_ibm_runtime.options.Options") class encapsulates all the options you can specify when invoking a primitive. It includes frequently used options, such as `optimization_level` and `resilience_level` as well as sub-categories, such as `transpilation` and `execution`. You can use auto-complete to easily find the options inside each sub-category, for example:

```python
from qiskit_ibm_runtime.options import Options

options = Options()
options.transpilation.initial_layout = [0, 1, 2, 3] # This an be done using auto-complete
```

You can also pass dictionaries to each sub-category, for example:

```python
from qiskit_ibm_runtime.options import Options

options = Options(transpilation={"initial_layout": [0, 1, 2, 3]})
```

## Classes

| | |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [`Options`](qiskit_ibm_runtime.options.Options "qiskit_ibm_runtime.options.Options")(\[optimization\_level, ...]) | Options for the primitives. |
| [`TranspilationOptions`](qiskit_ibm_runtime.options.TranspilationOptions "qiskit_ibm_runtime.options.TranspilationOptions")(\[skip\_transpilation, ...]) | Transpilation options. |
| [`ResilienceOptions`](qiskit_ibm_runtime.options.ResilienceOptions "qiskit_ibm_runtime.options.ResilienceOptions")(\[noise\_amplifier, ...]) | Resilience options. |
| [`ExecutionOptions`](qiskit_ibm_runtime.options.ExecutionOptions "qiskit_ibm_runtime.options.ExecutionOptions")(\[shots, init\_qubits]) | Execution options. |
| [`EnvironmentOptions`](qiskit_ibm_runtime.options.EnvironmentOptions "qiskit_ibm_runtime.options.EnvironmentOptions")(\[log\_level, callback, ...]) | Options related to the execution environment. |
| [`SimulatorOptions`](qiskit_ibm_runtime.options.SimulatorOptions "qiskit_ibm_runtime.options.SimulatorOptions")(\[noise\_model, ...]) | Simulator options. |

Loading

0 comments on commit 0b60acf

Please sign in to comment.