# Fault Simulation

PPSFP (Parallel-Pattern Single-Fault Propagation) style fault simulators and other utility functions for use in various projects.
These fault simulators are meant to be correct (ensured by unit-tests) and reasonably fast.

Fault simulation has $O(n^3)$ complexity. Every *fault* is simulated with every *pattern* involving every combinational *gate* in the circuit. We measure performance in terms of `gates * faults * patterns / second`. How fast can we make it?

## Quick Start

This project has submodules. To ensure everything is up-to-date, run
```
git submodule update --init --recursive
```
after `git clone`, `git pull` or `git checkout`.

This project manages reproducible programming environments with:
- [uv](https://docs.astral.sh/uv/) for managing python environments.
- [nix](https://nixos.org) for managing non-python tools and benchmark designs. Follow [this guide](https://librelane.readthedocs.io/en/stable/installation/nix_installation/index.html) or [this guide](https://github.com/fossi-foundation/nix-eda/blob/main/docs/installation.md) to setup [nix-eda](https://github.com/fossi-foundation/nix-eda/tree/main) binary cache to avoid re-building EDA-related tools.

Run all unit-tests: `uv run pytest`

Run a naive, baseline fault simulation with 1024 random patterns: `uv run main.py tests/c6288.bench`

Same on an 18k-gate circuit: `uv run main.py polito-itc99-b15-sky130`

`nix develop` makes [quaigh](https://github.com/coloquinte/quaigh) available, another simulator/atpg written in rust.

To run Jupyter Notebooks in the reproducible programming environment, install a kernelspec:
```
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --env PATH ${PATH} --name=uv-env
```
Run a Jupyter Lab server locally:
```
uv run jupyter lab
```
Choose `uv-env` as kernel in Jupyter Lab.


## Performance Statistics

Numbers are given in `gfs/s` = `gates * faults * patterns / second`.

Single-core `SAFSimSimple` on 1024 patterns (baseline):

| OS, CPU, RAM | `tests/c6288.bench` | `polito-itc99-b15-sky130` |
|--------------|---------------------|---------------------------|
|            | **2.4k gates, 7.7k SAF** | **17k gates, 24k SAF** |
| MacOS, M3 Max, 32GiB (Stefan)         | 1.52G | 1.97G |
| WSL, i7-14650HX, 15GiB (Zhang)        | 1.68G | 2.03G |
| Ubuntu, Xeon E5-1650, 251GiB (Nosaka) | 0.94G | 1.18G |
| WSL2, i5-8250U, 8GiB (Kawachi)        | 0.82G | 0.94G |
| GH Codespace, EPYC 7763  (Kelvin)     | 1.03G | ?     |
| Ubuntu, i5-8265U, 8GiB (Kelvin)       | 0.77G | ?     |

Single-core `SAFSimIncremental` on 1024 patterns:

| OS, CPU, RAM | `tests/c6288.bench` | `polito-itc99-b15-sky130` |
|--------------|---------------------|---------------------------|
|            | **2.4k gates, 7.7k SAF** | **17k gates, 24k SAF** |
| MacOS, M3 Max, 32GiB (Stefan)         | 2.83G | 7.71G |
| WSL, i7-14650HX, 15GiB (Zhang)        | ?     | ?     |
| Ubuntu, Xeon E5-1650, 251GiB (Nosaka) | ?     | ?     |
| WSL2, i5-8250U, 8GiB (Kawachi)        | 1.98G | 4.74G |
| GH Codespace, EPYC 7763  (Kelvin)     | ?     | ?     |
| Ubuntu, i5-8265U, 8GiB (Kelvin)       | ?     | ?     |

Single-core `SAFSimPPSFP` on 1024 patterns:

| OS, CPU, RAM | `tests/c6288.bench` | `polito-itc99-b15-sky130` |
|--------------|---------------------|---------------------------|
|            | **2.4k gates, 7.7k SAF** | **17k gates, 24k SAF** |
| MacOS, M3 Max, 32GiB (Stefan)         | 14.7G | 77.0G |
| WSL, i7-14650HX, 15GiB (Zhang)        | ?     | ?     |
| Ubuntu, Xeon E5-1650, 251GiB (Nosaka) | ?     | ?     |
| WSL2, i5-8250U, 8GiB (Kawachi)        | 7.33G | 38.1G |
| GH Codespace, EPYC 7763  (Kelvin)     | ?     | ?     |
| Ubuntu, i5-8265U, 8GiB (Kelvin)       | ?     | ?     |

## Notes

```
Common Fault Classes:
DT - Detected
DS - Detected By Simulation
DI - Detected By Implication
PT - Possibly detected
UD - Undetectable
UB - Undetectable - blocked
UR - Undetectable - redundant
AU - ATPG untestable
AN - ATPG untestable - not detected
ND - Not detected
NO - Not detected - not observed
```