# pyhdi/pyverilog architecture

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

- Interactive diagram: https://gitdiagram.com/pyhdi/pyverilog
- Repository: https://github.com/pyhdi/pyverilog

## Overview

##### Project Type and Purpose
- Pyverilog is an open-source, Python-based hardware design processing toolkit for Verilog HDL.
- It provides four core capabilities:
1. vparser (code parser → AST)
2. dataflow analyzer (data-dependency analysis and optimization)
3. controlflow analyzer (state-machine and activation condition analysis)
4. AST code generator (turn AST back into Verilog)

##### File-Structure Analysis
- Top-level directories:
- pyverilog/              ← main library package
– vparser/              ← AST definitions, lexer, parser, preprocessor
– dataflow/             ← data-flow analysis modules (bindvisitor, optimizer, graphgen, etc.)
– controlflow/          ← control-flow analysis modules (active analyzer, state transition, etc.)
– ast_code_generator/   ← Jinja2-based codegen templates and driver
– utils/                ← shared helpers (scope, inference, identifier replacement, etc.)
- examples/               ← sample scripts demonstrating each capability
- scripts/                ← CI/test/deploy helper scripts (test-python2/3, upload_pypi)
- tests/                  ← pytest integration and unit tests organized per feature
- verilogcode/            ← Verilog snippets used by tests
- setup.py & Makefile     ← installation and build instructions

##### README Highlights
- Lists toolkit features, dependencies (Python3, PLY, Jinja2, Graphviz), and usage patterns.
- Describes CLI examples for parser, dataflow, controlflow, graphgen, and codegen.

##### Diagramming the Architecture
- Input Layer
– Verilog source files (user HDL code)
– Configuration (CLI flags, parameters)
- Parser Layer (pyverilog.vparser)
– Preprocessor → Lexer → Parser → AST generator
- Analysis Layer
– Dataflow Analyzer (pyverilog.dataflow)
– Controlflow Analyzer (pyverilog.controlflow)
– Utilities (pyverilog.utils) shared by both
- Code Generation Layer (pyverilog.ast_code_generator)
- Graph Generation (examples/graphgen ↔ Graphviz via Pygraphviz)
- CLI/Script Layer (examples/*.py, scripts/*.sh)
- Packaging & Testing
– setup.py, Makefile
– tests/ (pytest harness)
- External Dependencies
– PLY, Jinja2, Graphviz (optional), Pygraphviz, Icarus Verilog, pytest

– Verilog source → Parser → AST
– AST → Dataflow Analyzer → dataflow graph
– AST → Controlflow Analyzer → state-machine graph
– AST → Code Generator → new Verilog output
– Analysis modules call shared utils → transformations
– Graph modules call Graphviz/Pygraphviz → PNG/SVG outputs
– CLI scripts invoke library modules → produce console/graph outputs

c. Architectural Patterns & Principles
– Modular package per feature (parser, analysis, codegen)
– Clear separation: AST is the common IR for all analyses and codegen
– Use of templates (Jinja2) for code generation → decoupled from logic

d. Key Technologies & Frameworks
– Python3 (≥3.7)
– PLY (lex/yacc) for parser
– Jinja2 for codegen templates
– Graphviz + Pygraphviz for visualization
– pytest for tests
– Icarus Verilog for HDL simulation (optional)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input/Output Layer
    VerilogFiles(("Verilog Source (.v)")):::inputOutput
    Config(("CLI Config")):::inputOutput

    %% Parser Layer
    subgraph "Parser Layer"
        direction TB
        Preprocessor["Preprocessor"]:::core
        Lexer["Lexer"]:::core
        ParserModule["Parser"]:::core
        ASTGen["AST Generator"]:::core
    end

    %% IR Artifact
    AST(("AST")):::util

    %% Analysis Layer
    subgraph "Analysis Layer"
        direction TB
        DataflowAnalyzer["Dataflow Analyzer"]:::core
        ControlflowAnalyzer["Controlflow Analyzer"]:::core
        Utils["Shared Utilities"]:::util
    end

    DataflowGraph(("Dataflow Graph")):::inputOutput
    ControlflowGraph(("Controlflow Graph")):::inputOutput

    %% Code Generation Layer
    subgraph "Code Generation Layer"
        direction TB
        CodeGenerator["AST Code Generator"]:::core
        NewVerilog(("Generated Verilog")):::inputOutput
    end

    %% Graph Generation
    GraphGenModule["Graph Generation (Pygraphviz)"]:::core
    GraphOutput(("PNG/SVG Outputs")):::inputOutput

    %% CLI and Scripts
    subgraph "CLI & Scripts"
        direction TB
        Examples["Example Scripts"]:::core
        Scripts["CI/Test/Deploy Scripts"]:::core
    end

    %% Packaging & Testing
    subgraph "Packaging & Testing"
        direction TB
        Packaging["setup.py & Makefile"]:::core
        Tests["pytest Harness"]:::core
        VerilogTests(("Verilog Test Inputs")):::inputOutput
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PLY["PLY"]:::external
        Jinja2["Jinja2"]:::external
        Graphviz["Graphviz"]:::external
        Pygraphviz["Pygraphviz"]:::external
        Pytest["pytest"]:::external
        Icarus["Icarus Verilog"]:::external
    end

    %% Data Flows
    VerilogFiles -->|".v files"| Preprocessor
    Config --> Preprocessor

    Preprocessor --> Lexer
    Lexer --> ParserModule
    ParserModule --> ASTGen
    ASTGen --> AST

    AST --> DataflowAnalyzer
    AST --> ControlflowAnalyzer
    AST --> CodeGenerator

    DataflowAnalyzer --> Utils
    ControlflowAnalyzer --> Utils

    DataflowAnalyzer --> DataflowGraph
    ControlflowAnalyzer --> ControlflowGraph

    DataflowGraph --> GraphGenModule
    ControlflowGraph --> GraphGenModule
    GraphGenModule --> GraphOutput

    CodeGenerator --> NewVerilog

    Examples --> Preprocessor
    Examples --> DataflowAnalyzer
    Examples --> ControlflowAnalyzer
    Examples --> GraphGenModule
    Examples --> CodeGenerator

    Scripts --> Preprocessor
    Scripts --> Tests
    Scripts --> Packaging

    Tests --> VerilogTests
    Tests --> Preprocessor
    Tests --> DataflowAnalyzer
    Tests --> CodeGenerator

    Packaging --> ASTGen

    %% External Calls
    Preprocessor -->|uses| PLY
    CodeGenerator -->|templates| Jinja2
    GraphGenModule -->|calls| Graphviz
    GraphGenModule -->|via| Pygraphviz
    Tests -->|run on| Pytest
    VerilogTests -->|validated by| Icarus

    %% Click Events
    click Preprocessor "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/vparser/preprocessor.py"
    click Lexer "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/vparser/lexer.py"
    click ParserModule "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/vparser/parser.py"
    click ASTGen "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/vparser/ast.py"
    click DataflowAnalyzer "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/dataflow/dataflow_analyzer.py"
    click bindvisitor "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/dataflow/bindvisitor.py"
    click optimizer "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/dataflow/optimizer.py"
    click graphgen "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/dataflow/graphgen.py"
    click dataflow "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/dataflow/dataflow.py"
    click ControlflowAnalyzer "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/controlflow/controlflow_analyzer.py"
    click active_analyzer "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/controlflow/active_analyzer.py"
    click active_range "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/controlflow/active_range.py"
    click splitter "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/controlflow/splitter.py"
    click transition "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/controlflow/transition.py"
    click CodeGenerator "https://github.com/pyhdi/pyverilog/blob/develop/pyverilog/ast_code_generator/codegen.py"
    click template "https://github.com/pyhdi/pyverilog/tree/develop/pyverilog/ast_code_generator/template/"
    click Utils "https://github.com/pyhdi/pyverilog/tree/develop/pyverilog/utils/"
    click Examples "https://github.com/pyhdi/pyverilog/tree/develop/examples/"
    click Scripts "https://github.com/pyhdi/pyverilog/tree/develop/scripts/"
    click Tests "https://github.com/pyhdi/pyverilog/tree/develop/tests/"
    click VerilogTests "https://github.com/pyhdi/pyverilog/tree/develop/verilogcode/"
    click Packaging "https://github.com/pyhdi/pyverilog/blob/develop/setup.py"

    %% Styles
    classDef inputOutput fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef util fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
