From 9a05b404b507a4d19c0143a7d5d7e49ab9c1d2c2 Mon Sep 17 00:00:00 2001
From: Ayman El Amrani <ayman.elamrani99@gmail.com>
Date: Sun, 14 Sep 2025 12:04:36 +0100
Subject: [PATCH] update README

---
 README.md | 154 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 129 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 17dbd169..658c0369 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,159 @@
-# SYN
+# SynIR
+
+## Contents
+- [1) What is SynIR?](#what-is-synir?)
+- [2) Getting Started](#getting-started)
+    - [Installing SynPy](#installing-synpy)
+    - [Installing SynIR](#installing-synir)
+    - [Setting Up Jupyter](#setting-up-jupyter)
+- [3) Data Structures](#data-structures)
+    - [Pauli Letter](#pauli-letter)
+    - [Pauli String](#pauli-string)
+    - [Pauli Polynomial](#pauli-polynomial)
+    - [Pauli Exponential](#pauli-exponential)
+    - [Clifford Tableau](#clifford-tableau)
+- [4) Algorithms](#algorithms)
+    - [WIP]()
+
+---
+
+## What is SynIR?
+WIP
+
+## Getting Started
+
+### Installing SynPy
+
+1. Install `pyenv` and `pyenv-virtualenv`
+```bash
+brew install pyenv pyenv-virtualenv
+```
 
+2. Run the `python_setup` script. This will create a virtualenv environment
+```bash
+make python_setup
+```
 
+3. Run the `python_project_setup` script. This will install required dependencies from `requirements.txt`
+```bash
+make python_project_setup
+```
 
-## Installation
+4. Add the following line to your `.zshrc` to enable `pyenv-virtualenv` to automatically activate the environment when in the project directory
+```zsh
+eval "$(pyenv init -)"
+eval "$(pyenv virtualenv-init -)"
+```
 
-### Python
+### Installing SynIR
 
-We currently use python for pre-commit hooks. We herefore have a pyenv setup, after having pyenv and pyenv-virtualenv installed, simply run:
+1. Install [rust (recommended)](https://www.rust-lang.org/tools/install)
+2. Run set-up scripts
 
+```bash
+make rust_project_setup
 ```
-make python_setup
+
+3. Build the project
+```bash
+make build
 ```
 
-and
+4. Run tests
+```bash
+make test
+```
 
+5. Format check
+```bash
+make format-check
 ```
-make python_project_setup
+6. Clean
+```bash
+make clean
 ```
 
-### Rust
+### Setting up Jupyter
 
-This project requires [rust](), please follow the guidelines for installation.
+1. Install Jupyter
+```bash
+pip install jupyter
+```
 
-To run the basic rust setup, run:
+2. Install the rust kernel for Jupyter provided by [excxr](https://github.com/evcxr/evcxr)
+```bash
+cargo install evcxr_jupyter
+```
 
+3. Register the kernel with Jupyter
+```bash
+evcxr_jupyter --install
 ```
-make rust_project_setup
+
+4. Start a Jupyter Notebook. When creating a new notebook, choose rust as the kernel
+```bash
+jupyter notebook
 ```
 
-Build the project:
+## Data Structures
 
-```
-make build
-```
+### Pauli Letter
+The `PauliLetter` data structure is the letter by which we refer to any of the four Pauli matrices: $X$, $Y$, $Z$, and $I$.
 
-Run tests:
+### Pauli String
 
-```
-make test
+A PauliString is a sequence of Pauli Letters representing the tensor product of the respective Pauli matrices. The `PaulString` data structure is defined as follows:
+```rust
+pub struct PauliString {
+    pub(super) x: RwLock<BitVec>,
+    pub(super) z: RwLock<BitVec>,
+}
 ```
 
-Format-Check:
+Here, the Pauli String `"XYZ"` is represented by the two thread-safe bitvectors, `x = [1, 1, 0]` and `z = [0, 1, 1]`. This encoding follows the binary symplectic representation. In this scheme, each position in the string is determined by a pair of bits `(xᵢ, zᵢ)`:
+- `(0, 0)` → Identity
+- `(1, 0)` → Pauli-X
+- `(0, 1)` → Pauli-Z
+- `(1, 1)` → Pauli-Y
 
-```
-make format-check
+This representation allows for fast bit-level operations and efficient Clifford updates.
+
+### Pauli Polynomial
+
+The Pauli Polynomial is the subsequence of Pauli Strings in the Pauli Exponential that we assume to be mutually commuting. An example of this is the Phase Polynomial, which is a Pauli Polynomial consisting only of $I$ and $Z$ Pauli Letters.
+
+The naming scheme is analogous to the Phase Polynomial. Similarly, a polynomial contains a sum of terms and since the sum of matrices is commutative, the terms in the Pauli Polynomial should also commute.
+
+The `PauliPolynomial` data structure is defined as follows:
+```rust
+pub struct PauliPolynomial {
+    chains: Vec<PauliString>,
+    angles: RwLock<Vec<Angle>>,
+    size: usize,
+}
 ```
 
-(You can run format and check individually)
+### Pauli Exponential
 
-Clean:
+The Pauli Exponential is the universal representation that we use in the library. It contains a Clifford Tableau and a sequence of Pauli Polynomials. An exponential is a product and since the product of matrices is not commutative, the sequences in the Pauli Exponential do not commute.
 
+The `PauliExponential` data structure is defined as follows:
+```rust
+pub struct PauliExponential {
+    pauli_polynomials: VecDeque<PauliPolynomial>,
+    clifford_tableau: CliffordTableau,
+}
 ```
-make clean
-```
\ No newline at end of file
+
+### Clifford Tableau
+
+The `CliffordTableau` data structure is defined as follows
+```rust
+pub struct CliffordTableau {
+    pauli_columns: Vec<PauliString>,
+    signs: BitVec,
+}
+```
+
+## Algorithms
+WIP
\ No newline at end of file