Skip to content

Commit

Permalink
sessions changes (#1169)
Browse files Browse the repository at this point in the history 
* sessions changes

* add more ticks

* fix link

* fix links

* Update docs/sessions.rst

Co-authored-by: abbycross <across@us.ibm.com>

* Update docs/sessions.rst

Co-authored-by: abbycross <across@us.ibm.com>

---------

Co-authored-by: abbycross <across@us.ibm.com>
  • Loading branch information
@beckykd @abbycross
beckykd and abbycross authored Oct 24, 2023
1 parent b4abf6a commit 226b9df
Show file tree
Hide file tree
Showing 3 changed files with 261 additions and 92 deletions.
37 changes: 4 additions & 33 deletions docs/faqs/max_execution_time.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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, <https://quantum-computing.ibm.com/>`__ `Jobs, <https://quantum-computing.ibm.com/jobs>`__ and `Account <https://quantum-computing.ibm.com/account>`__ pages.
- 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.
181 changes: 172 additions & 9 deletions docs/how_to/run_session.rst
View file
Original file line number Diff line number Diff line change
@@ -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>`__.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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 <https://quantum-computing.ibm.com/jobs>`__, or from the IBM Cloud Jobs page, which you access from your `Instances page <https://cloud.ibm.com/quantum/instances>`__. 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
------------
Expand Down
Loading

0 comments on commit 226b9df

Please sign in to comment.