This page contains example implementations of devices and other components of
the software stack that use QDMI. All examples distributed with QDMI are
contained in the examples/ directory in the repository.
\tableofcontents
A QDMI driver is a shared library implementing the @ref client_interface. Applications can select another compatible driver without rebuilding. The Client Interface defines the ABI and handle-lifetime requirements.
The example driver's QDMI_CONF file contains one device per line:
/path/to/libdevice.so PREFIX deployment.device-id
The third field is the nonempty client-visible QDMI_DEVICE_PROPERTY_ID. IDs
must be unique in the configured catalog. Multiple lines may use the same device
library and prefix with different IDs; each line gets its own device session.
The driver reads and validates the complete file transactionally when it
allocates the first session. A failed allocation can be retried with a corrected
file. Device libraries can omit this property because the QDMI driver owns the
public ID.
Below you find mock implementations of a QDMI device in C++.
\note Keep in mind, that even though the interface is defined in C, the device can be implemented in C++ or any other language that supports the C ABI.
Every device has to provide a name, its version, and the implemented QDMI library version through the query interface. The corresponding properties are
- @ref QDMI_DEVICE_PROPERTY_NAME
- @ref QDMI_DEVICE_PROPERTY_VERSION
- @ref QDMI_DEVICE_PROPERTY_LIBRARYVERSION
All of those properties are of type char* (string). Since they are properties
of the device, they are returned by the @ref
QDMI_device_session_query_device_property function. Below you find the
respective implementation in C++.
\dontinclude cxx_device.cpp \skip int CXX_QDMI_device_session_query_device_property \until QDMI_DEVICE_PROPERTY_LIBRARYVERSION \until size_ret) \skip QDMI_ERROR_NOTSUPPORTED \until DOXYGEN FUNCTION END
Both implementations use an auxiliary macro to add the string properties to the device. For an explanation of the macro, see the next section Auxiliary Macros.
The following macro is used to add string properties to the device. The macro is used, e.g., in the implementation of the @ref QDMI_device_session_query_device_property function.
\dontinclude cxx_device.cpp \skip #define ADD_STRING_PROPERTY \until DOXYGEN MACRO END
A similar macro is defined for other (fixed length) data types, for example,
int, double.
\dontinclude cxx_device.cpp \skip #define ADD_SINGLE_VALUE_PROPERTY \until DOXYGEN MACRO END
Another macro is defined for list properties of the data types above.
\dontinclude cxx_device.cpp \skip #define ADD_LIST_PROPERTY \until DOXYGEN MACRO END
The usage of the two latter macros is demonstrated in the following sections.
The following two examples demonstrate how to return integer or enumeration properties of the device.
\dontinclude cxx_device.cpp \skip int CXX_QDMI_device_session_query_device_property \until { \skip QDMI_DEVICE_PROPERTY_STATUS \until QDMI_DEVICE_PROPERTY_QUBITSNUM \until size_ret) \skip QDMI_ERROR_NOTSUPPORTED \until DOXYGEN FUNCTION END
Some properties are returned as a list of various data types. The following example shows how to return the coupling map of the device as a list of @ref QDMI_Site pairs. The pairs are flattened into a single list of @ref QDMI_Site's.
\dontinclude cxx_device.cpp \skipline constexpr std::array<const CXX_QDMI_Site_impl_d *, 20> \skip DEVICE_COUPLING_MAP \until ; \skip int CXX_QDMI_device_session_query_device_property \until { \skip ADD_LIST_PROPERTY \until DOXYGEN FUNCTION END
The properties that are returned by @ref QDMI_device_session_query_operation_property may depend on the actual site. The available @ref QDMI_Operation's and @ref QDMI_Site's, first, need to be retrieved through @ref QDMI_device_session_query_device_property. With the handles for a @ref QDMI_Operation and @ref QDMI_Site, corresponding properties can be queried. The following example demonstrates how different properties of operations, for example, varying fidelities of two-qubit gates can be returned.
\dontinclude cxx_device.cpp \skip QDMI_Pair_hash \until OPERATION_FIDELITIES \until ; \skip QDMI_device_session_query_operation_property \until DOXYGEN FUNCTION END
One crucial part of QDMI is that it allows submitting a job to the device for execution. The following example provides a mock implementation of the necessary functions to submit a job. The first example shows a mock implementation of @ref QDMI_device_session_create_device_job.
\dontinclude cxx_device.cpp \skip QDMI_device_session_create_device_job \until DOXYGEN FUNCTION END
The function @ref QDMI_device_job_set_parameter allows setting different parameters for the job, for example, the number of shots (@ref QDMI_JOB_PARAMETER_SHOTSNUM).
\dontinclude cxx_device.cpp \skip QDMI_device_job_set_parameter \until DOXYGEN FUNCTION END
The function @ref QDMI_device_job_set_programs sets an ordered list of programs with one format and one shot count per program. It copies the list before returning. Submit the job with @ref QDMI_device_job_submit and retrieve each program's results by its input index with @ref QDMI_device_job_get_results. The same index retrieves its original bytes with @ref QDMI_device_job_get_program. Execution order is unspecified. Devices may report individual outcomes through @ref QDMI_device_job_get_program_status so successful results remain available when other programs fail or are canceled.
\dontinclude cxx_device.cpp \skip QDMI_device_job_set_programs \until DOXYGEN FUNCTION END
After the job is set up, it can be submitted to the device. The following example shows a mock implementation of @ref QDMI_device_job_submit.
\dontinclude cxx_device.cpp \skip QDMI_device_job_submit \until DOXYGEN FUNCTION END
For the full implementation of the example devices we refer to the respective
source files in the QDMI repository, that is,
cxx_device.cpp
for the C++ implementation.