# teddy-van-jerry/ngspice-cmos architecture

> Architecture diagram of the GitHub repository teddy-van-jerry/ngspice-cmos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teddy-van-jerry/ngspice-cmos
- Repository: https://github.com/teddy-van-jerry/ngspice-cmos

## Overview

##### Project Purpose and Type
- The project is an educational and research tool built to simulate CMOS circuits (e.g., inverters, NAND, NOR, AND gates, and a clock-controlled SR latch) using NGSPICE.
- It serves as a course project for VLSI design, providing both the circuit netlists (subcircuit definitions in “.inc” files) and simulation “.cir” files, along with schematic illustrations (in the “fig” directory) and a comprehensive PDF report.
- It also includes a transistor library (“FreePDK45”) which contains model files and parameter definitions used by the circuit simulations.

##### File Structure for Architectural Components
- Core simulation scripts & circuit designs:
- Top-level SPICE netlist files like inv.cir, nand2.cir, and SR_latch_clk.cir.
- Corresponding subcircuit files (e.g., inv.inc, nand2.inc, nand4b.inc, etc.) that define the device-level details.
- Device Model Library:
- “FreePDK45” directory holding CMOS model files and different subdirectories for various operating corners (fast-fast, nominal, slow-slow), indicating the design’s reliance on accurate transistor-level modeling.
- Documentation and Reporting:
- The “README.md” provides an overview and usage instructions.
- The “fig” directory contains schematic sources and simulation plot templates (in LaTeX format and source images) for visualizing circuit designs and responses.
- The “report” folder contains LaTeX and BibTeX files used to generate a PDF report of the simulation results.
- Additional Artifacts:
- Configuration files (.spiceinit, .gitattributes, .gitignore, .github workflows) that help with toolchain integration (e.g., NGSPICE settings and GitHub Pages publishing).

##### Components
a. Main Components:
- NGSPICE Simulation Engine – representing the core engine for running the simulation.
- CMOS Circuit Designs – separate modules or blocks for each type of gate (e.g., Inverter, NAND2, NOR2, AND variants, SR Latch).
- FreePDK45 Transistor Library – the repository of transistor-level models and parameter files.
- Schematic & Documentation Module – illustrating how schematic plots are generated, LaTeX usage for reports, and the “fig” folder assets.
- Development & Integration Tools – configuration files (e.g., .spiceinit, GitHub workflow files) and IDE integration (e.g., .vscode folder).

b. Relationships and Data Flow:
- Data Flow starting from the design files (the “.cir” and “.inc” files) that feed into NGSPICE simulation.
- NGSPICE leverages the transistor models from the FreePDK45 library.
- Schematic generation and simulation outputs propagate into the “fig” directory (with LaTeX files generating final schematics and plots) and ultimately compile into a PDF report (located in the “report” directory).
- Documentation (README and pages) ties all modules together with usage instructions and results analysis.

c. Architectural Patterns & Design Principles:
- Modular Design: The project separates the core circuit definitions (subcircuits) from their simulations. This encourages reuse of device definitions across similar components.
- Layered Architecture: Device modeling (FreePDK45) serves as the lowest layer, followed by subcircuit definitions, simulation scripts, and finally post-processed documentation and reports.
- Extensibility: Additional circuits can be added by following the established file structure (similar naming conventions and folder organization).

d. Core Technologies, Frameworks, and Tools:
- NGSPICE – the simulation engine.
- LaTeX – for schematic representation and report generation.
- SPICE – the netlist/simulation language.
- Git/GitHub – for version control and CI/CD (via GitHub workflows).
- (Optional) IDE configuration settings found in .vscode.

- Every architectural element is included and appropriately connected.
- Pay special attention to detailing the modularity of the open-source tool—each component (design, simulation, and documentation) should be clearly identifiable and the interactions between them unambiguous.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Circuit Design Layer
    subgraph "Circuit Design Files"
        Inv["Inverter Module"]:::circuit
        NAND2["NAND2 Module"]:::circuit
        Other["Other Gate/Logic Modules"]:::circuit
        SRLatch["SR Latch Module"]:::circuit
    end

    %% Simulation Engine Layer
    Simulation["NGSPICE Simulation Engine"]:::engine

    %% Transistor Library Layer
    FreePDK45["FreePDK45 Transistor Library"]:::library

    %% Documentation & Schematic Output
    Docs["Schematic & Documentation Module"]:::docs

    %% Development & Integration Tools
    Tools["Development & Integration Tools"]:::tools

    %% Data Flows
    Inv -->|"feeds"| Simulation
    NAND2 -->|"feeds"| Simulation
    Other -->|"feeds"| Simulation
    SRLatch -->|"feeds"| Simulation

    FreePDK45 -->|"models used"| Simulation
    
    Simulation -->|"simulation output"| Docs

    Tools -->|"configures"| Simulation
    Tools -->|"supports"| Docs

    %% Click Events for Circuit Modules
    click Inv "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/inv.cir"
    click Inv "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/inv.inc"
    click Inv "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/inv.tex"
    click Inv "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/inv_schematic.tex"

    click NAND2 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nand2.cir"
    click NAND2 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nand2.inc"
    click NAND2 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/nand2.tex"
    click NAND2 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/nand2_schematic.tex"

    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and2.cir"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nand4a.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nand4b.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nor2.cir"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nor2.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8a.cir"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8a.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8b.cir"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8b.inc"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8c.cir"
    click Other "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/and8c.inc"

    click SRLatch "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/SR_latch_clk.cir"
    click SRLatch "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/SR_latch_clk.inc"
    click SRLatch "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/SR_latch_clk.tex"
    click SRLatch "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/fig/SR_latch_clk_schematic.tex"

    %% Click Events for NGSPICE Simulation Engine
    click Simulation "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/inv.cir"
    click Simulation "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/nand2.cir"
    click Simulation "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/SR_latch_clk.cir"
    click Simulation "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.spiceinit"

    %% Click Events for FreePDK45 Transistor Library
    click FreePDK45 "https://github.com/teddy-van-jerry/ngspice-cmos/tree/master/FreePDK45"
    click FreePDK45 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/FreePDK45/nom.inc"
    click FreePDK45 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/FreePDK45/ss.inc"
    click FreePDK45 "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/FreePDK45/ff.inc"
    click FreePDK45 "https://github.com/teddy-van-jerry/ngspice-cmos/tree/master/FreePDK45/tran_models"

    %% Click Events for Schematic & Documentation Module
    click Docs "https://github.com/teddy-van-jerry/ngspice-cmos/tree/master/fig"
    click Docs "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/report/NGSPICE_CMOS_Report.tex"
    click Docs "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/report/NGSPICE_CMOS_Report.pdf"
    click Docs "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/README.md"
    click Docs "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/pages/FreePDK45_README.md"

    %% Click Events for Development & Integration Tools
    click Tools "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.spiceinit"
    click Tools "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.gitattributes"
    click Tools "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.gitignore"
    click Tools "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.github/workflows/jekyll-gh-pages.yml"
    click Tools "https://github.com/teddy-van-jerry/ngspice-cmos/blob/master/.vscode"

    %% Styles
    classDef engine fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef circuit fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef library fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef docs fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef tools fill:#dda0dd,stroke:#000,stroke-width:2px;
```
