Merge branch 'main' into save-local-jobs

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e .
+          pip install -e '.[dev, visualization]'
       - name: Run black
         run: make style
       - name: Run lint
@@ -58,8 +58,7 @@ jobs:
           pip install -U tox
           pip install nbqa docutils
           sudo apt install -y graphviz pandoc
-          pip install -e .
-
+          pip install -e '.[dev, visualization]'
           wget https://github.com/errata-ai/vale/releases/download/v2.23.0/vale_2.23.0_Linux_64-bit.tar.gz
           mkdir $HOME/bin && tar -xf vale_2.23.0_Linux_64-bit.tar.gz -C $HOME/bin
           echo "$HOME/bin" >> $GITHUB_PATH
@@ -103,7 +102,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e .
+          pip install -e '.[dev, visualization]'
       - name: Run unit tests
         run: make unit-test-coverage
       - name: Report coverage to coveralls.io
@@ -131,6 +130,7 @@ jobs:
       QISKIT_IBM_TOKEN: ${{ secrets.QISKIT_IBM_TOKEN }}
       QISKIT_IBM_URL: ${{ secrets.QISKIT_IBM_URL }}
       QISKIT_IBM_INSTANCE: ${{ secrets.QISKIT_IBM_INSTANCE }}
+      QISKIT_IBM_QPU: ${{ secrets.QISKIT_IBM_QPU }}
       LOG_LEVEL: DEBUG
       STREAM_LOG: True
       QISKIT_IN_PARALLEL: True
@@ -145,7 +145,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e .
+          pip install -e '.[dev, visualization]'
       - name: Run integration tests
         run: make integration-test
   tests-finished:

.github/workflows/e2e-tests.yml

@@ -47,6 +47,6 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e .
+          pip install -e .[dev]
       - name: Run e2e tests
         run: make e2e-test

.github/workflows/integration-tests-qiskit-main.yml

@@ -33,6 +33,7 @@ jobs:
       QISKIT_IBM_TOKEN: ${{ secrets.QISKIT_IBM_TOKEN }}
       QISKIT_IBM_URL: ${{ secrets.QISKIT_IBM_URL }}
       QISKIT_IBM_INSTANCE: ${{ secrets.QISKIT_IBM_INSTANCE }}
+      QISKIT_IBM_QPU: ${{ secrets.QISKIT_IBM_QPU }}
       LOG_LEVEL: DEBUG
       STREAM_LOG: True
       QISKIT_IN_PARALLEL: True
@@ -47,6 +48,6 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e . git+https://github.com/Qiskit/qiskit.git
+          pip install -e '.[dev, visualization]' git+https://github.com/Qiskit/qiskit.git
       - name: Run integration tests
         run: make integration-test

.github/workflows/integration-tests.yml

@@ -18,7 +18,7 @@ on:
   workflow_dispatch:
 jobs:
   integration-tests:
-    if: github.repository_owner == 'Qiskit'
+    if: github.event_name == 'workflow_dispatch' || github.repository_owner == 'Qiskit'
     name: Run integration tests - ${{ matrix.environment }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -33,6 +33,8 @@ jobs:
       QISKIT_IBM_TOKEN: ${{ secrets.QISKIT_IBM_TOKEN }}
       QISKIT_IBM_URL: ${{ secrets.QISKIT_IBM_URL }}
       QISKIT_IBM_INSTANCE: ${{ secrets.QISKIT_IBM_INSTANCE }}
+      QISKIT_IBM_QPU: ${{ secrets.QISKIT_IBM_QPU }}
+
       LOG_LEVEL: DEBUG
       STREAM_LOG: True
       QISKIT_IN_PARALLEL: True
@@ -47,6 +49,6 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c constraints.txt -r requirements-dev.txt -e .
+          pip install -e '.[dev, visualization]'
       - name: Run integration tests
         run: make integration-test

.github/workflows/neko.yml

@@ -0,0 +1,18 @@
+name: Qiskit Neko Integration Tests
+on:
+  push:
+  pull_request:
+    branches: ['main', 'stable/*']
+concurrency:
+  group: ${{ github.repository }}-${{ github.ref }}-${{ github.head_ref }}-${{ github.workflow }}
+  # Only cancel in PR mode.  In push mode, don't cancel so we don't see spurious test "failures".
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  neko:
+    if: github.repository_owner == 'Qiskit'
+    name: Qiskit Neko Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Qiskit/qiskit-neko@main
+        with:
+          test_selection: backend

.github/workflows/unit-tests-terra-main.yml

@@ -37,7 +37,7 @@ jobs:
           python -m pip install --upgrade pip
           # Installing the complete environment should happen in one `pip install` step,
           # or pip will generally allow broken combinations of packages to be installed.
-          pip install -c constraints.txt -r requirements-dev.txt -e . git+https://github.com/Qiskit/qiskit.git
+          pip install -e '.[dev, visualization]' git+https://github.com/Qiskit/qiskit.git
       - name: Run tests
         # running unit tests against latest (non-released) code of qiskit-terra gives a basic level
         # of confidence that the integration between qiskit-ibm-runtime and qiskit-terra works

.gitignore

@@ -50,6 +50,7 @@ test/python/*.log
 test/python/*.pdf
 test/python/*.prof
 .stestr/
+.test_artifacts
 
 # Translations
 *.mo
@@ -115,4 +116,7 @@ Qconfig.py
 docs/release_notes.rst
 
 # Locally run jobs 
-qiskit_ibm_runtime/fake_provider/local_jobs
+qiskit_ibm_runtime/fake_provider/local_jobs
+
+# Version.txt
+qiskit_ibm_runtime/VERSION.txt

CONTRIBUTING.md

@@ -13,6 +13,31 @@ https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md
 In addition to the general guidelines there are specific details for
 contributing to qiskit-ibm-runtime, these are documented below.
 
+### Installing from source
+
+To install from source download this repository and follow the next steps.
+
+- Create a virtual environment
+``` {.bash}
+$ python3 -m venv .venv
+```
+- Activate your virtual environment
+``` {.bash}
+$ source .venv/bin/activate
+```
+- Install the dependencies
+``` {.bash}
+$ pip install -e .
+```
+- Install the visualization dependencies
+``` {.bash}
+$ pip install -e ".[visualization]"
+```
+- Install the development dependencies
+``` {.bash}
+$ pip install -e ".[dev]"
+```
+
 ### Open an issue
 
 * For documentation issues relating to pages in the Start, Build, Transpile, Verify, Run, and Migration guides sections of https://docs.quantum.ibm.com, please open an issue in the [Qiskit/documentation repo](https://github.com/Qiskit/documentation/issues/new/choose) rather than the Qiskit/qiskit-ibm-runtime repo. In other words, any page that DOES NOT have `/api/` in the url should be addressed in the Qiskit/documentation repo. (Exception: the Migration guide urls contain `/api/` but are managed in the Qiskit/documentation repo.)
@@ -155,7 +180,7 @@ Finally, preview the docs build by following the instructions in
 Building The release notes are part of the standard qiskit-ibm-runtime
 documentation builds. To check what the rendered html output of the release
 notes will look like for the current state of the repo you can run:
-`tox -edocs` which will build all the documentation into `docs/_build/html`
+`tox -e docs` which will build all the documentation into `docs/_build/html`
 and the release notes in particular will be located at
 `docs/_build/html/release_notes.html`.
 
@@ -206,20 +231,24 @@ Sample configuration for IBM Quantum
 QISKIT_IBM_TOKEN=...                                            # IBM Quantum API token
 QISKIT_IBM_URL=https://auth.quantum-computing.ibm.com/api       # IBM Quantum API URL
 QISKIT_IBM_INSTANCE=ibm-q/open/main                             # IBM Quantum provider to use (hub/group/project)
+QISKIT_IBM_QPU=...                                              # IBM Quantum Processing Unit to use
 ```
 
 Sample configuration for IBM Cloud
 ```bash
 QISKIT_IBM_TOKEN=...                                            # IBM Cloud API key
 QISKIT_IBM_URL=https://cloud.ibm.com                            # Cloud URL
 QISKIT_IBM_INSTANCE=crn:v1:bluemix:...                          # The CRN value of the Quantum service instance
+QISKIT_IBM_QPU=...                                              # The Quantum Processing Unit to use
 ```
 
 
 To enable test cases against external system in your private fork, make sure to set above values as
 [encrypted environment secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-an-environment).
 The names of the environments must match the ones that the [CI workflow](.github/workflows/ci.yml) relies
-upon.
+upon. 
+
+For example, in your github fork settings, add the environment you want to run tests on (ibm-quantum-production, ibm-quantum-staging, ibm-cloud-production, ibm-cloud-staging). Then add the appropriate environment secrets (QISKIT_IBM_INSTANCE, QISKIT_IBM_TOKEN, QISKIT_IBM_URL, QISKIT_IBM_DEVICE).
 
 ### Style guide
 

Makefile

@@ -16,12 +16,13 @@
 lint:
 	pylint -rn qiskit_ibm_runtime test
 	tools/verify_headers.py qiskit_ibm_runtime test
+	tools/verify_images.py
 
 mypy:
 	mypy --module qiskit_ibm_runtime --package test
 
 style:
-	black --check qiskit_ibm_runtime setup.py test
+	black --check qiskit_ibm_runtime test
 
 unit-test:
 	python -m unittest discover --verbose --top-level-directory . --start-directory test/unit
@@ -40,4 +41,4 @@ unit-test-coverage:
 	coverage lcov
 
 black:
-	black qiskit_ibm_runtime setup.py test
+	black qiskit_ibm_runtime test

README.md

@@ -147,7 +147,7 @@ pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
 isa_circuit = pm.run(bell)
 
 # 3. Execute using the Sampler primitive
-sampler = Sampler(backend=backend)
+sampler = Sampler(mode=backend)
 sampler.options.default_shots = 1024  # Options can be set using auto-complete.
 job = sampler.run([isa_circuit])
 print(f"Job ID is {job.job_id()}")
@@ -247,8 +247,8 @@ isa_circuit = pm.run(circuit)
 isa_observables = M1.apply_layout(isa_circuit.layout)
 
 # 3. Execute iteratively using the Estimator primitive
-with Session(service=service, backend=backend) as session:
-    estimator = Estimator(session=session)
+with Session(backend=backend) as session:
+    estimator = Estimator(mode=session)
     estimator.options.default_precision = 0.03  # Options can be set using auto-complete.
     #next test range
     thetac = thetab - (thetab - thetaa) / gr
@@ -296,8 +296,8 @@ backend1 = service.backend("ibmq_manila")
 # Optional: Specify the instance at the backend level, which overwrites the service-level specification when this backend is used.
 backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2")
 
-sampler1 = Sampler(backend=backend1)    # this will use hub1/group1/project1
-sampler2 = Sampler(backend=backend2)    # this will use hub2/group2/project2
+sampler1 = Sampler(mode=backend1)    # this will use hub1/group1/project1
+sampler2 = Sampler(mode=backend2)    # this will use hub2/group2/project2
 ```
 
 If you do not specify an instance, then the code will select one in the following order:

docs/_templates/autosummary/class.rst

@@ -1,23 +1,24 @@
-{% if referencefile %}
-.. include:: {{ referencefile }}
-{% endif %}
+{#
+   We show all the class's methods and attributes on the same page. By default, we document
+   all methods, including those defined by parent classes.
+-#}
 
-{{ objname }}
-{{ underline }}
+{{ objname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
    :no-members:
    :no-inherited-members:
    :no-special-members:
+   :show-inheritance:
 
 {% block attributes_summary %}
    {% if attributes %}
    .. rubric:: Attributes
       {% for item in all_attributes %}
          {%- if not item.startswith('_') %}
-   .. autoattribute:: {{ name }}.{{ item }}
+   .. autoattribute:: {{ item }}
          {%- endif -%}
       {%- endfor %}
    {% endif %}
@@ -28,7 +29,7 @@
    .. rubric:: Methods
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-   .. automethod:: {{ name }}.{{ item }}
+   .. automethod:: {{ item }}
       {%- endif -%}
    {%- endfor %}
 

docs/apidocs/debug_tools.rst

@@ -0,0 +1,4 @@
+.. automodule:: qiskit_ibm_runtime.debug_tools
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/index.rst

@@ -1,8 +1,8 @@
 .. vale off
 
-********************************
-qiskit-ibm-runtime API reference
-********************************
+************************************
+``qiskit-ibm-runtime`` API reference
+************************************
 
 .. toctree::
    :maxdepth: 1
@@ -15,3 +15,5 @@ qiskit-ibm-runtime API reference
    qiskit_ibm_runtime.transpiler.passes.scheduling
    fake_provider
    execution_span
+   debug_tools
+   visualization

docs/apidocs/visualization.rst

@@ -0,0 +1,4 @@
+.. automodule:: qiskit_ibm_runtime.visualization
+   :no-members:
+   :no-inherited-members:
+   :no-special-members: