How magical-eda/magical works
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