# dlr-wf/dopyqo architecture

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

- Interactive diagram: https://gitdiagram.com/dlr-wf/dopyqo
- Repository: https://github.com/dlr-wf/dopyqo

## Overview

Dopyqo post-processes Quantum ESPRESSO calculations: it reads saved orbitals and cell data, builds a many-body Hamiltonian, then computes classical or quantum many-body results. It also supports frozen-core and WF-in-DFT embedding, Wannier transformations, gradients, visualization, and Bader-charge analysis. The graph reflects documented capabilities and sampled call sites; several subsystem links use documented behavior because their source was not sampled.

Main entry points: [`dopyqo/scripts/main.py`](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/scripts/main.py) (CLI runner), [`dopyqo/wfc.py`](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/wfc.py) (QE wavefunctions), [`dopyqo/hamiltonian.py`](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py) (Hamiltonian), [`dopyqo/helpers/matrix_elements.py`](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/helpers/matrix_elements.py) (Integral bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["CLI runner<br/>[main.py]"]
end

subgraph group_qe["QE data and integrals"]
  node_wfc["QE wavefunctions<br/>[wfc.py]"]
  node_pseudo["Pseudopotentials<br/>[pseudopot.py]"]
  node_kinetic["Matrix elements"]
  node_ppcalc["Pseudopotential integrals<br/>[calc_pseudo_pot.py]"]
  node_eri["ERI integrals"]
  node_matrices["Integral bundle<br/>[matrix_elements.py]"]
end

subgraph group_theory["Embedding and basis"]
  node_embedding["Embedding potential"]
  node_density["Embedding density<br/>[density.py]"]
  node_hartree["Hartree potential<br/>[hartree.py]"]
  node_xc["XC potential<br/>[xc.py]"]
  node_wannier["Wannier transform<br/>[wannier90.py]"]
end

subgraph group_solvers["Many-body solving"]
  node_hamiltonian["Hamiltonian<br/>[hamiltonian.py]"]
  node_fci["FCI solver<br/>[hamiltonian.py]"]
  node_vqe["VQE solvers<br/>[hamiltonian.py]"]
  node_ccsd["CCSD solver<br/>[hamiltonian.py]"]
end

subgraph group_analysis["Analysis and output"]
  node_gradients["Atomic gradients"]
  node_bader["Bader charges<br/>[cube.py]"]
  node_visualization["Orbital visualization<br/>[plotting.py]"]
  node_results["Energies and results<br/>[main.py]"]
end

node_user(("Researcher"))
node_qe["QE calculation"]
node_pyscf["PySCF"]
node_quantum["Qiskit / TenCirChem"]
node_bader_tool["Bader analysis code"]

node_user -->|"configures"| node_api
node_user -->|"runs"| node_cli
node_qe -->|"provides saved data"| node_wfc
node_api -->|"loads calculation"| node_wfc
node_cli -->|"loads calculation"| node_wfc
node_cli -->|"calculates integrals"| node_kinetic
node_cli -->|"calculates integrals"| node_ppcalc
node_cli -->|"calculates integrals"| node_eri
node_wfc -->|"reads potentials"| node_pseudo
node_kinetic -->|"stores elements"| node_matrices
node_ppcalc -->|"stores elements"| node_matrices
node_eri -->|"stores integrals"| node_matrices
node_cli -->|"constructs"| node_hamiltonian
node_matrices -->|"provides integrals"| node_hamiltonian
node_hamiltonian -->|"solves with"| node_fci
node_hamiltonian -->|"solves with"| node_vqe
node_hamiltonian -->|"solves with"| node_ccsd
node_fci -->|"uses"| node_pyscf
node_ccsd -->|"uses"| node_pyscf
node_vqe -->|"uses"| node_quantum
node_cli -->|"applies embedding"| node_embedding
node_embedding -->|"evaluates Hartree"| node_hartree
node_embedding -->|"evaluates XC"| node_xc
node_embedding -->|"maps orbitals"| node_density
node_wfc -->|"transforms basis"| node_wannier
node_wannier -->|"transforms integrals"| node_matrices
node_wfc -->|"supplies structure"| node_gradients
node_cli -->|"reports"| node_results
node_wfc -.->|"exports density"| node_bader
node_bader -.->|"analyzes charges"| node_bader_tool
node_wfc -->|"provides orbitals"| node_visualization

click node_api "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/__init__.py"
click node_cli "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/scripts/main.py"
click node_wfc "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/wfc.py"
click node_pseudo "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/pseudopot.py"
click node_kinetic "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/calc_matrix_elements.py"
click node_ppcalc "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/calc_pseudo_pot.py"
click node_eri "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/eri_pair_densities.py"
click node_matrices "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/helpers/matrix_elements.py"
click node_hamiltonian "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py"
click node_fci "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py"
click node_vqe "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py"
click node_ccsd "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py"
click node_embedding "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/embedding_potential.py"
click node_density "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/density.py"
click node_hartree "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/hartree.py"
click node_xc "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/xc.py"
click node_wannier "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/wannier90.py"
click node_gradients "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/gradients_atom_positions.py"
click node_bader "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/cube.py"
click node_visualization "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/plotting.py"
click node_results "https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/scripts/main.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_api,node_cli toneBlue
class node_wfc,node_pseudo,node_kinetic,node_ppcalc,node_eri,node_matrices toneAmber
class node_embedding,node_density,node_hartree,node_xc,node_wannier toneMint
class node_hamiltonian,node_fci,node_vqe,node_ccsd toneRose
class node_gradients,node_bader,node_visualization,node_results,node_user,node_qe,node_pyscf,node_quantum,node_bader_tool toneIndigo
```

## Components

### User entry

- [Python API](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/__init__.py): `dopyqo/__init__.py`
- [CLI runner](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/scripts/main.py): `dopyqo/scripts/main.py`

### QE data and integrals

- [QE wavefunctions](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/wfc.py): `dopyqo/wfc.py`
- [Pseudopotentials](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/pseudopot.py): `dopyqo/pseudopot.py`
- [Matrix elements](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/calc_matrix_elements.py): `dopyqo/calc_matrix_elements.py`
- [Pseudopotential integrals](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/calc_pseudo_pot.py): `dopyqo/calc_pseudo_pot.py`
- [ERI integrals](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/eri_pair_densities.py): `dopyqo/eri_pair_densities.py`
- [Integral bundle](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/helpers/matrix_elements.py): `dopyqo/helpers/matrix_elements.py`

### Embedding and basis

- [Embedding potential](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/embedding_potential.py): `dopyqo/embedding/embedding_potential.py`
- [Embedding density](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/density.py): `dopyqo/embedding/density.py`
- [Hartree potential](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/hartree.py): `dopyqo/embedding/hartree.py`
- [XC potential](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/embedding/xc.py): `dopyqo/embedding/xc.py`
- [Wannier transform](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/wannier90.py): `dopyqo/wannier90.py`

### Many-body solving

- [Hamiltonian](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py): `dopyqo/hamiltonian.py`
- [FCI solver](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py): `dopyqo/hamiltonian.py`
- [VQE solvers](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py): `dopyqo/hamiltonian.py`
- [CCSD solver](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/hamiltonian.py): `dopyqo/hamiltonian.py`

### Analysis and output

- [Atomic gradients](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/gradients_atom_positions.py): `dopyqo/gradients_atom_positions.py`
- [Bader charges](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/cube.py): `dopyqo/cube.py`
- [Orbital visualization](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/plotting.py): `dopyqo/plotting.py`
- [Energies and results](https://github.com/dlr-wf/dopyqo/blob/main/dopyqo/scripts/main.py): `dopyqo/scripts/main.py`

### Other components

- **Researcher**
- **QE calculation**
- **PySCF**
- **Qiskit / TenCirChem**
- **Bader analysis code**

## Connections

- Researcher → Python API: configures
- Researcher → CLI runner: runs
- QE calculation → QE wavefunctions: provides saved data
- Python API → QE wavefunctions: loads calculation
- CLI runner → QE wavefunctions: loads calculation
- CLI runner → Matrix elements: calculates integrals
- CLI runner → Pseudopotential integrals: calculates integrals
- CLI runner → ERI integrals: calculates integrals
- QE wavefunctions → Pseudopotentials: reads potentials
- Matrix elements → Integral bundle: stores elements
- Pseudopotential integrals → Integral bundle: stores elements
- ERI integrals → Integral bundle: stores integrals
- CLI runner → Hamiltonian: constructs
- Integral bundle → Hamiltonian: provides integrals
- Hamiltonian → FCI solver: solves with
- Hamiltonian → VQE solvers: solves with
- Hamiltonian → CCSD solver: solves with
- FCI solver → PySCF: uses
- CCSD solver → PySCF: uses
- VQE solvers → Qiskit / TenCirChem: uses
- CLI runner → Embedding potential: applies embedding
- Embedding potential → Hartree potential: evaluates Hartree
- Embedding potential → XC potential: evaluates XC
- Embedding potential → Embedding density: maps orbitals
- QE wavefunctions → Wannier transform: transforms basis
- Wannier transform → Integral bundle: transforms integrals
- QE wavefunctions → Atomic gradients: supplies structure
- CLI runner → Energies and results: reports
- QE wavefunctions → Bader charges: exports density
- Bader charges → Bader analysis code: analyzes charges
- QE wavefunctions → Orbital visualization: provides orbitals