Execution Session - Classiq Docs

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 three 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.
minimize: Runs a variational minimization loop, iteratively sampling the circuit to minimize a cost function using the COBYLA optimizer.

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]])

The minimize method accepts a max_iteration parameter:

es.minimize(cost_function, initial_params, max_iteration)

max_iteration does not directly control the number of quantum jobs. It sets an upper bound on the number of classical optimizer (COBYLA) iterations; the optimizer may converge before reaching this limit. See the scipy COBYLA documentation for details on iteration and convergence behavior.

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.

​Initializing

​Quantum program

​OpenQASM string

​Operations

​Examples

​sample()

​estimate()

​Handling Long Jobs

​@cfunc

Initializing

Quantum program

OpenQASM string

Operations

Examples

sample()

estimate()

Handling Long Jobs

`@cfunc`