# googolplexing/hpcqc architecture

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

- Interactive diagram: https://gitdiagram.com/googolplexing/hpcqc
- Repository: https://github.com/googolplexing/hpcqc

## Overview

lumi-hpc-qc runs variational quantum experiments on HPC simulators or quantum hardware, and also provides a sweep engine for producing noise-atlas data. The principal workflow is config-driven: the CLI loads a run request, the controller validates plugins and selects a workflow, and the workflow executes through a backend; experiment records and exports support analysis and reproducibility. The README documents SLURM submission, monitoring, checkpointing, and researcher-extensible model and algorithm plugins. Sweep internals beyond the sampled placement-solver construction are not fully evidenced, so uncertain execution links are omitted.

Main entry points: [`src/lumi_hpc_qc/orchestration/workflow.py`](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/workflow.py) (Experiment workflows), [`src/lumi_hpc_qc/orchestration/controller.py`](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/controller.py) (Run controller), [`src/lumi_hpc_qc/cli/main.py`](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/cli/main.py) (Command-line interface), [`src/lumi_hpc_qc/backends/registry.py`](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/registry.py) (Backend registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_orchestration["CLI & orchestration"]
  node_cli["Command-line interface<br/>[main.py]"]
  node_config["Config loading<br/>[config_loader.py]"]
  node_controller["Run controller<br/>[controller.py]"]
  node_workflow["Experiment workflows<br/>[workflow.py]"]
  node_scheduler["SLURM scheduler<br/>[scheduler.py]"]
  node_checkpoint["Checkpoint manager<br/>[checkpoint.py]"]
end

subgraph group_execution["Execution backends"]
  node_backend_registry["Backend registry<br/>[registry.py]"]
  node_sim_backends["Aer CPU/GPU<br/>[aer_cpu.py]"]
  node_qpu_backend["IQM QPU<br/>[iqm_qpu.py]"]
  node_qx_client["QX API client<br/>[qx_client.py]"]
end

subgraph group_research_plugins["Research plugins"]
  node_plugin_registry["Plugin registry<br/>[registry.py]"]
  node_hamiltonians["Hamiltonians"]
  node_ansatze["Ansätze"]
  node_optimization["Optimizers &amp; gradients"]
  node_mitigation["Error mitigation"]
  node_initializers["Parameter initialization"]
end

subgraph group_sweeps["Sweep campaigns"]
  node_sweep_engine["Sweep engine<br/>[sweep_engine.py]"]
  node_placement_solver["QPU placement solver"]
  node_calibration_adapter["Calibration adapters<br/>[iqm_v2.py]"]
end

subgraph group_records["Experiment data"]
  node_hdf5_writer["HDF5 writer<br/>[hdf5_writer.py]"]
  node_experiment_tracker["Experiment tracking<br/>[experiment.py]"]
  node_result_store[("Result store<br/>[result_store.py]")]
  node_export["Data export<br/>[export.py]"]
end

node_user(("Researcher"))
node_slurm["SLURM"]
node_qpu_service["VTT Q50 / QX"]

node_user -->|"invokes"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"runs workflow"| node_controller
node_cli -->|"submits jobs"| node_scheduler
node_scheduler -->|"submits / queries"| node_slurm
node_controller -->|"discovers and validates"| node_plugin_registry
node_controller -->|"discovers"| node_backend_registry
node_controller -->|"selects and runs"| node_workflow
node_controller -->|"resumes from"| node_checkpoint
node_workflow -->|"uses"| node_hamiltonians
node_workflow -->|"uses"| node_ansatze
node_workflow -->|"uses"| node_optimization
node_workflow -->|"uses"| node_initializers
node_workflow -->|"uses"| node_mitigation
node_workflow -->|"selects backend"| node_backend_registry
node_backend_registry -->|"provides"| node_sim_backends
node_backend_registry -->|"provides"| node_qpu_backend
node_qpu_backend -->|"submits circuits"| node_qpu_service
node_qx_client -.->|"queries device and jobs"| node_qpu_service
node_workflow -->|"records experiment"| node_experiment_tracker
node_experiment_tracker -->|"stores results"| node_result_store
node_result_store -->|"exports records"| node_export
node_user -->|"configures sweep"| node_sweep_engine
node_sweep_engine -->|"constructs solver"| node_placement_solver
node_sweep_engine -->|"writes HDF5"| node_hdf5_writer
node_calibration_adapter -.->|"calibration support"| node_sweep_engine

click node_cli "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/cli/main.py"
click node_config "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/cli/config_loader.py"
click node_controller "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/controller.py"
click node_workflow "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/workflow.py"
click node_scheduler "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/scheduler.py"
click node_checkpoint "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/checkpoint.py"
click node_backend_registry "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/registry.py"
click node_sim_backends "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/aer_cpu.py"
click node_qpu_backend "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/iqm_qpu.py"
click node_qx_client "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/qx_client.py"
click node_plugin_registry "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/plugins/registry.py"
click node_hamiltonians "https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/hamiltonians"
click node_ansatze "https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/ansatze"
click node_optimization "https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/optimizers"
click node_mitigation "https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/error_mitigation"
click node_initializers "https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/initializers"
click node_sweep_engine "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/sweep/sweep_engine.py"
click node_placement_solver "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/sweep/placement_solver.py"
click node_calibration_adapter "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/plugins/calibration_adapters/iqm_v2.py"
click node_hdf5_writer "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/hdf5_writer.py"
click node_experiment_tracker "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/experiment.py"
click node_result_store "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/result_store.py"
click node_export "https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/export.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_cli,node_config,node_controller,node_workflow,node_scheduler,node_checkpoint toneBlue
class node_backend_registry,node_sim_backends,node_qpu_backend,node_qx_client toneAmber
class node_plugin_registry,node_hamiltonians,node_ansatze,node_optimization,node_mitigation,node_initializers toneMint
class node_sweep_engine,node_placement_solver,node_calibration_adapter toneRose
class node_hdf5_writer,node_experiment_tracker,node_result_store,node_export,node_user,node_slurm,node_qpu_service toneIndigo
```

## Components

### CLI & orchestration

- [Command-line interface](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/cli/main.py): `src/lumi_hpc_qc/cli/main.py`
- [Config loading](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/cli/config_loader.py): `src/lumi_hpc_qc/cli/config_loader.py`
- [Run controller](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/controller.py): `src/lumi_hpc_qc/orchestration/controller.py`
- [Experiment workflows](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/workflow.py): `src/lumi_hpc_qc/orchestration/workflow.py`
- [SLURM scheduler](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/scheduler.py): `src/lumi_hpc_qc/orchestration/scheduler.py`
- [Checkpoint manager](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/orchestration/checkpoint.py): `src/lumi_hpc_qc/orchestration/checkpoint.py`

### Execution backends

- [Backend registry](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/registry.py): `src/lumi_hpc_qc/backends/registry.py`
- [Aer CPU/GPU](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/aer_cpu.py): `src/lumi_hpc_qc/backends/aer_cpu.py`
- [IQM QPU](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/iqm_qpu.py): `src/lumi_hpc_qc/backends/iqm_qpu.py`
- [QX API client](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/backends/qx_client.py): `src/lumi_hpc_qc/backends/qx_client.py`

### Research plugins

- [Plugin registry](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/plugins/registry.py): `src/lumi_hpc_qc/plugins/registry.py`
- [Hamiltonians](https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/hamiltonians): `src/lumi_hpc_qc/plugins/hamiltonians`
- [Ansätze](https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/ansatze): `src/lumi_hpc_qc/plugins/ansatze`
- [Optimizers & gradients](https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/optimizers): `src/lumi_hpc_qc/plugins/optimizers`
- [Error mitigation](https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/error_mitigation): `src/lumi_hpc_qc/plugins/error_mitigation`
- [Parameter initialization](https://github.com/googolplexing/hpcqc/tree/main/src/lumi_hpc_qc/plugins/initializers): `src/lumi_hpc_qc/plugins/initializers`

### Sweep campaigns

- [Sweep engine](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/sweep/sweep_engine.py): `src/lumi_hpc_qc/sweep/sweep_engine.py`
- [QPU placement solver](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/sweep/placement_solver.py): `src/lumi_hpc_qc/sweep/placement_solver.py`
- [Calibration adapters](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/plugins/calibration_adapters/iqm_v2.py): `src/lumi_hpc_qc/plugins/calibration_adapters/iqm_v2.py`

### Experiment data

- [HDF5 writer](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/hdf5_writer.py): `src/lumi_hpc_qc/data/hdf5_writer.py`
- [Experiment tracking](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/experiment.py): `src/lumi_hpc_qc/data/experiment.py`
- [Result store](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/result_store.py): `src/lumi_hpc_qc/data/result_store.py`
- [Data export](https://github.com/googolplexing/hpcqc/blob/main/src/lumi_hpc_qc/data/export.py): `src/lumi_hpc_qc/data/export.py`

### Other components

- **Researcher**
- **SLURM**
- **VTT Q50 / QX**

## Connections

- Researcher → Command-line interface: invokes
- Command-line interface → Config loading: loads config
- Command-line interface → Run controller: runs workflow
- Command-line interface → SLURM scheduler: submits jobs
- SLURM scheduler → SLURM: submits / queries
- Run controller → Plugin registry: discovers and validates
- Run controller → Backend registry: discovers
- Run controller → Experiment workflows: selects and runs
- Run controller → Checkpoint manager: resumes from
- Experiment workflows → Hamiltonians: uses
- Experiment workflows → Ansätze: uses
- Experiment workflows → Optimizers & gradients: uses
- Experiment workflows → Parameter initialization: uses
- Experiment workflows → Error mitigation: uses
- Experiment workflows → Backend registry: selects backend
- Backend registry → Aer CPU/GPU: provides
- Backend registry → IQM QPU: provides
- IQM QPU → VTT Q50 / QX: submits circuits
- QX API client → VTT Q50 / QX: queries device and jobs
- Experiment workflows → Experiment tracking: records experiment
- Experiment tracking → Result store: stores results
- Result store → Data export: exports records
- Researcher → Sweep engine: configures sweep
- Sweep engine → QPU placement solver: constructs solver
- Sweep engine → HDF5 writer: writes HDF5
- Calibration adapters → Sweep engine: calibration support