constants.h

Go to the documentation of this file.

/*
 * Copyright (c) 2024 - 2026 QDMI Maintainers
 * All rights reserved.
 *
 * Licensed under the Apache License v2.0 with LLVM Exceptions (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://llvm.org/LICENSE.txt
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 *
 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 */

 
#ifndef QDMI_CONSTANTS_H
#define QDMI_CONSTANTS_H
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
// The following clang-tidy warnings cannot be addressed because this header is
// used from both C and C++ code.
// NOLINTBEGIN(performance-enum-size, modernize-use-using)

enum QDMI_STATUS {
  QDMI_WARN_GENERAL = 1,            
  QDMI_SUCCESS = 0,                 
  QDMI_ERROR_FATAL = -1,            
  QDMI_ERROR_OUTOFMEM = -2,         
  QDMI_ERROR_NOTIMPLEMENTED = -3,   
  QDMI_ERROR_LIBNOTFOUND = -4,      
  QDMI_ERROR_NOTFOUND = -5,         
  QDMI_ERROR_OUTOFRANGE = -6,       
  QDMI_ERROR_INVALIDARGUMENT = -7,  
  QDMI_ERROR_PERMISSIONDENIED = -8, 
  QDMI_ERROR_NOTSUPPORTED = -9,     
  QDMI_ERROR_BADSTATE = -10,
  QDMI_ERROR_TIMEOUT = -11, 
};

#define QDMI_CUSTOM_ENUM_VALUE_MIN 999999995
#define QDMI_CUSTOM_ENUM_VALUE_MAX INT32_MAX

enum QDMI_DEVICE_SESSION_PARAMETER_T {
  QDMI_DEVICE_SESSION_PARAMETER_BASEURL = 0,
  QDMI_DEVICE_SESSION_PARAMETER_TOKEN = 1,
  QDMI_DEVICE_SESSION_PARAMETER_AUTHFILE = 2,
  QDMI_DEVICE_SESSION_PARAMETER_AUTHURL = 3,
  QDMI_DEVICE_SESSION_PARAMETER_USERNAME = 4,
  QDMI_DEVICE_SESSION_PARAMETER_PASSWORD = 5,
  QDMI_DEVICE_SESSION_PARAMETER_CHILDDEVICE = 6,
  QDMI_DEVICE_SESSION_PARAMETER_MAX = 7,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM2 = 999999996,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM3 = 999999997,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM4 = 999999998,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM5 = 999999999,
  QDMI_DEVICE_SESSION_PARAMETER_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_DEVICE_SESSION_PARAMETER_T QDMI_Device_Session_Parameter;

enum QDMI_DEVICE_JOB_PARAMETER_T {
  QDMI_DEVICE_JOB_PARAMETER_PROGRAMFORMAT = 0,
  QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM = 1,
  QDMI_DEVICE_JOB_PARAMETER_MAX = 2,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM2 = 999999996,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM3 = 999999997,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM4 = 999999998,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM5 = 999999999,
  QDMI_DEVICE_JOB_PARAMETER_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_DEVICE_JOB_PARAMETER_T QDMI_Device_Job_Parameter;

enum QDMI_DEVICE_JOB_PROPERTY_T {
  QDMI_DEVICE_JOB_PROPERTY_ID = 0,
  QDMI_DEVICE_JOB_PROPERTY_PROGRAMFORMAT = 1,
  QDMI_DEVICE_JOB_PROPERTY_PROGRAM = 2,
  QDMI_DEVICE_JOB_PROPERTY_SHOTSNUM = 3,
  QDMI_DEVICE_JOB_PROPERTY_QUEUEPOSITION = 4,
  QDMI_DEVICE_JOB_PROPERTY_PROGRAMSNUM = 5,
  QDMI_DEVICE_JOB_PROPERTY_MAX = 6,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM2 = 999999996,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM3 = 999999997,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM4 = 999999998,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM5 = 999999999,
  QDMI_DEVICE_JOB_PROPERTY_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_DEVICE_JOB_PROPERTY_T QDMI_Device_Job_Property;

enum QDMI_DEVICE_PROPERTY_T {
  QDMI_DEVICE_PROPERTY_NAME = 0,
  QDMI_DEVICE_PROPERTY_VERSION = 1,
  QDMI_DEVICE_PROPERTY_STATUS = 2,
  QDMI_DEVICE_PROPERTY_LIBRARYVERSION = 3,
  QDMI_DEVICE_PROPERTY_QUBITSNUM = 4,
  QDMI_DEVICE_PROPERTY_SITES = 5,
  QDMI_DEVICE_PROPERTY_OPERATIONS = 6,
  QDMI_DEVICE_PROPERTY_COUPLINGMAP = 7,
  QDMI_DEVICE_PROPERTY_NEEDSCALIBRATION = 8,
  QDMI_DEVICE_PROPERTY_PULSESUPPORT = 9,
  QDMI_DEVICE_PROPERTY_LENGTHUNIT = 10,
  QDMI_DEVICE_PROPERTY_LENGTHSCALEFACTOR = 11,
  QDMI_DEVICE_PROPERTY_DURATIONUNIT = 12,
  QDMI_DEVICE_PROPERTY_DURATIONSCALEFACTOR = 13,
  QDMI_DEVICE_PROPERTY_MINATOMDISTANCE = 14,
  QDMI_DEVICE_PROPERTY_SUPPORTEDPROGRAMFORMATS = 15,
  QDMI_DEVICE_PROPERTY_CHILDDEVICES = 16,
  QDMI_DEVICE_PROPERTY_QUEUELENGTH = 17,
  QDMI_DEVICE_PROPERTY_MAX = 18,
  QDMI_DEVICE_PROPERTY_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_DEVICE_PROPERTY_CUSTOM2 = 999999996,
  QDMI_DEVICE_PROPERTY_CUSTOM3 = 999999997,
  QDMI_DEVICE_PROPERTY_CUSTOM4 = 999999998,
  QDMI_DEVICE_PROPERTY_CUSTOM5 = 999999999,
  QDMI_DEVICE_PROPERTY_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_DEVICE_PROPERTY_T QDMI_Device_Property;

enum QDMI_DEVICE_STATUS_T {
  QDMI_DEVICE_STATUS_OFFLINE = 0,     
  QDMI_DEVICE_STATUS_IDLE = 1,        
  QDMI_DEVICE_STATUS_BUSY = 2,        
  QDMI_DEVICE_STATUS_ERROR = 3,       
  QDMI_DEVICE_STATUS_MAINTENANCE = 4, 
  QDMI_DEVICE_STATUS_CALIBRATION = 5, 
  QDMI_DEVICE_STATUS_MAX = 6
};

typedef enum QDMI_DEVICE_STATUS_T QDMI_Device_Status;

enum QDMI_SITE_PROPERTY_T {
  QDMI_SITE_PROPERTY_INDEX = 0,
  QDMI_SITE_PROPERTY_T1 = 1,
  QDMI_SITE_PROPERTY_T2 = 2,
  QDMI_SITE_PROPERTY_NAME = 3,
  QDMI_SITE_PROPERTY_XCOORDINATE = 4,
  QDMI_SITE_PROPERTY_YCOORDINATE = 5,
  QDMI_SITE_PROPERTY_ZCOORDINATE = 6,
  QDMI_SITE_PROPERTY_ISZONE = 7,
  QDMI_SITE_PROPERTY_XEXTENT = 8,
  QDMI_SITE_PROPERTY_YEXTENT = 9,
  QDMI_SITE_PROPERTY_ZEXTENT = 10,
  QDMI_SITE_PROPERTY_MODULEINDEX = 11,
  QDMI_SITE_PROPERTY_SUBMODULEINDEX = 12,
  QDMI_SITE_PROPERTY_MAX = 13,
  QDMI_SITE_PROPERTY_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_SITE_PROPERTY_CUSTOM2 = 999999996,
  QDMI_SITE_PROPERTY_CUSTOM3 = 999999997,
  QDMI_SITE_PROPERTY_CUSTOM4 = 999999998,
  QDMI_SITE_PROPERTY_CUSTOM5 = 999999999,
  QDMI_SITE_PROPERTY_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_SITE_PROPERTY_T QDMI_Site_Property;

enum QDMI_OPERATION_PROPERTY_T {
  QDMI_OPERATION_PROPERTY_NAME = 0,
  QDMI_OPERATION_PROPERTY_QUBITSNUM = 1,
  QDMI_OPERATION_PROPERTY_PARAMETERSNUM = 2,
  QDMI_OPERATION_PROPERTY_DURATION = 3,
  QDMI_OPERATION_PROPERTY_FIDELITY = 4,
  QDMI_OPERATION_PROPERTY_INTERACTIONRADIUS = 5,
  QDMI_OPERATION_PROPERTY_BLOCKINGRADIUS = 6,
  QDMI_OPERATION_PROPERTY_IDLINGFIDELITY = 7,
  QDMI_OPERATION_PROPERTY_ISZONED = 8,
  QDMI_OPERATION_PROPERTY_SITES = 9,
  QDMI_OPERATION_PROPERTY_MEANSHUTTLINGSPEED = 10,
  QDMI_OPERATION_PROPERTY_MAX = 11,
  QDMI_OPERATION_PROPERTY_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_OPERATION_PROPERTY_CUSTOM2 = 999999996,
  QDMI_OPERATION_PROPERTY_CUSTOM3 = 999999997,
  QDMI_OPERATION_PROPERTY_CUSTOM4 = 999999998,
  QDMI_OPERATION_PROPERTY_CUSTOM5 = 999999999,
  QDMI_OPERATION_PROPERTY_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_OPERATION_PROPERTY_T QDMI_Operation_Property;

enum QDMI_JOB_STATUS_T {
  QDMI_JOB_STATUS_CREATED = 0,
  QDMI_JOB_STATUS_SUBMITTED = 1,
  QDMI_JOB_STATUS_QUEUED = 2,
  QDMI_JOB_STATUS_RUNNING = 3,
  QDMI_JOB_STATUS_DONE = 4,
  QDMI_JOB_STATUS_CANCELED = 5,
  QDMI_JOB_STATUS_FAILED = 6
};

typedef enum QDMI_JOB_STATUS_T QDMI_Job_Status;

#define QDMI_PROGRAM_ID_SIZE 64U

#define QDMI_MAKE_VERSION(major, minor, patch)                                 \
  ((((uint32_t)(major) & 0x3FFU) << 22U) |                                     \
   (((uint32_t)(minor) & 0x3FFU) << 12U) | ((uint32_t)(patch) & 0xFFFU))

#define QDMI_VERSION_MAJOR(version) (((uint32_t)(version) >> 22U) & 0x3FFU)
#define QDMI_VERSION_MINOR(version) (((uint32_t)(version) >> 12U) & 0x3FFU)
#define QDMI_VERSION_PATCH(version) ((uint32_t)(version) & 0xFFFU)

enum QDMI_PROGRAM_ENCODING_T {
  QDMI_PROGRAM_ENCODING_TEXT = 1,
  QDMI_PROGRAM_ENCODING_BINARY = 2
};

typedef enum QDMI_PROGRAM_ENCODING_T QDMI_Program_Encoding;

typedef struct QDMI_PROGRAM_FORMAT_T {
  uint32_t version;  
  uint32_t encoding; 
  char id[QDMI_PROGRAM_ID_SIZE];      
  char profile[QDMI_PROGRAM_ID_SIZE]; 
} QDMI_Program_Format;
 
#ifdef __cplusplus
static_assert(sizeof(QDMI_Program_Format) == 136U);
static_assert(alignof(QDMI_Program_Format) == 4U);
static_assert(offsetof(QDMI_Program_Format, version) == 0U);
static_assert(offsetof(QDMI_Program_Format, encoding) == 4U);
static_assert(offsetof(QDMI_Program_Format, id) == 8U);
static_assert(offsetof(QDMI_Program_Format, profile) == 72U);
#else
_Static_assert(sizeof(QDMI_Program_Format) == 136U,
               "QDMI_Program_Format must be 136 bytes");
_Static_assert(_Alignof(QDMI_Program_Format) == 4U,
               "QDMI_Program_Format must have four-byte alignment");
_Static_assert(offsetof(QDMI_Program_Format, version) == 0U,
               "QDMI_Program_Format.version must start at byte 0");
_Static_assert(offsetof(QDMI_Program_Format, encoding) == 4U,
               "QDMI_Program_Format.encoding must start at byte 4");
_Static_assert(offsetof(QDMI_Program_Format, id) == 8U,
               "QDMI_Program_Format.id must start at byte 8");
_Static_assert(offsetof(QDMI_Program_Format, profile) == 72U,
               "QDMI_Program_Format.profile must start at byte 72");
#endif

static inline int
QDMI_program_format_equal(const QDMI_Program_Format *const lhs,
                          const QDMI_Program_Format *const rhs) {
  if (lhs == NULL || rhs == NULL || lhs->version != rhs->version ||
      lhs->encoding != rhs->encoding) {
    return 0;
  }
  for (size_t index = 0U; index < QDMI_PROGRAM_ID_SIZE; ++index) {
    if (lhs->id[index] != rhs->id[index] ||
        lhs->profile[index] != rhs->profile[index]) {
      return 0;
    }
  }
  return 1;
}

#define QDMI_PROGRAM_FEATURE_ID_SIZE 64U

#define QDMI_PROGRAM_CONSTRAINT_ID_SIZE 64U

typedef struct QDMI_PROGRAM_FEATURE_T {
  char id[QDMI_PROGRAM_FEATURE_ID_SIZE]; 
  uint64_t value;                        
  char constraint_id[QDMI_PROGRAM_CONSTRAINT_ID_SIZE];
  uint64_t constraint_value; 
} QDMI_Program_Feature;

#define QDMI_PROGRAM_FEATURE_UNCONSTRAINED(feature_id, feature_value)          \
  {feature_id, feature_value, "", 0U}

#define QDMI_PROGRAM_FEATURE_MID_CIRCUIT_MEASUREMENT "mid-circuit-measurement"
#define QDMI_PROGRAM_FEATURE_MEASURED_QUBIT_REUSE "measured-qubit-reuse"
#define QDMI_PROGRAM_FEATURE_MEASUREMENT_RESULT_USE "measurement-result-use"
#define QDMI_PROGRAM_FEATURE_BOOLEAN_COMPUTATION "boolean-computation"
#define QDMI_PROGRAM_FEATURE_FORWARD_BRANCHING "forward-branching"
#define QDMI_PROGRAM_FEATURE_COUNTED_ITERATION "counted-iteration"
#define QDMI_PROGRAM_FEATURE_CONDITIONAL_LOOP "conditional-loop"
#define QDMI_PROGRAM_FEATURE_MULTIWAY_BRANCHING "multiway-branching"
#define QDMI_PROGRAM_FEATURE_INTEGER_COMPUTATION "integer-computation"
#define QDMI_PROGRAM_FEATURE_FLOAT_COMPUTATION "float-computation"
#define QDMI_PROGRAM_FEATURE_IR_FUNCTIONS "ir-functions"
#define QDMI_PROGRAM_FEATURE_MULTIPLE_RETURN_POINTS "multiple-return-points"
#define QDMI_PROGRAM_FEATURE_DYNAMIC_QUBIT_MANAGEMENT "dynamic-qubit-management"
#define QDMI_PROGRAM_FEATURE_DYNAMIC_RESULT_MANAGEMENT                         \
  "dynamic-result-management"

#define QDMI_PROGRAM_FEATURE_ARRAYS "arrays"

#define QDMI_PROGRAM_CONSTRAINT_MAX_CONTROL_FLOW_NESTING_DEPTH                 \
  "max-control-flow-nesting-depth"

#define QDMI_PROGRAM_CONSTRAINT_MAX_ITERATION_COUNT "max-iteration-count"
#define QDMI_PROGRAM_CONSTRAINT_MAX_CASE_COUNT "max-case-count"

enum QDMI_JOB_RESULT_T {
  QDMI_JOB_RESULT_SHOTS = 0,
  QDMI_JOB_RESULT_HIST_KEYS = 1,
  QDMI_JOB_RESULT_HIST_VALUES = 2,
  QDMI_JOB_RESULT_STATEVECTOR_DENSE = 3,
  QDMI_JOB_RESULT_PROBABILITIES_DENSE = 4,
  QDMI_JOB_RESULT_STATEVECTOR_SPARSE_KEYS = 5,
  QDMI_JOB_RESULT_STATEVECTOR_SPARSE_VALUES = 6,
  QDMI_JOB_RESULT_PROBABILITIES_SPARSE_KEYS = 7,
  QDMI_JOB_RESULT_PROBABILITIES_SPARSE_VALUES = 8,
  QDMI_JOB_RESULT_PROGRAMOUTPUT = 9,
  QDMI_JOB_RESULT_MAX = 10,
  QDMI_JOB_RESULT_CUSTOM1 = QDMI_CUSTOM_ENUM_VALUE_MIN,
  QDMI_JOB_RESULT_CUSTOM2 = 999999996,
  QDMI_JOB_RESULT_CUSTOM3 = 999999997,
  QDMI_JOB_RESULT_CUSTOM4 = 999999998,
  QDMI_JOB_RESULT_CUSTOM5 = 999999999,
  QDMI_JOB_RESULT_CUSTOM_MAX = QDMI_CUSTOM_ENUM_VALUE_MAX
};

typedef enum QDMI_JOB_RESULT_T QDMI_Job_Result;

enum QDMI_DEVICE_PULSE_SUPPORT_LEVEL_T {
  QDMI_DEVICE_PULSE_SUPPORT_LEVEL_NONE = 0,
  QDMI_DEVICE_PULSE_SUPPORT_LEVEL_SITE = 1,
  QDMI_DEVICE_PULSE_SUPPORT_LEVEL_CHANNEL = 2,
  QDMI_DEVICE_PULSE_SUPPORT_LEVEL_SITEANDCHANNEL = 3,
};

typedef enum QDMI_DEVICE_PULSE_SUPPORT_LEVEL_T QDMI_Device_Pulse_Support_Level;
 
// NOLINTEND(performance-enum-size, modernize-use-using)
 
#ifdef __cplusplus
} // extern "C"
#endif
 
#endif // QDMI_CONSTANTS_H