# parallaxsw/opensta architecture

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

- Interactive diagram: https://gitdiagram.com/parallaxsw/opensta
- Repository: https://github.com/parallaxsw/opensta

## Overview

##### Project Type and Purpose
- Type: Native C++ static timing analysis engine with a TCL‐based CLI.
- Purpose: Read standard EDA file formats (Verilog, Liberty, SDC, SDF, SPEF, VCD/SAIF), build an internal netlist/timing graph, run delay calculations and path searches, and produce timing reports or Spice output.
- Key indicator: README describes “timing engine,” “TCL command interpreter,” input formats, and analysis features.

##### File Structure
- Top‐level build/CI: CMakeLists.txt, Dockerfiles, Jenkinsfiles.
- Core application: app/ (Main.cc, StaApp.i, StaMain.cc).
- Public API: include/sta/ *.hh, StaMain.hh, Sta.h.
- Modules by function:
– Verilog parser: verilog/
– Liberty reader: liberty/
– SDC constraints: sdc/
– SDF delay annotation: sdf/
– Parasitics (SPEF): parasitics/
– Power activities (VCD/SAIF): power/
– Delay calculators: dcalc/
– Graph utilities: graph/
– Network adapter: network/
– Search/path analysis: search/
– Spice export: spice/
– TCL extensions: tcl/
– Utilities: util/
- Examples, tests, docs live in examples/, test/, doc/.

##### README for Architecture Insights
- Uses a “network adapter” to integrate host netlist.
- Modular timing engine (“easily bolted on to other tools”).
- TCL layer for commands and scripting.
- External libraries: CUDD, Eigen, zlib, TCL, SWIG.

##### Main Components
a. External Inputs:
– Verilog netlist file
– Liberty library
– SDC constraints
– SDF delay annotation
– SPEF parasitics
– VCD/SAIF power activity
b. Parsers/Readers:
– verilog/ → internal netlist format
– liberty/ → timing model
– sdc/ → constraint graph
– sdf/ → annotated delays
– parasitics/ → RC parasitic data
– power/ → activity data
c. Core Data Structures:
– CircuitSim, Network, ConcreteNetwork, Parasitics, Corner, Path, TimingArc
– Stored in include/sta and util/ modules
d. Analysis Engines:
– DelayCalc variants (dcalc/)
– GraphTraversal (graph/)
– Search/Path enumeration (search/)
– Clock analysis, exception paths (sdc/)
– Spice export (spice/)
e. TCL Interpreter Layer:
– SWIG bindings (app/StaApp.i, *.tcl under tcl/)
– CLI commands under tcl/ and graph/*.tcl
f. Outputs:
– Timing reports (console, JSON)
– Annotated netlists (SDF, SPEF)
– Spice netlists (Spice, Xyce)
g. Build & CI:
– CMake, Dockerfiles, Jenkins pipelines
h. External Libraries:
– CUDD (BDD engine)
– Eigen (linear algebra)
– zlib (optional compression)
– TCL, SWIG, Flex/Bison

##### Relationships & Data Flows
- Parsers feed Core Data Structures
- Core Data Structures → Analysis Engines (delay, search)
- Analysis Engines → Outputs
- CLI (TCL interpreter) instantiates Engine, passes commands, loads inputs, triggers analyses, displays results
- Build/CI orchestrates compilation and testing

##### Architectural Patterns & Design Principles
- Modular, layered architecture (separate parser, core, analysis, CLI layers)
- Adapter pattern for “network adapter” to integrate external netlist
- Plugin‐style modules for each file format and analysis type
- Query‐based incremental updates (per README)
- SWIG bindings to expose C++ API into TCL

##### Essential Elements to Capture
- Module boundaries: e.g., verilog parser does not know about search modules.
- Data transformation flow: file → parse → internal graph → analysis → report.
- External dependencies (CUDD, Eigen, TCL) clearly.
- Build/CI context (Docker, Jenkins, CMake).

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% External Inputs
  subgraph "External Inputs" 
    direction TB
    VerilogFile["Verilog Netlist"]:::external
    LibertyFile["Liberty Library"]:::external
    SDCFile["SDC Constraints"]:::external
    SDFFile["SDF Annotations"]:::external
    SPEFFile["SPEF Parasitics"]:::external
    VCDFile["VCD/SAIF Activity"]:::external
  end

  %% Parser Modules
  subgraph "Parser/Reader Modules" 
    direction TB
    Verilog["verilog/"]:::parser
    Liberty["liberty/"]:::parser
    SDCReader["sdc/"]:::parser
    SDFReader["sdf/"]:::parser
    Parasitics["parasitics/"]:::parser
    Power["power/"]:::parser
  end

  %% Core Data Structures & Adapters
  subgraph "Core Engine & Data Structures"
    direction TB
    API["include/sta/"]:::core
    NetworkAdapter["network/"]:::core
    Utilities["util/"]:::core
  end

  %% Analysis Engines
  subgraph "Analysis Modules"
    direction TB
    DelayCalc["dcalc/"]:::analysis
    GraphUtil["graph/"]:::analysis
    SearchEngine["search/"]:::analysis
    SpiceExport["spice/"]:::analysis
  end

  %% CLI / Application
  subgraph "CLI Interface & Application"
    direction TB
    MainCC["Main.cc"]:::cli
    StaMainCC["StaMain.cc"]:::cli
    StaAppI["StaApp.i"]:::cli
    TclExt["tcl/"]:::cli
  end

  %% Outputs
  subgraph "Outputs"
    direction TB
    TimingReport["Timing Reports"]:::output
    AnnotatedNetlist["Annotated Netlists (SDF/SPEF)"]:::output
    SpiceNetlist["Spice Netlists"]:::output
  end

  %% Build & CI
  subgraph "Build & CI"
    direction TB
    CMake["CMake/CI Config"]:::build
  end

  %% External Libraries
  subgraph "External Libraries"
    direction TB
    CUDD["CUDD"]:::external
    Eigen["Eigen"]:::external
    Zlib["zlib"]:::external
    TCLLib["TCL"]:::external
    SWIG["SWIG"]:::external
  end

  %% Data Flows
  VerilogFile --> Verilog
  LibertyFile --> Liberty
  SDCFile --> SDCReader
  SDFFile --> SDFReader
  SPEFFile --> Parasitics
  VCDFile --> Power

  Verilog --> API
  Liberty --> API
  SDCReader --> API
  SDFReader --> API
  Parasitics --> API
  Power --> API

  API --> DelayCalc
  API --> GraphUtil
  API --> SearchEngine
  API --> SpiceExport
  NetworkAdapter --> API
  Utilities --> API

  DelayCalc --> TimingReport
  GraphUtil --> TimingReport
  SearchEngine --> TimingReport
  SpiceExport --> SpiceNetlist
  SpiceExport --> AnnotatedNetlist

  MainCC --> API
  StaMainCC --> API
  StaAppI --> API
  TclExt --> API
  MainCC --> DelayCalc
  MainCC --> GraphUtil
  MainCC --> SearchEngine
  MainCC --> SpiceExport

  MainCC --> TimingReport
  TclExt --> SearchEngine
  TclExt --> DelayCalc

  CMake --> MainCC
  CMake --> API
  CMake --> Verilog
  CMake --> Liberty
  CMake --> SDCReader
  CMake --> SDFReader
  CMake --> Parasitics
  CMake --> Power
  CMake --> DelayCalc
  CMake --> GraphUtil
  CMake --> SearchEngine
  CMake --> SpiceExport
  CMake --> TclExt

  CUDD -.-> SearchEngine
  Eigen -.-> DelayCalc
  Zlib -.-> API
  TCLLib -.-> TclExt
  SWIG -.-> TclExt

  %% Click Events
  click MainCC "https://github.com/parallaxsw/opensta/blob/master/app/Main.cc"
  click StaMainCC "https://github.com/parallaxsw/opensta/blob/master/app/StaMain.cc"
  click StaAppI "https://github.com/parallaxsw/opensta/blob/master/app/StaApp.i"
  click API "https://github.com/parallaxsw/opensta/tree/master/include/sta/"
  click Verilog "https://github.com/parallaxsw/opensta/tree/master/verilog/"
  click Liberty "https://github.com/parallaxsw/opensta/tree/master/liberty/"
  click SDCReader "https://github.com/parallaxsw/opensta/tree/master/sdc/"
  click SDFReader "https://github.com/parallaxsw/opensta/tree/master/sdf/"
  click Parasitics "https://github.com/parallaxsw/opensta/tree/master/parasitics/"
  click Power "https://github.com/parallaxsw/opensta/tree/master/power/"
  click NetworkAdapter "https://github.com/parallaxsw/opensta/tree/master/network/"
  click Utilities "https://github.com/parallaxsw/opensta/tree/master/util/"
  click DelayCalc "https://github.com/parallaxsw/opensta/tree/master/dcalc/"
  click GraphUtil "https://github.com/parallaxsw/opensta/tree/master/graph/"
  click SearchEngine "https://github.com/parallaxsw/opensta/tree/master/search/"
  click SpiceExport "https://github.com/parallaxsw/opensta/tree/master/spice/"
  click TclExt "https://github.com/parallaxsw/opensta/tree/master/tcl/"
  click CMake "https://github.com/parallaxsw/opensta/blob/master/CMakeLists.txt"

  %% Styles
  classDef external fill:#e0f7fa,stroke:#0288d1,color:#000
  classDef parser fill:#e8f5e9,stroke:#2e7d32,color:#000
  classDef core fill:#fff9c4,stroke:#f9a825,color:#000
  classDef analysis fill:#ffe0b2,stroke:#ef6c00,color:#000
  classDef cli fill:#f3e5f5,stroke:#8e24aa,color:#000
  classDef build fill:#eceff1,stroke:#546e7a,color:#000
  classDef output fill:#fafafa,stroke:#9e9e9e,color:#000
```
