Message Definitions (Router-Dealer Mode)
========================================

Dispatch Computing Task
-----------------------

**Function:** This message is used by the Sinan system to dispatch calculation tasks to the control system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgTask``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **TaskId** (``String``): [Required] Task ID. 

- **ConvertQProg** (``String``): [Required] Instructions to be executed by the control system (photonic quantum platform specific format). 

- **Configure.TaskPriority** (``Uint32_t``): [Optional, defaults to 0] Task priority. Currently only supports 2 priority levels: 0 (normal task), 1 (high priority). 

- **Configure.Shot** (``Uint32_t``): [Required] Number of repetitions. Value range: 100\ :math:`\sim`\ 10000; defaults to 1000 if exceeded. 

- **Configure.IsExperiment** (``Bool``): [Optional] Whether it is in experiment mode. true: experiment mode; false: non-experiment mode (normal user task). When this field is empty, it represents the normal user task mode. 

- **Configure.ClockCycle** (``Uint32_t``): [Optional] Execution timing. Maximum circuit execution cycle, unit: microseconds. Sinan automatically determines whether to pass this parameter based on the maximum execution cycle of the chip returned by the control system. For example, if the control system returns that the current chip’s normal execution cycle is 100us and the maximum execution cycle is 500us, and if a task’s execution timing exceeds 100us but is less than 500us, this parameter will be adjusted according to the specific circuit timing situation; if the user’s circuit execution timing is less than 100us, this parameter does not need to be passed. 

- **Configure.PointLabel** (``Uint32_t``): [Required] Application factory label, tentatively set to 128. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgTaskAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. Can be empty when there is no error; required when an error occurs. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"MsgTask",
       "SN":133,
       "TaskId":"11D919FA044846F3B4DF453A827AE901",
       "ConvertQProg":"[{\"RZ\": [0, 180.0]},{\"CNOT\": [1, 2]},{\"H\": [2]},{\"Measure\": [[1, 0]]}]",
       "Configure":{
           "Shot":1000,
           "TaskPriority":1,
           "IsExperiment": true, 
           "PointLabel":128
       }
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"MsgTaskAck",
       "SN":133,
       "ErrCode":2,
       "ErrInfo":"configure error."
   } 

Task Status Query
-----------------

**Function:** Sinan sends task status inquiry information to the control system to determine the current task calculation status. When Sinan cannot receive the calculation result for a long time, it can use this message to query the task status from the control system to prevent Sinan from waiting indefinitely under abnormal conditions. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``TaskStatus``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **TaskId** (``String``): [Required] Task ID. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``TaskStatusAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **TaskId** (``String``): [Required] Task ID. 

- **TaskStatus** (``Uint32_t``): [Required] Task status, refer to the "Type Definitions" section. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"TaskStatus",
       "SN":10086,
       "TaskId":"11D919FA044846F3B4DF453A827AE901"
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"TaskStatusAck",
       "SN":10086,
       "TaskId":"11D919FA044846F3B4DF453A827AE901",
       "TaskStatus":3
   }

Return Computing Result
-----------------------

**Function:** The control system returns the computing result to the Sinan system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgTaskResult``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **TaskId** (``String``): [Required] Task ID. 

- **ProbCount** (``Int Array``): [Required] Collapse count, the collapse count corresponding to each Key. 

- **NoteTime.CompileTime** (``Int``): [Required] Compilation time consumption information, unit: ms. 

- **NoteTime.PendingTime** (``Int``): [Required] Queuing time consumption information, unit: ms. 

- **NoteTime.MeasureTime** (``Int``): [Required] Measurement time consumption information, unit: ms. 

- **NoteTime.PostProcessTime** (``Int``): [Required] Post-processing time consumption information, unit: ms. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgTaskResultAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"MsgTaskResult",
       "SN":133,
       "TaskId":"11D919FA044846F3B4DF453A827AE901",
       #"key":"Quantum states are uniformly represented by hexadecimal strings",
       "Key": [["0x0","0x1"],["0x0","0x1"]],
       "ProbCount": [[111,656],[103,703]],
       "NoteTime":
       {
           "CompileTime":1,
           "PendingTime":94,
           "MeasureTime":2306,
           "PostProcessTime":105
       },
       "ErrCode":0,
       "ErrInfo":""
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"MsgTaskResultAck",
       "SN":133,
       "ErrCode":3,
       "ErrInfo":"data error."
   } 

Heartbeat Message
-----------------

**Function:** Used to detect the connection status between the Sinan system and the control system. The control system maintains the system service; the Sinan system actively sends a heartbeat packet, and after receiving the heartbeat packet, the control system sends a heartbeat response. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgHeartbeat``. 

- **SN** (``Uint32_t``): [Required] Heartbeat message sequence ID. 

- **TimeStamp** (``Uint64_t``): [Required] 64-bit integer timestamp, milliseconds. 

- **ChipID** (``Uint32_t``): [Required] Chip name, for example: 72. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``MsgHeartbeatAck``. 

- **SN** (``Uint32_t``): [Required] Heartbeat message sequence ID. 

- **backend** (``Uint32_t``): [Required] Backend chip ID. 

- **TimeStamp** (``Uint64_t``): [Required] 64-bit integer timestamp, milliseconds. 

- **Topic** (``String``): [Required] Subscribed message topic. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"MsgHeartbeat",
       "SN":133,
       "ChipID":72,
       "TimeStamp":1638769359507
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"MsgHeartbeatAck",
       "SN":133, 
       "backend":72,
       "TimeStamp":1638769359517,
       "Topic":"Y4-231011-DesignVerification-72bit_300pin_V9.2.3_Base-3#_|_Y4-231011-DesignVerification-72bit_300pin_V9.2.3_Base-3#"
   }

Get Chip Calibration Time
-------------------------

**Function:** Used to actively obtain the time of the last calibration of the chip by the control system. Returned by the control system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetUpdateTime``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetUpdateTimeAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **backend** (``Uint32_t``): [Required] Backend chip ID. 

- **LastUpdateTime.qubit** (``Uint32_t``): [Required] Qubit names for the chip calibration timestamp (integer data). 

- **LastUpdateTime.timeStamp** (``Uint64_t``): [Required] Corresponding times for the chip calibration timestamps (64-bit integer timestamp, milliseconds). 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"GetUpdateTime",
       "SN":133
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"GetUpdateTimeAck", 
       "SN":133,
       "backend":72,
       "LastUpdateTime":
       {
           "qubit":[43,45,46,48,49,52,53,54,60],
           "timeStamp":[1687243363189,1687243363189,1687243363189,
           1687243363189,1687243363189,
           1687243363189,1687243363189,
           1687243363189]
       },
       "ErrCode":0,
       "ErrInfo":""
   }

Get RB Experiment Data
----------------------

**Function:** Used to actively obtain RB experiment data. Returned by the control system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetRBData``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ChipID** (``Uint32_t``): [Required] Chip name, for example: 72. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetRBDataAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **backend** (``Uint32_t``): [Required] Backend chip ID. 

- **SingleGateCircuitDepth** (``Uint32_t``): [Required] Maximum single-gate circuit depth for the RB experiment. 

- **DoubleGateCircuitDepth** (``Uint32_t``): [Required] Maximum double-gate circuit depth for the RB experiment. 

- **SingleGateFidelity** (``String``): [Required] Single qubit fidelity (string type map table). 

- **DoubleGateFidelity** (``String``): [Required] Double qubit fidelity (string type map table). 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"GetRBData",
       "SN":133,
       "ChipID":72
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"GetRBDataAck",
       "SN":133,
       "backend":72,
       "SingleGateCircuitDepth":[50,50,50,50,50,50,50,50,50,50],
       "DoubleGateCircuitDepth":[0,50,50,50,50,50,50,0], 
       "SingleGateFidelity":
       {
           "qubit":["45","46","48","52"],
           "fidelity":[0.9,0.9,0.9,0.9]
       },
       "DoubleGateFidelity":
       {
           "qubitPair":["45-46","46-52","48-54","52-53"],
           "fidelity":[0.9,0.9,0.9,0.9]
       },
       "ErrCode":0,
       "ErrInfo":"" 
   }

Get Chip Configuration Parameters
---------------------------------

**Function:** Obtain chip configuration parameters (json data), returned by the control system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetChipConfig``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ChipID** (``Uint32_t``): [Required] Chip name, for example: 72. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetChipConfigAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **backend** (``Uint32_t``): [Required] Backend chip ID. 

- **PointLabelList** (``Uint32_t Array``): [Required] List of workspace modes supported by the current chip. 

- **ChipConfig** (``String``): [Required] Chip parameters json string. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"GetChipConfig",
       "SN":133,
       "ChipID":72
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"GetChipConfigAck",
       "SN":133,
       "backend":72,
       "PointLabelList":[1,2],
       "ChipConfig":{
         "1":"QuantumChipArch.json related configuration information",
         "2":"QuantumChipArch.json related configuration information"
       }, 
       "ErrCode":0,
       "ErrInfo":""
   }

Request Specified Task Result
-----------------------------

**Function:** Used under abnormal conditions when Sinan fails to correctly receive the calculation result returned by the control system; Sinan actively requests the calculation result information of the specified task from the control system. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``GetTaskResult``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **TaskId** (``String``): [Required] Task ID. 

**Return Information:** The return result information is consistent with the format in the "2.3 Return Computing Result" section, but the "TaskResult" and "FidelityMat" field information are deleted.  **Note: The message serial number in the return result is consistent with the serial number of the get-result message.** 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"GetTaskResult",
       "SN":134,
       "TaskId":"11D919FA044846F3B4DF453A827AE901"
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"MsgTaskResult",
       "SN":134,
       "TaskId":"11D919FA044846F3B4DF453A827AE901",
       #"key":"Quantum states are uniformly represented by hexadecimal strings",
       "Key": [["0x0","0x1"],["0x0","0x1"]],
       "ProbCount": [[111,656],[103,703]],
       "NoteTime":
       {
           "CompileTime":1,
           "PendingTime":94,
           "MeasureTime":2306, 
           "PostProcessTime":105
       },
       "ErrCode":0,
       "ErrInfo":""
   }

Set Exclusive Machine Time
--------------------------

**Function:** Used in specific demand scenarios where Sinan sets an exclusive machine time to ensure that tasks do not need to queue during the exclusive time. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``SetVip``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **OffsetTime** (``Uint64_t``): [Required] Offset time relative to the current system time (unit: seconds). 

- **ExclusiveTime** (``Uint64_t``): [Required] Exclusive machine time duration (unit: seconds). 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``SetVipAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"SetVip",
       "SN":134, 
       "OffsetTime":120,
       "ExclusiveTime":600
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"SetVipAck",
       "SN":134,
       "ErrCode":0,
       "ErrInfo":""
   }

Release Exclusive Machine Time
------------------------------

**Function:** Used after completing tasks in exclusive machine time to execute a release exclusive machine time operation and restore normal mode. 

**Parameter Definitions:**

- **MsgType** (``String``): [Required] Message type, fixed as ``ReleaseVip``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

**Return Information:**

- **MsgType** (``String``): [Required] Message type, fixed as ``ReleaseVipAck``. 

- **SN** (``Uint32_t``): [Required] Message sequence ID. 

- **ErrCode** (``Uint32_t``): [Required] Error code. 

- **ErrInfo** (``String``): [Conditionally Required] Error information. 

**Request Example:**

.. code-block:: json

   {
       "MsgType":"ReleaseVip",
       "SN":135
   }

**Return Example:**

.. code-block:: json

   {
       "MsgType":"ReleaseVipAck",
       "SN":135,
       "ErrCode":0,
       "ErrInfo":"" 
   }