Namespace fomac¶

namespace fomac¶

Typedefs

using CustomJobParameter = std::variant<std::string, bool, int, double>¶

template<typename T> using remove_optional_t = remove_optional<T>::type¶

Helper type to strip std::optional from a type if it is present.

This is useful for template metaprogramming when you want to work with the underlying type of optional without caring about its optionality.

Template Parameters:: T – The type to strip optional from.

Enums

enum class CustomProperty : std::uint8_t¶

Identifies one of QDMI’s implementation-defined custom slots.

The same selector is used for custom device, site, operation, and job properties as well as custom job results.

Values:

enumerator Custom1¶

enumerator Custom2¶

enumerator Custom3¶

enumerator Custom4¶

enumerator Custom5¶

class Device¶

#include <FoMaC.hpp>

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

Subclassed by na::Session::Device

Public Functions

std::string getName() const¶

See also

QDMI_DEVICE_PROPERTY_NAME

std::string getVersion() const¶

See also

QDMI_DEVICE_PROPERTY_VERSION

QDMI_Device_Status getStatus() const¶

See also

QDMI_DEVICE_PROPERTY_STATUS

std::string getLibraryVersion() const¶

See also

QDMI_DEVICE_PROPERTY_LIBRARYVERSION

size_t getQubitsNum() const¶

See also

QDMI_DEVICE_PROPERTY_QUBITSNUM

std::vector<Site> getSites() const¶

See also

QDMI_DEVICE_PROPERTY_SITES

std::vector<Site> 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.

See also

QDMI_DEVICE_PROPERTY_SITES

Returns:: vector of regular sites

std::vector<Site> 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.

See also

QDMI_DEVICE_PROPERTY_SITES

Returns:: a vector of zone sites

std::vector<Operation> getOperations() const¶

See also

QDMI_DEVICE_PROPERTY_OPERATIONS

std::optional<std::vector<std::pair<Site, Site>>> getCouplingMap() const¶

See also

QDMI_DEVICE_PROPERTY_COUPLINGMAP

std::optional<size_t> getNeedsCalibration() const¶

See also

QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION

std::optional<size_t> getQueueLength() const¶

See also

QDMI_DEVICE_PROPERTY_QUEUELENGTH

std::optional<std::string> getLengthUnit() const¶

See also

QDMI_DEVICE_PROPERTY_LENGTHUNIT

std::optional<double> getLengthScaleFactor() const¶

See also

QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR

std::optional<std::string> getDurationUnit() const¶

See also

QDMI_DEVICE_PROPERTY_DURATIONUNIT

std::optional<double> getDurationScaleFactor() const¶

See also

QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR

std::optional<uint64_t> getMinAtomDistance() const¶

See also

QDMI_DEVICE_PROPERTY_MINATOMDISTANCE

std::vector<QDMI_Program_Format> getSupportedProgramFormats() const¶

See also

QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS

std::vector<Device> getChildDevices() const¶

Returns the direct child devices managed by this device.

See also

QDMI_DEVICE_PROPERTY_CHILDDEVICES

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

template<custom_property_value T> inline std::optional<T> queryCustomProperty(const CustomProperty property) const¶

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.
Throws:: std::invalid_argument – If the returned bytes do not match T.
Returns:: The decoded value, or std::nullopt if the slot is unsupported.

std::optional<std::vector<Operation>> queryCustomOperations(CustomProperty property) const¶

Queries a custom device property containing operation handles.

Parameters:: property – Custom property slot to query.
Throws:: std::invalid_argument – If the returned byte count is not a multiple of sizeof(QDMI_Operation).
Returns:: Normal FoMaC operation wrappers, or std::nullopt if the slot is unsupported. A supported empty list is returned as an engaged optional.

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.

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

See also

QDMI_job_submit

Throws:: std::invalid_argument – If the format requires binary submission, names a batch job, or names a calibration run.

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.

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

See also

QDMI_job_submit

Throws:: std::invalid_argument – If the format names a batch job or a calibration run.

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.

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.

See also

QDMI_job_submit

Parameters:: program – The calibration payload. An empty span or std::nullopt means that the job has no payload.

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.

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

See also

QDMI_job_submit

Parameters:: program – The calibration payload.

Job 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.

See also

QDMI_session_retrieve_job_by_id

Parameters:: jobId – The nonempty opaque ID returned by Job::getId.
Throws:: std::runtime_error – If the driver or device cannot retrieve the job.

class Job¶

#include <FoMaC.hpp>

Class representing a submitted job.

This class provides methods to query job status and retrieve results.

The class can only be constructed by Device instances.

See also

QDMI_Job

Public Functions

QDMI_Job_Status check() const¶

See also

QDMI_job_check

bool wait(size_t timeout = 0) const¶

See also

QDMI_job_wait

Parameters:: timeout – The maximum time to wait in seconds. 0 (default) means wait indefinitely.
Returns:: true if the job completed successfully, false if it timed out

void cancel() const¶

See also

QDMI_job_cancel

std::string getId() const¶: Get the job ID.

QDMI_Program_Format getProgramFormat() const¶: Get the program format.

std::string getProgram() const¶

Gets a textual program without its terminating null byte.

Throws:: std::invalid_argument – If the format is not textual or the device does not return a null-terminated payload.

std::vector<std::byte> getProgramBytes() const¶: Gets the submitted program bytes exactly as returned by the device.

size_t getNumShots() const¶: Get the number of shots.

std::optional<size_t> getQueuePosition() const¶

Gets the current number of jobs ahead of this job in its queue.

See also

QDMI_JOB_PROPERTY_QUEUEPOSITION

Throws:: std::runtime_error – If the provider status refresh or property query fails for another reason.
Returns:: The queue position, or std::nullopt if it is unavailable or not applicable in the job’s current state.

template<custom_property_value T> inline std::optional<T> queryCustomProperty(const CustomProperty property) const¶

Queries an implementation-defined custom job 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.
Throws:: std::invalid_argument – If the returned bytes do not match T.
Returns:: The decoded value, or std::nullopt if the slot is unsupported.

template<custom_property_value T> inline std::optional<T> getCustomResult(const CustomProperty property) const¶

Retrieves an implementation-defined custom job result.

Template Parameters:: T – Expected value type. Use std::vector<std::byte> to retrieve the raw value without interpretation.
Parameters:: property – Custom result slot to query.
Throws:: std::invalid_argument – If the returned bytes do not match T.
Returns:: The decoded value, or std::nullopt if the slot is unsupported.

std::vector<std::string> getShots() const¶

Returns the measurement shots as a vector of bitstrings.

See also

QDMI_JOB_RESULT_SHOTS

std::map<std::string, size_t> getCounts() const¶

Returns a map of measurement outcomes to their respective counts.

See also

QDMI_JOB_RESULT_HIST_KEYS

See also

QDMI_JOB_RESULT_HIST_VALUES

std::vector<std::complex<double>> getDenseStateVector() const¶

Returns the dense state vector as a vector of complex numbers.

See also

QDMI_JOB_RESULT_STATEVECTOR_DENSE

std::vector<double> getDenseProbabilities() const¶

Returns the dense probabilities as a vector of doubles.

See also

QDMI_JOB_RESULT_PROBABILITIES_DENSE

std::map<std::string, std::complex<double>> getSparseStateVector() const¶

Returns the sparse state vector as a map of bitstrings to complex amplitudes.

See also

QDMI_JOB_RESULT_STATEVECTOR_SPARSE_KEYS

See also

QDMI_JOB_RESULT_STATEVECTOR_SPARSE_VALUES

std::map<std::string, double> getSparseProbabilities() const¶

Returns the sparse probabilities as a map of bitstrings to probabilities.

See also

QDMI_JOB_RESULT_PROBABILITIES_SPARSE_KEYS

See also

QDMI_JOB_RESULT_PROBABILITIES_SPARSE_VALUES

class Operation¶

#include <FoMaC.hpp>

Class representing an operation (gate) supported by the device.

This class provides methods to query properties of the operation.

The class can only be constructed by Device instances.

See also

QDMI_Operation

Public Functions

std::string getName(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_NAME

std::optional<size_t> getQubitsNum(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_QUBITSNUM

size_t getParametersNum(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_PARAMETERSNUM

std::optional<uint64_t> getDuration(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_DURATION

std::optional<double> getFidelity(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_FIDELITY

std::optional<uint64_t> getInteractionRadius(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_INTERACTIONRADIUS

std::optional<uint64_t> getBlockingRadius(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_BLOCKINGRADIUS

std::optional<double> getIdlingFidelity(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_IDLINGFIDELITY

bool isZoned() const¶

See also

QDMI_OPERATION_PROPERTY_ISZONED

std::optional<std::vector<Site>> getSites() const¶

See also

QDMI_OPERATION_PROPERTY_SITES

std::optional<std::vector<std::pair<Site, Site>>> getSitePairs() const¶

Returns the list of site pairs the local 2-qubit operation can be performed on.

For local 2-qubit operations, this function interprets the returned list of sites by QDMI as site pairs according to the QDMI specification. Hence, this function facilitates easier iteration over supported site pairs.

See also

QDMI_OPERATION_PROPERTY_SITES

Returns:: Optional vector of site pairs if this is a local 2-qubit operation, std::nullopt otherwise.

std::optional<uint64_t> getMeanShuttlingSpeed(const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

See also

QDMI_OPERATION_PROPERTY_MEANSHUTTLINGSPEED

template<custom_property_value T> inline std::optional<T> queryCustomProperty(const CustomProperty property, const std::vector<Site> &sites = {}, const std::vector<double> &params = {}) const¶

Queries an implementation-defined custom operation 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.
sites – Sites for context-dependent operation properties.
params – Parameters for context-dependent operation properties.

Throws:

std::invalid_argument – If the returned bytes do not match T.

Returns:

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

template<typename T> struct remove_optional¶

#include <FoMaC.hpp>

See also

remove_optional_t

class Session¶

#include <FoMaC.hpp>

Class representing the Session library.

This class provides methods to query available devices and manage the QDMI session.

See also

QDMI_Session

Public Functions

explicit Session(const SessionConfig &config = {})¶

Constructs a new QDMI Session with optional authentication.

Creates, allocates, and initializes a new QDMI session.

Parameters:: config – Optional session configuration containing authentication parameters. If not provided, uses default (no authentication).

std::vector<Device> getDevices()¶

See also

QDMI_SESSION_PROPERTY_DEVICES

Public Static Functions

static Device createSessionlessDevice(QDMI_Device device)¶

Creates a Device object from a QDMI_Device handle.

Note

This is a factory method for use in bindings where a session is not accessible.

Parameters:: device – The QDMI_Device handle to wrap.
Returns:: A Device object wrapping the given handle.

static Device openDevice(std::string_view id, const qdmi::DeviceSessionConfig &overrides = {})¶

Opens a registered QDMI device as a fresh device session.

Parameters:

id – Stable registered device ID.
overrides – Session values that replace registered defaults.

Returns:

An owning device wrapper for the new session.

struct SessionConfig¶

#include <FoMaC.hpp>

Configuration structure for session authentication parameters.

All parameters are optional. Only set the parameters needed for your authentication method. Parameters are validated when the session is constructed.

Public Members

std::optional<std::string> token¶: Authentication token.

std::optional<std::filesystem::path> authFile¶: Path to file containing authentication information.

std::optional<std::string> authUrl¶: URL to authentication server.

std::optional<std::string> username¶: Username for authentication.

std::optional<std::string> password¶: Password for authentication.

std::optional<std::string> projectId¶: Project ID for session.

std::optional<std::string> custom1¶: Custom configuration parameter 1.

std::optional<std::string> custom2¶: Custom configuration parameter 2.

std::optional<std::string> custom3¶: Custom configuration parameter 3.

std::optional<std::string> custom4¶: Custom configuration parameter 4.

std::optional<std::string> custom5¶: Custom configuration parameter 5.

class Site¶

#include <FoMaC.hpp>

Class representing a site (qubit) on the device.

This class provides methods to query properties of the site.

The class can only be constructed by Device and Operation instances.

See also

QDMI_Site

Public Functions

size_t getIndex() const¶

See also

QDMI_SITE_PROPERTY_INDEX

std::optional<uint64_t> getT1() const¶

See also

QDMI_SITE_PROPERTY_T1

std::optional<uint64_t> getT2() const¶

See also

QDMI_SITE_PROPERTY_T2

std::optional<std::string> getName() const¶

See also

QDMI_SITE_PROPERTY_NAME

std::optional<int64_t> getXCoordinate() const¶

See also

QDMI_SITE_PROPERTY_XCOORDINATE

std::optional<int64_t> getYCoordinate() const¶

See also

QDMI_SITE_PROPERTY_YCOORDINATE

std::optional<int64_t> getZCoordinate() const¶

See also

QDMI_SITE_PROPERTY_ZCOORDINATE

bool isZone() const¶

See also

QDMI_SITE_PROPERTY_ISZONE

std::optional<uint64_t> getXExtent() const¶

See also

QDMI_SITE_PROPERTY_XEXTENT

std::optional<uint64_t> getYExtent() const¶

See also

QDMI_SITE_PROPERTY_YEXTENT

std::optional<uint64_t> getZExtent() const¶

See also

QDMI_SITE_PROPERTY_ZEXTENT

std::optional<uint64_t> getModuleIndex() const¶

See also

QDMI_SITE_PROPERTY_MODULEINDEX

std::optional<uint64_t> getSubmoduleIndex() const¶

See also

QDMI_SITE_PROPERTY_SUBMODULEINDEX

template<custom_property_value T> inline std::optional<T> queryCustomProperty(const CustomProperty property) const¶

Queries an implementation-defined custom site 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.
Throws:: std::invalid_argument – If the returned bytes do not match T.
Returns:: The decoded value, or std::nullopt if the slot is unsupported.

namespace detail¶

Functions

inline std::optional<size_t> queuePositionFromResult(const int result, const size_t queuePosition)¶

template<custom_property_value T, typename Query> std::optional<T> queryCustomValue(Query query, const std::string_view description)¶

template<typename Handle, typename Query> std::optional<std::vector<Handle>> queryHandleArray(Query query, const std::string_view description)¶

constexpr QDMI_Device_Property toDeviceProperty(const CustomProperty property)¶

constexpr QDMI_Site_Property toSiteProperty(const CustomProperty property)¶

constexpr QDMI_Operation_Property toOperationProperty(const CustomProperty property)¶

constexpr QDMI_Job_Property toJobProperty(const CustomProperty property)¶

constexpr QDMI_Job_Result toJobResult(const CustomProperty property)¶

namespace slurm¶

Functions

Device openDeviceFromLicense()¶

Opens the QDMI device named by the Slurm license environment.

The SLURM_JOB_LICENSES value must contain exactly one local license. Its name must equal a registered QDMI device ID. The optional license count must be one. The device must report QDMI_DEVICE_STATUS_IDLE or QDMI_DEVICE_STATUS_BUSY.

Warning

This function uses process-mutable environment data for device selection. It does not verify a Slurm allocation, authenticate the caller, or authorize access to the device. The provider or operating system must enforce access independently.

Throws:: std::runtime_error – If the license value is missing, malformed, compound, remote, has a non-unit count, names an unknown device, or names a device in another state.
Returns:: A fresh device session using the registered device definition.