From f9cfaa05f6ddaff64ee979f8ce08f2bd7b4768ab Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Fri, 17 Jan 2025 15:35:22 -0600 Subject: [PATCH] Get rid of separate Intro to sessions --- docs/guides/execution-modes.mdx | 7 +-- docs/guides/primitives-examples.ipynb | 4 +- docs/guides/sessions.mdx | 75 --------------------------- scripts/config/internal-links.json | 13 ----- 4 files changed, 6 insertions(+), 93 deletions(-) delete mode 100644 docs/guides/sessions.mdx diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index 49c66872875..bfa0a01642e 100644 --- a/docs/guides/execution-modes.mdx +++ b/docs/guides/execution-modes.mdx @@ -5,7 +5,7 @@ description: An overview of the available execution modes in Qiskit Runtime; ses --- # Introduction to Qiskit Runtime execution modes -There are several ways to run workloads, depending on your needs. Execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your jobs to run efficiently within your time budget. +There are several ways to run workloads, depending on your needs. Execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your jobs to run efficiently within your budget. **Job mode**: A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify `mode=backend` when instantiating a primitive. See [Primitives examples](/guides/primitives-examples) for examples. @@ -60,8 +60,9 @@ The the benefits of each are summarazed below: - There is usually minimal delay between jobs, which can help avoid drift. - If you partition your workload into multiple jobs and run them in batch mode, you can get results from individual jobs, which makes them more flexible to work with. - **Session** - - Dedicated and exclusive access to the QPU during the session active window, and no other users’ or QPU jobs can run. - - Useful for workloads that don’t have all inputs ready at the outset. + - Dedicated and exclusive access to the QPU during the session active window. + - Can run multiple experiments simultaneously. + - Useful for workloads that don’t have all inputs ready at the outset or for iterative workloads that require dedicated access. - **Job** - Easiest to use when running a small experiment. - Might run sooner than batch mode. diff --git a/docs/guides/primitives-examples.ipynb b/docs/guides/primitives-examples.ipynb index de0606ccd00..7fe4254a888 100644 --- a/docs/guides/primitives-examples.ipynb +++ b/docs/guides/primitives-examples.ipynb @@ -59,7 +59,7 @@ "isa_circuit = pm.run(circuit)\n", "isa_observable = observable.apply_layout(isa_circuit.layout)\n", "\n", - "estimator = Estimator(backend)\n", + "estimator = Estimator(mode=backend)\n", "job = estimator.run([(isa_circuit, isa_observable)])\n", "result = job.result()\n", "\n", @@ -440,7 +440,7 @@ "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", "isa_circuits = pm.run(circuits)\n", "\n", - "sampler = Sampler(backend)\n", + "sampler = Sampler(mode=backend)\n", "job = sampler.run(isa_circuits)\n", "result = job.result()\n", "\n", diff --git a/docs/guides/sessions.mdx b/docs/guides/sessions.mdx deleted file mode 100644 index 83c96ae2b47..00000000000 --- a/docs/guides/sessions.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Sessions -description: An overview of Qiskit Runtime sessions and when to use them. - ---- -# Introduction to Qiskit Runtime sessions - - -Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead. - - -## What is a session? - -A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources. - - -The queuing time does not decrease for the first job submitted within a session. Therefore, a session does not provide any benefits when running a single job. Additionally, sessions do not work on simulators because simulators do not have a queue. - - -## Advantages of using sessions - -There are several benefits to using sessions: - -- Efficiency: Multiple jobs from a single algorithm run can be run sequentially without interruptions. -- Flexibility: You can submit jobs, check results, and submit new jobs within an active session without needing to start a new one. - -For instructions to start a session, see [Run a job in a session](/guides/run-jobs-session). - - -## End a session - -A session ends in the following circumstances: - -* The maximum timeout (TTL) value is reached, resulting in the cancelation of all queued jobs. -* The session is manually canceled, resulting in the cancelation of all queued jobs. -* The session is manually closed. The session stops accepting new jobs but continues to run queued jobs with priority. -* If you use Session as a context manager, that is, `with Session()`, the session is automatically closed when the context ends (the same behavior as using `session.close()`). - - -When a session ends, the QPU finishes running any job that is currently running. - - -## Usage patterns - -Sessions are especially useful for algorithms that require classical post-processing, where jobs submitted within the interactive time-out are processed immediately. If you want to submit jobs in a batch instead, see [Run jobs in a batch.](run-jobs-batch) - -Example: Run an iterative workload that uses the classical SciPy optimizer to minimize a cost function. In this model, SciPy uses the output of the cost function to calculate its next input. - -```python -def cost_func(params, ansatz, hamiltonian, estimator): - # Return estimate of energy from estimator - - energy = estimator.run(ansatz, hamiltonian, parameter_values=params).result().values[0] - return energy - -x0 = 2 * np.pi * np.random.random(num_params) - -session = Session(backend=backend) - -# If using qiskit-ibm-runtime earlier than 0.24.0, change `mode=` to `session=` -estimator = Estimator(mode=session, options={"shots": int(1e4)}) -res = minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method="cobyla") - -# Close the session because we didn't use a context manager. -session.close() -``` - -## Next steps - - - - Try an example in the [Quantum approximate optimization algorithm (QAOA)](https://learning.quantum.ibm.com/tutorial/quantum-approximate-optimization-algorithm) tutorial. - - Review the [Session API](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.Session) reference. - - Review the execution modes [best practices.](execution-modes#best-practices) - - Learn how to [run a job in a session.](./run-jobs-session) - \ No newline at end of file diff --git a/scripts/config/internal-links.json b/scripts/config/internal-links.json index d849e558ab4..ec26064a37b 100644 --- a/scripts/config/internal-links.json +++ b/scripts/config/internal-links.json @@ -1684,19 +1684,6 @@ "#when-should-i-use-qiskit-serverless" ] }, - { - "path": "docs/guides/sessions.mdx", - "anchors": [ - "#advantages-of-using-sessions", - "#end-a-session", - "#ends", - "#how-sessions-work", - "#introduction-to-qiskit-runtime-sessions", - "#next-steps", - "#usage-patterns", - "#what-is-a-session" - ] - }, { "path": "docs/guides/set-optimization.ipynb", "anchors": [