# akshayuttarkarc/qupepfold architecture

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

- Interactive diagram: https://gitdiagram.com/akshayuttarkarc/qupepfold
- Repository: https://github.com/akshayuttarkarc/qupepfold

## Overview

QuPepFold is a command-line peptide-folding simulator: a user supplies an amino-acid sequence and run options, and the CLI maps the sequence to qubits, runs CVaR-VQE, evaluates the resulting bitstring distribution, and can export reports, plots, and 3D PDB structures. The core module also covers the distinct mapping, energy, circuit, simulation, and structure-generation stages. The CLI and selected core routines are sampled; some internal optimizer wiring is described by the package documentation rather than shown in the excerpts.

Main entry points: [`QuPepFold/qupepfold/cli.py`](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py) (CLI orchestration), [`QuPepFold/qupepfold/qupepfold.py`](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py) (State probabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI workflow"]
  node_cli["CLI orchestration<br/>[cli.py]"]
end

subgraph group_quantum["Quantum folding"]
  node_mapping["Qubit mapping<br/>[qupepfold.py]"]
  node_interactions["MJ interactions<br/>[qupepfold.py]"]
  node_ansatz["Ansatz circuit<br/>[qupepfold.py]"]
  node_optimizer["CVaR optimizer<br/>[qupepfold.py]"]
  node_objective["CVaR objective<br/>[qupepfold.py]"]
  node_hamiltonian["Energy evaluation<br/>[qupepfold.py]"]
  node_probabilities["State probabilities<br/>[qupepfold.py]"]
end

subgraph group_structure["Structure export"]
  node_structure["3D backbone builder<br/>[qupepfold.py]"]
  node_pdb["PDB exporter<br/>[qupepfold.py]"]
end

subgraph group_results["Result outputs"]
  node_reporting["Summary and CSV<br/>[cli.py]"]
  node_visualization["Plots and circuit<br/>[cli.py]"]
  node_breakdown["Energy breakdown<br/>[qupepfold.py]"]
end

node_user(("CLI user"))
node_simulator["Aer simulator"]
node_output["Output directory"]

node_user -->|"provides options"| node_cli
node_cli -->|"maps sequence"| node_mapping
node_cli -->|"builds matrix"| node_interactions
node_cli -->|"optimizes"| node_optimizer
node_optimizer -->|"evaluates circuit"| node_ansatz
node_optimizer -->|"minimizes"| node_objective
node_objective -->|"requests probabilities"| node_probabilities
node_objective -->|"scores states"| node_hamiltonian
node_hamiltonian -->|"reads energies"| node_interactions
node_probabilities -->|"simulates"| node_ansatz
node_probabilities -->|"runs statevector"| node_simulator
node_cli -->|"builds optimum circuit"| node_ansatz
node_cli -->|"computes distribution"| node_probabilities
node_cli -->|"evaluates states"| node_hamiltonian
node_cli -->|"writes summaries"| node_reporting
node_cli -->|"renders results"| node_visualization
node_cli -->|"requests breakdown"| node_breakdown
node_cli -->|"exports folds"| node_pdb
node_pdb -->|"builds coordinates"| node_structure
node_reporting -->|"writes files"| node_output
node_visualization -->|"writes images"| node_output
node_breakdown -->|"writes analysis"| node_output
node_pdb -->|"writes PDBs"| node_output

click node_cli "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py"
click node_mapping "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_interactions "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_ansatz "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_optimizer "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_objective "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_hamiltonian "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_probabilities "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_structure "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_pdb "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py"
click node_reporting "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py"
click node_visualization "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py"
click node_breakdown "https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.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_user toneBlue
class node_mapping,node_interactions,node_ansatz,node_optimizer,node_objective,node_hamiltonian,node_probabilities toneAmber
class node_structure,node_pdb toneMint
class node_reporting,node_visualization,node_breakdown toneRose
class node_simulator,node_output toneIndigo
```

## Components

### CLI workflow

- [CLI orchestration](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py): `QuPepFold/qupepfold/cli.py`

### Quantum folding

- [Qubit mapping](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [MJ interactions](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [Ansatz circuit](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [CVaR optimizer](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [CVaR objective](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [Energy evaluation](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [State probabilities](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`

### Structure export

- [3D backbone builder](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`
- [PDB exporter](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`

### Result outputs

- [Summary and CSV](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py): `QuPepFold/qupepfold/cli.py`
- [Plots and circuit](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/cli.py): `QuPepFold/qupepfold/cli.py`
- [Energy breakdown](https://github.com/akshayuttarkarc/qupepfold/blob/main/QuPepFold/qupepfold/qupepfold.py): `QuPepFold/qupepfold/qupepfold.py`

### Other components

- **CLI user**
- **Aer simulator**
- **Output directory**

## Connections

- CLI user → CLI orchestration: provides options
- CLI orchestration → Qubit mapping: maps sequence
- CLI orchestration → MJ interactions: builds matrix
- CLI orchestration → CVaR optimizer: optimizes
- CVaR optimizer → Ansatz circuit: evaluates circuit
- CVaR optimizer → CVaR objective: minimizes
- CVaR objective → State probabilities: requests probabilities
- CVaR objective → Energy evaluation: scores states
- Energy evaluation → MJ interactions: reads energies
- State probabilities → Ansatz circuit: simulates
- State probabilities → Aer simulator: runs statevector
- CLI orchestration → Ansatz circuit: builds optimum circuit
- CLI orchestration → State probabilities: computes distribution
- CLI orchestration → Energy evaluation: evaluates states
- CLI orchestration → Summary and CSV: writes summaries
- CLI orchestration → Plots and circuit: renders results
- CLI orchestration → Energy breakdown: requests breakdown
- CLI orchestration → PDB exporter: exports folds
- PDB exporter → 3D backbone builder: builds coordinates
- Summary and CSV → Output directory: writes files
- Plots and circuit → Output directory: writes images
- Energy breakdown → Output directory: writes analysis
- PDB exporter → Output directory: writes PDBs