# magical-eda/magical architecture

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

- Interactive diagram: https://gitdiagram.com/magical-eda/magical
- Repository: https://github.com/magical-eda/magical

## Overview

##### Project type and purpose
- MAGICAL is an open-source EDA “flow” tool for automatic analog IC layout.
- It integrates separate modules (constraint generation, placement, routing) through a top-level Python orchestrator.
- It reads a netlist/schematic + PDK tech files, generates symmetry constraints, places devices, routes interconnect, and emits a GDSII layout.

##### File structure
- Top-level:
- Dockerfile, build scripts (build.sh) and submodule management (.gitmodules)
- ConstGen, device_generation, anaroute, IdeaPlaceEx – placeholder or legacy repos for constraint gen, device sizing, routing, and placement respectively.
- `flow/` directory holds both C++ core library (`flow/cpp/magical_flow`) and Python orchestrator (`flow/python`).
- `examples/` with benchmark circuits and run.sh scripts.
- `mockPDK/` with sample LEF/tech files.
- C++ module (`flow/cpp/magical_flow`):
- APIs under `src/api/*` exposing functionality (Parsing, LayoutDB, Graph, Write, etc.)
- Core engine under `src/csflow` & `src/db` for design data structures
- Parser and writer components under `src/parser` & `src/writer`
- Unit tests under `unittest/`
- Python orchestrator (`flow/python`):
- Flow.py invokes PnR, Router, Placer, Constraint, etc.
- Modules for each step (Constraint.py, Placer.py, Router.py, PnR.py)
- Wrapper code for C++ APIs (Magical.py / MagicalDB.py) via pyx bindings

##### Extracting README insights
- Top-level Python flow integrates independently developed components.
- Dependencies: Python 3.7, Boost, Flex, Zlib, Limbo, LPSolve, Lemon
- Users run `examples/<bench>/run.sh` to produce `.route.gds` output.
- Custom symmetry constraint files (.sym, .symnet) are inputs/outputs of the constraint generator.

a. Main components
1. User / CLI – issues `run.sh`, passes netlist, PDK (mockPDK)
2. Python Flow Orchestrator – Flow.py
3. Constraint Generator – Python module + possible C++ API
4. Design Database & Graph – C++ `DesignDB`, `CktGraph`
5. Placement Engine – Python Placer.py calling IdeaPlaceEx or C++ API
6. Routing Engine – Python Router.py invoking anaroute or C++ API
7. GDSII Writer – C++ GdsWriter API
8. External Dependencies – Boost, Flex, Zlib, Limbo, LPSolve, Lemon
9. Docker Container / Host Environment

b. Relationships and data flow
- CLI → Python Flow
- Python Flow calls Parser (C++) to read netlist/schematic → populates DesignDB
- Python Flow invokes Constraint Generator → outputs `.sym` / `.symnet`
- Python Flow invokes Placer → modifies DesignDB with placed coordinates
- Python Flow invokes Router → takes placed design + constraint → produces routed geometry
- C++ GdsWriter consumes final DesignDB → writes `.route.gds`
- Python Flow collates outputs back to user directory

c. Architectural patterns & design principles
- Pipeline pattern: clear chain of responsibility from parsing → constraint → placement → routing → writing
- Hybrid language boundary: Python for control, C++ for performance-critical data structures & algorithms
- Modularization: each major step lives in its own module/repo, integrated via Python APIs
- Testability: unit tests in C++ for DB and parser

d. Key technologies & frameworks
- Python 3.7: Flow orchestration and scripting
- C++11+ library: `flow/cpp/magical_flow`
- cython/pyx: Python bindings to C++ APIs
- Docker: repeatable build & run environment
- External libs: Boost, Flex, Zlib, Limbo, LPSolve, Lemon

##### Additional recommendations
- User/CLI
- Orchestration (Python)
- Core engine (C++)
- External dependencies

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Swimlanes
  subgraph "User/CLI"
    CLI["Run.sh<br/>(examples/*/run.sh)"]:::external
  end

  subgraph "Python Orchestrator"
    Flow["Flow.py"]:::python
    ConstraintPy["Constraint.py"]:::python
    PlacerPy["Placer.py"]:::python
    RouterPy["Router.py"]:::python
    DeviceGenPy["Device_generator.py"]:::python
    DesignDBWrap["DesignDB.py"]:::python
    MagicalDB["MagicalDB.py"]:::python
    BindingUtil["pyximportcpp.py"]:::python
    PageRankPX["pagerank.pyx"]:::python
  end

  subgraph "C++ Core Engine"
    Parser["Parser<br/>(ParseSimpleTech, ParseGDS)"]:::cpp
    DesignDBCPP["DesignDB"]:::cpp
    CktGraph["CktGraph"]:::cpp
    DesignDBAPI["DesignDBAPI"]:::cpp
    CktGraphAPI["CktGraphAPI"]:::cpp
    CSFlow["CSFlow"]:::cpp
    GdsWriter["GdsWriter"]:::cpp
  end

  subgraph "External Modules"
    ConstGen["ConstGen/"]:::external
    DeviceGenLegacy["device_generation/"]:::external
    IdeaPlaceEx["IdeaPlaceEx/"]:::external
    Anaroute["anaroute/"]:::external
  end

  subgraph "External Dependencies"
    Boost["Boost"]:::external
    Flex["Flex"]:::external
    Zlib["Zlib"]:::external
    Limbo["Limbo"]:::external
    LPSolve["LPSolve"]:::external
    Lemon["Lemon"]:::external
    Docker["Docker"]:::external
  end

  subgraph "Artifacts"
    Netlist["Netlist + PDK"]:::artifact
    SymFiles[".sym / .symnet"]:::artifact
    PlacedData["Placed Design"]:::artifact
    RoutedGeom["Routed Geometry"]:::artifact
    GDS[".route.gds"]:::artifact
  end

  %% Connections
  CLI -->|"invoke"| Flow
  Flow -->|"reads"| Netlist
  Flow -->|"calls"| Parser
  Parser -->|"populates"| DesignDBCPP
  DesignDBCPP -->|"exposes API"| DesignDBAPI
  CktGraph -->|"exposes API"| CktGraphAPI
  DesignDBAPI -->|bindings| DesignDBWrap
  CktGraphAPI -->|bindings| DesignDBWrap
  BindingUtil -->|supports| DesignDBWrap
  PageRankPX -->|supports| DesignDBWrap
  Flow -->|"Constraint step"| ConstraintPy
  ConstraintPy -->|may call| ConstGen
  ConstraintPy -->|outputs| SymFiles
  Flow -->|"Placement step"| PlacerPy
  PlacerPy -->|may call| IdeaPlaceEx
  PlacerPy -->|modifies| PlacedData
  Flow -->|"Routing step"| RouterPy
  RouterPy -->|may call| Anaroute
  RouterPy -->|produces| RoutedGeom
  Flow -->|"writes"| GdsWriter
  GdsWriter -->|consumes| CSFlow
  CSFlow -->|uses DB| DesignDBCPP
  GdsWriter -->|emits| GDS
  Flow -->|"collects"| GDS

  %% External Dependencies Connections
  Parser -->|depends| Boost
  Parser -->|depends| Flex
  CSFlow -->|depends| Zlib
  ConstraintPy -->|depends| LPSolve
  RouterPy -->|depends| Lemon
  Flow -->|runs in| Docker

  %% Click Events
  click CLI "https://github.com/magical-eda/magical/blob/master/examples/adc1/run.sh"
  click Flow "https://github.com/magical-eda/magical/blob/master/flow/python/Flow.py"
  click ConstraintPy "https://github.com/magical-eda/magical/blob/master/flow/python/Constraint.py"
  click ConstGen "https://github.com/magical-eda/magical/tree/master/ConstGen/"
  click DesignDBCPP "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/db/DesignDB.cpp"
  click CktGraph "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/db/CktGraph.h"
  click DesignDBAPI "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/api/DesignDBAPI.cpp"
  click CktGraphAPI "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/api/CktGraphAPI.cpp"
  click DesignDBWrap "https://github.com/magical-eda/magical/blob/master/flow/python/DesignDB.py"
  click MagicalDB "https://github.com/magical-eda/magical/blob/master/flow/python/MagicalDB.py"
  click PlacerPy "https://github.com/magical-eda/magical/blob/master/flow/python/Placer.py"
  click IdeaPlaceEx "https://github.com/magical-eda/magical/tree/master/IdeaPlaceEx/"
  click RouterPy "https://github.com/magical-eda/magical/blob/master/flow/python/Router.py"
  click Anaroute "https://github.com/magical-eda/magical/tree/master/anaroute/"
  click Parser "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/parser/ParseSimpleTech.cpp"
  click GdsWriter "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/writer/GdsWriter.h"
  click CSFlow "https://github.com/magical-eda/magical/blob/master/flow/cpp/magical_flow/src/csflow/CSFlow.cpp"
  click BindingUtil "https://github.com/magical-eda/magical/blob/master/flow/python/pyximportcpp.py"
  click PageRankPX "https://github.com/magical-eda/magical/blob/master/flow/python/pagerank.pyx"
  click DeviceGenPy "https://github.com/magical-eda/magical/blob/master/flow/python/Device_generator.py"
  click DeviceGenLegacy "https://github.com/magical-eda/magical/tree/master/device_generation/"

  %% Styles
  classDef python fill:#E8F1F8,stroke:#333,stroke-width:1px;
  classDef cpp fill:#F5F5F5,stroke:#333,stroke-width:1px;
  classDef external fill:#E8F8E8,stroke:#333,stroke-width:1px;
  classDef artifact fill:#FFF8DC,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
