# simulation_acceleration - Fast Simulation

A tool layer for AI agents to quickly verify RTL/testbenches **before entering
Vivado**. It uses open-source simulators (Icarus / Verilator / cocotb) for
lightweight smoke verification and writes the results as compact AI evidence.

> This tool does **not** bundle a simulator. Install the open-source runtimes
> yourself, then run `check_fast_sim.ps1` to confirm.
>
> **A pure-Verilog testbench only needs Icarus (iverilog/vvp)**; no
> Python/cocotb required. cocotb is only needed for flows that use Python
> verification logic (note: cocotb 2.0.x supports up to **Python 3.13**, and
> cannot be installed on Python 3.14).

## Runtime Requirements (installed by the customer)

- **Icarus Verilog (iverilog / vvp)**: required (core simulator)
  https://bleyer.org/icarus/
- **Python 3.13** (only needed for cocotb flows): https://www.python.org/downloads/
  - cocotb: `python -m pip install cocotb` (needs Python 3.13)
  - Pure-Verilog flows can skip Python entirely
- Verilator (optional): https://www.verilator.org/
- C++ toolchain (optional, for Verilator C++): make + g++/clang

## Install Options (choose one)

> **The AI will not auto-launch a GUI install wizard.** When Icarus is missing,
> the AI will ask you to choose one of the three options below.

- **[A] Manual install**: download https://bleyer.org/icarus/, run the wizard,
  then tell the AI the install path (or have it re-run the check).
- **[B] Authorize the AI to install silently**: after your explicit consent the
  AI installs once via a non-GUI package manager:
  `winget install -e --id Icaros.iverilog` or `choco install iverilog`
- **[C] Already installed but not on PATH**: let the AI confirm with a given dir:
  `powershell -File tools\simulation_acceleration\scripts\check_fast_sim.ps1 -IverilogDir "C:\iverilog\bin"`

After any option, run `check_fast_sim.ps1` to verify; the AI records the actual
path in the manifest for later use.

## Usage

```powershell
# 1) Check runtimes (shows what is missing + install guide)
powershell -File tools\simulation_acceleration\scripts\check_fast_sim.ps1

# 2) Run the bundled counter example (Icarus + cocotb, needs Python 3.13)
powershell -File tools\simulation_acceleration\scripts\run_smoke_counter.ps1
```

For your own projects, run any simulation command with `run_with_evidence.py`
and record evidence (`--timeout` prevents a stuck testbench from hanging;
default 300 s, 0 = no limit):

```powershell
python tools\simulation_acceleration\scripts\run_with_evidence.py `
  --project-root <your project> --run-name <name> --tool cocotb_icarus `
  -- python <your sim entry.py>
```

Results go to `<project>\.vivado_ai_mcp\simulation\runs\<timestamp>_<name>\`:
`summary.json`, `failures.json`, `raw/stdout.log`, `raw/stderr.log`.

## Reference

- `scripts/check_fast_sim.ps1` - runtime detection
- `scripts/run_with_evidence.py` - simulation command to compact evidence
- `examples/counter_cocotb/` - minimal runnable example (RTL + cocotb testbench)
- `templates/sim_manifest.example.yaml` - example simulation manifest
- `docs/simulation_evidence.md` - evidence structure conventions
- `AGENT_SIM_WORKFLOW.md` - AI usage workflow

## Boundaries

- This is fast functional smoke verification, **not** a replacement for full
  Xilinx-integrated simulation (Vivado/xsim).
- Only RTL/testbench verification; does not produce bitstreams or timing.
