qdmi::Device Class Reference

Class representing a quantum device. More...

#include <Client.hpp>

Public Member Functions
	operator QDMI_Device () const
std::string	getName () const
std::string	getVersion () const
QDMI_Device_Status	getStatus () const
std::string	getLibraryVersion () const
size_t	getQubitsNum () const
std::vector< Site >	getSites () const
std::vector< Site >	getRegularSites () const
	Returns the list of regular sites (without zone sites) available on the device.
std::vector< Site >	getZones () const
	Returns the list of zone sites (without regular sites) available on the device.
std::vector< Operation >	getOperations () const
std::optional< std::vector< std::pair< Site, Site > > >	getCouplingMap () const
std::optional< size_t >	getNeedsCalibration () const
std::optional< size_t >	getQueueLength () const
std::optional< std::string >	getLengthUnit () const
std::optional< double >	getLengthScaleFactor () const
std::optional< std::string >	getDurationUnit () const
std::optional< double >	getDurationScaleFactor () const
std::optional< uint64_t >	getMinAtomDistance () const
std::vector< QDMI_Program_Format >	getSupportedProgramFormats () const
std::vector< Device >	getChildDevices () const
	Returns the direct child devices managed by this device.
template<custom_property_value T>
std::optional< T >	queryCustomProperty (const CustomProperty property) const
	Queries an implementation-defined custom device property.
std::optional< std::vector< Operation > >	queryCustomOperations (CustomProperty property) const
	Queries a custom device property containing operation handles.
Job	submitJob (const std::string &program, QDMI_Program_Format format, size_t numShots, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Submits a textual program.
Job	submitJob (const std::string &program, QDMI_Program_Format format, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Submits a textual program without setting a shot count.
Job	submitJob (std::span< const std::byte > program, QDMI_Program_Format format, size_t numShots, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Submits a binary program.
Job	submitJob (std::span< const std::byte > program, QDMI_Program_Format format, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Submits a binary program without setting a shot count.
Job	submitCalibrationJob (std::optional< std::span< const std::byte > > program=std::nullopt, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Triggers a calibration run.
Job	submitCalibrationJob (const std::string &program, const std::optional< CustomJobParameter > &custom1=std::nullopt, const std::optional< CustomJobParameter > &custom2=std::nullopt, const std::optional< CustomJobParameter > &custom3=std::nullopt, const std::optional< CustomJobParameter > &custom4=std::nullopt, const std::optional< CustomJobParameter > &custom5=std::nullopt) const
	Triggers a calibration run with a text payload.
Job	retrieveJobById (std::string_view jobId) const
	Retrieves an existing job by its device-provided ID.
auto	operator<=> (const Device &) const noexcept=default

Friends
class	Session

Detailed Description

Class representing a quantum device.

This class provides methods to query properties of the device, its sites, and its operations.

The class can only be constructed by Session instances.

See also

QDMI_Device

Member Function Documentation

operator QDMI_Device()

qdmi::Device::operator QDMI_Device ( ) const

inline

getName()

std::string qdmi::Device::getName

(

)

const

See also

QDMI_DEVICE_PROPERTY_NAME

getVersion()

std::string qdmi::Device::getVersion

(

)

const

See also

QDMI_DEVICE_PROPERTY_VERSION

getStatus()

QDMI_Device_Status qdmi::Device::getStatus

(

)

const

See also

QDMI_DEVICE_PROPERTY_STATUS

getLibraryVersion()

std::string qdmi::Device::getLibraryVersion

(

)

const

See also

QDMI_DEVICE_PROPERTY_LIBRARYVERSION

getQubitsNum()

size_t qdmi::Device::getQubitsNum

(

)

const

See also

QDMI_DEVICE_PROPERTY_QUBITSNUM

getSites()

std::vector< Site > qdmi::Device::getSites

(

)

const

See also

QDMI_DEVICE_PROPERTY_SITES

getRegularSites()

std::vector< Site > qdmi::Device::getRegularSites

(

)

const

Returns the list of regular sites (without zone sites) available on the device.

Filters all sites and only returns regular sites, i.e., where isZone() yields false. These represent actual potential physical qubit locations on the device lattice.

Returns

vector of regular sites

See also

QDMI_DEVICE_PROPERTY_SITES

getZones()

std::vector< Site > qdmi::Device::getZones

(

)

const

Returns the list of zone sites (without regular sites) available on the device.

Filters all sites and only returns zone sites, i.e., where isZone() yields true. These represent a zone, i.e., an extent where zoned operations can be performed, not individual qubit locations.

Returns

a vector of zone sites

See also

QDMI_DEVICE_PROPERTY_SITES

getOperations()

std::vector< Operation > qdmi::Device::getOperations

(

)

const

See also

QDMI_DEVICE_PROPERTY_OPERATIONS

getCouplingMap()

std::optional< std::vector< std::pair< Site, Site > > > qdmi::Device::getCouplingMap

(

)

const

See also

QDMI_DEVICE_PROPERTY_COUPLINGMAP

getNeedsCalibration()

std::optional< size_t > qdmi::Device::getNeedsCalibration

(

)

const

See also

QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION

getQueueLength()

std::optional< size_t > qdmi::Device::getQueueLength

(

)

const

See also

QDMI_DEVICE_PROPERTY_QUEUELENGTH

getLengthUnit()

std::optional< std::string > qdmi::Device::getLengthUnit

(

)

const

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT

getLengthScaleFactor()

std::optional< double > qdmi::Device::getLengthScaleFactor

(

)

const

See also

QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR

getDurationUnit()

std::optional< std::string > qdmi::Device::getDurationUnit

(

)

const

See also

QDMI_DEVICE_PROPERTY_DURATIONUNIT

getDurationScaleFactor()

std::optional< double > qdmi::Device::getDurationScaleFactor

(

)

const

See also

QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR

getMinAtomDistance()

std::optional< uint64_t > qdmi::Device::getMinAtomDistance

(

)

const

See also

QDMI_DEVICE_PROPERTY_MINATOMDISTANCE

getSupportedProgramFormats()

std::vector< QDMI_Program_Format > qdmi::Device::getSupportedProgramFormats

(

)

const

See also

QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS

getChildDevices()

std::vector< Device > qdmi::Device::getChildDevices

(

)

const

Returns the direct child devices managed by this device.

Returns

The child devices, or an empty vector if child devices are not supported.

See also

QDMI_DEVICE_PROPERTY_CHILDDEVICES

queryCustomProperty()

template<custom_property_value T>

std::optional< T > qdmi::Device::queryCustomProperty ( const CustomProperty  property ) const

inline

Queries an implementation-defined custom device property.

Template Parameters

T	Expected value type. Use std::vector<std::byte> to retrieve the raw value without interpretation.

Parameters

property

Custom property slot to query.

Returns

The decoded value, or std::nullopt if the slot is unsupported.

Exceptions

std::invalid_argument

If the returned bytes do not match T.

queryCustomOperations()

std::optional< std::vector< Operation > > qdmi::Device::queryCustomOperations

(

CustomProperty

property

)

const

Queries a custom device property containing operation handles.

Parameters

property

Custom property slot to query.

Returns

Normal QDMI operation wrappers, or std::nullopt if the slot is unsupported. A supported empty list is returned as an engaged optional.

Exceptions

std::invalid_argument

If the returned byte count is not a multiple of sizeof(QDMI_Operation).

submitJob() [1/4]

Job qdmi::Device::submitJob	(	const std::string &	program,
		QDMI_Program_Format	format,
		size_t	numShots,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Submits a textual program.

The terminating null byte required by QDMI text formats is included in the submitted payload.

Exceptions

std::invalid_argument

If the format requires binary submission, names a batch job, or names a calibration run.

See also

QDMI_job_submit

submitJob() [2/4]

Job qdmi::Device::submitJob	(	const std::string &	program,
		QDMI_Program_Format	format,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Submits a textual program without setting a shot count.

Repetition semantics are left to the submitted program and device.

See also

QDMI_job_submit

submitJob() [3/4]

Job qdmi::Device::submitJob	(	std::span< const std::byte >	program,
		QDMI_Program_Format	format,
		size_t	numShots,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Submits a binary program.

The bytes are submitted exactly as provided without appending a null byte.

Exceptions

std::invalid_argument

If the format names a batch job or a calibration run.

See also

QDMI_job_submit

submitJob() [4/4]

Job qdmi::Device::submitJob	(	std::span< const std::byte >	program,
		QDMI_Program_Format	format,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Submits a binary program without setting a shot count.

Repetition semantics are left to the submitted program and device.

See also

QDMI_job_submit

submitCalibrationJob() [1/2]

Job qdmi::Device::submitCalibrationJob	(	std::optional< std::span< const std::byte > >	program = std::nullopt,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Triggers a calibration run.

A device that reports a nonzero QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION is asked to calibrate by submitting a job in the QDMI_PROGRAM_FORMAT_CALIBRATION format. QDMI does not require a program for such a job, so the payload is optional; when it is present, the device defines what it means, which is usually a configuration for the run. A calibration run executes no circuit, so no shot count is set.

Parameters

program	The calibration payload. An empty span or std::nullopt means that the job has no payload.
custom1,custom2,custom3,custom4,custom5	Optional provider-defined job parameters.

See also

QDMI_job_submit

submitCalibrationJob() [2/2]

Job qdmi::Device::submitCalibrationJob	(	const std::string &	program,
		const std::optional< CustomJobParameter > &	custom1 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom2 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom3 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom4 = std::nullopt,
		const std::optional< CustomJobParameter > &	custom5 = std::nullopt
	)		const

Triggers a calibration run with a text payload.

The terminating null byte required by QDMI text formats is included in the submitted payload.

Parameters

program	The calibration payload.
custom1,custom2,custom3,custom4,custom5	Optional provider-defined job parameters.

See also

QDMI_job_submit

retrieveJobById()

Job qdmi::Device::retrieveJobById

(

std::string_view

jobId

)

const

Retrieves an existing job by its device-provided ID.

Opening a job does not submit, clone, or modify the remote job. The returned handle can be used to query its state and retrieve results.

Parameters

jobId

The nonempty opaque ID returned by Job::getId.

Exceptions

std::runtime_error

If the driver or device cannot retrieve the job.

See also

QDMI_session_retrieve_job_by_id

operator<=>()

auto qdmi::Device::operator<=> ( const Device &  ) const

defaultnoexcept

Friends And Related Symbol Documentation

Session

friend class Session

friend