# 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)