qlauncher.launcher.aql.aql

qlauncher.launcher.aql.aql#

Asynchronous QLauncher orchestration layer (AQL).

AQL is a lightweight orchestration utility that lets you submit one or more QLauncher executions to a pluggable job manager (BaseJobManager) and collect the results later.

Conceptually, AQL builds a dependency graph of tasks and runs a scheduler thread that: - submits tasks whose dependencies are satisfied, - waits for any job to finish via the manager, - reads results, surfaces exceptions, and triggers callbacks.

Execution modes: - default: tasks are submitted as soon as they are ready. - optimize_session: for device backends (backend.is_device == True), a task is split into a

formatter step (problem conversion) and a quantum execution step. Two barrier “gateway” tasks are then inserted so that the global ordering becomes: (classical prerequisites of quantum) -> (all quantum tasks) -> (remaining classical tasks).

Example

from qlauncher.workflow.new_aql import AQL from qlauncher.launcher.qlauncher import QLauncher from qlauncher.routines.qiskit import FALQON, QiskitBackend

problem = … # Problem / Hamiltonian algo = FALQON(max_reps=1) backend = QiskitBackend(“local_simulator”) launcher = QLauncher(problem, algo, backend)

with AQL(mode=”default”) as aql:

aql.add_task(launcher, shots=128) aql.start() result = aql.results(timeout=60)[0]

Summary#

Classes:

AQL

Launches QLauncher tasks asynchronously, using a provided BaseJobManager.

Reference#

class qlauncher.launcher.aql.aql.AQL(mode: Literal['default', 'optimize_session'] = 'default', manager: BaseJobManager | None = None)[source]#

Bases: object

Launches QLauncher tasks asynchronously, using a provided BaseJobManager.

  • In ‘default’ mode, tasks are submitted as they become ready.

  • In ‘optimize_session’ mode, real-device tasks are split (format + quantum run) and

    a dependency barrier is inserted so that: (all classical prereqs of quantum) -> (all quantum tasks) -> (remaining classical tasks).

Notes: - **run_kwargs are forwarded to QLauncher.run(**run_kwargs). - manager_kwargs are forwarded to manager.submit(…, **manager_kwargs).

running_task_count() → int[source]#

Return the number of currently running internal tasks.

Parameters:

None.

Returns:

Number of tasks for which task.running() is True.

Return type:

int

cancel_running_tasks() → None[source]#

Best-effort cancellation of all internal tasks (classical + quantum).

Parameters:

None.

Returns:

None.

Return type:

None

results(timeout: float | int | None = None, cancel_tasks_on_timeout: bool = True) → list[Result | None][source]#

Collect results from user-visible tasks (in the order they were added).

Parameters:

  • timeout (float | int | None) – Total timeout budget (seconds) shared across all result() waits.

  • cancel_tasks_on_timeout (bool) – If True, cancel any still-running tasks when a TimeoutError is raised.

Returns:

A list of results aligned with add_task order. Cancelled tasks yield None.

Raises:

  • TimeoutError – If the overall timeout is exceeded while waiting for results.

  • BaseException – Re-raises any exception from the underlying task or scheduler.

Return type:

list[Result | None]

add_task(launcher: QLauncher | tuple[Problem | Model, Algorithm, Backend], dependencies: list[ManagerBackedTask] | None = None, callbacks: list[Callable] | None = None, manager_kwargs: dict[str, Any] | None = None, **run_kwargs: object) → ManagerBackedTask[source]#

Add a QLauncher task to the execution queue.

In default mode (or when launcher.backend.is_device is False), this creates a single task that calls launcher.run(**run_kwargs).

In optimize_session mode for device backends, the submission is split into: 1) a formatter task (launcher._get_compatible_problem), 2) a quantum execution task that builds a new launcher in the worker and runs it. The returned (user-visible) task is the quantum execution task.

Parameters:

  • launcher (QLauncher | tuple[Problem | Model, Algorithm, Backend]) – Either a QLauncher instance or a tuple (problem, algorithm, backend) used to construct one.

  • dependencies (list[ManagerBackedTask] | None) – Optional list of tasks that must complete before this task can run.

  • callbacks (list[Callable] | None) – Optional list of callables invoked with the task outcome.

  • manager_kwargs (dict[str, Any] | None) – Keyword arguments forwarded to manager.submit(...) when the task is submitted.

  • **run_kwargs (object) – Keyword arguments forwarded to QLauncher.run(**run_kwargs).

Returns:

A ManagerBackedTask representing the submitted work. For device backends in optimize_session mode, this is the quantum execution task.

Return type:

ManagerBackedTask

start() → None[source]#

Start scheduling and execution in a background thread.

This validates that no tasks were previously submitted, prepares session barriers for optimize_session mode (once), and then starts the scheduler loop.

Parameters:

None.

Returns:

None.

Raises:

ValueError – If the scheduler is already running or tasks were already submitted/finished.

Return type:

None