QuantumProgram

class QuantumProgram(backend, seed=None, progress_queue=None, program_id=None, precision=8, **kwargs)

Bases: ABC

Abstract base class for quantum programs.

Subclasses must implement:

• run(): Execute the quantum algorithm

Variables:

• backend – The quantum circuit execution backend.

• _seed – Random seed for reproducible results.

• _progress_queue – Queue for progress reporting.

Initialize the QuantumProgram.

Parameters:

• backend (CircuitRunner) – Quantum circuit execution backend.

• seed (int | None) – Random seed for reproducible results. Defaults to None.

• progress_queue (Queue | None) – Queue for progress reporting. Defaults to None.

• program_id (str | None) – Program identifier for progress reporting in batch operations. If provided along with progress_queue, enables queue-based progress reporting.

• precision (int) – Decimal places for numeric parameter values in QASM emission. Higher values produce longer QASM strings; lower values shrink them at the cost of parameter resolution. Defaults to DEFAULT_PRECISION.

Attributes Summary

precision	Decimal places used for numeric parameter values in QASM emission.
total_circuit_count	Get the total number of circuits executed.
total_run_time	Get the total runtime across all circuit executions.

Methods Summary

cancel_unfinished_job()	Cancel the currently running cloud job if one exists.
dry_run(*[, force_circuit_generation])	Run forward pass on all pipelines and return a fan-out analysis.
has_results()	Return True once the program has produced results.
run(**kwargs)	Execute the quantum algorithm.

Attributes Documentation

precision

Decimal places used for numeric parameter values in QASM emission.

total_circuit_count

Get the total number of circuits executed.

Returns:

Cumulative count of circuits submitted for execution.

Return type:

int

total_run_time

Get the total runtime across all circuit executions.

Returns:

Cumulative execution time in seconds.

Return type:

float

Methods Documentation

cancel_unfinished_job()

Cancel the currently running cloud job if one exists.

This method attempts to cancel the job associated with the current ExecutionResult. It is best-effort and will log warnings for any errors (e.g., job already completed, permission denied) without raising exceptions.

This is typically called by ProgramEnsemble when handling cancellation to ensure cloud jobs are cancelled before local threads terminate.

dry_run(*, force_circuit_generation=False)

Run forward pass on all pipelines and return a fan-out analysis.

Traverses each pipeline stage without executing circuits and collects the fan-out factor, per-stage metadata, and total circuit count into a dict of DryRunReport objects keyed by the names registered in _build_pipelines(). Pass the returned dict to format_dry_run() for the pretty tree output.

Uses the analytic dry path by default; see the user guide for how that trades circuit generation for multiplicative-factor bookkeeping.

Parameters:

force_circuit_generation (bool) – If True, force every stage to run its full expand path so that the trace contains real DAGs and QASM strings. Useful when inspecting actual pipeline output (e.g. debugging a stage’s circuit transformation). Defaults to False.

Return type:

dict[str, DryRunReport]

Example

>>> from divi.pipeline import format_dry_run
>>> reports = program.dry_run()
>>> format_dry_run(reports)  # pretty-print to stdout

abstractmethod has_results()

Return True once the program has produced results.

Return type:

bool

abstractmethod run(**kwargs)

Execute the quantum algorithm.

Parameters:

**kwargs – Additional keyword arguments for subclasses.

Returns:

Returns self for method chaining.

Return type:

QuantumProgram