From 25a690cdee5c51e1a15306f6a05017a0961a70ea Mon Sep 17 00:00:00 2001
From: Alec Edgington <alec.edgington@quantinuum.com>
Date: Wed, 15 Nov 2023 11:38:36 +0000
Subject: [PATCH 1/2] Port text deleted in
 https://github.com/CQCL/hugr/pull/694 .

---
 docs/quantum.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/quantum.md

diff --git a/docs/quantum.md b/docs/quantum.md
new file mode 100644
index 00000000..11bbf98f
--- /dev/null
+++ b/docs/quantum.md
@@ -0,0 +1,64 @@
+# Representation of quantum types in HUGR
+
+Besides a range of quantum operations (like Hadamard, CX, etc.)
+that take and return `Qubit`, we note the following operations for
+allocating/deallocating `Qubit`s:
+
+```
+qalloc: () -> Qubit
+qfree: Qubit -> ()
+```
+
+`qalloc` allocates a fresh, 0 state Qubit - if none is available at
+runtime it panics. `qfree` loses a handle to a Qubit (may be reallocated
+in future). The point at which an allocated qubit is reset may be
+target/compiler specific.
+
+Note there are also `measurez: Qubit -> (i1, Qubit)` and on supported
+targets `reset: Qubit -> Qubit` operations to measure or reset a qubit
+without losing a handle to it.
+
+## Dynamic vs static allocation
+
+With these operations the programmer/front-end can request dynamic qubit
+allocation, and the compiler can add/remove/move these operations to use
+more or fewer qubits. In some use cases, that may not be desirable, and
+we may instead want to guarantee only a certain number of qubits are
+used by the program. For this purpose TKET2 places additional
+constraints on the HUGR that are in line with TKET1 backwards
+compatibility:
+
+1. The `main` function takes one `Array<N, Qubit>`
+input and has one output of the same type (the same statically known
+size).
+2. All Operations that have a `FunctionType` involving `Qubit` have as
+ many `Qubit` input wires as output.
+
+
+With these constraints, we can treat all `Qubit` operations as returning all qubits they take
+in. The implicit bijection from input `Qubit` to output allows register
+allocation for all `Qubit` wires. 
+If further the program does not contain any `qalloc` or `qfree`
+operations we can state the program only uses `N` qubits.
+
+## Angles
+
+The "angle" extension defines a specialized `angle<N>` type which is used
+to express parameters of rotation gates. The type is parametrized by the
+_log-denominator_, which is an integer $N \in [0, 53]$; angles with
+log-denominator $N$ are multiples of $2 \pi / 2^N$, where the multiplier is an
+unsigned `int<N>` in the range $[0, 2^N]$. The maximum log-denominator $53$
+effectively gives the resolution of a `float64` value; but note that unlike
+`float64` all angle values are equatable and hashable; and two `angle<N>` that
+differ by a multiple of $2 \pi$ are _equal_.
+
+The following operations are defined:
+
+| Name           | Inputs     | Outputs    | Meaning |
+| -------------- | ---------- | ---------- | ------- |
+| `aconst<N, x>` | none       | `angle<N>` | const node producing angle $2 \pi x / 2^N$ (where $0 \leq x \lt 2^N$) |
+| `atrunc<M,N>`  | `angle<M>` | `angle<N>` | round `angle<M>` to `angle<N>`, where $M \geq N$, rounding down in $[0, 2\pi)$ if necessary |
+| `aconvert<M,N>`  | `angle<M>` | `Sum(angle<N>, ErrorType)` | convert `angle<M>` to `angle<N>`, returning an error if $M \gt N$ and exact conversion is impossible |
+| `aadd<M,N>`    | `angle<M>`, `angle<N>` | `angle<max(M,N)>` | add two angles |
+| `asub<M,N>`    | `angle<M>`, `angle<N>` | `angle<max(M,N)>` | subtract the second angle from the first |
+| `aneg<N>`      | `angle<N>` | `angle<N>` | negate an angle |

From 565fab0fb6f2a6528e7b2a9114b551f7579492c2 Mon Sep 17 00:00:00 2001
From: Alec Edgington <alec.edgington@quantinuum.com>
Date: Wed, 15 Nov 2023 12:05:57 +0000
Subject: [PATCH 2/2] Add reference to HUGR spec.

---
 docs/quantum.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/quantum.md b/docs/quantum.md
index 11bbf98f..d5dcade6 100644
--- a/docs/quantum.md
+++ b/docs/quantum.md
@@ -1,5 +1,10 @@
 # Representation of quantum types in HUGR
 
+TKET2 makes use of the
+[HUGR](https://github.com/CQCL/hugr/blob/main/specification/hugr.md)
+IR to represent programs. Here we describe how quantum operations (and
+the angles associated with some of them) are represented.
+
 Besides a range of quantum operations (like Hadamard, CX, etc.)
 that take and return `Qubit`, we note the following operations for
 allocating/deallocating `Qubit`s: