Add readout function for probabilities to QDMI

[MariusEviden]

Currently there one has the possibility to use the "QDMI_control_readout_raw" function to transfer the readout results via QMDI. The function expects integer values for the results, i.e. number of counts per state (int array "num").

For simulated backends it is also possible to calculate the exact probability without having a finite shot number. Therefore it may makes sense to provide the possibility to give probabilities as result instead of counts. This is currently not possible due to the fact that "num" expects integer values. Maybe this can be achieved by providing an additional function (e.g. QDMI_control_readout_probabilities) that expects a double array "num" instead of an integer one, or by adapting the function QDMI_control_readout_raw.

[burgholzer]

Thanks for raising this issue! This is something we noticed during the latest work on QDMI as well. The functions you are referring to, no longer exist in the current version of QDMI. Instead, a single function

/**
 * @brief Retrieve the results of a job.
 * @details The results of a job can vary
 * @param[in] job The job to retrieve the results from.
 * @param[in] result The result to retrieve.
 * @param[in] size The size of the data buffer in bytes.
 * @param[out] data The data of the result.
 * @param[out] size_ret The size of the returned data in bytes.
 * @return @ref QDMI_SUCCESS if the results were successfully retrieved.
 * @return @ref QDMI_ERROR_INVALIDARGUMENT if the job has not finished yet, was
 * cancelled, or does not exist.
 * @return @ref QDMI_ERROR_FATAL if an error occurred during the retrieval.
 */
int QDMI_control_get_data_dev(QDMI_Job job, QDMI_Job_Result result, int size,
                              void *data, int *size_ret);

is provided here.

That method takes a QDMI_Job_Result result, which is an enum defined here, and a buffer for data (int size, void *data).

With that function, almost arbitrary results can be returned from a job. Two obvious candidates related to the issue at hand here, which are not yet available as QDMI_Job_Result are

• QDMI_JOB_RESULT_STATEVECTOR
• QDMI_JOB_RESULT_PROBABILITIES

The reason we haven't added these right away is because there still is some discussion to be had on what the expected semantics for these result types are. For example,

• what is the expected behaviour when passing a buffer that is not large enough to hold the full result? I would argue it should just truncate the result.
• should there be dense and sparse versions of these results? I would argue, yes. A full state vector is only feasible up to a certain number of qubits. Yet some states are very sparse.
• in such a sparse result, what are the semantics of providing a buffer that is too small to hold the complete result? Should it return the most probable results? Should it just start from 0...0 and truncate? Truncation is easy, but might not be very useful in practice.

Overall, my current proposal would be to add the following return value possibilities:

• QDMI_JOB_RESULT_STATEVECTOR_DENSE, returning a full $2^n$ dimensional, complex-valued state vector containing the amplitudes
• QDMI_JOB_RESULT_PROBABILITIES_DENSE, returning a full $2^n$ dimensional, real-valued vector containing the probabilities

Sparse versions of these results with a similar dict-like interface to the current histogram result:

• QDMI_JOB_RESULT_STATEVECTOR_SPARSE_KEYS,
• QDMI_JOB_RESULT_STATEVECTOR_SPARSE_VALUES
• QDMI_JOB_RESULT_PROBABILITIES_SPARSE_KEYS
• QDMI_JOB_RESULT_PROBABILITIES_SPARSE_VALUES

Given a buffer that can only hold $x$ out of $y$ result elements with $x<y$, the results should resemble a dictionary from bitstrings to amplitudes/probabilities that contains the y elements with the highest magnitude/probability.

Comments welcome!

[MariusEviden]

Thanks for the clarification, that makes a lot of sense. Also the return values you propose make a lot of sense.

Maybe it is also reasonable to think about the possibility to return an expectation value of an observable as another possibility. For simulated backends there is often the possibility to directly return the expectation value of an observable instead of a statevector or probabilities, which makes the return object much more compact. For a real hardware this is probably more difficult. However, I could imagine that some hardware providers will have inbuilt pre- and postprocessing that also leads to the return of an observable expectation value instead of the full data vector. However, this would probybly also need the possibility to define an observalbe job as inuput somehow

[burgholzer]

Maybe it is also reasonable to think about the possibility to return an expectation value of an observable as another possibility. For simulated backends there is often the possibility to directly return the expectation value of an observable instead of a statevector or probabilities, which makes the return object much more compact. For a real hardware this is probably more difficult, however, I could imagine that some hardware providers will have inbuilt pre- and postprocessing that also leads to the return of an observable expectation value instead of the full data vector. However, this would of course also need the possibility to define an observalbe job as inuput somehow

Totally agreed! We have had some initial discussions on that as well over the last couple of weeks. The difficult part to get right here is exactly as you say the specification of the observable as an input to the job in addition to the computation itself. We already have an enum for Job Parameters here. I could imagine that this would allow us to pass the observable to the job. I would propose to take this one step at a time: let's first try to get state vectors and probabilities properly supported and think about how to express expectation values afterwards and in a separate issue.

[MariusEviden]

Yes, it definitely makes sense to take a stepwise approach here and first look at state vectors and probabilities and care about the expectation values in a second step.