# cern-qti/quask architecture

> Architecture diagram of the GitHub repository cern-qti/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/cern-qti/quask
- Repository: https://github.com/cern-qti/quask

## Overview

QuASK is a Python library for constructing quantum kernels, evaluating their properties, and searching for improved kernels. The principal workflow is to define an operation-based ansatz and kernel, execute it through a quantum backend, measure kernel quality, then optionally optimize the kernel. The README also identifies multiple SDK backends and evaluation criteria as major capabilities. The graph represents these stages and the documented capabilities; links without a shown caller or explicit README relationship are omitted rather than inferred.

Main entry points: [`src/quask/evaluator/kernel_evaluator.py`](https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/kernel_evaluator.py) (Kernel evaluator), [`src/quask/core/ansatz.py`](https://github.com/cern-qti/quask/blob/main/src/quask/core/ansatz.py) (Ansatz), [`src/quask/core_implementation`](https://github.com/cern-qti/quask/tree/main/src/quask/core_implementation) (Backend selection), [`src/quask/core/kernel.py`](https://github.com/cern-qti/quask/blob/main/src/quask/core/kernel.py) (Kernel model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel_design["Kernel design"]
  node_operations["Operations<br/>[operation.py]"]
  node_ansatz["Ansatz<br/>[ansatz.py]"]
  node_kernel["Kernel model<br/>[kernel.py]"]
  node_factory["Kernel factory<br/>[kernel_factory.py]"]
end

subgraph group_execution["Quantum execution"]
  node_backend_select["Backend selection"]
  node_pennylane["PennyLane backend"]
  node_qiskit["Qiskit backend<br/>[qiskit_kernel.py]"]
  node_braket["Braket backend<br/>[braket_kernel.py]"]
  node_qibo["Qibo backend<br/>[qibo_kernel.py]"]
end

subgraph group_analysis["Kernel analysis"]
  node_kernel_eval["Kernel evaluator"]
  node_alignment["Alignment measures"]
  node_expressibility["Expressibility measures"]
  node_generalization["Generalization measures"]
  node_spectral["Spectral bias"]
  node_complexity["Complexity measures"]
end

subgraph group_search["Kernel search"]
  node_optimizer_base["Optimizer interface"]
  node_optimizer_methods["Search strategies"]
  node_wide_env["Wide-kernel environment"]
end

node_user(("Library user"))

node_user -->|"defines"| node_ansatz
node_user -->|"constructs"| node_kernel
node_ansatz -->|"contains"| node_operations
node_kernel -->|"uses"| node_ansatz
node_kernel -->|"restores through"| node_factory
node_backend_select -->|"offers"| node_pennylane
node_backend_select -->|"offers"| node_qiskit
node_backend_select -->|"offers"| node_braket
node_backend_select -->|"offers"| node_qibo
node_qiskit -->|"encodes"| node_ansatz
node_pennylane -->|"executes"| node_ansatz
node_braket -->|"extends"| node_pennylane
node_user -->|"evaluates"| node_kernel_eval
node_kernel_eval -->|"includes"| node_alignment
node_kernel_eval -->|"includes"| node_expressibility
node_kernel_eval -->|"includes"| node_generalization
node_kernel_eval -->|"includes"| node_spectral
node_kernel_eval -->|"includes"| node_complexity
node_user -->|"optimizes"| node_optimizer_methods
node_optimizer_methods -->|"implements"| node_optimizer_base
node_optimizer_methods -->|"uses"| node_wide_env
node_wide_env -->|"scores"| node_kernel_eval
node_wide_env -->|"updates"| node_ansatz

click node_operations "https://github.com/cern-qti/quask/blob/main/src/quask/core/operation.py"
click node_ansatz "https://github.com/cern-qti/quask/blob/main/src/quask/core/ansatz.py"
click node_kernel "https://github.com/cern-qti/quask/blob/main/src/quask/core/kernel.py"
click node_factory "https://github.com/cern-qti/quask/blob/main/src/quask/core/kernel_factory.py"
click node_backend_select "https://github.com/cern-qti/quask/tree/main/src/quask/core_implementation"
click node_pennylane "https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/pennylane_kernel.py"
click node_qiskit "https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/qiskit_kernel.py"
click node_braket "https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/braket_kernel.py"
click node_qibo "https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/qibo_kernel.py"
click node_kernel_eval "https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/kernel_evaluator.py"
click node_alignment "https://github.com/cern-qti/quask/tree/main/src/quask/evaluator"
click node_expressibility "https://github.com/cern-qti/quask/tree/main/src/quask/evaluator"
click node_generalization "https://github.com/cern-qti/quask/tree/main/src/quask/evaluator"
click node_spectral "https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/spectral_bias_evaluator.py"
click node_complexity "https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/ess_model_complexity_evaluator.py"
click node_optimizer_base "https://github.com/cern-qti/quask/blob/main/src/quask/optimizer/base_kernel_optimizer.py"
click node_optimizer_methods "https://github.com/cern-qti/quask/tree/main/src/quask/optimizer"
click node_wide_env "https://github.com/cern-qti/quask/blob/main/src/quask/optimizer/wide_kernel_environment.py"

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_operations,node_ansatz,node_kernel,node_factory,node_user toneBlue
class node_backend_select,node_pennylane,node_qiskit,node_braket,node_qibo toneAmber
class node_kernel_eval,node_alignment,node_expressibility,node_generalization,node_spectral,node_complexity toneMint
class node_optimizer_base,node_optimizer_methods,node_wide_env toneRose
```

## Components

### Kernel design

- [Operations](https://github.com/cern-qti/quask/blob/main/src/quask/core/operation.py): `src/quask/core/operation.py`
- [Ansatz](https://github.com/cern-qti/quask/blob/main/src/quask/core/ansatz.py): `src/quask/core/ansatz.py`
- [Kernel model](https://github.com/cern-qti/quask/blob/main/src/quask/core/kernel.py): `src/quask/core/kernel.py`
- [Kernel factory](https://github.com/cern-qti/quask/blob/main/src/quask/core/kernel_factory.py): `src/quask/core/kernel_factory.py`

### Quantum execution

- [Backend selection](https://github.com/cern-qti/quask/tree/main/src/quask/core_implementation): `src/quask/core_implementation`
- [PennyLane backend](https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/pennylane_kernel.py): `src/quask/core_implementation/pennylane_kernel.py`
- [Qiskit backend](https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/qiskit_kernel.py): `src/quask/core_implementation/qiskit_kernel.py`
- [Braket backend](https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/braket_kernel.py): `src/quask/core_implementation/braket_kernel.py`
- [Qibo backend](https://github.com/cern-qti/quask/blob/main/src/quask/core_implementation/qibo_kernel.py): `src/quask/core_implementation/qibo_kernel.py`

### Kernel analysis

- [Kernel evaluator](https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/kernel_evaluator.py): `src/quask/evaluator/kernel_evaluator.py`
- [Alignment measures](https://github.com/cern-qti/quask/tree/main/src/quask/evaluator): `src/quask/evaluator`
- [Expressibility measures](https://github.com/cern-qti/quask/tree/main/src/quask/evaluator): `src/quask/evaluator`
- [Generalization measures](https://github.com/cern-qti/quask/tree/main/src/quask/evaluator): `src/quask/evaluator`
- [Spectral bias](https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/spectral_bias_evaluator.py): `src/quask/evaluator/spectral_bias_evaluator.py`
- [Complexity measures](https://github.com/cern-qti/quask/blob/main/src/quask/evaluator/ess_model_complexity_evaluator.py): `src/quask/evaluator/ess_model_complexity_evaluator.py`

### Kernel search

- [Optimizer interface](https://github.com/cern-qti/quask/blob/main/src/quask/optimizer/base_kernel_optimizer.py): `src/quask/optimizer/base_kernel_optimizer.py`
- [Search strategies](https://github.com/cern-qti/quask/tree/main/src/quask/optimizer): `src/quask/optimizer`
- [Wide-kernel environment](https://github.com/cern-qti/quask/blob/main/src/quask/optimizer/wide_kernel_environment.py): `src/quask/optimizer/wide_kernel_environment.py`

### Other components

- **Library user**

## Connections

- Library user → Ansatz: defines (evidence: `README.md`)
- Library user → Kernel model: constructs (evidence: `README.md`)
- Ansatz → Operations: contains (evidence: `src/quask/core/ansatz.py`)
- Kernel model → Ansatz: uses (evidence: `src/quask/core/kernel.py`)
- Kernel model → Kernel factory: restores through (evidence: `src/quask/core/kernel.py`)
- Backend selection → PennyLane backend: offers (evidence: `src/quask/core_implementation/__init__.py`)
- Backend selection → Qiskit backend: offers (evidence: `src/quask/core_implementation/__init__.py`)
- Backend selection → Braket backend: offers (evidence: `src/quask/core_implementation/__init__.py`)
- Backend selection → Qibo backend: offers (evidence: `src/quask/core_implementation/__init__.py`)
- Qiskit backend → Ansatz: encodes (evidence: `src/quask/core_implementation/qiskit_kernel.py`)
- PennyLane backend → Ansatz: executes (evidence: `src/quask/core_implementation/pennylane_kernel.py`)
- Braket backend → PennyLane backend: extends (evidence: `src/quask/core_implementation/braket_kernel.py`)
- Library user → Kernel evaluator: evaluates (evidence: `README.md`)
- Kernel evaluator → Alignment measures: includes (evidence: `src/quask/evaluator/__init__.py`)
- Kernel evaluator → Expressibility measures: includes (evidence: `src/quask/evaluator/__init__.py`)
- Kernel evaluator → Generalization measures: includes (evidence: `src/quask/evaluator/__init__.py`)
- Kernel evaluator → Spectral bias: includes (evidence: `src/quask/evaluator/__init__.py`)
- Kernel evaluator → Complexity measures: includes (evidence: `src/quask/evaluator/__init__.py`)
- Library user → Search strategies: optimizes (evidence: `README.md`)
- Search strategies → Optimizer interface: implements (evidence: `src/quask/optimizer/bayesian_optimizer.py`)
- Search strategies → Wide-kernel environment: uses (evidence: `src/quask/optimizer/greedy_optimizer.py`)
- Wide-kernel environment → Kernel evaluator: scores (evidence: `src/quask/optimizer/wide_kernel_environment.py`)
- Wide-kernel environment → Ansatz: updates (evidence: `src/quask/optimizer/wide_kernel_environment.py`)