Merge branch 'main' into test/missing-ops

.github/workflows/release-plz.yml

@@ -22,7 +22,6 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
         uses: MarcoIeni/[email protected]
-        with:
-          command: release-pr
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

src/circuit_json.rs

@@ -12,10 +12,12 @@ pub struct Register(pub String, pub Vec<i64>);
 /// A gate defined by a circuit.
 #[derive(Deserialize, Serialize, Clone, Debug, PartialEq)]
 pub struct CompositeGate {
-    // List of Symbols
+    /// Name of the composite gate.
+    name: String,
+    /// Expressions corresponding to parameter values of the composite gate, if it has parameters.
     args: Vec<String>,
+    /// The circuit defining the gate.
     definition: Box<SerialCircuit>,
-    name: String,
 }
 
 /// A classical bit register.
@@ -25,6 +27,22 @@ pub struct BitRegister {
     size: u32,
 }
 
+/// A vector of booleans.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
+#[serde(transparent)]
+pub struct Bitstring {
+    /// Vector of booleans.
+    pub vec: Vec<bool>,
+}
+
+/// A 2D matrix.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
+#[serde(transparent)]
+pub struct Matrix<T = f32> {
+    /// A 2D vector of complex numbers.
+    pub data: Vec<Vec<(T, T)>>,
+}
+
 /// The units used in a [`ClassicalExp`].
 #[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
 #[serde(untagged)]

src/opbox.rs

@@ -1,7 +1,13 @@
 //! Data definition for box operations.
+//!
+//! These definitions correspond to the operations' `box` attribute in the
+//! [`circuit_v1`](https://github.com/CQCL/tket/blob/develop/schemas/circuit_v1.json)
+//! schema.
+
+use std::collections::HashMap;
 
 use crate::circuit_json::{
-    ClassicalExp, CompositeGate, Operation, Permutation, Register, SerialCircuit,
+    Bitstring, ClassicalExp, CompositeGate, Matrix, Operation, Permutation, Register, SerialCircuit,
 };
 use crate::optype::OpType;
 use serde::{Deserialize, Serialize};
@@ -61,48 +67,70 @@ pub enum OpBox {
         #[serde(default)]
         cx_config: String,
     },
-    /// Operation defined as a pair of exponential of a tensor of Pauli operators.
+    /// A pair of (not necessarily commuting) Pauli exponentials performed in sequence.
     PauliExpPairBox {
         id: BoxID,
         /// List of List of Pauli operators.
-        paulis: Vec<Vec<String>>,
+        paulis_pair: Vec<Vec<String>>,
         /// List of Symengine expressions.
-        phase: Vec<String>,
+        phase_pair: Vec<String>,
         /// Config param for decomposition of Pauli exponentials.
         cx_config: String,
     },
     /// Operation defined as a set of commuting exponentials of a tensor of Pauli operators.
     PauliExpCommutingSetBox {
         id: BoxID,
-        /// List of List of Pauli operators.
-        paulis: Vec<(Vec<String>, String)>,
         /// List of Symengine expressions.
         pauli_gadgets: Vec<(Vec<String>, String)>,
         /// Config param for decomposition of Pauli exponentials.
         cx_config: String,
     },
+    /// An unordered collection of Pauli exponentials that can be synthesised in
+    /// any order, causing a change in the unitary operation. Synthesis order
+    /// depends on the synthesis strategy chosen only.
+    TermSequenceBox {
+        id: BoxID,
+        /// List of Symengine expressions.
+        pauli_gadgets: Vec<(Vec<String>, String)>,
+        /// Synthesis strategy. See [`PauliSynthStrat`].
+        #[serde(default)]
+        synth_strategy: PauliSynthStrat,
+        /// Partition strategy. See [`PauliPartitionStrat`].
+        #[serde(default)]
+        partition_strategy: PauliPartitionStrat,
+        /// Graph colouring method. See [`GraphColourMethod`].
+        #[serde(default)]
+        graph_colouring: GraphColourMethod,
+        /// Configurations for CXs upon decompose phase gadgets.
+        #[serde(default)]
+        cx_config: CXConfigType,
+    },
     /// An operation capable of representing arbitrary Circuits made up of CNOT
     /// and RZ, as a PhasePolynomial plus a boolean matrix representing an
     /// additional linear transformation.
     PhasePolyBox {
         id: BoxID,
         /// Number of qubits.
         n_qubits: u32,
+        /// Map from qubits to inputs.
         qubit_indices: Vec<(Register, u32)>,
+        /// The phase polynomial definition.
+        /// Represented by a map from bitstring to expression of coefficient.
+        phase_polynomial: Vec<Vec<(Bitstring, String)>>,
+        ///
+        linear_transformation: Matrix,
     },
     /// A user-defined assertion specified by a list of Pauli stabilisers.
     StabiliserAssertionBox {
         id: BoxID,
         stabilisers: Vec<PauliStabiliser>,
     },
     /// A user-defined assertion specified by a 2x2, 4x4, or 8x8 projector matrix.
-    ProjectorAssertionBox {
-        id: BoxID,
-        matrix: Vec<Vec<(f32, f32)>>,
-    },
-    /// A user-defined gate defined by a parametrized Circuit.
-    Composite {
+    ProjectorAssertionBox { id: BoxID, matrix: Matrix },
+    /// A user-defined gate defined by a parametrised Circuit.
+    CustomGate {
         id: BoxID,
+        /// The gate defined as a circuit.
         gate: CompositeGate,
         // Vec of Symengine Expr
         params: Vec<String>,
@@ -126,25 +154,37 @@ pub enum OpBox {
         n_o: u32,
         exp: ClassicalExp,
     },
+    /// Binary matrix form of a stabilizer tableau for unitary Clifford circuits.
+    UnitaryTableauBox {
+        id: BoxID,
+        /// The tableau.
+        tab: UnitaryTableau,
+    },
     /// A user-defined multiplexor specified by a map from bitstrings to Operations.
     MultiplexorBox {
         id: BoxID,
-        op_map: Vec<(Vec<bool>, Operation)>,
+        op_map: Vec<(Bitstring, Operation)>,
     },
     /// A user-defined multiplexed rotation gate specified by a map from
     /// bitstrings to Operations.
     MultiplexedRotationBox {
         id: BoxID,
-        op_map: Vec<(Vec<bool>, Operation)>,
+        op_map: Vec<(Bitstring, Operation)>,
     },
     /// A user-defined multiplexed rotation gate specified by a map from
     /// bitstrings to Operations.
     MultiplexedU2Box {
         id: BoxID,
-        op_map: Vec<(Vec<bool>, Operation)>,
-        #[serde(default = "default_impl_diag")]
+        op_map: Vec<(Bitstring, Operation)>,
+        #[serde(default = "default_true")]
         impl_diag: bool,
     },
+    /// A user-defined multiplexed tensor product of U2 gates specified by a map
+    /// from bitstrings to lists of Op or a list of bitstring-list(Op s) pairs.
+    MultiplexedTensoredU2Box {
+        id: BoxID,
+        op_map: Vec<(Bitstring, Operation)>,
+    },
     /// An operation that constructs a circuit to implement the specified
     /// permutation of classical basis states.
     ToffoliBox {
@@ -160,9 +200,55 @@ pub enum OpBox {
         #[serde(default)]
         rotation_axis: Option<OpType>,
     },
+    /// An operation composed of ‘action’, ‘compute’ and ‘uncompute’ circuits
+    ConjugationBox {
+        id: BoxID,
+        /// Reversible computation.
+        compute: Box<Operation>,
+        /// Internal operation to be applied.
+        action: Box<Operation>,
+        /// Reverse uncomputation.
+        #[serde(default)]
+        uncompute: Option<Box<Operation>>,
+    },
+    /// A placeholder operation that holds resource data. This box type cannot
+    /// be decomposed into a circuit. It only serves to record resource data for
+    /// a region of a circuit: for example, upper and lower bounds on gate
+    /// counts and depth. A circuit containing such a box cannot be executed.
+    DummyBox {
+        id: BoxID,
+        /// Number of qubits.
+        n_qubits: u32,
+        /// Number of bits.
+        n_bits: u32,
+        /// Dummy resource data.
+        resource_data: ResourceData,
+    },
+    /// A box for preparing quantum states using multiplexed-Ry and multiplexed-Rz gates.
+    StatePreparationBox {
+        id: BoxID,
+        /// Normalised statevector of complex numbers
+        statevector: Matrix,
+        /// Whether to implement the dagger of the state preparation circuit, default to false.
+        #[serde(default)]
+        is_inverse: bool,
+        /// Whether to explicitly set the state to zero initially (by default
+        /// the initial zero state is assumed and no explicit reset is applied).
+        #[serde(default)]
+        with_initial_reset: bool,
+    },
+    /// A box for synthesising a diagonal unitary matrix into a sequence of multiplexed-Rz gates.
+    DiagonalBox {
+        id: BoxID,
+        /// Diagonal entries.
+        diagonal: Matrix,
+        /// Indicates whether the multiplexed-Rz gates take the shape of an upper triangle or a lower triangle. Default to true.
+        #[serde(default = "default_true")]
+        upper_triangle: bool,
+    },
 }
 
-fn default_impl_diag() -> bool {
+fn default_true() -> bool {
     true
 }
 
@@ -176,10 +262,119 @@ pub enum ToffoliBoxSynthStrat {
     Cycle,
 }
 
+/// Strategies for synthesising PauliBoxes.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
+#[non_exhaustive]
+pub enum PauliSynthStrat {
+    /// Synthesise gadgets individually.
+    Individual,
+    /// Synthesise gadgets using an efficient pairwise strategy from Cowtan et
+    /// al <https://arxiv.org/abs/1906.01734>.
+    Pairwise,
+    /// Synthesise gadgets in commuting sets.
+    #[default]
+    Sets,
+}
+
+/// Strategies for partitioning Pauli tensors.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
+#[non_exhaustive]
+pub enum PauliPartitionStrat {
+    /// Build sets of Pauli tensors in which each qubit has the same Pauli or
+    /// Pauli.I. Requires no additional CX gates for diagonalisation.
+    NonConflictingSets,
+    /// Build sets of mutually commuting Pauli tensors. Requires O(n^2) CX gates to diagonalise.
+    #[default]
+    CommutingSets,
+}
+
+/// Available methods to perform graph colouring.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
+#[non_exhaustive]
+pub enum GraphColourMethod {
+    /// Does not build the graph before performing the colouring; partitions
+    /// while iterating through the Pauli tensors in the input order.
+    #[default]
+    Lazy,
+    /// Builds the graph and then greedily colours by iterating through the
+    /// vertices, with the highest degree first.
+    LargestFirst,
+    /// Builds the graph and then systematically checks all possibilities until
+    /// it finds a colouring with the minimum possible number of colours. Such
+    /// colourings need not be unique. Exponential time in the worst case, but
+    /// often runs much faster.
+    Exhaustive,
+}
+
+/// Available configurations for CXs upon decompose phase gadgets
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
+#[non_exhaustive]
+pub enum CXConfigType {
+    /// Linear nearest neighbour CX sequence. Linear depth.
+    Snake,
+    /// Every CX has same target, linear depth, good for gate cancellation.
+    Star,
+    /// Balanced tree: logarithmic depth, harder to route.
+    #[default]
+    Tree,
+    /// Support for multi-qubit architectures, decomposing to 3-qubit XXPhase3
+    /// gates instead of CXs where possible.
+    MultiQGate,
+}
+
 /// A simple struct for Pauli strings with +/- phase, used to represent Pauli
 /// strings in a stabiliser subgroup.
 #[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PauliStabiliser {
     coeff: bool,
     string: Vec<String>,
 }
+
+/// An object holding resource data for use in a [`OpType::DummyBox`].
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq)]
+pub struct ResourceData {
+    /// Dictionary of counts of selected [`OpType`]s.
+    pub op_type_count: HashMap<OpType, ResourceBounds>,
+    /// Overall gate depth.
+    pub gate_depth: ResourceBounds,
+    /// Dictionary of depths of selected [`OpType`]s.
+    pub op_type_depth: HashMap<OpType, ResourceBounds>,
+    /// Overall two-qubit-gate depth.
+    pub two_qubit_gate_depth: ResourceBounds,
+}
+
+/// Structure holding a minimum and maximum value of some resource, where both
+/// values are unsigned integers.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq)]
+pub struct ResourceBounds {
+    /// Minimum value.
+    pub min: u32,
+    /// Maximum value.
+    pub max: u32,
+}
+
+/// Binary matrix form of a stabilizer tableau for unitary Clifford circuits.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct UnitaryTableau {
+    /// A symplectic tableau.
+    pub tab: SymplecticTableau,
+    /// Ordered naming of qubits in the tableau.
+    pub qubits: Vec<Register>,
+}
+
+/// Binary matrix form of a collection of Pauli strings.
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct SymplecticTableau {
+    /// Number of rows in the tableau.
+    #[serde(default)]
+    pub nrows: u32,
+    /// Number of columns in the tableau.
+    #[serde(default)]
+    pub nqubits: u32,
+    /// The X matrix.
+    pub xmat: Matrix<bool>,
+    /// The Z matrix.
+    pub zmat: Matrix<bool>,
+    /// The phase matrix.
+    pub phase: Matrix<bool>,
+}