# xenofon-chiotopoulos/onebqf architecture

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

- Interactive diagram: https://gitdiagram.com/xenofon-chiotopoulos/onebqf
- Repository: https://github.com/xenofon-chiotopoulos/onebqf

## Overview

OneBQF is a research codebase for quantum-filter-based particle tracking. The documented workflow generates synthetic detector events, constructs a Hamiltonian tracking problem, applies a quantum linear-system algorithm, and evaluates measured solutions; a separate toy workflow aggregates reconstruction metrics. The README also describes circuit-complexity and noisy-hardware fidelity analyses. Notebook internals and unsampled subsystem wiring are not verified, so those connections are shown only where documentation supports them.

Main entry points: [`example.ipynb`](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/example.ipynb) (Example Workflow), [`data`](https://github.com/xenofon-chiotopoulos/onebqf/tree/main/data) (Experiment Results), [`plotting_notebooks/plot_fidelity_results.ipynb`](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_fidelity_results.ipynb) (Fidelity Analysis), [`quantum_algorithms/HHL.py`](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/quantum_algorithms/HHL.py) (HHL Solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Event Simulation"]
  node_stategen["State Event Generator"]
  node_scattergen["Scattering Generator"]
  node_eventmodel["Event Model"]
  node_velo["VELO Workflow<br/>[velo_workflow.py]"]
end

subgraph group_tracking["Tracking Model"]
  node_hamiltonian["Hamiltonian API<br/>[hamiltonian.py]"]
  node_simpleham["Simple Hamiltonian"]
  node_validator["Track Validator<br/>[toy_validator.py]"]
end

subgraph group_quantum["Quantum Solvers"]
  node_example["Example Workflow<br/>[example.ipynb]"]
  node_hhl["HHL Solver<br/>[HHL.py]"]
  node_onebqf["OneBQF Solver<br/>[OneBQF.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_complexity["Complexity Analysis"]
  node_fidelity["Fidelity Analysis"]
  node_segments["Segment Analysis"]
  node_eventdisplay["Event Display"]
  node_results["Experiment Results"]
end

node_researcher(("Researcher"))
node_simulator["Quantum Simulator"]
node_hardware["Quantum Hardware"]
node_quantinuum["Quantinuum Emulators"]

node_researcher -->|"runs"| node_example
node_example -->|"generates events"| node_stategen
node_example -->|"generates events"| node_scattergen
node_stategen -->|"creates records"| node_eventmodel
node_scattergen -->|"creates records"| node_eventmodel
node_velo -->|"generates events"| node_stategen
node_velo -->|"computes metrics"| node_validator
node_example -->|"constructs problem"| node_simpleham
node_simpleham -->|"implements"| node_hamiltonian
node_example -->|"solves problem"| node_hhl
node_example -->|"solves problem"| node_onebqf
node_hhl -->|"runs circuit"| node_simulator
node_onebqf -->|"runs circuit"| node_simulator
node_hhl -->|"returns solution"| node_example
node_onebqf -->|"returns solution"| node_example
node_example -->|"records results"| node_results
node_complexity -->|"analyzes metrics"| node_results
node_fidelity -->|"analyzes fidelity"| node_results
node_segments -->|"analyzes efficiency"| node_results
node_eventdisplay -->|"visualizes events"| node_eventmodel
node_fidelity -.->|"uses noise models"| node_hardware
node_fidelity -.->|"compiles and runs"| node_quantinuum

click node_example "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/example.ipynb"
click node_stategen "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/state_event_generator.py"
click node_scattergen "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/multi_scattering_generator.py"
click node_eventmodel "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/state_event_model.py"
click node_velo "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/velo_workflow.py"
click node_hamiltonian "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/hamiltonian.py"
click node_simpleham "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/simple_hamiltonian.py"
click node_validator "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/toy_validator.py"
click node_hhl "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/quantum_algorithms/HHL.py"
click node_onebqf "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/quantum_algorithms/OneBQF.py"
click node_complexity "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plotting_complexity_figure4.ipynb"
click node_fidelity "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_fidelity_results.ipynb"
click node_segments "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_segement_analysis.ipynb"
click node_eventdisplay "https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_event_display.ipynb"
click node_results "https://github.com/xenofon-chiotopoulos/onebqf/tree/main/data"

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_stategen,node_scattergen,node_eventmodel,node_velo toneBlue
class node_hamiltonian,node_simpleham,node_validator toneAmber
class node_example,node_hhl,node_onebqf toneMint
class node_complexity,node_fidelity,node_segments,node_eventdisplay,node_results toneRose
class node_researcher,node_simulator,node_hardware,node_quantinuum toneIndigo
```

## Components

### Event Simulation

- [State Event Generator](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/state_event_generator.py): `toy_model/state_event_generator.py`
- [Scattering Generator](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/multi_scattering_generator.py): `toy_model/multi_scattering_generator.py`
- [Event Model](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/state_event_model.py): `toy_model/state_event_model.py`
- [VELO Workflow](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/velo_workflow.py): `toy_model/velo_workflow.py`

### Tracking Model

- [Hamiltonian API](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/hamiltonian.py): `toy_model/hamiltonian.py`
- [Simple Hamiltonian](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/simple_hamiltonian.py): `toy_model/simple_hamiltonian.py`
- [Track Validator](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/toy_model/toy_validator.py): `toy_model/toy_validator.py`

### Quantum Solvers

- [Example Workflow](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/example.ipynb): `example.ipynb`
- [HHL Solver](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/quantum_algorithms/HHL.py): `quantum_algorithms/HHL.py`
- [OneBQF Solver](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/quantum_algorithms/OneBQF.py): `quantum_algorithms/OneBQF.py`

### Evaluation

- [Complexity Analysis](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plotting_complexity_figure4.ipynb): `plotting_notebooks/plotting_complexity_figure4.ipynb`
- [Fidelity Analysis](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_fidelity_results.ipynb): `plotting_notebooks/plot_fidelity_results.ipynb`
- [Segment Analysis](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_segement_analysis.ipynb): `plotting_notebooks/plot_segement_analysis.ipynb`
- [Event Display](https://github.com/xenofon-chiotopoulos/onebqf/blob/main/plotting_notebooks/plot_event_display.ipynb): `plotting_notebooks/plot_event_display.ipynb`
- [Experiment Results](https://github.com/xenofon-chiotopoulos/onebqf/tree/main/data): `data`

### Other components

- **Researcher**
- **Quantum Simulator**
- **Quantum Hardware**
- **Quantinuum Emulators**

## Connections

- Researcher → Example Workflow: runs
- Example Workflow → State Event Generator: generates events
- Example Workflow → Scattering Generator: generates events
- State Event Generator → Event Model: creates records
- Scattering Generator → Event Model: creates records
- VELO Workflow → State Event Generator: generates events
- VELO Workflow → Track Validator: computes metrics
- Example Workflow → Simple Hamiltonian: constructs problem
- Simple Hamiltonian → Hamiltonian API: implements
- Example Workflow → HHL Solver: solves problem
- Example Workflow → OneBQF Solver: solves problem
- HHL Solver → Quantum Simulator: runs circuit
- OneBQF Solver → Quantum Simulator: runs circuit
- HHL Solver → Example Workflow: returns solution
- OneBQF Solver → Example Workflow: returns solution
- Example Workflow → Experiment Results: records results
- Complexity Analysis → Experiment Results: analyzes metrics
- Fidelity Analysis → Experiment Results: analyzes fidelity
- Segment Analysis → Experiment Results: analyzes efficiency
- Event Display → Event Model: visualizes events
- Fidelity Analysis → Quantum Hardware: uses noise models
- Fidelity Analysis → Quantinuum Emulators: compiles and runs