How lfl-lab/squadds works
Project Type and Purpose
• SQuADDS is an open-source Python library and workflow toolkit for superconducting qubit and device design, simulation, interpolation, and database curation.
• It provides a programmatic API (via squadds/… packages), a command-line/Docker workflow, and an optional Web UI (squadds/ui/app.py) to drive simulations, generate design data, interpolate results, and publish validated datasets to a remote store (e.g., Hugging Face).
Architectural Overview from the File Tree and README
Top-level structure:
• squadds/
• core modules: calcs, components, interpolations, simulations, gds processing, database upload logic, and a minimal ui/app.py.
• tests/ and tutorials/ for validation and user guides.
• Dockerfile, CI/CD workflows (.github/workflows/…), and docs/ for documentation.
• scripts/ (e.g., contributor update), configuration (.env.example, setup.py, requirements*.txt).
Main Components
a. User Interfaces
• CLI / Python API — Users write Python scripts or Jupyter notebooks (in tutorials/) that import squadds modules.
• Web UI — Served by squadds/ui/app.py, providing a React‐style or Flask/FastAPI frontend (depending on implementation) for nonprogrammatic access.
b. Core Library Layers
1. Design Generators & Calculators (squadds/calcs, squadds/components)
2. Simulation Engine Adapter (squadds/simulations/ansys_simulator.py, simulator.py)
3. GDS Processing (squadds/gds/processing.py)
4. Interpolation & ML (squadds/interpolations/interpolator.py, physics.py)
5. Database & Contribution Pipeline (squadds/database/*) — Handles data validation, contributor metadata (GitHub/Hugging Face), and upload.
6. Core Utilities & Patterns (squadds/core/*) — Shared logging, metrics, processing utilities.
c. External Dependencies and Services
• Qiskit-Metal (via conda environment)
• ANSYS or other simulator backends
• Hugging Face Datasets Hub (for data storage)
• GitHub (for metadata, issue templates, CI/CD)
• Docker container image (ghcr.io/lfl-lab/squadds_env)
• Continuous integration (GitHub Actions)
• ReadTheDocs (documentation hosting)
Relationships and Data Flows
• User → Web UI or CLI → Core Library
• Core Library → Simulation Adapter → External Simulator
• Simulation Results → Processing & Metrics → Interpolator
• Interpolated Data → Database Module → Remote Dataset (Hugging Face)
• Contributor Metadata (GitHub OAuth/API) → Database Module → Remote Dataset
• Test Suite (local) and CI/CD pipelines validate each stage.
Architectural Patterns and Principles
• Layered Architecture: Separation between UI, business logic (design generation, simulation orchestration, interpolation), and persistence.
• Plugin/Adapter Pattern: Simulation engines and database backends are abstracted behind interfaces (abstract_upload_data.py, simulator.py).
• Modular Package Structure: Each subpackage (calcs, components, simulations, interpolations, database) implements a single responsibility.
• CI/CD as Code: GitHub workflows for build, test, Docker image, and PyPI release.
• Documentation-Driven: Sphinx docs under docs/; auto-generated API docs.
Technologies, Frameworks, Libraries
• Python 3 library (packaged via setup.py, pip install SQuADDS)
• Docker & conda environment for reproducibility
• CI/CD with GitHub Actions
• Sphinx/ReadTheDocs for documentation
• Qiskit-Metal and possibly PyAnsys for simulation backends
• Hugging Face Datasets and Hub APIs
• Jupyter Notebooks for tutorials
Final Checklist
• Notes on protocols (Python API, REST, CLI)
• Call out CI/CD & Documentation Hosting as side processes