[CQT-271] Update spec with newly added instructions (#79)

* Add initial pages for init, barrier, and wait instructions.
Add SWAP gate to standard gate set.

* Fix theta value of CRk.

* Add documentation of barrier instruction.

* Add documentation on the wait instruction.

* Update docs/language_specification/statements/instructions/control_instructions/barrier_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Update docs/language_specification/statements/instructions/control_instructions/barrier_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Update docs/language_specification/statements/instructions/control_instructions/barrier_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Update docs/language_specification/statements/instructions/non_unitary_instructions/init_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Update docs/language_specification/statements/instructions/non_unitary_instructions/init_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Update docs/language_specification/statements/instructions/non_unitary_instructions/init_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

* Resolve review comments.

* Update docs/language_specification/statements/instructions/control_instructions/wait_instruction.md

Co-authored-by: Roberto Turrado Camblor <[email protected]>

---------

Co-authored-by: Roberto Turrado Camblor <[email protected]>

Author: elenbaasc

docs/appendices/spin_2.md renamed to docs/appendices/spin_2plus.md

@@ -1,6 +1,6 @@
-# Spin-2
+# Spin-2+
 
-The Spin-2 system developed by QuTech supports the following subset of the cQASM language:
+The Spin-2+ system developed by QuTech supports the following subset of the cQASM language:
 
 * Multiple line comments in `/* … */` are supported.
 * Single line comments in `// …`, `# …`, `/* …*/` are supported.
@@ -13,7 +13,6 @@ The Spin-2 system developed by QuTech supports the following subset of the cQASM
 * The single-gate-multiple-qubit (SGMQ) notation is fully supported for single qubit gates
 * The SGMQ notation is not supported for two qubit gates.
 * The SGMQ notation results in a bundle resulting in a sequential list of gate operations.
-* Subcircuit headers are accepted (and subsequently ignored).
 * All other libqasm 1.x language structures are not supported.
 * No `prep_X` and `measure_X` instructions are allowed, the lls will init all supported qubits before circuit execution
   and measure all in the z-basis at the end of the circuit and only return the subset as defined in the qubit register.

docs/language_specification/general_overview.md

@@ -43,8 +43,12 @@ The unitary operations, commonly know as gates, can be either
 - Instructions:
     - [Unitary instructions](statements/instructions/unitary_instructions.md) (_i.e._, gates)
     - Non-unitary instructions:
+        - [Init instruction](statements/instructions/non_unitary_instructions/init_instruction.md)
         - [Measure instruction](statements/instructions/non_unitary_instructions/measure_instruction.md)
         - [Reset instruction](statements/instructions/non_unitary_instructions/reset_instruction.md)
+    - Control instructions:
+        - [Barrier instruction](statements/instructions/control_instructions/barrier_instruction.md)
+        - [Wait instruction](statements/instructions/control_instructions/wait_instruction.md)
    - [Single-gate-multiple-qubit (SGMQ) notation](statements/instructions/single-gate-multiple-qubit-notation.md)
 
 !!! example ""

docs/language_specification/statements/instructions/control_instructions/barrier_instruction.md

@@ -0,0 +1,103 @@
+The **`barrier`** instruction is a single-qubit control instruction
+that is used to constrain the optimization of a scheduler.
+It tells a scheduler that instructions on the specified qubit(s) cannot be scheduled across the barrier.
+See the [**`wait`** instruction](wait_instruction.md), to impose a time delay following a barrier.
+
+The general form of the **`barrier`** instruction is as follows:
+
+!!! info ""
+
+     **`barrier`** _qubit-argument_
+
+??? info "Grammar for **`barrier`** instruction"
+    
+    _barrier-instruction_:  
+      __`barrier`__ _qubit-argument_
+
+    _qubit-argument_:  
+      _qubit-variable_  
+      _qubit-index_
+
+    _qubit-variable_:  
+      _identifier_
+
+    _qubit-index_:  
+      _index_
+
+!!! note
+
+    The **`barrier`** instruction accepts
+    [SGMQ notation](../single-gate-multiple-qubit-notation.md).
+    SGMQ notation allows you to express the application of an instruction to multiple qubits.
+    However, SGMQ notation does not guarantee simultaneity.
+    In general, a compiler will unpack this notation to separate consecutive
+    single-qubit instructions on each respective qubit.
+    This will depend on the scheduling optimization that is applied during the compilation process.
+
+    For certain backends,
+    groups of consecutive **`barrier`** instructions are linked together to form a _uniform_ barrier,
+    across which no instructions on the specified qubits can be scheduled.
+    Note that one can create a group of consecutive **`barrier`** instructions, _i.e._ a _uniform_ barrier,
+    using SGMQ notation.
+
+!!! example
+
+    === "Single qubit"
+    
+        ```linenums="1", hl_lines="3"
+        qubit q
+        X q
+        barrier q
+        X q
+        ```
+    
+    === "Multiple qubits"
+    
+        ```linenums="1", hl_lines="3"
+        qubit[3] q
+        X q[0]
+        barrier q[0, 1]
+        H q[0]
+        X q[2]
+        H q[1]
+        ```
+
+In the examples above it is shown how the **`barrier`** instruction can be used with a single qubit and multiple qubits.
+In the case of the single qubit,
+an optimizer would generally fuse the two **`X`** gates into a single identity gate, **`I`**.
+However, because of the presence of the **`barrier`** instruction, the user explicitly states that the instructions on
+**`q`** are not permitted to be optimized across the barrier.
+The second example shows that a barrier can be placed for multiple qubits.
+Note that the **`barrier`** instruction is applied to qubits **`q[0]`** and **`q[1]`**.
+Qubit **`q[2]`** can be optimized freely across this circuit, _i.e._, be scheduled before or after the barrier. 
+
+The following code snippet illustrates how the **`barrier`** instruction might be used in context.
+
+```linenums="1", hl_lines="9 12 19"
+version 3.0
+
+qubit[2] q
+init q
+
+// Phi+ state
+H q[0]
+CNOT q[0], q[1]
+barrier q
+b[0,1] = measure q
+
+barrier q
+reset q
+
+// Psi+ state
+H q[0]
+X q[1]
+CNOT q[0], q[1]
+barrier q
+b[2, 3] = measure q
+```
+
+In the above code snippet, the $\Phi_{+}$ and $\Psi_{+}$ Bell states are generated and measured, successively.
+The **`barrier`** instruction is used to guarantee that the
+[**`measure`** instruction](../non_unitary_instructions/measure_instruction.md) is scheduled _after_ the respective
+states have been generated. 
+Moreover, an extra **`barrier`** instruction is used to separate the generation and measurement of the two Bell states.

docs/language_specification/statements/instructions/control_instructions/wait_instruction.md

@@ -0,0 +1,115 @@
+The **`wait`** instruction is a single-qubit control instruction that is used to constrain the optimization of a
+scheduler.
+It tells the scheduler to delay the subsequent instructions on the specified qubit(s) by a given time.
+The delay time is passed along with the instruction as a dimensionless parameter,
+the unit of which represents the duration of a single-qubit gate on the backend,
+_i.e._, an execution cycle. 
+Moreover, the **`wait`** instruction will also function as a [_barrier_](barrier_instruction.md),
+telling the scheduler that instructions on the specified qubit(s) cannot be scheduled across the position of the 
+**`wait`** instruction.
+
+!!! warning
+
+    The [**`barrier`** instruction](barrier_instruction.md) may be considered equal to the **`wait`** instruction with a
+    time delay set to 0.
+    Note however that for certain backends, groups of consecutive **`barrier`** instructions are linked together to
+    form a _uniform_ barrier, across which no instructions on the specified qubits can be scheduled.
+    This is **not** the case for the **`wait`** instruction; consecutive **`wait`** instructions on different qubits
+    are considered to be independent instructions.
+
+    Multiple successive **`wait`** instructions on the _same_ qubit,
+    however, may be fused into a single **`wait`** instruction,
+    where the delay time is set to the sum of the delay times of the separate instructions.
+    For example,
+    
+    ```hl_lines="1 3"
+    wait(3) q[0]
+    wait(4) q[1]
+    wait(2) q[0]
+    ```
+
+    could be optimized to:
+    
+    ```hl_lines="1"
+    wait(5) q[0]
+    wait(4) q[1]
+    ```
+
+The general form of the **`wait`** instruction is as follows:
+
+!!! info ""
+
+     __`wait(`__ _parameter_ __`)`__ _qubit-argument_
+
+??? info "Grammar for **`wait`** instruction"
+    
+    _wait-instruction_:  
+     __`wait(`__ _parameter_ __`)`__ _qubit-argument_
+
+    _parameter_:  
+      _integer-literal_ 
+
+    _qubit-argument_:  
+      _qubit-variable_  
+      _qubit-index_
+
+    _qubit-variable_:  
+      _identifier_
+
+    _qubit-index_:  
+      _index_
+
+!!! note
+
+    The **`wait`** instruction accepts
+    [SGMQ notation](../single-gate-multiple-qubit-notation.md), similar to gates.
+
+!!! example
+
+    === "Single qubit"
+    
+        ```linenums="1", hl_lines="3"
+        qubit q
+        X q
+        wait(5) q  // time delay of 5 execution cycles
+        X q
+        ```
+    
+    === "Multiple qubits"
+    
+        ```linenums="1", hl_lines="3"
+        qubit[3] q
+        X q[0]
+        wait(5) q[0, 1]  // time delay of 5 execution cycles
+        H q[0]
+        X q[2]
+        H q[1]
+        ```
+
+In the examples above it is shown how the **`wait`** instruction can be used with a single qubit and multiple qubits.
+In the case of the single qubit, the **`wait`** instruction tells the scheduler to schedule a delay of 5 execution
+cycles between the successive **`X`** gates.
+Note that it also implicitly places a [barrier](barrier_instruction.md) between the two **`X`** gates,
+such that they cannot be fused into a single identity gate, **`I`**.
+In the second example, using SGMQ notation, the **`wait`** instruction is applied to qubits **`q[0]`** and **`q[1]`**.
+Enforcing a delay of 5 execution cycles on any following instructions involving those qubits,
+_e.g._, here **`H q[0]`** and **`H q[1]`**.
+Qubit **`q[2]`** can be optimized freely across this circuit,
+_i.e._, be scheduled before or after **`wait`** instruction, regardless of any specified time delay. 
+
+The following code snippet illustrates how the **`wait`** instruction might be used in context.
+
+```linenums="1", hl_lines="7"
+version 3.0
+
+qubit[2] q
+bit[2] b
+init q
+
+wait(100) q[0]
+b[0] = measure q[0]
+```
+
+Here, the [measurement](../non_unitary_instructions/measure_instruction.md) of **`q[0]`** is forced to be scheduled at
+least 100 execution cycles after the [initialization](../non_unitary_instructions/init_instruction.md)
+of the qubit is complete.

docs/language_specification/statements/instructions/non_unitary_instructions/init_instruction.md

@@ -0,0 +1,101 @@
+In general, qubits are initialized in the $|0\rangle$ state.
+Nonetheless, to explicitly initialize (particular) qubits in the $|0\rangle$ state
+one can use the **`init`** instruction.
+The general form of an **`init`** instruction is as follows:
+
+!!! info ""
+
+     **`init`** _qubit-argument_
+
+??? info "Grammar for **`init`** instruction"
+    
+    _init-instruction_:  
+      __`init`__ _qubit-argument_
+
+    _qubit-argument_:  
+      _qubit-variable_  
+      _qubit-index_
+
+    _qubit-variable_:  
+      _identifier_
+
+    _qubit-index_:  
+      _index_
+
+!!! example
+
+    === "Initialize a single qubit"
+    
+        ```linenums="1", hl_lines="2"
+        qubit q
+        init q
+        ```
+    
+    === "Initialize multiple qubits through their register index"
+    
+        ```linenums="1", hl_lines="2"
+        qubit[5] q
+        init q[2, 4]
+        ```
+
+!!! note
+
+    The **`init`** instruction accepts
+    [SGMQ notation](../single-gate-multiple-qubit-notation.md), similar to gates.
+
+The following code snippet shows how the **`init`** instruction might be used in context.
+
+```linenums="1" hl_lines="6"
+version 3.0
+
+qubit[2] q
+bit[2] b
+
+init q  // Initializes the qubits to |0>
+
+H q[0]
+CNOT q[0], q[1]
+
+b = measure q
+```
+
+In the code example above, the qubits are first declared and subsequently initialized.
+Note that the initialization of qubits needs to be done before any instruction
+(excluding a control instruction)
+is applied to them (see warning below).
+If one wishes to _reset_ the state of the qubit to $|0\rangle$ mid-circuit,
+one should use the [**`reset`**](../non_unitary_instructions/reset_instruction.md) instruction.
+
+
+!!! warning
+    
+    Initialization of a qubit can only be done immediately after declaration of the qubit, _i.e._, 
+    it is not possible to initialize a qubit, if prior to that an instruction was applied to the qubit
+    (excluding a control instruction).
+
+    === "Invalid initialization"
+        
+        ```linenums="1" hl_lines="8"
+        version 3.0
+    
+        qubit[2] q
+
+        barrier q  // Control instructions may be applied to qubits before initialization
+        H q[1]
+
+        init q[1]  // Invalid use, since the H gate was applied to q[1] before initialization
+        ```
+
+    === "Valid initialization"
+        
+        ```linenums="1" hl_lines="8"
+        version 3.0
+    
+        qubit[2] q
+    
+        barrier q  // Control instructions may be applied to qubits before initialization
+        H q[1]
+
+        init q[0]  // Valid use, because no instruction is applied to q[0] before initalization
+        ```
+    

docs/language_specification/statements/instructions/non_unitary_instructions/measure_instruction.md

@@ -1,12 +1,12 @@
 A **`measure`** instruction performs a measurement to its qubit argument and
 assigns the outcome to a bit variable.
-The general form of a measure instruction is as follows:
+The general form of a **`measure`** instruction is as follows:
 
 !!! info ""
 
      _bit-argument_ **`=`** **`measure`** _qubit-argument_
 
-??? info "Grammar for measure instruction"
+??? info "Grammar for **`measure`** instruction"
 
     _measure-instruction_:  
       _bit-argument_ __`=`__ __`measure`__ _qubit-argument_
@@ -51,10 +51,10 @@ The general form of a measure instruction is as follows:
 
 !!! note
 
-    The measure instruction accepts
+    The **`measure`** instruction accepts
     [SGMQ notation](../single-gate-multiple-qubit-notation.md), similar to gates.
 
-The following code snippet shows how the measure instruction might be used in context.
+The following code snippet shows how the **`measure`** instruction might be used in context.
 
 ```linenums="1" hl_lines="9"
 version 3.0