# chys1203/fan_atpg architecture

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

- Interactive diagram: https://gitdiagram.com/chys1203/fan_atpg
- Repository: https://github.com/chys1203/fan_atpg

## Overview

##### Project type and purpose
- This is a command-line, open-source tool for Automatic Test Pattern Generation (ATPG) and Fault Simulation on benchmark circuits (FAN_ATPG).
- It implements Fujiwara-Shimono’s fan-out-oriented ATPG algorithm plus fault collapsing, parallel fault simulation, static/dynamic compression, and pattern conversion (STIL, ASCII, .pat).

##### File structure
- Top-level build:
- Makefile, common.mk, info.mk, rule.mk, copyHeader.sh → drive compilation and header copying.
- Binaries & libraries:
- bin/opt/ → compiled executables (“fan”)
- lib/opt/ → compiled libraries (.a, .so)
- Headers & sources:
- / ← collection of all public headers
- pkg/ → 4 main packages:
– common/ → CLI support, command parsing, console utilities
– core/   → ATPG algorithm, fault simulator, decision trees, logic, patterns
– interface/ → parsers and builders for netlist, pattern files (LEX/YACC), SDF, STIL, techlib, Verilog
– fan/    → “main” entry point, CLI commands mapping to core
- Data & assets:
- mod_netlist/, netlist/ → benchmark Verilog netlists
- techlib/ → cell libraries (Nangate)
- pat/ → generated test patterns (.pat, .stil)
- rpt/ → reports (per-circuit ATPG/fault-sim results)
- script/ → bash scripts to orchestrate runs
- utility/ → Python scripts for STIL↔.pat conversion

##### Core components and interactions
- User invokes “fan” executable via script or CLI
→ common: parse flags, scripts (.script)
→ interface: read benchmark netlist + techlib + prior pattern files
→ core: perform fault collapsing, ATPG loops, fault simulation, test compression
→ interface: serialize output patterns in requested formats (ASCII, STIL, .pat)
→ core/util: generate coverage reports → rpt/
→ filesystem: store patterns in pat/, reports in rpt/

##### Architectural patterns & design principles
- Modular layering:
- CLI layer (common + fan)
- Parser/IO layer (interface)
- Algorithmic engine (core)
- Utilities & conversion (utility)
- Separation of concerns: parsing vs. algorithm vs. user-facing entry point.
- Use of build automation (Makefiles at root and per-pkg) for reproducible binaries & libraries.
- Data-driven workflows: scripts drive the sequence of reads (netlist) → compute (core) → writes (pat/rpt).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Script Orchestrator
    Script["Script Orchestrator\n(script/)"]:::script
    click Script "https://github.com/chys1203/fan_atpg/tree/main/script/"

    %% CLI Layer
    subgraph "CLI Layer"
        FanExec["fan executable\n(bin/opt/)"]:::cli
        click FanExec "https://github.com/chys1203/fan_atpg/tree/main/bin/opt/"
        MainCPP["main.cpp\n(pkg/fan/src/main.cpp)"]:::cli
        click MainCPP "https://github.com/chys1203/fan_atpg/blob/main/pkg/fan/src/main.cpp"
        CommonInclude["include/common/"]:::cli
        click CommonInclude "https://github.com/chys1203/fan_atpg/tree/main/include/common/"
        CommonSrc["pkg/common/src/"]:::cli
        click CommonSrc "https://github.com/chys1203/fan_atpg/tree/main/pkg/common/src/"
        FanInclude["include/fan/"]:::cli
        click FanInclude "https://github.com/chys1203/fan_atpg/tree/main/include/fan/"
        FanPkgSrc["pkg/fan/src/"]:::cli
        click FanPkgSrc "https://github.com/chys1203/fan_atpg/tree/main/pkg/fan/src/"
    end

    Script -->|invokes| FanExec
    FanExec -->|calls| MainCPP
    MainCPP -->|uses| CommonSrc
    MainCPP -->|includes| CommonInclude
    MainCPP -->|includes| FanInclude
    MainCPP -->|uses| FanPkgSrc

    %% Parser/IO Layer
    subgraph "Parser/IO Layer"
        InterfaceInclude["include/interface/"]:::interface
        click InterfaceInclude "https://github.com/chys1203/fan_atpg/tree/main/include/interface/"
        InterfaceSrc["pkg/interface/src/"]:::interface
        click InterfaceSrc "https://github.com/chys1203/fan_atpg/tree/main/pkg/interface/src/"
    end

    MainCPP -->|read netlists| InterfaceSrc
    InterfaceSrc -->|headers| InterfaceInclude

    %% Core Algorithm Engine
    subgraph "Core Engine"
        CoreInclude["include/core/"]:::core
        click CoreInclude "https://github.com/chys1203/fan_atpg/tree/main/include/core/"
        CoreSrc["pkg/core/src/"]:::core
        click CoreSrc "https://github.com/chys1203/fan_atpg/tree/main/pkg/core/src/"
    end

    InterfaceSrc -->|parsed data| CoreSrc
    CoreSrc -->|algorithms| CoreInclude

    %% Output through Interface
    CoreSrc -->|generate patterns/reports| InterfaceSrc
    InterfaceSrc -->|write patterns| Patterns
    InterfaceSrc -->|write reports| Reports

    %% Utility Converters
    subgraph "Utilities"
        PatConvert1["pat2stil.py"]:::util
        click PatConvert1 "https://github.com/chys1203/fan_atpg/blob/main/utility/patConvert/pat2stil.py"
        PatConvert2["stil2pat.py"]:::util
        click PatConvert2 "https://github.com/chys1203/fan_atpg/blob/main/utility/patConvert/stil2pat.py"
    end

    InterfaceSrc -->|STIL conversion| PatConvert1
    PatConvert1 -->|converted| PatConvert2

    %% Data Stores
    subgraph "Data Stores"
        Netlist["Benchmark Netlists\n(netlist/, mod_netlist/)"]:::data
        click Netlist "https://github.com/chys1203/fan_atpg/tree/main/netlist/"
        click Netlist "https://github.com/chys1203/fan_atpg/tree/main/mod_netlist/"
        Techlib["Technology Library\n(techlib/)"]:::data
        click Techlib "https://github.com/chys1203/fan_atpg/tree/main/techlib/"
        Patterns["Pattern Output\n(pat/)"]:::data
        click Patterns "https://github.com/chys1203/fan_atpg/tree/main/pat/"
        Reports["Reports Output\n(rpt/)"]:::data
        click Reports "https://github.com/chys1203/fan_atpg/tree/main/rpt/"
    end

    InterfaceSrc -->|read .v files| Netlist
    InterfaceSrc -->|read techlib| Techlib
    Patterns --> Reports

    %% Styling
    classDef cli fill:#add8e6,stroke:#333,stroke-width:1px
    classDef interface fill:#90ee90,stroke:#333,stroke-width:1px
    classDef core fill:#ffa500,stroke:#333,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef util fill:#ffff99,stroke:#333,stroke-width:1px
    classDef script fill:#ffffe0,stroke:#333,stroke-width:1px
```
