# CQC Interface¶

## Introduction¶

Here we specifiy the CQC message interface. For programming SimulaQron via the CQC Interface using the Python or C provided, you do not need to know the extend of this message format. The below will be necessary, if you want to write your own library in another language. The easiest way of programming SimulaQron is via the Python CQC lib, so we recommend to get started there. Documentation of how to use the Python CQC lib can be found here Getting started: and examples here Examples using the python library.

Upon establishing a connection to the CQC Backend, the following packet format can be used to issue commands to the simulated quantum network. Each interaction to and from the interface starts with a CQC Header, followed by additional headers as appropriate to the message type.

When accessing the interface directly, you must keep track of qubit IDs for each application ID yourself. It is a deliberate choice that the CQC Backend does not itself keep track of qubit or application IDs, leaving such management to you (and indeed higher levels of abstraction if you wish). When a qubit is created with the command CQC_CMD_NEW a CQC message will be returned of the type CQC_TP_NEW_OK followed by a CQCXtraQubitHeader containing the qubit ID. Note that if the option notify, see below, is set to true a message of type CQC_TP_DONE will also be returned, after the notification header, saying that the command is finished.

The CQC header indicates the start of a new CQC program. Therefore, every CQC program must start with a CQC header. The end of the program is indicated by the length field of this header, which contains the number of bytes following this header which constitute the current CQC program. NOTE: CQC defines many headers, but the CQC header is one specific header.

Function

Type

Length

Comment

version

unsigned integer (uint8_t)

1 byte

Current version is 2

type

unsigned integer (uint8_t)

1 byte

Message type (see below)

app_id

unsigned integer (uint16_t)

2 bytes

Application ID, return messages will be tagged appropriately

length

unsigned integer (uint32_t)

4 bytes

Total length of the CQC instruction packet (excluding this header)

Possible message types are listed below. Depending on the message type additional headers may be required as specified below:

class CQCType(IntEnum):
HELLO           =       0  # Alive check
COMMAND         =       1  # Execute a command list
FACTORY         =       2  # Start executing command list repeatedly
EXPIRE          =       3  # Qubit has expired
DONE            =       4  # Done with command
RECV            =       5  # Received qubit
EPR_OK          =       6  # Created EPR pair
MEASOUT         =       7  # Measurement outcome
GET_TIME        =       8  # Get creation time of qubit
INF_TIME        =       9  # Return timinig information
NEW_OK          =       10  # Created a new qubit
MIX             =       11  # Indicate that the CQC program will contain multiple header types
IF              =       12  # Announce a CQC IF header

ERR_GENERAL     =       20  # General purpose error (no details
ERR_NOQUBIT     =       21  # No more qubits available
ERR_UNSUPP      =       22  # No sequence not supported
ERR_TIMEOUT     =       23  # Timeout
ERR_INUSE       =       24  # Qubit already in use
ERR_UNKNOWN     =       25  # Unknown qubit ID


If the message type is CQC_TP_COMMAND, CQC_TP_FACTORY or CQC_TP_GET_TIME, then the following additional command header must be supplied. It identifies the specific instruction to execute, as well as the qubit ID on which to perform this instructions. For rotations, two qubit gates, request to send or receive, and produce entanglement, the additional headers are required supplying further information.

If CQC_OPT_NOTIFY set to true, each of these commmands return a CQC message of type CQC_TP_DONE. Some commands also return additional messages before the optional done-message, as described below:

• CQC_CMD_NEW: Returns CQC_TP_NEW_OK followed by a CQCXtraQubitHeader containing the qubit ID.

• CQC_CMD_MEASURE(_INPLACE): Returns CQC_TP_MEASOUT followed by a CQCMeasOutHeader containing the measurement outcome.

• CQC_CMD_RECV: Returns CQC_TP_RECV followed by a CQCXtraQubitHeader containing the qubit ID.

• CQC_CMD_EPR(_RECV): Returns CQC_TP_EPR_OK followed by CQCXtraQubitHeader and an entanglement information header.

• CQCHeader (type CQC_TP_COMMAND)

• CQCCmdHeader (instr CQC_CMD_ROT_X)

• CQCCmdHeader (instr CQC_CMD_Z)

An example with factory that does X rotation, then a Z gate, 4 times:

• CQCHeader (type CQC_TP_FACTORY)

• CQCFactoryHeader (num_iter = 4)

• CQCCmdHeader (instr CQC_CMD_ROT_X)

• CQCCmdHeader (instr CQC_CMD_Z)

Function

Type

Length

Comment

qubit_id

unsigned int (uint16_t)

2 bytes

Qubit ID to perform the operation on

instr

unsigned int (uint8_t)

1 byte

Instruction to perform (see below)

options

unsigned int (uint8_t)

1 byte

Options when executing the command

The value of instr can be any of the following:

/* Possible commands */
#define CQC_CMD_I               0       /* Identity (do nothing, wait one step) */
#define CQC_CMD_NEW             1       /* Ask for a new qubit */
#define CQC_CMD_MEASURE         2       /* Measure qubit */
#define CQC_CMD_MEASURE_INPLACE 3       /* Measure qubit inplace */
#define CQC_CMD_RESET           4       /* Reset qubit to |0> */
#define CQC_CMD_SEND            5       /* Send qubit to another node */
#define CQC_CMD_EPR             7       /* Create EPR pair with the specified node */
#define CQC_CMD_EPR_RECV        8       /* Create EPR pair with the specified node */

#define CQC_CMD_X               10      /* Pauli X */
#define CQC_CMD_Z               11      /* Pauli Z */
#define CQC_CMD_Y               12      /* Pauli Y */
#define CQC_CMD_T               13      /* T Gate */
#define CQC_CMD_ROT_X           14      /* Rotation over angle around X in pi/256 increments */
#define CQC_CMD_ROT_Y           15      /* Rotation over angle around Y in pi/256 increments */
#define CQC_CMD_ROT_Z           16      /* Rotation over angle around Z in pi/256 increments */
#define CQC_CMD_H               17      /* Hadamard Gate */
#define CQC_CMD_K               18      /* K Gate - taking computational to Y eigenbasis */

#define CQC_CMD_CNOT            20      /* CNOT Gate with this as control */
#define CQC_CMD_CPHASE          21      /* CPHASE Gate with this as control */

#define CQC_CMD_ALLOCATE        22      /* Allocate a number of qubits */
#define CQC_CMD_RELEASE         23      /* Release a qubit */

/* Command options */
#define CQC_OPT_NOTIFY          0x01    /* Send a notification when cmd done */
#define CQC_OPT_ACTION          0x02    /* Deprecated. The value of this option has no effect. */
#define CQC_OPT_BLOCK           0x04    /* Block until command is done */
#define CQC_OPT_IFTHEN          0x08    /* Execute command after done */


The CQCXtraHeader is deprecated and will be removed in the future. It is split up in multiple headers now. Additional header containing further information. The following commands require an xtra header when issued to the CQC Backend: CQC_CMD_SEND, CQC_CMD_RECV, CQC_CMD_CPHASE, CQC_CMD_CNOT, CQC_CMD_ROT_X, CQC_CMD_ROT_Y, CQC_CMD_ROT_Z

Function

Type

Length

xtra_qubit_id

unsigned int (uint16_t)

2 bytes

ID of the target qubit in a 2 qubit controlled gate

remote_app_id

unsigned int (uint16_t)

2 bytes

Remote Application ID

remote_node

unsigned int (uint32_t)

4 bytes

IP of the remote node (IPv4)

cmdLength

unsigned int (uint32_t)

4 bytes

Length of the additional commands to execute upon completion.

remote_port

unsigned int (uint16_t)

2 bytes

Port of the remode node for sending classical control info

steps

unsigned int (uint8_t)

1 byte

Angle step of rotation (ROT) OR number of repetitions (FACTORY)

unused

unsigned int (uint8_t)

1 byte

4 byte align

Additional header used to store a measurement outcome in the backend and assign it a reference ID. Every measurement command (CQC_CMD_MEASURE or CQC_CMD_MEASURE_INPLACE) is followed by a CQC Assign Header. The value can be retrieved by future instructions by refering to this ID. Currently, only the CQC If Header supports retrieving measurement outcomes by reference ID.

Function

Type

Length

reference ID

unsigned int (uint32_t)

4 bytes

Reference ID to which to assign the value that the preceding header yielded

Additional header used to define the rotation angle of a rotation gate.

Function

Type

Length

step

unsigned int (uint8_t)

1 bytes

Angle step of rotation (increments in 1/256 per step)

Function

Type

Length

qubit_id

unsigned int (uint16_t)

2 bytes

Qubit_id of the target qubit

Additional header used to send to which node to send information to. Used in send and EPR commands.

Function

Type

Length

remote_app_id

unsigned int (uint16_t)

2 bytes

Remote Application ID

remote_port

unsigned int (uint16_t)

2 bytes

Port of the remode node for sending classical control info

remote_node

unsigned int (uint32_t)

4 bytes

IP of the remote node (IPv4)

Additional header used to send factory information. Factory commands are used to tell the backend to do the following command or a sequence of commands multiple times.

Function

Type

Length

num_iter

unsigned int (uint8_t)

1 byte

Number of iterations to do the sequence

options

unsigned int (uint8_t)

1 byte

Options when executing the factory

The value of options can be any of the following:

#define CQC_OPT_NOTIFY          0x01    /* Send a notification when cmd is done */
#define CQC_OPT_BLOCK           0x04    /* Block until factory is done */


The CQCNotifyHeader is deprecated and will be removed in the future. It is split up in CQCXtraQubitHeader, CQCMeasOutHeaderand CQCTimeinfoHeader now. In some cases, the CQC Backend will return notifications to the client that require additional information. For example, where a qubit was received from, the lifetime of a qubit, the measurement outcome etc.

Function

Type

Length

qubit_id

unsigned int (uint16_t)

2 bytes

remote_app_id

unsigned int (uint16_t)

2 bytes

Remote application ID

remote_node

unsigned int (uint32_t)

4 bytes

IP of the remote node

datetime

unsigned int (uint64_t)

8 bytes

Time of creation

remote_port

unsigned int (uint16_t)

2 bytes

Port of the remote node for sending classical control info

outcome

unsigned int (uint8_t)

1 byte

Measurement outcome

unused

unsigned int (uint8_t)

1 byte

4 byte align

Function

Type

Length

meas_out

unsigned int (uint8_t)

1 byte

Measurement outcome

Function

Type

Length

datetime

unsigned int (uint64_t)

8 bytes

Time of creation

When an EPR-pair is created the CQC Backend will return information about the entanglement which can be used in a entanglement management protocol. The entanglement information header contains information about the parties that share the EPR-pair, the time of creation, how good the entanglement is (goodness). Furthermore, the entanglement information header contain a entanglement ID (id_AB) which can be used to keep track of the entanglement in the network. The entanglement ID is incremented with respect to the pair of nodes and who initialized the entanglement (DF). For this reason the entanglement ID together with the nodes and the directionality flag gives a unique way to identify the entanglement in the network.

Function

Type

Length

node_A

unsigned int (uint32_t)

4 bytes

IP of this node

port_A

unsigned int (uint16_t)

2 bytes

Port of this node

app_id_A

unsigned int (uint16_t)

2 bytes

App ID of this node

node_B

unsigned int (uint32_t)

4 bytes

IP of other node

port_B

unsigned int (uint16_t)

2 bytes

Port of other node

app_id_B

unsigned int (uint16_t)

2 byte

App ID of other node

id_AB

unsigned int (uint32_t)

4 byte

Entanglement ID

timestamp

unsigned int (uint64_t)

8 byte

Time of creation

ToG

unsigned int (uint64_t)

8 byte

Time of goodness

goodness

unsigned int (uint16_t)

2 byte

Goodness (estimate of the fidelity of state)

DF

unsigned int (uint8_t)

1 byte

Directionality flag (0=Mid-source, 1=node_A, 2=node_B)

unused

unsigned int (uint8_t)

1 byte

4 byte align

Function

Type

Length

type

unsigned int (uint8_t)

1 bytes

Type of next header. Any of the types CQC Header supports, except type Mix.

length

unsigned int (uint32_t)

4 bytes

Number of bytes until the next type header

The If header can only be used inside programs of type Mix. It enables comparison of a measurement outcome to a value in the backend.

Function

Type

first operand

unsigned int (uint32_t)

4 bytes

Reference ID of the first operand

operator

unsigned int (uint8_t)

1 byte

Operator ID. See table below.

type of second operand

unsigned int (uint8_t)

1 byte

Can be 0 or 1. 0 means value, 1 means reference ID

second operand

unsigned int (uint32_t)

4 bytes

Reference ID or value of the second operand

length

unsigned int (uint32_t)

4 bytes

Number of bytes to skip if the conditional is False.

Field operator can be any of the following comparison operators:

Equality        0
Inequality      1


The field type of second operand indicates whether second operand is a value or a reference ID. This enables comparison of a reference to a value, as well as comparison of a reference to another reference.