Runners.h File Reference

Include dependency graph for Runners.h:

This graph shows which files directly or indirectly include this file:

Functions
std::expected< std::string, Error >	mqss::qrmci::chooseBackend (const mqss::QuantumTask &task, const BackendRegistry &availableBackends, BackendSelectionPolicy policy=BackendSelectionPolicy::LowestName)
	Choose the backend that should execute a quantum task.
std::expected< void, Error >	mqss::qrmci::compileQuantumTask (mqss::QuantumTask &task, const BackendWrapper &backendInfo, mqss::mqssci::MQSSCompiler &compiler)
	Compile the quantum task using compiler.
std::expected< void, Error >	mqss::qrmci::compileQuantumTask (mqss::QuantumTask &task, const BackendWrapper &backendInfo)
	Compile the quantum task with a compiler of this function's own, for callers that have no reason to own one.
std::expected< mqss::QuantumResult, Error >	mqss::qrmci::buildQuantumResult (const mqss::QuantumTask &task, const std::vector< std::optional< mqss::submitter::Counts > > &histogram)
	Build a QuantumResult from a task and its job-result histogram, the shared tail end of submitQuantumTask()+collectQuantumResult() and executeQuantumTask().
std::expected< std::vector< mqss::submitter::Job >, Error >	mqss::qrmci::submitQuantumTask (const mqss::QuantumTask &task, const mqss::submitter::Device &device)
	Submit the quantum task's circuits to the device without waiting for their results.
std::expected< std::vector< mqss::submitter::Job >, Error >	mqss::qrmci::submitQuantumTask (const mqss::QuantumTask &task, const mqss::submitter::Device &device, const std::atomic< bool > &terminationFlag)
	Interruptible overload of submitQuantumTask(), for a daemon work loop composing its own termination flag.
std::expected< mqss::QuantumResult, Error >	mqss::qrmci::collectQuantumResult (const mqss::QuantumTask &task, std::vector< mqss::submitter::Job > &jobs, std::chrono::seconds waitTimeout)
	Collect the results of previously submitted quantum jobs.
std::expected< mqss::QuantumResult, Error >	mqss::qrmci::collectQuantumResult (const mqss::QuantumTask &task, std::vector< mqss::submitter::Job > &jobs, std::chrono::seconds waitTimeout, const std::atomic< bool > &terminationFlag)
	Interruptible overload of collectQuantumResult(), for a daemon work loop composing its own termination flag.
std::expected< mqss::QuantumResult, Error >	mqss::qrmci::executeQuantumTask (const mqss::QuantumTask &task, const mqss::submitter::Device &device, std::chrono::seconds waitTimeout)
	Execute the quantum task on the device: submits it and collects its result in one call.
std::expected< mqss::QuantumResult, Error >	mqss::qrmci::executeQuantumTask (const mqss::QuantumTask &task, const mqss::submitter::Device &device, std::chrono::seconds waitTimeout, const std::atomic< bool > &terminationFlag)
	Interruptible overload of executeQuantumTask(), composing the interruptible submitQuantumTask()/collectQuantumResult() overloads.
mqss::QuantumResult	mqss::qrmci::cancelQuantumTask (const mqss::QuantumTask &task, const std::string &cancelReason)
	Cancel the quantum task and return a cancellation result.

Detailed Description

The QRM&CI pipeline stages as free functions: choosing a backend, compiling a task for it, submitting it to a device, collecting its result, and reporting a cancellation.

An entrypoint composes these into whatever loop it needs; none of them owns state of its own.

Definition in file Runners.h.

Function Documentation

buildQuantumResult()

std::expected< mqss::QuantumResult, Error > mqss::qrmci::buildQuantumResult ( const mqss::QuantumTask & task, const std::vector< std::optional< mqss::submitter::Counts > > & histogram )

nodiscard

Build a QuantumResult from a task and its job-result histogram, the shared tail end of submitQuantumTask()+collectQuantumResult() and executeQuantumTask().

histogram's length must equal task's circuit file count, and every entry must carry counts: cardinality is preserved rather than collapsed, so the result has exactly one entry per circuit, in the same order, on success. Every count must also fit in the wire format's int32_t. Validated up front, before anything is written to the result, so a failure never returns a partially assembled QuantumResult.

Parameters

task	The quantum task the histogram belongs to (used to populate the result's task/destination/QPU fields).
histogram	One counts map per circuit file, or nullopt for a circuit that produced no counts.

Returns

An expected QuantumResult containing one result entry per circuit, or a DeviceError if the histogram's length does not match the task's circuit count, any entry is nullopt, or any count exceeds INT32_MAX – each case naming the offending circuit index, or bitstring and value.

cancelQuantumTask()

mqss::QuantumResult mqss::qrmci::cancelQuantumTask ( const mqss::QuantumTask & task, const std::string & cancelReason )

nodiscard

Cancel the quantum task and return a cancellation result.

Parameters

task	The quantum task to cancel.
cancelReason	The reason for cancellation.

Returns

A QuantumResult indicating the task was cancelled, including the cancellation reason.

chooseBackend()

std::expected< std::string, Error > mqss::qrmci::chooseBackend ( const mqss::QuantumTask & task, const BackendRegistry & availableBackends, BackendSelectionPolicy policy = BackendSelectionPolicy::LowestName )

nodiscard

Choose the backend that should execute a quantum task.

A pure query: it neither reads nor writes the task's scheduled QPU, so the caller assigns the returned name itself. The task's preferred QPU wins whenever it is registered, online and able to run the task; otherwise policy picks among every backend that can, deterministically.

Parameters

task	The quantum task to choose a backend for.
availableBackends	The backends to choose from.
policy	The rule for picking among several compatible backends.

Returns

The name of the chosen backend, or a NoBackendAvailable error if no suitable backend is found.

collectQuantumResult() [1/2]

std::expected< mqss::QuantumResult, Error > mqss::qrmci::collectQuantumResult ( const mqss::QuantumTask & task, std::vector< mqss::submitter::Job > & jobs, std::chrono::seconds waitTimeout )

nodiscard

Collect the results of previously submitted quantum jobs.

Pairs with submitQuantumTask(); see that function's documentation for why the two are split apart.

Uninterruptible: unsuitable for a daemon work loop that must shut down promptly. Delegates to the four-argument overload with a flag that is never set.

Parameters

task	The quantum task the jobs were submitted for (used to populate the result's task/destination/QPU fields).
jobs	The jobs returned by submitQuantumTask(), waited on in order.
waitTimeout	How long to wait for each job; zero waits indefinitely.

Returns

An expected QuantumResult containing one result entry per job, or a DeviceError if a wait or a counts read failed, if a job finished in any state other than Done, or if a count exceeds INT32_MAX (buildQuantumResult()'s own checks; jobs' length already matches the task's circuit count here, so cardinality itself cannot mismatch).

collectQuantumResult() [2/2]

std::expected< mqss::QuantumResult, Error > mqss::qrmci::collectQuantumResult ( const mqss::QuantumTask & task, std::vector< mqss::submitter::Job > & jobs, std::chrono::seconds waitTimeout, const std::atomic< bool > & terminationFlag )

nodiscard

Interruptible overload of collectQuantumResult(), for a daemon work loop composing its own termination flag.

Each job is waited on in slices of at most one second rather than in one blocking call, so terminationFlag is checked, and a shutdown honoured, between slices instead of only before the whole wait. A zero waitTimeout still waits indefinitely absent a shutdown, but is now interruptible rather than truly unbounded; a positive waitTimeout still times out at the same total deadline as the three-argument overload.

Parameters

task	The quantum task the jobs were submitted for.
jobs	The jobs returned by submitQuantumTask(), waited on in order.
waitTimeout	How long to wait for each job; zero waits indefinitely.
terminationFlag	Consulted before every wait slice.

Returns

An expected QuantumResult as the three-argument overload describes, or ShutdownRequested if terminationFlag was set before every job finished.

compileQuantumTask() [1/2]

std::expected< void, Error > mqss::qrmci::compileQuantumTask ( mqss::QuantumTask & task, const BackendWrapper & backendInfo )

nodiscard

Compile the quantum task with a compiler of this function's own, for callers that have no reason to own one.

A caller that compiles repeatedly should construct an mqss::mqssci::MQSSCompiler once and use the three-argument overload instead, rather than paying for a fresh compiler per task.

Parameters

task	The quantum task to compile.
backendInfo	The backend information to use for compilation.

Returns

Returns nothing on success, or an error describing why compilation failed.

compileQuantumTask() [2/2]

std::expected< void, Error > mqss::qrmci::compileQuantumTask ( mqss::QuantumTask & task, const BackendWrapper & backendInfo, mqss::mqssci::MQSSCompiler & compiler )

nodiscard

Compile the quantum task using compiler.

Parameters

task	The quantum task to compile.
backendInfo	The backend information to use for compilation.
compiler	The compiler to use for compilation.

Returns

Returns nothing on success, or an error describing why compilation failed.

executeQuantumTask() [1/2]

std::expected< mqss::QuantumResult, Error > mqss::qrmci::executeQuantumTask ( const mqss::QuantumTask & task, const mqss::submitter::Device & device, std::chrono::seconds waitTimeout )

nodiscard

Execute the quantum task on the device: submits it and collects its result in one call.

Equivalent to submitQuantumTask() followed by collectQuantumResult(); use those directly to submit several tasks before collecting any of their results (pipelined batch submission).

Uninterruptible: unsuitable for a daemon work loop that must shut down promptly. Delegates to the four-argument overload with a flag that is never set.

Parameters

task	The quantum task to execute.
device	The device to execute on.
waitTimeout	How long to wait for each job; zero waits indefinitely.

Returns

An expected QuantumResult containing the execution results, or the error reported by whichever of the two steps failed.

executeQuantumTask() [2/2]

std::expected< mqss::QuantumResult, Error > mqss::qrmci::executeQuantumTask ( const mqss::QuantumTask & task, const mqss::submitter::Device & device, std::chrono::seconds waitTimeout, const std::atomic< bool > & terminationFlag )

nodiscard

Interruptible overload of executeQuantumTask(), composing the interruptible submitQuantumTask()/collectQuantumResult() overloads.

Parameters

task	The quantum task to execute.
device	The device to execute on.
waitTimeout	How long to wait for each job; zero waits indefinitely.
terminationFlag	Consulted by both the submission and collection stages; see their own documentation for exactly when.

Returns

An expected QuantumResult as the three-argument overload describes, or ShutdownRequested if terminationFlag was set before submission or collection finished.

submitQuantumTask() [1/2]

std::expected< std::vector< mqss::submitter::Job >, Error > mqss::qrmci::submitQuantumTask ( const mqss::QuantumTask & task, const mqss::submitter::Device & device )

nodiscard

Submit the quantum task's circuits to the device without waiting for their results.

Pairs with collectQuantumResult() to let a caller submit several tasks back-to-back before collecting any of their results (pipelined batch submission), instead of blocking on each task's result in turn the way executeQuantumTask() does.

A Job carries exactly one payload, so a task with N circuit files becomes N jobs, submitted in the files' own order and returned in that order. The first submission failure short-circuits without waiting on or collecting any job already submitted for this task.

Uninterruptible: unsuitable for a daemon work loop that must shut down promptly. Delegates to the three-argument overload with a flag that is never set.

Parameters

task	The quantum task to submit.
device	The device to submit to.

Returns

The submitted jobs, one per circuit file, or a SubmissionFailed error – which also covers a task with no circuit files or a zero shot count, both refused before the device is touched.

submitQuantumTask() [2/2]

std::expected< std::vector< mqss::submitter::Job >, Error > mqss::qrmci::submitQuantumTask ( const mqss::QuantumTask & task, const mqss::submitter::Device & device, const std::atomic< bool > & terminationFlag )

nodiscard

Interruptible overload of submitQuantumTask(), for a daemon work loop composing its own termination flag.

terminationFlag is checked before each circuit's submission. If it is set, every job already submitted for this task is best-effort cancelled (a cancellation failure is logged, not propagated) and the call returns Error::Kind::ShutdownRequested instead of submitting the rest.

Parameters

task	The quantum task to submit.
device	The device to submit to.
terminationFlag	Consulted before every circuit submission.

Returns

The submitted jobs, one per circuit file; a SubmissionFailed error as the two-argument overload describes; or ShutdownRequested if terminationFlag was set before every circuit could be submitted.