diff --git a/docs/faqs/max_execution_time.rst b/docs/faqs/max_execution_time.rst
index 086fa344f..32e763372 100644
--- a/docs/faqs/max_execution_time.rst
+++ b/docs/faqs/max_execution_time.rst
@@ -47,44 +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"):
- ...
+Session maximum execution time
+*******************************
-If you don't specify a session ``max_time``, the system defaults are used (see table below).
+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>`__.
-Additionally, there is an *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. The interactive timeout value is based on the plan type:
-
-.. note:: The timer for the session's ``max_time`` is not paused during any temporary deactivation periods.
-
-+---------------------+-----------------------------------+--------------------------+
-| | Primitive programs | Private programs |
-+=====================+=======================+===========+==============+===========+
-| | Premium or Cloud user | Open user | Premium user | Open user |
-+---------------------+-----------------------+-----------+--------------+-----------+
-| Max time defaults | 8h | 15m | 8h | N/A |
-+---------------------+-----------------------+-----------+--------------+-----------+
-| Interactive timeout | 5m | 2s | 5m | N/A |
-+---------------------+-----------------------+-----------+--------------+-----------+
-
-Note that a *premium user* here means an IBM Quantum channel user who has access to backends in instances other than ``ibm-q/open/main``.
-A *Cloud user* here means an IBM Qiskit Runtime Cloud Standard plan user.
-
-.. note::
- Session ``max_time`` is based on wall clock time.
Other limitations
***************************
- Programs cannot exceed 750KB 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, `__ `Jobs, `__ and `Account `__ pages.
\ No newline at end of file
+- 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, `__ `Jobs, `__ and `Account `__ page.
\ No newline at end of file
diff --git a/docs/how_to/run_session.rst b/docs/how_to/run_session.rst
index 685b986bb..1339e983a 100644
--- a/docs/how_to/run_session.rst
+++ b/docs/how_to/run_session.rst
@@ -1,4 +1,4 @@
-Run a primitive in a session
+Run jobs in a session
=================================
There are several ways to set up and use sessions. The following information should not be considered mandatory steps to follow. Instead, choose the configuration that best suits your needs. To learn more about sessions, see `Introduction to sessions <../sessions.html>`__. This information assumes that you are using Qiskit Runtime `primitives <../primitives.html>`__.
@@ -34,7 +34,7 @@ A session can be created by initializing the `Session` class, which can then be
**Context manager**
-The context manager automatically opens a session for you. A session is started when the first primitive job in this context manager starts (not when it is queued). Primitives created in the context automatically use that session. Example:
+The context manager automatically opens and closes a session for you. A session is started when the first primitive job in this context manager starts (not when it is queued). Primitives created in the context automatically use that session. Example:
.. code-block:: python
@@ -66,13 +66,14 @@ There are two ways to specify a backend in a session:
with Session(backend=backend):
...
+.. _session_length:
Specify the session length
--------------------------
When a session is started, it is assigned a maximum session timeout value. After the session has been open the specified amount of time, the session expires and is forcefully closed. You can no longer submit jobs to that session. See `What happens when a session ends <../sessions.html#ends>`__ for further details.
-You can configure the maximum session timeout value through the ``max_time`` parameter, which can be specified as seconds (int) or a string, like "2h 30m 40s". This value has to be greater than the ``max_execution_time`` of the job and less than the system’s ``max_time``. The default value is the system’s ``max_time``. See `What is the maximum execution time for a Qiskit Runtime job? <../faqs/max_execution_time.html>`__ to determine the system limit.
+You can configure the maximum session timeout value through the ``max_time`` parameter, which can be specified as seconds (int) or a string, like "2h 30m 40s". This value has to be greater than the ``max_execution_time`` of the job and less than the system’s ``max_time``. The default value is the system’s ``max_time``. See `Determine session details <#determine-session-details>`__ to determine the system limit.
When setting the session length, consider how long each job within the session might take. For example, if you run five jobs within a session and each job is estimated to be five minutes long, the maximum time for the session should at least 25 min.
@@ -81,24 +82,186 @@ When setting the session length, consider how long each job within the session m
with Session(service=service, backend=backend, max_time="25m"):
...
-There is also an interactive timeout value (5 minutes), which is not configurable. If no session jobs are queued within that window, the session is temporarily deactivated. For more details about session length and timeout, see `How long a session stays active <../sessions.html#active>`__.
+There is also an interactive timeout value (ITTL) that cannot be configured. If no session jobs are queued within that window, the session is temporarily deactivated. For more details about session length and timeout, see `How long a session stays active <../sessions.html#active>`__. To determine a session's ITTL, follow the instructions in `Determine session details <#determine-session-details>`__ and look for the ``interactive_timeout`` value.
-.. _close session:
+
+.. _close_session:
Close a session
---------------
-When the context manager exits or when `session.close()` is explicitly called, the session won't accept any more jobs. Any queued jobs will run until completion or until the max time expires.
+With `qiskit-ibm-runtime` 0.13 or later releases, when the session context manager is exited, the session is put into `In progress, not accepting new jobs` status. This means that the session will finish processing all running or queued jobs until the maximum timeout value is reached. After all jobs are completed, the session is immediately closed. This allows the
+scheduler to run the next job without waiting for the session interactive timeout,
+therefore reducing the average job queueing time. You cannot submit jobs to a
+closed session.
-When a session that is not accepting jobs has run out of jobs to run, it is immediately closed.
+This behavior exists in `qiskit-ibm-runtime` 0.13 or later releases only. Previously, `session.close()` **canceled** the session.
.. code-block:: python
with Session(service=service, backend=backend):
estimator = Estimator()
job = estimator.run(...)
- # results can also be retrieved after the context manager exits
- result = job.result()
+
+ # The session is no longer accepting jobs but the submitted job will run to completion
+ result = job.result()
+
+.. _cancel_session:
+
+Cancel a session
+----------------
+
+If a session is canceled, the session is put into `Closed` status. Any jobs that are already running continue to run but queued jobs are put into a failed state and no further jobs can be submitted to the session. This is a convenient way to quickly fail all queued jobs within a session.
+
+### For Qiskit runtime releases 0.13 or later
+
+Use the `session.cancel()` method to cancel a session.
+
+.. code-block:: python
+
+ with Session(service=service, backend=backend) as session:
+ estimator = Estimator()
+ job1 = estimator.run(...)
+ job2 = estimator.run(...)
+ # You can use session.cancel() to fail all pending jobs, for example,
+ # if you realize you made a mistake.
+ session.cancel()
+
+For Qiskit Runtime releases 0.13 or later
++++++++++++++++++++++++++++++++++++++++++
+
+Use the `session.cancel()` method to cancel a session.
+
+.. code-block:: python
+
+ with Session(service=service, backend=backend) as session:
+ estimator = Estimator()
+ job1 = estimator.run(...)
+ job2 = estimator.run(...)
+ # You can use session.cancel() to fail all pending jobs, for example,
+ # if you realize you made a mistake.
+ session.cancel()
+
+For Qiskit Runtime releases before 0.13
++++++++++++++++++++++++++++++++++++++++++
+
+Use the `session.close()` method to cancel a session. This allows the
+scheduler to run the next job without waiting for the session timeout,
+therefore making it easier for everyone. You cannot submit jobs to a
+closed session.
+
+.. code-block:: python
+
+ with Session(service=service, backend=backend) as session:
+ estimator = Estimator()
+ job = estimator.run(...)
+ # Do not close here, the job might not be completed!
+ result = job.result()
+ # Reaching this line means that the job is finished.
+ # This close() method would fail all pending jobs.
+ session.close()
+
+Invoke multiple primitives in a session
+----------------------------------------
+You are not restricted to a single primitive function within a session. In this section we will show you an example of using multiple primitives.
+
+First we prepare a circuit for the Sampler primitive.
+
+.. code-block:: python
+
+ from qiskit.circuit.random import random_circuit
+
+ sampler_circuit = random_circuit(2, 2, seed=0).decompose(reps=1)
+ sampler_circuit.measure_all()
+ display(circuit.draw("mpl"))
+
+The following example shows how you can create both an instance of the `Sampler` class and one of the `Estimator` class and invoke their `run()` methods within a session.
+
+.. code-block:: python
+
+ from qiskit_ibm_runtime import Session, Sampler, Estimator
+
+ with Session(backend=backend):
+ sampler = Sampler()
+ estimator = Estimator()
+
+ result = sampler.run(sampler_circuit).result()
+ print(f">>> Quasi-probability distribution from the sampler job: {result.quasi_dists[0]}")
+
+ result = estimator.run(circuit, observable).result()
+ print(f">>> Expectation value from the estimator job: {result.values[0]}")
+
+The calls can also be synchronous. You don’t need to wait for the result of a previous job before submitting another one, as shown below:
+
+.. code-block:: python
+
+ from qiskit_ibm_runtime import Session, Sampler, Estimator
+
+ with Session(backend=backend):
+ sampler = Sampler()
+ estimator = Estimator()
+
+ sampler_job = sampler.run(sampler_circuit)
+ estimator_job = estimator.run(circuit, observable)
+
+ print(
+ f">>> Quasi-probability distribution from the sampler job: {sampler_job.result().quasi_dists[0]}"
+ )
+ print(f">>> Expectation value from the estimator job: {estimator_job.result().values[0]}")
+
+.. _session_status:
+
+Query session status
+---------------------
+
+
+You can query the status of a session using `session.status()`. You can also view a session's status on the Jobs page for your channel.
+
+Session status can be one of the following:
+
+- `Pending`: Session has not started or has been deactivated. The next session job needs to wait in the queue like other jobs.
+- `In progress, accepting new jobs`: Session is active and accepting new jobs.
+- `In progress, not accepting new jobs`: Session is active but not accepting new jobs. Job submission to the session will be rejected, but outstanding session jobs will run to completion. The session will be automatically closed once all jobs finish.
+- `Closed`: Session maximum timeout value has been reached, or session was explicitly closed.
+
+.. _session_details:
+
+Determine session details
+--------------------------
+
+You can find details about a session by using the `session.details()` method, from the `Quantum Platform Jobs page `__, or from the IBM Cloud Jobs page, which you access from your `Instances page `__. From the session details you can determine the `maximum <..sessions#max-ttl.html>`__ and `interactive <..sessions#ttl.html>`__ time to live (TTL) values, its status, whether it's currently accepting jobs, and more.
+
+Example:
+
+.. code-block:: python
+
+ from qiskit_ibm_runtime import QiskitRuntimeService
+
+ service = QiskitRuntimeService()
+
+ with Session(service=service, backend="ibmq_qasm_simulator") as session:
+ estimator = Estimator()
+ job = estimator.run(circuit, observable)
+ print(session.details())
+
+Output:
+
+.. code-block:: text
+
+ {
+ 'id': 'cki5d18m3kt305s4pndg',
+ 'backend_name': 'ibm_algiers',
+ 'interactive_timeout': 300, # This is the interactive timeout, in seconds
+ 'max_time': 28800, # This is the maximum session timeout, in seconds
+ 'active_timeout': 28800,
+ 'state': 'closed',
+ 'accepting_jobs': True,
+ 'last_job_started': '2023-10-09T19:37:42.004Z',
+ 'last_job_completed': '2023-10-09T19:38:10.064Z',
+ 'started_at': '2023-10-09T19:37:42.004Z',
+ 'closed_at': '2023-10-09T19:38:39.406Z'
+ }
+
Full example
------------
diff --git a/docs/sessions.rst b/docs/sessions.rst
index d57764c40..ba28143c8 100644
--- a/docs/sessions.rst
+++ b/docs/sessions.rst
@@ -1,13 +1,11 @@
Introduction to sessions
=============================
-A session is a contract between the user and the Qiskit Runtime service that ensures that a collection of jobs can be grouped and jointly prioritized by the quantum computer’s job scheduler. This eliminates artificial delays caused by other users’ jobs running on the same quantum device during the session time.
+A session allows a collection of jobs to be grouped and jointly scheduled by the Qiskit Runtime service, facilitating iterative use of quantum computers without incurring queuing delays on each iteration. This eliminates artificial delays caused by other users’ jobs running on the same quantum device during the session.
.. image:: images/session-overview.png
:width: 400
-In simple terms, once your session is active, jobs submitted within the session are not interrupted by other users’ jobs.
-
Compared with jobs that use the `fair-share scheduler `__, sessions become particularly beneficial when running programs that require iterative calls between classical and quantum resources, where a large number of jobs are submitted sequentially. This is the case, for example, when training a variational algorithm such as VQE or QAOA, or in device characterization experiments.
Runtime sessions can be used in conjunction with Qiskit Runtime primitives. Primitive program interfaces vary based on the type of task that you want to run on the quantum computer and the corresponding data that you want returned as a result. After identifying the appropriate primitive for your program, you can use Qiskit to prepare inputs, such as circuits, observables (for Estimator), and customizable options to optimize your job. For more information, see the `Primitives `__ topic.
@@ -38,80 +36,107 @@ A quantum processor still executes one job at a time. Therefore, jobs that belon
.. note::
* Internal systems jobs such as calibration have priority over session jobs.
-Iterations and batching
---------------------------
+Maximum session timeout
+++++++++++++++++++++++++++++
-Sessions can be used for iterative or batch execution.
+When a session is started, it is assigned a *maximum session timeout*
+value. You can set this value by using the ``max_time`` parameter, which
+can be greater than the program's ``max_execution_time``. For
+instructions, see `Run a primitive in a session `__.
-Iterative
-+++++++++++++++++++++
+If you do not specify a timeout value, it is set to the system limit.
-Any session job submitted within the five-minute interactive timeout, also known as Time to live (TTL), is processed immediately. This allows some time for variational algorithms, such as VQE, to perform classical post-processing.
+To find the maximum session timeout value for a session, follow the instructions in `Determine session details `__.
-- The quantum device is locked to the session user unless the TTL is reached.
-- Post-processing could be done anywhere, such as a personal computer, cloud service, or an HPC environment.
-.. image:: images/iterative.png
+.. _ttl:
-Batch
-+++++++++++++++++++++
+Interactive timeout value
++++++++++++++++++++++++++++++
-Ideal for running experiments closely together to avoid device drifts, that is, to maintain device characterization.
+Every session has an *interactive timeout value* (ITTL, or interactive time to live). If there are no session jobs queued within the
+ITTL window, the session is temporarily deactivated and normal job
+selection resumes. A deactivated session can be resumed if it has not
+reached its maximum timeout value. The session is resumed when a
+subsequent session job starts. Once a session is deactivated, its next
+job waits in the queue like other jobs.
-- Suitable for batching many jobs together.
-- Jobs that fit within the maximum session time run back-to-back on hardware.
+After a session is deactivated, the next job in the queue is selected to
+run. This newly selected job (which can belong to a different user) can
+run as a singleton, but it can also start a different session. In other
+words, a deactivated session does not block the creation of other
+sessions. Jobs from this new session would then take priority until it
+is deactivated or closed, at which point normal job selection resumes.
-.. note::
- When batching, jobs are not guaranteed to run in the order they are submitted.
+To find the interactive timeout value for a session, follow the instructions in `Determine session details `__.
-.. image:: images/batch.png
+.. _ends:
-.. _active:
+What happens when a session ends
+-------------------------------------
-How long a session stays active
---------------------------------
+A session ends by reaching its maximum timeout value, when it is `closed `__, or when it is canceled by using the `session.cancel()` method. What happens to unfinished session jobs when the session ends depends on how it ended:
-The length of time a session is active is controlled by the *maximum session timeout* (``max_time``) value and the *interactive* timeout value (TTL). The ``max_time`` timer starts when the session becomes active. That is, when the first job runs, not when it is queued. It does not stop if a session becomes inactive. The TTL timer starts each time a session job finishes.
.. note::
- For an Open plan user, the maximum session timeout is 15 minutes.
-
-Maximum session timeout
-++++++++++++++++++++++++++++
+ Previously, `session.close()` **canceled** the session. Starting with `qiskit-ibm-runtime` 0.13, `session.close()` **closes** the session. The `session.cancel()` method was added in `qiskit-ibm-runtime` 0.13.
+
+If the maximum timeout value was reached:
+ - Any jobs that are already running continue to run.
+ - Any queued jobs remaining in the session are put into a failed state.
+ - No further jobs can be submitted to the session.
+ - The session cannot be reopened.
+
+If the maximum timeout value has not been reached:
+
+- When using `qiskit-ibm-runtime` 0.13 or later releases:
+ - If a session is closed:
+ - Session status becomes "In progress, not accepting new jobs".
+ - New job submissions to the session are rejected.
+ - Queued or running jobs continue to run.
+ - The session cannot be reopened.
+ - If a session is canceled:
+ - Session status becomes "Closed."
+ - Running jobs continue to run.
+ - Queued jobs are put into a failed state.
+ - The session cannot be reopened.
+
+- When using Qiskit Runtime releases before 0.13:
+ - Any jobs that are already running continue to run.
+ - Any queued jobs remaining in the session are put into a failed state.
+ - No further jobs can be submitted to the session.
+ - The session cannot be reopened.
+
+Different ways of using sessions
+----------------------------------
-When a session is started, it is assigned a *maximum session timeout* value. You can set this value by using the ``max_time`` parameter, which can be greater than the program's ``max_execution_time``. For instructions, see `Run a primitive in a session `__.
+Sessions can be used for iterative or batch execution.
+Iterative
++++++++++++++++++++++
-If you do not specify a timeout value, it is the smaller of these values:
+Any session job submitted within the five-minute interactive timeout, also known as interactive time to live (ITTL), is processed immediately. This allows some time for variational algorithms, such as VQE, to perform classical post-processing.
- * The system limit
- * The ``max_execution_time`` defined by the program
+- The quantum device is locked to the session user unless the TTL is reached.
+- Post-processing could be done anywhere, such as a personal computer, cloud service, or an HPC environment.
-See `What is the maximum execution time for a Qiskit Runtime job? `__ to determine the system limit and the ``max_execution_time`` for primitive programs.
+.. image:: images/iterative.png
-.. _ttl:
+.. note::
+ There might be a limit imposed on the ITTL value depending on whether your hub is Premium, Open, and so on.
-Interactive timeout value
-+++++++++++++++++++++++++++++
+Batch
++++++++++++++++++++++
-Every session has an *interactive timeout value*, or time to live (TTL), of five minutes, which cannot be changed. If there are no session jobs queued within the TTL window, the session is temporarily deactivated and normal job selection resumes. A deactivated session can be resumed if it has not reached its maximum timeout value. The session is resumed when a subsequent session job starts. Once a session is deactivated, its next job waits in the queue like other jobs.
+Ideal for running experiments closely together to avoid device drifts, that is, to maintain device characterization.
-After a session is deactivated, the next job in the queue is selected to run. This newly selected job (which can belong to a different user) can run as a singleton, but it can also start a different session. In other words, a deactivated session does not block the creation of other sessions. Jobs from this new session would then take priority until it is deactivated or closed, at which point normal job selection resumes.
+- Suitable for batching many jobs together.
+- Jobs that fit within the maximum session time run back-to-back on hardware.
.. note::
- When running jobs through the Open Plan, the interactive timeout value is two seconds.
-
-.. _ends:
-
-What happens when a session ends
--------------------------------------
-
-A session ends by reaching its maximum timeout value or when it is manually closed by the user. Do not close a session until all jobs **complete**. See `Close a session `__ for details. After a session is closed, the following occurs:
-
-* Any queued jobs remaining in the session (whether they are queued or not) are put into a failed state.
-* No further jobs can be submitted to the session.
-* The session cannot be reopened.
+ When batching, jobs are not guaranteed to run in the order they are submitted.
+.. image:: images/batch.png
Sessions and reservations
-------------------------
@@ -120,6 +145,16 @@ IBM Quantum Premium users can access both reservations and sessions on specific
.. image:: images/jobs-failing.png
+Summary
+---------
+
+- Jobs within an active session take priority over other queued jobs.
+- A session becomes active when its first job starts running.
+- A session stays active until one of the following happens:
+ - Its maximum timeout value is reached. In this case all queued jobs are canceled, but running jobs will finish.
+ - Its interactive timeout value is reached. In this case the session is deactivated but can be resumed if another session job starts running.
+ - The session is closed or cancelled. This can be done using the corresponding methods or upon exiting a session context.
+- Sessions can be used for iterative or batch execution.
Next steps
------------