Skip to main content
This section explains how to execute a quantum program using the ExecutionSession class. The class enables executing a quantum program with parameters and operations, eliminating the need to resynthesize the model.

​
Initializing

Initialize ExecutionSession with either:
  • A quantum program (the output of synthesize), or
  • OpenQASM 2.0 or 3.0 source as a string (same semantics as the first argument to sample).
It is recommended to use ExecutionSession as a context manager in order to ensure resources are cleaned up. Alternatively, you can call the close method directly.

​
Quantum program

from classiq import qfunc, synthesize, ExecutionSession


@qfunc
def main():
    pass


qprog = synthesize(main)

with ExecutionSession(qprog) as es:
    ...

​
OpenQASM string

from classiq import ExecutionSession

openqasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[1];
h q[0];
"""

with ExecutionSession(openqasm) as es:
    details = es.sample()
When the first argument is OpenQASM text, do not use parameters on sample / submit_sample for Qmod-style main arguments; use a synthesized QuantumProgram instead.

​
Operations

ExecutionSession supports two types of operations:
  • sample: Executes the quantum program with the specified parameters.
  • estimate: Computes the expectation value of the specified Hamiltonian using the quantum program.
When estimating using a simulator, the ClassiqSimulatorBackendNames.SIMULATOR_STATEVECTOR backend calculates the expectation value directly from the computed state vector, as opposed to computing it from shots. Each invocation mode can use one of these options:
  • single
  • submit: When using submit as a prefix, the job object returns immediately, and the results should be polled. See ExecutionJob in the sdk reference.
For the sample method, pass a single parameter dict or a list for batch execution:
  • es.sample(parameters: Optional[ExecutionParams | List[ExecutionParams]])
  • es.submit_sample(parameters: Optional[ExecutionParams | List[ExecutionParams]])
The estimate method works the same way:
  • es.estimate(hamiltonian: SparsePauliOp, parameters: Optional[ExecutionParams | List[ExecutionParams]])
  • es.submit_estimate(hamiltonian: SparsePauliOp, parameters: Optional[ExecutionParams | List[ExecutionParams]])

​
Examples

​
sample()

A simple example of how to use sample and its variations: 
from classiq import (
    qfunc,
    Output,
    QBit,
    CReal,
    synthesize,
    RX,
    allocate,
    ExecutionSession,
)


@qfunc
def main(x: Output[QBit], t: CReal):
    allocate(1, x)
    RX(t, x)


qprog = synthesize(main)

with ExecutionSession(qprog) as execution_session:
    sample_result = execution_session.sample({"t": 0.5})
    print(sample_result.dataframe)
    batch_sample_result = execution_session.sample([{"t": 0.5}, {"t": 0.6}])
    sample_job = execution_session.submit_sample({"t": 0.5})
    batch_sample_job = execution_session.submit_sample([{"t": 0.5}, {"t": 0.6}])

​
estimate()

An example that shows how to use estimate and its variations: 
from classiq import (
    qfunc,
    Output,
    QBit,
    CReal,
    synthesize,
    Pauli,
    RX,
    allocate,
    ExecutionSession,
)


@qfunc
def main(x: Output[QBit], t: CReal):
    allocate(1, x)
    RX(t, x)


qprog = synthesize(main)

with ExecutionSession(qprog) as execution_session:
    hamiltonian = Pauli.I(0) + 2 * Pauli.Z(0)

    estimate_result = execution_session.estimate(hamiltonian, {"t": 0.5})
    batch_estimate_result = execution_session.estimate(
        hamiltonian, [{"t": 0.5}, {"t": 0.6}]
    )
    estimate_job = execution_session.submit_estimate(hamiltonian, {"t": 0.5})
    batch_estimate_job = execution_session.submit_estimate(
        hamiltonian, [{"t": 0.5}, {"t": 0.6}]
    )

​
Handling Long Jobs

When handling long-running jobs (jobs that are submitted to HW providers with potentially very long queues) it is advisable to retrieve and save the job ID for future reference: 
...
with ExecutionSession(qprog) as session:
    job = session.submit_sample()
    job_ID = job.id

restored_job = ExecutionJob.from_id(job_ID)
results = restored_job.get_sample_result()
Alternatively, for scenarios requiring result polling, e.g., iterative hybrid algorithms, consider the following partial code example. This example runs a series of quantum estimation jobs, step by step. It automatically submits each job, collects the results, checks they meet certain criteria (for example, does the cost exceed a certain threshold), and adjusts the parameters for the next job based on those results. 
from classiq import ExecutionSession, ExecutionJob


def get_data_from_file():
    # read data from file
    return data


def store_data_in_file(data):
    # save data in file
    return


with ExecutionSession(qprog) as session:
    iterations_data = get_data_from_file() or []

    for _ in range(max_iterations - len(iterations_data)):
        if iterations_data and "result" not in iterations_data[-1]:
            # continue the loop from the last iteration
            last_job = ExecutionJob.from_id(iterations_data[-1]["job_id"])
        else:
            last_job = session.submit_estimate(hamiltonian, params)
            iterations_data.append({"job_id": last_job.id, "params": params})
            store_data_in_file(iterations_data)

        result = last_job.get_estimate_result()
        iterations_data[-1]["result"] = result
        store_data_in_file(iterations_data)

        if result_is_good_enough(result):
            break

        params = compute_the_next_parameters(result)

​
@cfunc

Note that Classiq does not support algorithms utilizing @cfunc (or cscope in Qmod native) for long job execution.