# lfl-lab/squadds architecture

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

- Interactive diagram: https://gitdiagram.com/lfl-lab/squadds
- Repository: https://github.com/lfl-lab/squadds

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        UI_API["CLI / Python API"]:::internal
        UI_Web["Web UI"]:::internal
    end

    %% Core Library Layers
    subgraph "Core Library"
        subgraph "Design & Calculations"
            Calcs["Design Generators & Calculators"]:::internal
        end
        subgraph "Simulation Adapter"
            Sim["Simulation Engine Adapter"]:::internal
        end
        subgraph "GDS Processing"
            GDS["GDS Processing"]:::internal
        end
        subgraph "Interpolation Layer"
            Interp["Interpolation & ML"]:::internal
        end
        subgraph "Database & Contribution"
            DB["Database & Contribution Pipeline"]:::internal
        end
        subgraph "Core Utilities"
            Util["Core Utilities & Patterns"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        Qiskit["Qiskit-Metal"]:::external
        ANSYS["ANSYS Simulator"]:::external
        HF["Hugging Face Hub"]:::external
        GH["GitHub API"]:::external
    end

    %% Testing, Tutorials, Documentation, CI/CD, Docker
    subgraph "Support & Deployment"
        Test["Tests & Validation"]:::infra
        Tut["Tutorials & Guides"]:::internal
        CI["CI/CD Workflows"]:::infra
        Doc["Documentation (ReadTheDocs)"]:::infra
        Dock["Docker & Environment"]:::infra
    end

    %% Data Flows
    UI_API -->|"Python API / CLI"| Calcs
    UI_Web -->|"REST API"| Calcs
    Calcs -->|"generate_designs()"| Sim
    Sim -->|"run_simulation()"| ANSYS
    Sim -->|"run_simulation()"| Qiskit
    ANSYS -->|"results"| GDS
    Qiskit -->|"results"| GDS
    GDS -->|"process_gds()"| Interp
    Interp -->|"interpolate()"| DB
    DB -->|"upload_data()"| HF
    DB -->|"github_metadata()"| GH

    %% Utilities Dependencies
    Util --> Calcs
    Util --> Sim
    Util --> GDS
    Util --> Interp
    Util --> DB

    %% Support flows
    CI --> Calcs
    CI --> Sim
    CI --> GDS
    CI --> Interp
    CI --> DB
    CI --> Dock

    Doc --> Calcs
    Doc --> Sim

    Dock --> Calcs

    %% Click Events
    click UI_API "https://github.com/lfl-lab/squadds/blob/master/squadds/__init__.py"
    click UI_API "https://github.com/lfl-lab/squadds/blob/master/setup.py"
    click UI_Web "https://github.com/lfl-lab/squadds/blob/master/squadds/ui/app.py"
    click Calcs "https://github.com/lfl-lab/squadds/tree/master/squadds/calcs/"
    click Calcs "https://github.com/lfl-lab/squadds/tree/master/squadds/components/"
    click Sim "https://github.com/lfl-lab/squadds/blob/master/squadds/simulations/ansys_simulator.py"
    click Sim "https://github.com/lfl-lab/squadds/blob/master/squadds/simulations/simulator.py"
    click Sim "https://github.com/lfl-lab/squadds/blob/master/squadds/simulations/objects.py"
    click Sim "https://github.com/lfl-lab/squadds/blob/master/squadds/simulations/utils.py"
    click Sim "https://github.com/lfl-lab/squadds/blob/master/squadds/simulations/sweeper_helperfunctions.py"
    click GDS "https://github.com/lfl-lab/squadds/blob/master/squadds/gds/processing.py"
    click Interp "https://github.com/lfl-lab/squadds/blob/master/squadds/interpolations/interpolator.py"
    click Interp "https://github.com/lfl-lab/squadds/blob/master/squadds/interpolations/physics.py"
    click Interp "https://github.com/lfl-lab/squadds/blob/master/squadds/interpolations/utils.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/abstract_upload_data.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/HuggingFace.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/github.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/contributor.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/contributor_HF.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/new_contribution.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/checker.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/config.py"
    click DB "https://github.com/lfl-lab/squadds/blob/master/squadds/database/utils.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/analysis.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/db.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/design_patterns.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/globals.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/metrics.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/processing.py"
    click Util "https://github.com/lfl-lab/squadds/blob/master/squadds/core/utils.py"
    click Test "https://github.com/lfl-lab/squadds/blob/master/tests/imports_test.py"
    click Test "https://github.com/lfl-lab/squadds/blob/master/tests/mvp_test.py"
    click Test "https://github.com/lfl-lab/squadds/blob/master/tests/hwc_test.py"
    click Tut "https://github.com/lfl-lab/squadds/tree/master/tutorials/"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/ci.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/docker-build.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/prepare-release.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/pypi.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/release-drafter.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/test_build.yml"
    click CI "https://github.com/lfl-lab/squadds/blob/master/.github/workflows/update_contributors.yml"
    click Doc "https://github.com/lfl-lab/squadds/tree/master/docs/source/apidocs/"
    click Doc "https://github.com/lfl-lab/squadds/tree/master/docs/source/tutorials/"
    click Doc "https://github.com/lfl-lab/squadds/blob/master/docs/conf.py"
    click Dock "https://github.com/lfl-lab/squadds/tree/master/Dockerfile"
    click Dock "https://github.com/lfl-lab/squadds/blob/master/environment.yml"
    click Dock "https://github.com/lfl-lab/squadds/blob/master/requirements.txt"

    %% Styles
    classDef internal fill:#D0E1FD,stroke:#0366d6,color:#0366d6
    classDef external fill:#e3fcef,stroke:#28a745,color:#28a745
    classDef infra fill:#fff5b1,stroke:#d2a106,color:#d2a106
```
