# ucb-art/bag architecture

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

- Interactive diagram: https://gitdiagram.com/ucb-art/bag
- Repository: https://github.com/ucb-art/bag

## Overview

##### Project type and purpose
- This is an open-source Python framework (BAG3++) for automated analog/mixed-signal (AMS) circuit generation, simulation, verification, and optimization.
- It provides both a library (“src/bag/...”) and a set of command‐line entrypoints (“run_scripts/…”) that invoke the library to generate netlists/layouts, run simulations, perform DRC/LVS and other verifications, and orchestrate MDAO loops.

##### File structure
- Top‐level directories
– run_scripts/: CLI scripts (Perl/IL/sh/Python) that invoke the BAG engine for various tasks (compile, generate, simulate, export, verify).
– src/bag/: Core Python package, subdivided into functional subpackages:
· concurrent: HPC/LSF parallelism
· core: flow orchestration, session/env management
· data: parameter/data definitions for circuits
· design: netlist and module generation APIs
· layout: physical layout generation, routing, templates
· simulation: SPICE integration (NGSpice, Spectre, etc.), cache, data handling
· verification: wrappers around Calibre, ICV, PVS, layout export/import configs
· interface: EDA tool front-ends (Virtuoso, Ocean, LEF/OA, Skill, ZMQ)
· io: file, template, GUI, and process I/O utilities
· mdao: modules for multidisciplinary analysis & optimization
· util: general utilities (logging, math, parsing, caching)
– docs/: Documentation and scripts for building docs.
– tests/: Pytest tests, including mocks for EDA environments.
– Configuration files: environment.yml, env_3p8.yml, pytest.ini.
– GitHub workflows for CI (pr_u2004.yaml, pr_u2204.yaml).

##### README for additional insights
- Confirms focus on parameterizable generation of tape-out ready netlists/layouts.
- Mentions built-in automation of simulation with post-processing, physical verification, and design optimization.

a. Main components
– CLI Layer (run_scripts/…): User entrypoints & shell wrappers
– Core Engine (src/bag/core.py + session/env modules)
– Design Module (src/bag/design): Generates parameterized netlists and module hierarchies
– Layout Module (src/bag/layout): Generates GDS/OASIS physical layouts using templates and routing
– Simulation Module (src/bag/simulation): Drives SPICE backends, caches results, post-processes data
– Verification Module (src/bag/verification): Invokes Calibre, ICV, PVS for DRC/LVS/ERC; handles export/import configs
– I/O & Interface Layer (src/bag/io & src/bag/interface): Abstracts file I/O, EDA tool APIs (Virtuoso, Ocean, LEF/OA, Skill), ZMQ messaging
– Concurrency Module (src/bag/concurrent): Submits jobs to LSF or local pools
– MDAO Module (src/bag/mdao): Orchestrates optimization loops over design parameters
– Utilities (src/bag/util, src/bag/math): Support functions
– External Tools/Services:
- SPICE engines (Spectre, NGSpice, libpsf, etc.)
- Layout editors/viewers (KLayout)
- Physical verification tools (Calibre, ICV, PVS)
- Cadence Virtuoso/OCEAN/Skill environment
- HPC cluster (LSF)

b. Relationships & data flows
1. User runs a script → CLI Layer
2. CLI calls Core Engine, supplying configuration (YAML/env)
3. Core invokes Design Module → outputs netlist descriptions
4. Core invokes Layout Module → outputs GDS/OASIS layout
5. Core → Simulation Module → SPICE invocation via Interface + IO → returns simulation data
6. Core → Verification Module → physical checks via external tools → returns reports
7. (Optional) MDAO Module loops back results → refines parameters → re-invoke Design/Sim
8. Concurrency Module parallelizes steps on LSF or local pool

c. Architectural patterns & design principles
- Separation of concerns: CLI vs. engine vs. functional modules
- Plugin/adapter pattern: interface subpackage abstracts EDA tools
- Template-based code generation: design/layout templates in modules and “interface/templates”
- Concurrency abstraction: same API for local vs. cluster execution
- Data‐driven flows: YAML configs drive all modules

d. Key technologies & frameworks
- Python 3.8+ with Conda environment
- PyYAML for config
- ZMQ for messaging between engine and EDA processes
- HDF5 for simulation data storage
- External EDA tools: Cadence Virtuoso, Spectre, Calibre, ICV, NGSpice, KLayout

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["run_scripts/"]:::cli
    end
    CLI -->|"invoke"| Core

    Core["Core Engine\n(src/bag/core.py,\nsrc/bag/env.py)"]:::internal

    subgraph "Functional Modules"
        Design["Design Module\nsrc/bag/design/"]:::internal
        Layout["Layout Module\nsrc/bag/layout/"]:::internal
        Sim["Simulation Module\nsrc/bag/simulation/"]:::internal
        Verify["Verification Module\nsrc/bag/verification/"]:::internal
        MDAO["MDAO Module\nsrc/bag/mdao/"]:::internal
    end

    Core -->|"generate netlist"| Design
    Core -->|"generate layout"| Layout
    Core -->|"run simulation"| Sim
    Core -->|"run verification"| Verify
    Core -->|"optimize loop"| MDAO

    subgraph "Support Modules"
        Interface["Interface Layer\nsrc/bag/interface/"]:::internal
        IO["I/O Utilities\nsrc/bag/io/"]:::internal
        Concurrent["Concurrency Module\nsrc/bag/concurrent/"]:::internal
        Data["Data Definitions\nsrc/bag/data/"]:::internal
        Util["Utilities\nsrc/bag/util &\nsrc/bag/math"]:::internal
    end

    Core --> Interface
    Core --> IO
    Core --> Concurrent
    Core --> Data
    Core --> Util

    subgraph "External Tools & Services"
        SPICE["SPICE Engines\n(Spectre, NGSpice)"]:::external
        Virt["Cadence Virtuoso & OCEAN"]:::external
        PV["Physical Verification\n(Calibre, ICV, PVS)"]:::external
        LSF["HPC Cluster\n(LSF)"]:::external
        KLAY["KLayout"]:::external
    end

    Design -->|"use adapters"| Interface
    Layout -->|"use adapters"| Interface
    Sim -->|"SPICE deck"| SPICE
    Sim -->|"via ZMQ"| Interface
    Verify -->|"run tools"| PV
    Verify -->|"export layouts"| KLAY
    Concurrent -->|"submit jobs"| LSF

    subgraph "Data Stores"
        CFG["Config Files\n(YAML)"]:::datastore
        HDF["HDF5 Simulation Data"]:::datastore
    end

    CLI --> CFG
    Sim --> HDF

    click CLI "https://github.com/ucb-art/bag/tree/develop/run_scripts/"
    click Core "https://github.com/ucb-art/bag/blob/develop/src/bag/core.py"
    click Core "https://github.com/ucb-art/bag/blob/develop/src/bag/env.py"
    click Design "https://github.com/ucb-art/bag/tree/develop/src/bag/design/"
    click Layout "https://github.com/ucb-art/bag/tree/develop/src/bag/layout/"
    click Sim "https://github.com/ucb-art/bag/tree/develop/src/bag/simulation/"
    click Verify "https://github.com/ucb-art/bag/tree/develop/src/bag/verification/"
    click Interface "https://github.com/ucb-art/bag/tree/develop/src/bag/interface/"
    click IO "https://github.com/ucb-art/bag/tree/develop/src/bag/io/"
    click Concurrent "https://github.com/ucb-art/bag/tree/develop/src/bag/concurrent/"
    click MDAO "https://github.com/ucb-art/bag/tree/develop/src/bag/mdao/"
    click Data "https://github.com/ucb-art/bag/tree/develop/src/bag/data/"
    click Util "https://github.com/ucb-art/bag/tree/develop/src/bag/util/"
    click Util "https://github.com/ucb-art/bag/tree/develop/src/bag/math/"

    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef cli fill:#c2f0c2,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd9b5,stroke:#333,stroke-width:1px;
    classDef datastore fill:#d9d9d9,stroke:#333,stroke-width:1px;
```
