Qiskit · jyu00 · Oct 31, 2023 · Sep 10, 2023 · Sep 11, 2023 · Sep 11, 2023
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -20,6 +20,9 @@ on:
 jobs:
   Deploy:
     runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
     strategy:
       matrix:
         python-version: [3.9]
@@ -28,12 +31,12 @@ jobs:
       - uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Install deps
+        run: pip install -U pip setuptools build
+      - name: Build sdist
+        run: python3 -m build
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./dist/*
       - name: Deploy to Pypi
-        env:
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-          TWINE_USERNAME: qiskit
-        run : |
-          pip install -U twine pip setuptools virtualenv wheel
-          python3 setup.py sdist bdist_wheel
-          twine upload dist/qiskit*
-        shell: bash
+        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/README.md b/README.md
@@ -9,8 +9,8 @@
 
 **Qiskit** is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.
 
-**Qiskit IBM Runtime** is a new environment offered by IBM Quantum that streamlines quantum computations and provides optimal 
-implementations of the Qiskit primitives `sampler` and `estimator` for IBM Quantum hardware. It is designed to use additional classical compute resources to execute quantum circuits with more efficiency on quantum processors, by including near-time computations such as error suppression and error mitigation. Examples of error suppression include dynamical decoupling, noise-aware compilation, error mitigation including readout mitigation, zero-noise extrapolation (ZNE), and probabilistic error cancellation (PEC).  
+**Qiskit IBM Runtime** is a new environment offered by IBM Quantum that streamlines quantum computations and provides optimal
+implementations of the Qiskit primitives `sampler` and `estimator` for IBM Quantum hardware. It is designed to use additional classical compute resources to execute quantum circuits with more efficiency on quantum processors, by including near-time computations such as error suppression and error mitigation. Examples of error suppression include dynamical decoupling, noise-aware compilation, error mitigation including readout mitigation, zero-noise extrapolation (ZNE), and probabilistic error cancellation (PEC).
 
 Using the runtime service, a research team at IBM Quantum was able to achieve a 120x speedup
 in their lithium hydride simulation. For more information, see the
@@ -30,8 +30,6 @@ pip install qiskit-ibm-runtime
 
 ### Qiskit Runtime service on IBM Quantum Platform
 
-The default method for using the runtime service is IBM Quantum Platform.
-
 You will need your IBM Quantum API token to authenticate with the runtime service:
 
 1. Create an IBM Quantum account or log in to your existing account by visiting the [IBM Quantum login page].
@@ -114,7 +112,7 @@ All quantum applications and algorithms level are fundamentally built using thre
 
 The IBM Runtime service offers these primitives with additional features, such as built-in error suppression and mitigation.
 
-There are several different options you can specify when calling the primitives. See [`qiskit_ibm_runtime.Options`](https://github.com/Qiskit/qiskit-ibm-runtime/blob/main/qiskit_ibm_runtime/options.py#L103) class for more information.
+There are several different options you can specify when calling the primitives. See [`qiskit_ibm_runtime.Options`](https://github.com/Qiskit/qiskit-ibm-runtime/blob/main/qiskit_ibm_runtime/options/options.py#L33) class for more information.
 
 ### Sampler
 
@@ -138,7 +136,7 @@ bell.cx(0, 1)
 # 2. Map the qubits to a classical register in ascending order
 bell.measure_all()
 
-# 3. Execute using the Sampler primitive 
+# 3. Execute using the Sampler primitive
 backend = service.get_backend('ibmq_qasm_simulator')
 sampler = Sampler(backend=backend, options=options)
 job = sampler.run(circuits=bell)
@@ -174,14 +172,14 @@ qc_example.cx(0, 2) # condition 2nd qubit on 0th qubit
 # 2. the observable to be measured
 M1 = SparsePauliOp.from_list([("XXY", 1), ("XYX", 1), ("YXX", 1), ("YYY", -1)])
 
-# batch of theta parameters to be executed 
+# batch of theta parameters to be executed
 points = 50
 theta1 = []
 for x in range(points):
     theta = [x*2.0*np.pi/50]
     theta1.append(theta)
 
-# 3. Execute using the Estimator primitive 
+# 3. Execute using the Estimator primitive
 backend = service.get_backend('ibmq_qasm_simulator')
 estimator = Estimator(backend, options=options)
 job = estimator.run(circuits=[qc_example]*points, observables=[M1]*points, parameter_values=theta1)
@@ -197,7 +195,7 @@ This code batches together 50 parameters to be executed in a single job. If a us
 In many algorithms and applications, an Estimator needs to be called iteratively without incurring queuing delays on each iteration. To solve this, the IBM Runtime service provides a **Session**. A session starts when the first job within the session is started, and subsequent jobs within the session are prioritized by the scheduler.
 
 You can use the [`qiskit_ibm_runtime.Session`](https://github.com/Qiskit/qiskit-ibm-runtime/blob/main/qiskit_ibm_runtime/session.py) class to start a
-session. Consider the same example above and try to find the optimal `theta`. The following example uses the [golden search method](https://en.wikipedia.org/wiki/Golden-section_search) to iteratively find the optimal theta that maximizes the observable. 
+session. Consider the same example above and try to find the optimal `theta`. The following example uses the [golden search method](https://en.wikipedia.org/wiki/Golden-section_search) to iteratively find the optimal theta that maximizes the observable.
 
 To invoke the `Estimator` primitive within a session:
 
@@ -224,15 +222,15 @@ qc_example.cx(0, 2) # condition 2nd qubit on 0th qubit
 M1 = SparsePauliOp.from_list([("XXY", 1), ("XYX", 1), ("YXX", 1), ("YYY", -1)])
 
 
-gr = (np.sqrt(5) + 1) / 2 # golden ratio   
+gr = (np.sqrt(5) + 1) / 2 # golden ratio
 thetaa = 0 # lower range of theta
 thetab = 2*np.pi # upper range of theta
-tol = 1e-1 # tol 
+tol = 1e-1 # tol
 
-# 3. Execute iteratively using the Estimator primitive 
+# 3. Execute iteratively using the Estimator primitive
 with Session(service=service, backend="ibmq_qasm_simulator") as session:
     estimator = Estimator(session=session, options=options)
-    #next test range 
+    #next test range
     thetac = thetab - (thetab - thetaa) / gr
     thetad = thetaa + (thetab - thetaa) / gr
     while abs(thetab - thetaa) > tol:
@@ -245,8 +243,8 @@ with Session(service=service, backend="ibmq_qasm_simulator") as session:
             thetaa = thetac
         thetac = thetab - (thetab - thetaa) / gr
         thetad = thetaa + (thetab - thetaa) / gr
-        
-    # Final job to evaluate Estimator at midpoint found using golden search method 
+
+    # Final job to evaluate Estimator at midpoint found using golden search method
     theta_mid = (thetab + thetaa) / 2
     job = estimator.run(circuits=qc_example, observables=M1, parameter_values=theta_mid)
     print(f"Session ID is {session.session_id}")
@@ -256,6 +254,38 @@ with Session(service=service, backend="ibmq_qasm_simulator") as session:
 
 This code returns `Job result is [4.] at theta = 1.575674623307102` using only nine iterations. This is a very powerful extension to the primitives. However, using too much code between iterative calls can lock the QPU and use excessive QPU time, which is expensive. We recommend only using sessions when needed. The Sampler can also be used within a session, but there are not any well-defined examples for this.
 
+## Instances
+
+Access to IBM Quantum Platform channel is controlled by the instances (previously called providers) to which you are assigned. An instance is defined by a hierarchical organization of hub, group, and project. A hub is the top level of a given hierarchy (organization) and contains within it one or more groups. These groups are in turn populated with projects. The combination of hub/group/project is called an instance. Users can belong to more than one instance at any time.
+
+> **_NOTE:_** IBM Cloud instances are different from IBM Quantum Platform instances.  IBM Cloud does not use the hub/group/project structure for user management. To view and create IBM Cloud instances, visit the [IBM Cloud Quantum Instances page](https://cloud.ibm.com/quantum/instances).
+
+To view a list of your instances, visit your [account settings page](https://www.quantum-computing.ibm.com/account) or use the `instances()` method.
+
+You can specify an instance when initializing the service or provider, or when picking a backend:
+
+```python
+# Optional: List all the instances you can access.
+service = QiskitRuntimeService(channel='ibm_quantum')
+print(service.instances())
+
+# Optional: Specify the instance at service level. This becomes the default unless overwritten.
+service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1")
+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
+```
+
+If you do not specify an instance, then the code will select one in the following order:
+
+1. If your account only has access to one instance, it is selected by default.
+2. If your account has access to multiple instances, but only one can access the requested backend, the instance with access is selected.
+3. In all other cases, the code selects the first instance other than ibm-q/open/main that has access to the backend.
+
 ## Access your IBM Quantum backends
 
 A **backend** is a quantum device or simulator capable of running quantum circuits or pulse schedules.

diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -17,11 +17,9 @@
 
    .. rubric:: Attributes
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_attributes %}
       {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
+   .. autoattribute:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% endif %}
@@ -32,16 +30,14 @@
 
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% for item in inherited_members %}
       {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
 

diff --git a/docs/cloud/cost.rst b/docs/cloud/cost.rst
@@ -8,7 +8,7 @@ Time limits on programs
 
 The maximum execution time for the Sampler primitive is 10000 seconds (2.78 hours). The maximum execution time for the Estimator primitive is 18000 seconds (5 hours).
 
-Additionally, the system limit on the job execution time is 3 hours for a job that is running on a simulator and 8 hours for a job running on a physical system.
+Additionally, the system limit on the system execution time is 3 hours for a job that is running on a simulator and 8 hours for a job running on a physical system.
 
 How to limit your cost
 ***********************

diff --git a/docs/conf.py b/docs/conf.py
@@ -42,7 +42,7 @@
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '0.12.1'
+release = '0.13.1'
 
 docs_url_prefix = "ecosystem/ibm-runtime"
 
@@ -146,18 +146,20 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-html_theme = 'qiskit_sphinx_theme'
+html_theme = "qiskit-ecosystem"
+html_title = f"{project} {release}"
 
-html_logo = 'images/logo.png'
-html_last_updated_fmt = '%Y/%m/%d'
+html_logo = "images/ibm-quantum-logo.png"
 
 html_theme_options = {
-    'logo_only': True,
-    'display_version': True,
-    'prev_next_buttons_location': 'bottom',
-    'style_external_links': True,
+    # Because this is an IBM-focused project, we use a blue color scheme.
+    "light_css_variables": {
+        "color-brand-primary": "var(--qiskit-color-blue)",
+    },
 }
 
+html_last_updated_fmt = '%Y/%m/%d'
+
 html_sourcelink_suffix = ''
 
 autoclass_content = 'both'
diff --git a/docs/faqs/max_execution_time.rst b/docs/faqs/max_execution_time.rst
@@ -13,12 +13,11 @@ a job exceeds this time limit, it is forcibly cancelled and a ``RuntimeJobMaxTim
 exception is raised.
 
 .. note::
-   As of August 7, 2023, the ``max_execution_time`` value is based on quantum
-   time instead of wall clock time. Quantum time represents the time that the QPU
+   As of August 7, 2023, the ``max_execution_time`` value is based on system execution time, which is the time that the QPU
    complex (including control software, control electronics, QPU, and so on) is engaged in
-   processing the job.
+   processing the job, instead of wall clock time.
 
-   Simulator jobs continue to use wall clock time because they do not have quantum time.
+   Simulator jobs continue to use wall clock time.
 
 You can set the maximum execution time (in seconds) on the job options by using one of the following methods:
 
@@ -32,12 +31,12 @@ You can set the maximum execution time (in seconds) on the job options by using
    # Create the options object with attributes and values
    options = {"max_execution_time": 360}
 
-You can also find quantum time used by previously completed jobs by using:
+You can also find the system execution time for previously completed jobs by using:
 
 .. code-block:: python
 
-   # Find quantum time used by the job
-   print(f"Quantum time used by job {job.job_id()} was {job.metrics()['usage']['quantum_seconds']} seconds")
+   # Find the system execution time
+   print(f"Job {job.job_id()} system execution time was {job.metrics()['usage']['seconds']} seconds")
 
 In addition, the system calculates an appropriate job timeout value based on the
 input circuits and options. This system-calculated timeout is currently capped
@@ -48,42 +47,15 @@ For example, if you specify ``max_execution_time=5000``, but the system determin
 it should not take more than 5 minutes (300 seconds) to execute the job, then the job will be
 cancelled after 5 minutes.
 
-Session time limits
-***************************
-
-When a session is started, it is assigned a maximum session timeout value.
-After this timeout is reached, the session is terminated, any jobs that are already running continue running, and any queued jobs that remain in the session are put into a ``failed`` state.
-You can set the maximum session timeout value using the ``max_time`` parameter:
-
-.. code-block:: python
-
-   # Set the session max time
-   with Session(max_time="1h"):
-       ...
-
-If you don't specify a session ``max_time``, the system defaults are used:
-
-+--------------+------------------+--------------+-----------+
-| Primitive programs              | Private programs         |
-+==============+==================+==============+===========+
-| Premium User | Open User        | Premium User | Open User |
-+--------------+------------------+--------------+-----------+
-| 8h           | 4h               | 8h           | N/A       |
-+--------------+------------------+--------------+-----------+
-
-Note that a *premium user* here means a user who has access to backends in providers other than ``ibm-q/open/main``.
-
-.. note::
-   Session ``max_time`` is based on wall clock time, not quantum time.
-
-
-Additionally, there is a 5 minute *interactive* timeout value. If there are no session jobs queued within that window, the session is temporarily deactivated and normal job selection resumes. During job selection, if the job scheduler gets a new job from the session and its maximum timeout value has not been reached, the session is reactivated until its maximum timeout value is reached.
+Session maximum execution time
+*******************************
 
-.. note:: The timer for the session's ``max_time`` is not paused during any temporary deactivation periods.
+When a session is started, it is assigned a maximum session timeout value. After this timeout is reached, the session is terminated, any jobs that are already running continue running, and any queued jobs that remain in the session are put into a failed state.  For instructions to set the session maximum time, see `Specify the session length <../how_to/run_session#session_length.html>`__.
 
 
 Other limitations
 ***************************
 
 - Programs cannot exceed 750KB in size.
-- Inputs to jobs cannot exceed 64MB in size.
+- Inputs to jobs cannot exceed 64MB in size.
+- Open plan users can use up to 10 minutes of system execution time per month (resets at 00:00 UTC on the first of each month). System execution time is the amount of time that the system is dedicated to processing your job. You can track your monthly usage on the `Platform dashboard, <https://quantum-computing.ibm.com/>`__ `Jobs, <https://quantum-computing.ibm.com/jobs>`__ and `Account <https://quantum-computing.ibm.com/account>`__ page.
diff --git a/docs/how_to/backends.rst b/docs/how_to/backends.rst
@@ -122,11 +122,9 @@ If you are using a runtime session, add the ``backend`` option when starting you
 
   service = QiskitRuntimeService()
   with Session(service=service, backend="ibmq_qasm_simulator") as session:
-       estimator = Estimator(session=session, options=options)
-       job = estimator.run(circuit, observable)
-       result = job.result()
-       # Close the session only if all jobs are finished, and you don't need to run more in the session
-       session.close() # Closes the session
+      estimator = Estimator(session=session, options=options)
+      job = estimator.run(circuit, observable)
+      result = job.result()
 
   display(circuit.draw("mpl"))
   print(f" > Observable: {observable.paulis}")