diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3160365
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# WRPLL simulation
+
+A time domain simulation for WRPLL
+
+## Installing dependencies
+
+### Nix:
+```bash
+nix develop
+```
+### Others:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+(venv) pip install -r requirements.txt
+```
+
+## Quick start
+- Three notebook examples are included 
+    1. `helper_PLL_example.ipynb` : helper PLL only
+    2. `main_PLL_example.ipynb` : main PLL only with a user specific helper frequency
+    3. `both_PLL_example.ipynb` : main and helper PLL
+
+- RAM usage and execution time estimate for simulation **ONLY**
+
+    1. 100,000,000 time steps: 6GiB RAM and 12 seconds 
+    
+    2. 200,000,000 time steps: 11GiB RAM and 20 seconds
+
+    3. 300,000,000 time steps: 16GiB RAM and 35 seconds
+
+
+<br>
+<details><summary><b>WRPLL formulas</b></summary>
+
+- Assume the difference between $f_{main}, f_{gtx}$ is very small
+
+    - Let $f_{in} = f_{main} = f_{gtx}$
+
+    - $f_{helper} = f_{in} * \dfrac{N-1}{N}$
+    
+    - $f_{beat} = f_{in} - f_{helper} =  \dfrac{f_{in}}{N}$
+
+- Main and helper Si549 DCXO **ADPLL** setting
+
+    - $ADPLL = \dfrac{\Delta f_{outppm}}{0.0001164}$
+
+</details><br>
+
+## Limitation
+As the simulation is not cycle nor delay accurate, there will be more glitches than the hardware implementation
+
+### Helper PLL glitches (remedies are added to follow hardware behavior) 
+
+- Cycle slipping issue will appear as $|\Delta{period}| \sim N$ 
+    - During hardware testing, slipping issue is not common 
+    - It's recommended to turn cycle_slip_comp ON to reduce slipping and have a more accurate simulation 
+
+![cycle_slip](img/cycle_slipping.png)
+
+
+- Deglitcher fail issue will appear as $|\Delta{period}| \sim N/2$ 
+    - There are no such issue for hardware
+    - It's recommended to set blind_period higher than the hardware setting (around 300 is sufficient)
+
+![deglitch_fail](img/deglitch_fail.png)
+
+
diff --git a/img/cycle_slipping.png b/img/cycle_slipping.png
new file mode 100644
index 0000000..426c8d2
Binary files /dev/null and b/img/cycle_slipping.png differ
diff --git a/img/deglitch_fail.png b/img/deglitch_fail.png
new file mode 100644
index 0000000..ed08641
Binary files /dev/null and b/img/deglitch_fail.png differ