Type definitions

DQCsim defines some types and enumerations. These are documented below. Note that DQCsim does not define any structures; all types used on the interface are primitive. This should hopefully simplify using the bindings from languages other than C, which may not support such things.

Return codes

Almost all functions in DQCsim can fail. They indicate failure through their return value. For some types this return value is obvious; for instance, NULL is used for functions that return a string or another kind of pointer. For enumerations, the failure return value is usually 0 or -1. In other cases, the failure return value will be listed in the function documentation.

There are two special cases: functions that return a boolean and functions that don't otherwise return a value. These have the following two special enumerations defined for them:

dqcs_return_t

Default return type for functions that don't need to return anything.

typedef enum { ... } dqcs_return_t;

Variants:

DQCS_FAILURE = -1
The function has failed. More information may be obtained through `dqcsim_explain()`.
DQCS_SUCCESS = 0
The function did what it was supposed to.

dqcs_bool_return_t

Return type for functions that normally return a boolean but can also fail.

typedef enum { ... } dqcs_bool_return_t;

Variants:

DQCS_BOOL_FAILURE = -1
The function has failed. More information may be obtained through `dqcsim_explain()`.
DQCS_FALSE = 0
The function did what it was supposed to and returned false.
DQCS_TRUE = 1
The function did what it was supposed to and returned true.

Simulator object references

The following types are used to refer to simulator objects.

dqcs_handle_t

Type for a handle.

typedef unsigned long long dqcs_handle_t;

Handles are like pointers into DQCsim's internal structures: all API calls use these to refer to objects. Besides the object, they contain type information. This type can be retrieved using dqcs_handle_type().

Handles are always positive integers, counting upwards from 1 upon allocation, and they are not reused even after being deleted. Thus, every subsequent object allocation returns a handle one greater than the previous. Note however that DQCsim may allocate objects as well without the user specifically requesting this, so external code should generally not rely on this behavior unless otherwise noted. The value zero is reserved for invalid references or error propagation.

Note that the scope for handles is thread-local. That is, data referenced by a handle cannot be shared or moved between threads.

The value zero is reserved for invalid references or error propagation.

dqcs_qubit_t

Type for a qubit reference.

typedef unsigned long long dqcs_qubit_t;

Qubit references are exchanged between the frontend, operator, and backend plugins to indicate which qubits a gate operates on. Note that this makes them fundamentally different from handles, which are thread-local.

Qubit references are always positive integers, counting upwards from 1 upon allocation, and they are not reused even after the qubit is deallocated. Thus, every subsequent allocation returns a qubit reference one greater than the previous. This is guaranteed behavior that external code can rely upon. The value zero is reserved for invalid references or error propagation.

dqcs_plugin_state_t

Type for a plugin state.

typedef void *dqcs_plugin_state_t;

This is an opaque type that is passed along to plugin implementation callback functions, which those callbacks can then use to interact with the plugin instance. User code shall not create or modify values of this type, and shall only use the values when calling dqcs_plugin_* functions.

Timekeeping

DQCsim supports timed simulation using integral cycle numbers as a unit. The following typedef is used to refer to such timestamps.

dqcs_cycle_t

Type for a simulation cycle timestamp.

typedef long long dqcs_cycle_t;

Timestamps count upward from zero. The type is signed to allow usage of -1 for errors, and to allow numerical differences to be represented.

Misc. enumerations

The following enumerations are used for various purposes within the API.

dqcs_handle_type_t

Enumeration of types that can be associated with a handle.

typedef enum { ... } dqcs_handle_type_t;

Variants:

DQCS_HTYPE_INVALID = 0
Indicates that the given handle is invalid.

This indicates one of the following:

  • The handle value is invalid (zero or negative).
  • The handle has not been used yet.
  • The object associated with the handle was deleted.
DQCS_HTYPE_ARB_DATA = 100
Indicates that the given handle belongs to an `ArbData` object.

This means that the handle supports the handle and arb interfaces.

DQCS_HTYPE_ARB_CMD = 101
Indicates that the given handle belongs to an `ArbCmd` object.

This means that the handle supports the handle, arb, and cmd interfaces.

DQCS_HTYPE_ARB_CMD_QUEUE = 102
Indicates that the given handle belongs to a queue of `ArbCmd` object.

This means that the handle supports the handle, arb, cmd, and cq interfaces.

DQCS_HTYPE_QUBIT_SET = 103
Indicates that the given handle belongs to a set of qubit references.

This means that the handle supports the handle and qbset interfaces.

DQCS_HTYPE_GATE = 104
Indicates that the given handle belongs to a quantum gate description.

This means that the handle supports the handle, gate, and arb interfaces.

DQCS_HTYPE_MEAS = 105
Indicates that the given handle belongs to a qubit measurement result.

This means that the handle supports the handle, meas, and arb interfaces. It can also be used in place of a qubit measurement result set by functions that consume the object.

DQCS_HTYPE_MEAS_SET = 106
Indicates that the given handle belongs to a set of qubit measurement results.

This means that the handle supports the handle and mset interfaces.

DQCS_HTYPE_MATRIX = 107
Indicates that the given handle belongs to a matrix.

This means that the handle supports the handle and mat interfaces.

DQCS_HTYPE_GATE_MAP = 108
Indicates that the given handle belongs to a gate map.

This means that the handle supports the handle and gm interfaces.

DQCS_HTYPE_FRONT_PROCESS_CONFIG = 200
Indicates that the given handle belongs to a frontend plugin process configuration object.

This means that the handle supports the handle, pcfg, and xcfg interfaces.

DQCS_HTYPE_OPER_PROCESS_CONFIG = 201
Indicates that the given handle belongs to an operator plugin process configuration object.

This means that the handle supports the handle, pcfg, and xcfg interfaces.

DQCS_HTYPE_BACK_PROCESS_CONFIG = 203
Indicates that the given handle belongs to a backend plugin process configuration object.

This means that the handle supports the handle, pcfg, and xcfg interfaces.

DQCS_HTYPE_FRONT_THREAD_CONFIG = 204
Indicates that the given handle belongs to a frontend plugin thread configuration object.

This means that the handle supports the handle, tcfg, and xcfg interfaces.

DQCS_HTYPE_OPER_THREAD_CONFIG = 205
Indicates that the given handle belongs to an operator plugin thread configuration object.

This means that the handle supports the handle, tcfg, and xcfg interfaces.

DQCS_HTYPE_BACK_THREAD_CONFIG = 206
Indicates that the given handle belongs to a backend plugin thread configuration object.

This means that the handle supports the handle, tcfg, and xcfg interfaces.

DQCS_HTYPE_SIM_CONFIG = 207
Indicates that the given handle belongs to a simulator configuration object.

This means that the handle supports the handle and scfg interfaces.

DQCS_HTYPE_SIM = 208
Indicates that the given handle belongs to a simulator instance.

This means that the handle supports the handle and sim interfaces.

DQCS_HTYPE_FRONT_DEF = 300
Indicates that the given handle belongs to a frontend plugin definition object.

This means that the handle supports the handle and pdef interfaces.

DQCS_HTYPE_OPER_DEF = 301
Indicates that the given handle belongs to an operator plugin definition object.

This means that the handle supports the handle and pdef interfaces.

DQCS_HTYPE_BACK_DEF = 302
Indicates that the given handle belongs to a backend plugin definition object.

This means that the handle supports the handle and pdef interfaces.

DQCS_HTYPE_PLUGIN_JOIN = 303
Indicates that the given handle belongs to a plugin thread join handle.

This means that the handle supports the handle and pjoin interfaces.

dqcs_loglevel_t

Enumeration of loglevels and logging modes.

typedef enum { ... } dqcs_loglevel_t;

Variants:

DQCS_LOG_INVALID = -1
Invalid loglevel. Used to indicate failure of an API that returns a loglevel.
DQCS_LOG_OFF = 0
Turns logging off.
DQCS_LOG_FATAL = 1
This loglevel is to be used for reporting a fatal error, resulting from the owner of the logger getting into an illegal state from which it cannot recover. Such problems are also reported to the API caller via Result::Err if applicable.
DQCS_LOG_ERROR = 2
This loglevel is to be used for reporting or propagating a non-fatal error caused by the API caller doing something wrong. Such problems are also reported to the API caller via Result::Err if applicable.
DQCS_LOG_WARN = 3
This loglevel is to be used for reporting that a called API/function is telling us we did something wrong (that we weren't expecting), but we can recover. For instance, for a failed connection attempt to something that really should not be failing, we can still retry (and eventually report critical or error if a retry counter overflows). Since we're still trying to rectify things at this point, such problems are NOT reported to the API/function caller via Result::Err.
DQCS_LOG_NOTE = 4
This loglevel is to be used for reporting information specifically requested by the user/API caller, such as the result of an API function requested through the command line, or an explicitly captured stdout/stderr stream.
DQCS_LOG_INFO = 5
This loglevel is to be used for reporting information NOT specifically requested by the user/API caller, such as a plugin starting up or shutting down.
DQCS_LOG_DEBUG = 6
This loglevel is to be used for reporting debugging information useful for debugging the user of the API provided by the logged instance.
DQCS_LOG_TRACE = 7
This loglevel is to be used for reporting debugging information useful for debugging the internals of the logged instance. Such messages would normally only be generated by debug builds, to prevent them from impacting performance under normal circumstances.
DQCS_LOG_PASS = 8
This is intended to be used when configuring the stdout/stderr capture mode for a plugin process. Selecting it will prevent the stream from being captured; it will just be the same stream as DQCsim's own stdout/stderr. When used as the loglevel for a message, the message itself is sent to stderr instead of passing into DQCsim's log system. Using this for loglevel filters leads to undefined behavior.

dqcs_measurement_t

Qubit measurement value.

typedef enum { ... } dqcs_measurement_t;

Variants:

DQCS_MEAS_INVALID = -1
Error value used to indicate that something went wrong.
DQCS_MEAS_ZERO = 0
Indicates that the qubit was measured to be zero.
DQCS_MEAS_ONE = 1
Indicates that the qubit was measured to be one.
DQCS_MEAS_UNDEFINED = 2
Indicates that the measurement value is unknown for whatever reason.

dqcs_path_style_t

Reproduction file path style.

typedef enum { ... } dqcs_path_style_t;

Variants:

DQCS_PATH_STYLE_INVALID = -1
Error value used to indicate that something went wrong.
DQCS_PATH_STYLE_KEEP = 0
Specifies that paths should be saved the same way they were specified on the command line.
DQCS_PATH_STYLE_RELATIVE = 1
Specifies that all paths should be saved relative to DQCsim's working directory.
DQCS_PATH_STYLE_ABSOLUTE = 2
Specifies that all paths should be saved canonically, i.e. relative to the root directory.

dqcs_plugin_type_t

Enumeration of the three types of plugins.

typedef enum { ... } dqcs_plugin_type_t;

Variants:

DQCS_PTYPE_INVALID = -1
Invalid plugin type. Used to indicate failure of an API that returns a plugin type.
DQCS_PTYPE_FRONT = 0
Frontend plugin.
DQCS_PTYPE_OPER = 1
Operator plugin.
DQCS_PTYPE_BACK = 2
Backend plugin.