# omkarbihani/quantum-resource-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/omkarbihani/quantum-resource-analysis
- Repository: https://github.com/omkarbihani/quantum-resource-analysis

## Overview

This repository is an experimental toolkit for measuring sparse Pauli decompositions of random operators and matrices arising in Max-Cut SDP solvers. The main workflow runs configured experiments, generates operators or graph instances, invokes IPM/ADMM where applicable, measures matrix and decomposition properties, and saves tabular results; notebooks use those results to create analysis figures. The graph separates the three experiment branches and shared numerical utilities. Notebook behavior is documented in the README; unsampled notebook internals are not inferred.

Main entry points: [`IPM/experiment.py`](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/experiment.py) (Schur Matrix Experiment), [`ADMM/experiment.py`](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/experiment.py) (KKT Matrix Experiment), [`operator_analysis/experiment.py`](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/experiment.py) (Random Operator Scan), [`utils/spd_utils.py`](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/spd_utils.py) (Pauli Decomposition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator Experiments"]
  node_operator_config["Operator Config<br/>[config.py]"]
  node_operator_run["Operator Runner<br/>[run.py]"]
  node_operator_experiment["Random Operator Scan<br/>[experiment.py]"]
  node_operator_results["Operator CSV Results"]
end

subgraph group_ipm["IPM Experiments"]
  node_ipm_config["IPM Config<br/>[config.py]"]
  node_ipm_run["IPM Runner<br/>[run.py]"]
  node_ipm_experiment["Schur Matrix Experiment<br/>[experiment.py]"]
  node_ipm_solver["Primal-Dual IPM<br/>[ipm.py]"]
  node_ipm_results["IPM CSV Results"]
end

subgraph group_admm["ADMM Experiments"]
  node_admm_config["ADMM Config<br/>[config.py]"]
  node_admm_run["ADMM Runner<br/>[run.py]"]
  node_admm_experiment["KKT Matrix Experiment<br/>[experiment.py]"]
  node_admm_solver["ADMM SDP Solver<br/>[admm.py]"]
  node_admm_results["ADMM CSV Results"]
end

subgraph group_shared["Shared Utilities"]
  node_graph_helpers["Graph SDP Helpers<br/>[graph_utils.py]"]
  node_matrix_metrics["Matrix Diagnostics<br/>[matrix_metrics.py]"]
  node_pauli_utils["Pauli Decomposition<br/>[spd_utils.py]"]
end

subgraph group_analysis["Result Analysis"]
  node_operator_notebooks["Operator Analysis"]
  node_ipm_notebooks["IPM Analysis"]
  node_admm_notebooks["ADMM Analysis"]
end

node_researcher(("Experimenter"))

node_researcher -->|"runs"| node_operator_run
node_researcher -->|"runs"| node_ipm_run
node_researcher -->|"runs"| node_admm_run
node_operator_run -->|"loads settings"| node_operator_config
node_operator_run -->|"starts scan"| node_operator_experiment
node_operator_experiment -->|"uses settings"| node_operator_config
node_operator_experiment -->|"generates and measures"| node_pauli_utils
node_operator_experiment -->|"writes CSV"| node_operator_results
node_ipm_run -->|"loads settings"| node_ipm_config
node_ipm_run -->|"starts experiment"| node_ipm_experiment
node_ipm_experiment -->|"uses settings"| node_ipm_config
node_ipm_experiment -->|"builds Laplacian"| node_graph_helpers
node_ipm_experiment -->|"solves SDP"| node_ipm_solver
node_ipm_experiment -->|"measures matrices"| node_matrix_metrics
node_ipm_experiment -->|"decomposes matrices"| node_pauli_utils
node_ipm_experiment -->|"writes CSV"| node_ipm_results
node_admm_run -->|"loads settings"| node_admm_config
node_admm_run -->|"starts experiment"| node_admm_experiment
node_admm_experiment -->|"uses settings"| node_admm_config
node_admm_experiment -->|"builds Laplacian"| node_graph_helpers
node_admm_experiment -->|"solves SDP"| node_admm_solver
node_admm_experiment -->|"measures matrices"| node_matrix_metrics
node_admm_experiment -->|"decomposes matrices"| node_pauli_utils
node_admm_experiment -->|"writes CSV"| node_admm_results
node_pauli_utils -->|"computes condition"| node_matrix_metrics
node_operator_notebooks -->|"reads results"| node_operator_results
node_ipm_notebooks -->|"reads results"| node_ipm_results
node_admm_notebooks -->|"reads results"| node_admm_results

click node_operator_config "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/config.py"
click node_operator_run "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/run.py"
click node_operator_experiment "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/experiment.py"
click node_operator_results "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/operator_analysis/results"
click node_ipm_config "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/config.py"
click node_ipm_run "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/run.py"
click node_ipm_experiment "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/experiment.py"
click node_ipm_solver "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/ipm.py"
click node_ipm_results "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/IPM/results"
click node_admm_config "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/config.py"
click node_admm_run "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/run.py"
click node_admm_experiment "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/experiment.py"
click node_admm_solver "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/admm.py"
click node_admm_results "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/ADMM/results"
click node_graph_helpers "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/graph_utils.py"
click node_matrix_metrics "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/matrix_metrics.py"
click node_pauli_utils "https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/spd_utils.py"
click node_operator_notebooks "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/operator_analysis/notebooks"
click node_ipm_notebooks "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/IPM/notebooks"
click node_admm_notebooks "https://github.com/omkarbihani/quantum-resource-analysis/tree/main/ADMM/notebooks"

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_operator_config,node_operator_run,node_operator_experiment,node_operator_results toneBlue
class node_ipm_config,node_ipm_run,node_ipm_experiment,node_ipm_solver,node_ipm_results toneAmber
class node_admm_config,node_admm_run,node_admm_experiment,node_admm_solver,node_admm_results toneMint
class node_graph_helpers,node_matrix_metrics,node_pauli_utils toneRose
class node_operator_notebooks,node_ipm_notebooks,node_admm_notebooks,node_researcher toneIndigo
```

## Components

### Operator Experiments

- [Operator Config](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/config.py): `operator_analysis/config.py`
- [Operator Runner](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/run.py): `operator_analysis/run.py`
- [Random Operator Scan](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/operator_analysis/experiment.py): `operator_analysis/experiment.py`
- [Operator CSV Results](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/operator_analysis/results): `operator_analysis/results`

### IPM Experiments

- [IPM Config](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/config.py): `IPM/config.py`
- [IPM Runner](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/run.py): `IPM/run.py`
- [Schur Matrix Experiment](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/experiment.py): `IPM/experiment.py`
- [Primal-Dual IPM](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/IPM/ipm.py): `IPM/ipm.py`
- [IPM CSV Results](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/IPM/results): `IPM/results`

### ADMM Experiments

- [ADMM Config](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/config.py): `ADMM/config.py`
- [ADMM Runner](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/run.py): `ADMM/run.py`
- [KKT Matrix Experiment](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/experiment.py): `ADMM/experiment.py`
- [ADMM SDP Solver](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/ADMM/admm.py): `ADMM/admm.py`
- [ADMM CSV Results](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/ADMM/results): `ADMM/results`

### Shared Utilities

- [Graph SDP Helpers](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/graph_utils.py): `utils/graph_utils.py`
- [Matrix Diagnostics](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/matrix_metrics.py): `utils/matrix_metrics.py`
- [Pauli Decomposition](https://github.com/omkarbihani/quantum-resource-analysis/blob/main/utils/spd_utils.py): `utils/spd_utils.py`

### Result Analysis

- [Operator Analysis](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/operator_analysis/notebooks): `operator_analysis/notebooks`
- [IPM Analysis](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/IPM/notebooks): `IPM/notebooks`
- [ADMM Analysis](https://github.com/omkarbihani/quantum-resource-analysis/tree/main/ADMM/notebooks): `ADMM/notebooks`

### Other components

- **Experimenter**

## Connections

- Experimenter → Operator Runner: runs (evidence: `README.md`)
- Experimenter → IPM Runner: runs (evidence: `README.md`)
- Experimenter → ADMM Runner: runs (evidence: `README.md`)
- Operator Runner → Operator Config: loads settings (evidence: `operator_analysis/run.py`)
- Operator Runner → Random Operator Scan: starts scan (evidence: `operator_analysis/run.py`)
- Random Operator Scan → Operator Config: uses settings (evidence: `operator_analysis/experiment.py`)
- Random Operator Scan → Pauli Decomposition: generates and measures (evidence: `operator_analysis/experiment.py`)
- Random Operator Scan → Operator CSV Results: writes CSV (evidence: `operator_analysis/experiment.py`)
- IPM Runner → IPM Config: loads settings (evidence: `IPM/run.py`)
- IPM Runner → Schur Matrix Experiment: starts experiment (evidence: `IPM/run.py`)
- Schur Matrix Experiment → IPM Config: uses settings (evidence: `IPM/experiment.py`)
- Schur Matrix Experiment → Graph SDP Helpers: builds Laplacian (evidence: `IPM/experiment.py`)
- Schur Matrix Experiment → Primal-Dual IPM: solves SDP (evidence: `IPM/experiment.py`)
- Schur Matrix Experiment → Matrix Diagnostics: measures matrices (evidence: `IPM/experiment.py`)
- Schur Matrix Experiment → Pauli Decomposition: decomposes matrices (evidence: `IPM/experiment.py`)
- Schur Matrix Experiment → IPM CSV Results: writes CSV (evidence: `IPM/experiment.py`)
- ADMM Runner → ADMM Config: loads settings (evidence: `ADMM/run.py`)
- ADMM Runner → KKT Matrix Experiment: starts experiment (evidence: `ADMM/run.py`)
- KKT Matrix Experiment → ADMM Config: uses settings (evidence: `ADMM/experiment.py`)
- KKT Matrix Experiment → Graph SDP Helpers: builds Laplacian (evidence: `ADMM/experiment.py`)
- KKT Matrix Experiment → ADMM SDP Solver: solves SDP (evidence: `ADMM/experiment.py`)
- KKT Matrix Experiment → Matrix Diagnostics: measures matrices (evidence: `ADMM/experiment.py`)
- KKT Matrix Experiment → Pauli Decomposition: decomposes matrices (evidence: `ADMM/experiment.py`)
- KKT Matrix Experiment → ADMM CSV Results: writes CSV (evidence: `ADMM/experiment.py`)
- Pauli Decomposition → Matrix Diagnostics: computes condition (evidence: `utils/spd_utils.py`)
- Operator Analysis → Operator CSV Results: reads results (evidence: `README.md`)
- IPM Analysis → IPM CSV Results: reads results (evidence: `README.md`)
- ADMM Analysis → ADMM CSV Results: reads results (evidence: `README.md`)
