# maheshgouru/gpuverify-extended architecture

> Architecture diagram of the GitHub repository maheshgouru/gpuverify-extended, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maheshgouru/gpuverify-extended
- Repository: https://github.com/maheshgouru/gpuverify-extended

## Overview

##### Project Type and Purpose
- GPUVerify is a command‐line static analyser for GPU kernels (OpenCL/CUDA).
- It ingests kernel source, generates verification conditions (VCs), invokes Boogie+SMT solvers, then post‐processes results to report races or divergence issues.

##### File Structure
Top‐level components:
– CLI wrappers & orchestrators:
- GPUVerify.py / gpuverify (Python)
- gputester.py, GPUVerify.bat, gvfindtools.py, etc.
– Core analysis libraries & executables (all C#/.NET):
- VC generator: GPUVerifyVCGen/
- Boogie driver: GPUVerifyBoogieDriver/
- Interpreter (“cruncher”): GPUVerifyCruncher/
- Shared library: GPUVerifyLib/
– Python support modules: GPUVerifyScript/
– External tool binaries: BoogieBinaries/, plus CI scripts to download Z3/CVC4.
– Testsuite: testsuite/CUDA/, testsuite/OpenCL/
– Documentation, CI workflows (.github/workflows), utilities (utils/GPUVerifyRise4Fun/).

##### Key Architecture Insights from README
- Static analysis pipeline: source → VCGen → Boogie → SMT solvers → cruncher → report.
- Sphinx‐based documentation.
- CI integrates multi‐platform builds, solver downloads, and test execution.

##### Main Components
a. CLI Layer (Python)
– GPUVerify.py / gpuverify entry‐point
– Argument parser & JSON loader (GPUVerifyScript/)
b. Analysis Pipeline (C# .NET executables)
– VC Generator (GPUVerifyVCGen)
– Boogie Driver (GPUVerifyBoogieDriver)
– Cruncher / Interpreter (GPUVerifyCruncher)
– Shared analysis routines (GPUVerifyLib)
c. External Tools
– Boogie engine (BoogieBinaries)
– SMT solvers (Z3, CVC4, …)
d. Test Harness & Utilities
– Test runner (gputester.py) → invokes CLI
– Rise4Fun webservice (utils/GPUVerifyRise4Fun)

##### Relationships & Data Flows
- The CLI reads kernel source and flags → calls VCGen.exe → produces .bpl (Boogie) file
- BoogieDriver.exe invokes Boogie on .bpl → passes queries to SMT solvers → collects raw solver output
- Cruncher.exe interprets Boogie traces & error models → generates human‐readable reports / JSON
- GPUVerify.py assembles results, formats output, and returns exit codes.
- Testsuite scripts drive this CLI sequence for each test .cu/.cl file.
- CI workflows trigger builds, downloads solvers, runs tests, and publishes badges.

##### Architectural Patterns & Design Principles
- Modular pipeline: each stage is a separate executable / library.
- Language separation: Python for orchestration, C# for heavy analysis, external tools for solving.
- Plugin‐style extensibility: support for new SMT backends, new analysis rules in VCGen.
- Clear separation of concerns: parsing/configuration vs. VC generation vs. solving vs. post‐processing.

##### Technologies & Frameworks
- Python 3.x for CLI and scripting
- .NET Framework / .NET Core for C# executables (projects under *.csproj)
- Boogie verification framework
- SMT solvers: Z3, CVC4
- Sphinx for documentation
- GitHub Actions for CI

##### Essential Elements to Capture
– Clear component boundaries (CLI, VCGen, BoogieDriver, Cruncher, Solvers)
– Data flow for kernel → verification → report
– External dependencies (Boogie, Z3/CVC4)
– Language/runtime pivots (Python vs. .NET)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Test Harness & CI"
        gvtest["gvtester.py"]:::ci
        bat["GPUVerify.bat"]:::ci
        findtools["gvfindtools.py"]:::ci
        cicfg["build-and-test.yml"]:::ci
        downloadz3["download_and_symlink_z3.sh"]:::ci
        downloadcvc4["download_and_symlink_cvc4.sh"]:::ci
    end

    subgraph "CLI Layer (Python)"
        pycli["GPUVerify.py"]:::python
        wrapper["gpuverify"]:::python
        modules["GPUVerifyScript/*"]:::python
    end

    subgraph "C# Pipeline"
        subgraph "VC Generator"
            vcgenexe["VCGen.exe (GPUVerifyVCGen)"]:::csharp
        end
        subgraph "Boogie Driver"
            boogieexe["BoogieDriver.exe (GPUVerifyBoogieDriver)"]:::csharp
        end
        subgraph "Cruncher"
            cruncherexe["Cruncher.exe (GPUVerifyCruncher)"]:::csharp
        end
        subgraph "Shared Library"
            lib["GPUVerifyLib"]:::csharp
        end
    end

    subgraph "External Tools"
        boogiebin["BoogieBinaries"]:::external
        z3["Z3 Solver"]:::external
        cvc4["CVC4 Solver"]:::external
    end

    results["JSON Report / Exit Code"]:::external

    gvtest -->|invokes| wrapper
    bat -->|invokes| wrapper
    wrapper -->|"reads source (.cu/.cl)"| pycli
    pycli -->|"calls VCGen.exe"| vcgenexe
    vcgenexe -->|".bpl file"| boogieexe
    boogieexe -->|"invoke Boogie"| boogiebin
    boogieexe -->|"SMT queries"| z3
    boogieexe -->|"SMT queries"| cvc4
    z3 -->|"solver results"| boogieexe
    cvc4 -->|"solver results"| boogieexe
    boogieexe -->|"trace dump"| cruncherexe
    cruncherexe -->|"JSON report"| pycli
    pycli -->|"outputs"| results

    click gvtest "https://github.com/maheshgouru/gpuverify-extended/blob/master//gvtester.py"
    click findtools "https://github.com/maheshgouru/gpuverify-extended/blob/master//.github/workflows/gvfindtools.py"
    click bat "https://github.com/maheshgouru/gpuverify-extended/blob/master//GPUVerify.bat"
    click cicfg "https://github.com/maheshgouru/gpuverify-extended/blob/master//.github/workflows/build-and-test.yml"
    click downloadz3 "https://github.com/maheshgouru/gpuverify-extended/blob/master//.github/workflows/download_and_symlink_z3.sh"
    click downloadcvc4 "https://github.com/maheshgouru/gpuverify-extended/blob/master//.github/workflows/download_and_symlink_cvc4.sh"
    click pycli "https://github.com/maheshgouru/gpuverify-extended/blob/master//GPUVerify.py"
    click wrapper "https://github.com/maheshgouru/gpuverify-extended/tree/master//gpuverify"
    click modules "https://github.com/maheshgouru/gpuverify-extended/tree/master//GPUVerifyScript/"
    click vcgenexe "https://github.com/maheshgouru/gpuverify-extended/tree/master//GPUVerifyVCGen/"
    click boogieexe "https://github.com/maheshgouru/gpuverify-extended/blob/master//GPUVerifyBoogieDriver/GPUVerifyBoogieDriver.cs"
    click cruncherexe "https://github.com/maheshgouru/gpuverify-extended/blob/master//GPUVerifyCruncher/GPUVerifyCruncher.cs"
    click lib "https://github.com/maheshgouru/gpuverify-extended/tree/master//GPUVerifyLib/"

    classDef python fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef csharp fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef ci fill:#ffe0b3,stroke:#333,stroke-width:1px
```
