How heitzmann/gdstk works
Main Components
a. Core C++ Library:
• Files under “src” (primary source code for various layout operations such as cell creation, polygon manipulations, curve and flexpath operations, etc.).
• Header files under “include” that define the API (e.g., cell.hpp, flexpath.hpp, polygon.hpp).
b. Python Module/Bindings:
• The “python” directory contains the binding code (with CMakeLists.txt and wrapping CPP files) that links Python calls to the core C++ library.
c. External Dependencies:
• External libraries such as zlib, Qhull, and the clipper module (found under “external/clipper” and referenced within the C++ source).
d. Documentation and Examples:
• “docs” directory documents the API, usage examples, and includes Sphinx configurations along with demo files.
e. Benchmarks and Performance Testing:
• “benchmarks” directory, which contains various Python scripts to measure performance gains.
f. Testing and CI/CD:
• “tests” directory for unit tests.
• GitHub workflows (in “.github/workflows”) that automate testing, documentation publishing, and package releases.
g. Build and Configuration:
• CMake configuration files (at the root, in “python” and “docs/cpp”) and the Makefile that orchestrate building the library and wrappers.
• Supporting scripts like CMakeLists.txt in the root and “pyproject.toml” for Python packaging.
Relationships and Interactions
• The Python module layer depends on the core C++ library, acting as a thin wrapper/binding so that Python users can leverage the high-performance C++ routines.
• The core C++ library interacts with external libraries (zlib, Qhull, and Clipper) to perform complex computations like polygon booleans, offsets, and geometry operations.
• Documentation is generated from the source code (both C++ and Python) and lives separately in the “docs” folder; it is also integrated into the CI/CD pipeline.
• Benchmark scripts call into both the Python interface and possibly directly into the C++ functions, illustrating performance differences.
• Tests exercise both the C++ logic (likely indirectly via the Python bindings) and integration aspects, triggered through automated workflows.
Architectural Patterns/Design Principles
• Layered Architecture: The design clearly separates the low-level geometric processing (core C++ logic) from the higher-level language bindings (Python module). This separation enables modular development and easier testing.
• Build Abstraction: The use of CMake and accompanying build scripts abstracts hardware/platform-specific details.
• Extensibility: The library components are designed to be used directly (as a C++ static library) or via Python, emphasizing modularity and reusability.
• Testing and Continuous Integration: Automated tests (via Python’s pytest or similar framework) and CI workflows demonstrate a commitment to robust, quality-assured design.
Technologies and Frameworks to Note
• C++ for the core implementation.
• Python for the wrapper module.
• CMake and Makefile for build automation.
• Sphinx (with relevant themes and plugins) for generating documentation.
• External libraries: zlib, Qhull, and Clipper.
Elements
– “Core C++ Library (src/include)”
– “Python Bindings/Module”
– “External Dependencies (zlib, Qhull, Clipper)”
– “Documentation (Sphinx, docs)”
– “Benchmarks (Performance Scripts)”
– “Tests (Unit Tests & CI/CD Workflows)”
– Data and function calling from Python to the C++ library.
– Interactions between the core library and external dependencies.
– The flow of the build process from CMake/Makefile to the final binaries and wheels.
– Core system components (e.g., libraries) versus auxiliary tools (e.g., documentation, tests).
– Programming language layers (C++ vs. Python).
Additional Recommendations
• Annotations explaining key architectural decisions (e.g., “This layer abstracts all geometry operations for high efficiency”, or “This binding layer exposes the API to Python users”).