# tinkueg/quask architecture

> Architecture diagram of the GitHub repository tinkueg/quask, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tinkueg/quask
- Repository: https://github.com/tinkueg/quask

## Overview

QuASK is a Python quantum-machine-learning toolkit whose main workflow retrieves data, preprocesses and splits it, computes classical or quantum Gram matrices, then evaluates kernel performance. The CLI orchestrates these stages; the library also exposes kernel registers, PennyLane circuit templates, trainable kernels, projected kernels, and metric calculations. The README documents additional analysis capabilities, including prediction bounds and observable-based studies, but the excerpts do not show their full implementation. Edges use the README or source-index relationships where available; undocumented internals are not inferred.

Main entry points: [`quask/__main__.py`](https://github.com/tinkueg/quask/blob/main/quask/__main__.py) (QuASK CLI), [`quask/template_pennylane.py`](https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py) (Quantum kernels), [`quask/datasets.py`](https://github.com/tinkueg/quask/blob/main/quask/datasets.py) (Dataset registry), [`quask/kernels.py`](https://github.com/tinkueg/quask/blob/main/quask/kernels.py) (Kernel registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Data workflow"]
  node_cli["QuASK CLI<br/>[__main__.py]"]
  node_dataset_registry["Dataset registry<br/>[datasets.py]"]
  node_openml[("OpenML datasets")]
  node_quantum_data[("Bundled quantum data")]
  node_preprocessing["Preprocessing<br/>[__main__.py]"]
  node_split_data["Train/test data<br/>[__main__.py]"]
end

subgraph group_kernels["Kernel computation"]
  node_kernel_registry["Kernel registry<br/>[kernels.py]"]
  node_classical_kernels["Classical kernels<br/>[kernels.py]"]
  node_quantum_kernels["Quantum kernels"]
  node_projected_kernels["Projected kernels"]
  node_gram_matrices["Gram matrices<br/>[__main__.py]"]
end

subgraph group_analysis["Kernel analysis"]
  node_metrics["Kernel metrics<br/>[metrics.py]"]
  node_performance["Performance assessment<br/>[__main__.py]"]
  node_advantage_bounds["Advantage bounds"]
end

subgraph group_quantum["Quantum models"]
  node_quantum_templates["Circuit templates"]
  node_trainable_kernel["Trainable kernels"]
  node_observable_studies["Observable studies"]
end

node_researcher(("Researcher"))
node_quantum_frameworks["Quantum frameworks"]

node_researcher -->|"runs commands"| node_cli
node_cli -->|"retrieves datasets"| node_dataset_registry
node_dataset_registry -->|"downloads data"| node_openml
node_dataset_registry -->|"loads data"| node_quantum_data
node_cli -->|"preprocesses data"| node_preprocessing
node_preprocessing -->|"splits data"| node_split_data
node_cli -->|"selects kernels"| node_kernel_registry
node_kernel_registry -->|"registers kernels"| node_classical_kernels
node_kernel_registry -->|"registers kernels"| node_quantum_kernels
node_quantum_kernels -->|"uses templates"| node_quantum_templates
node_quantum_kernels -->|"supports projection"| node_projected_kernels
node_cli -->|"optimizes circuits"| node_trainable_kernel
node_trainable_kernel -->|"builds circuits"| node_quantum_templates
node_classical_kernels -->|"computes matrices"| node_gram_matrices
node_quantum_kernels -->|"computes matrices"| node_gram_matrices
node_trainable_kernel -->|"returns matrices"| node_gram_matrices
node_cli -->|"evaluates metrics"| node_metrics
node_metrics -->|"assesses performance"| node_performance
node_gram_matrices -->|"provides inputs"| node_performance
node_metrics -.->|"supports bounds"| node_advantage_bounds
node_quantum_templates -.->|"supports observables"| node_observable_studies
node_quantum_templates -->|"uses PennyLane"| node_quantum_frameworks

click node_cli "https://github.com/tinkueg/quask/blob/main/quask/__main__.py"
click node_dataset_registry "https://github.com/tinkueg/quask/blob/main/quask/datasets.py"
click node_quantum_data "https://github.com/tinkueg/quask/tree/main/quask/resources"
click node_preprocessing "https://github.com/tinkueg/quask/blob/main/quask/__main__.py"
click node_split_data "https://github.com/tinkueg/quask/blob/main/quask/__main__.py"
click node_kernel_registry "https://github.com/tinkueg/quask/blob/main/quask/kernels.py"
click node_classical_kernels "https://github.com/tinkueg/quask/blob/main/quask/kernels.py"
click node_quantum_templates "https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py"
click node_quantum_kernels "https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py"
click node_projected_kernels "https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py"
click node_trainable_kernel "https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py"
click node_gram_matrices "https://github.com/tinkueg/quask/blob/main/quask/__main__.py"
click node_metrics "https://github.com/tinkueg/quask/blob/main/quask/metrics.py"
click node_performance "https://github.com/tinkueg/quask/blob/main/quask/__main__.py"
click node_advantage_bounds "https://github.com/tinkueg/quask/tree/main/quask"
click node_observable_studies "https://github.com/tinkueg/quask/tree/main/quask"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_dataset_registry,node_openml,node_quantum_data,node_preprocessing,node_split_data toneBlue
class node_kernel_registry,node_classical_kernels,node_quantum_kernels,node_projected_kernels,node_gram_matrices toneAmber
class node_metrics,node_performance,node_advantage_bounds toneMint
class node_quantum_templates,node_trainable_kernel,node_observable_studies toneRose
class node_researcher,node_quantum_frameworks toneIndigo
```

## Components

### Data workflow

- [QuASK CLI](https://github.com/tinkueg/quask/blob/main/quask/__main__.py): `quask/__main__.py`
- [Dataset registry](https://github.com/tinkueg/quask/blob/main/quask/datasets.py): `quask/datasets.py`
- **OpenML datasets**
- [Bundled quantum data](https://github.com/tinkueg/quask/tree/main/quask/resources): `quask/resources`
- [Preprocessing](https://github.com/tinkueg/quask/blob/main/quask/__main__.py): `quask/__main__.py`
- [Train/test data](https://github.com/tinkueg/quask/blob/main/quask/__main__.py): `quask/__main__.py`

### Kernel computation

- [Kernel registry](https://github.com/tinkueg/quask/blob/main/quask/kernels.py): `quask/kernels.py`
- [Classical kernels](https://github.com/tinkueg/quask/blob/main/quask/kernels.py): `quask/kernels.py`
- [Quantum kernels](https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py): `quask/template_pennylane.py`
- [Projected kernels](https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py): `quask/template_pennylane.py`
- [Gram matrices](https://github.com/tinkueg/quask/blob/main/quask/__main__.py): `quask/__main__.py`

### Kernel analysis

- [Kernel metrics](https://github.com/tinkueg/quask/blob/main/quask/metrics.py): `quask/metrics.py`
- [Performance assessment](https://github.com/tinkueg/quask/blob/main/quask/__main__.py): `quask/__main__.py`
- [Advantage bounds](https://github.com/tinkueg/quask/tree/main/quask): `quask`

### Quantum models

- [Circuit templates](https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py): `quask/template_pennylane.py`
- [Trainable kernels](https://github.com/tinkueg/quask/blob/main/quask/template_pennylane.py): `quask/template_pennylane.py`
- [Observable studies](https://github.com/tinkueg/quask/tree/main/quask): `quask`

### Other components

- **Researcher**
- **Quantum frameworks**

## Connections

- Researcher → QuASK CLI: runs commands (evidence: `README.md`)
- QuASK CLI → Dataset registry: retrieves datasets (evidence: `quask/__main__.py`)
- Dataset registry → OpenML datasets: downloads data (evidence: `quask/datasets.py`)
- Dataset registry → Bundled quantum data: loads data (evidence: `quask/datasets.py`)
- QuASK CLI → Preprocessing: preprocesses data (evidence: `README.md`)
- Preprocessing → Train/test data: splits data (evidence: `quask/__main__.py`)
- QuASK CLI → Kernel registry: selects kernels (evidence: `quask/__main__.py`)
- Kernel registry → Classical kernels: registers kernels (evidence: `quask/kernels.py`)
- Kernel registry → Quantum kernels: registers kernels (evidence: `quask/kernels.py`)
- Quantum kernels → Circuit templates: uses templates (evidence: `quask/kernels.py`)
- Quantum kernels → Projected kernels: supports projection (evidence: `quask/kernels.py`)
- QuASK CLI → Trainable kernels: optimizes circuits (evidence: `quask/__main__.py`)
- Trainable kernels → Circuit templates: builds circuits (evidence: `quask/template_pennylane.py`)
- Classical kernels → Gram matrices: computes matrices (evidence: `README.md`)
- Quantum kernels → Gram matrices: computes matrices (evidence: `quask/__main__.py`)
- Trainable kernels → Gram matrices: returns matrices (evidence: `quask/template_pennylane.py`)
- QuASK CLI → Kernel metrics: evaluates metrics (evidence: `quask/__main__.py`)
- Kernel metrics → Performance assessment: assesses performance (evidence: `README.md`)
- Gram matrices → Performance assessment: provides inputs (evidence: `README.md`)
- Kernel metrics → Advantage bounds: supports bounds (evidence: `README.md`)
- Circuit templates → Observable studies: supports observables (evidence: `README.md`)
- Circuit templates → Quantum frameworks: uses PennyLane (evidence: `quask/template_pennylane.py`)