# sebwouters/pydmet architecture

> Architecture diagram of the GitHub repository sebwouters/pydmet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebwouters/pydmet
- Repository: https://github.com/sebwouters/pydmet

## Overview

##### Project type and purpose
- PyDMET is a domain‐specific, scientific computing library and CLI tool written in Python.
- Its purpose is to implement density matrix embedding theory (DMET) workflows: setting up model Hamiltonians, performing embedding, solving correlated sub‐problems (via CheMPS2), and computing observables such as local density of states (LDOS) or density–density response (LDDR).

##### File structure
- Top‐level scripts:
- start.py, LDOS1D.py, LDOS2D.py, LDDR2D.py – user‐facing entry points for different calculations.
- preloadmkl.sh – environment setup for Intel MKL.
- “src” directory: core library modules:
- Hamiltonian builders (HamFull.py, HamInterface.py, HubbardDMET.py)
- DMET algorithm drivers (DMETham.py, DMETorbitals.py, InsulatingPMguess.py)
- Numerical tools (DIIS.py, LinalgWrappers.py, MinimizeCostFunction.py)
- Correlated‐solver interface (SolveCorrelated.py)
- Configuration/metadata: .gitignore, LICENSE, README.md.

##### Insights from README
- Dependencies: Python, SciPy, libchemps2 (PyCheMPS2).
- Execution flow: “Start from start.py; LDOS2D.py; LDOS1D.py; LDDR2D.py and adjust these files to start using PyDMET.”

a. Main components
1. User Interface Layer (entry‐point scripts)
2. Core DMET Engine (the “src” modules)
3. External Numerical Libraries
– Python interpreter + SciPy stack (BLAS/LAPACK, MKL)
– libchemps2 (external C++ library)
4. Data / File I/O (input parameter files, result files)
b. Relationships and interactions
- Entry‐point scripts call high‐level DMET routines in src/ (e.g., instantiate HubbardDMET, build Hamiltonian, call SolveCorrelated).
- DMET Engine modules orchestrate:
– Hamiltonian construction → HamFull/HamInterface
– Orbital selection and embedding → DMETham, DMETorbitals, InsulatingPMguess
– Iterative solver accelerators → DIIS, MinimizeCostFunction
– Correlated sub‐problem via SolveCorrelated → bridges to libchemps2
- Core numerical routines delegate to LinalgWrappers (SciPy/MKL).
- Results (LDOS, LDDR) produced and written by scripts.
c. Architectural patterns and design principles
– Modular layering: UI layer separated from core algorithm modules.
– Plugin‐style solver interface: external C++ solver (CheMPS2) is abstracted behind SolveCorrelated.py.
– Iterative‐algorithm pattern: DIIS for convergence acceleration.
d. Key technologies/frameworks
– Python 3.x, SciPy, NumPy
– Intel MKL (optional, via preloadmkl.sh)
– C++ CheMPS2 library (exposed through PyCheMPS2)
– Git for version control

##### Detail
- Major data flows: “1-electron integrals”, “embedding potentials”, “correlated wavefunction”, “LDOS output.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        start["start.py"]:::ui
        LDOS1D["LDOS1D.py"]:::ui
        LDOS2D["LDOS2D.py"]:::ui
        LDDR2D["LDDR2D.py"]:::ui
    end

    %% Core DMET Engine
    subgraph "Core DMET Engine"
        direction TB

        subgraph "Hamiltonian Construction"
            HamFull["HamFull"]:::core
            HamInterface["HamInterface"]:::core
            HubbardDMET["HubbardDMET"]:::core
        end

        subgraph "Embedding & Orbital Selection"
            DMETham["DMETham"]:::core
            DMETorbitals["DMETorbitals"]:::core
            InsulatingPMguess["InsulatingPMguess"]:::core
        end

        subgraph "Iterative Solver Acceleration"
            DIIS["DIIS"]:::core
            MinimizeCostFunction["MinimizeCostFunction"]:::core
        end

        LinalgWrappers["LinalgWrappers"]:::core
        SolveCorrelated["SolveCorrelated"]:::core
    end

    %% Data / File I/O
    Results["Result Files"]:::data
    Inputs["Input Parameter Files"]:::data

    %% External Dependencies
    preloadMKL["preloadmkl.sh"]:::ext
    SciPyMKL["SciPy/MKL"]:::ext
    CheMPS2["libchemps2"]:::ext

    %% Connections: UI to Core
    start -->|calls| HubbardDMET
    LDOS1D -->|calls| HubbardDMET
    LDOS2D -->|calls| HubbardDMET
    LDDR2D -->|calls| HubbardDMET

    %% Core orchestration
    HubbardDMET -->|builds| HamFull
    HubbardDMET -->|interfaces| HamInterface
    HubbardDMET -->|orchestrates| DMETham

    DMETham -->|selects orbitals| DMETorbitals
    DMETham -->|initial guess| InsulatingPMguess

    HubbardDMET -->|accelerates| DIIS
    DIIS -->|uses| MinimizeCostFunction
    MinimizeCostFunction -->|feedback| HamInterface

    HubbardDMET -->|delegates LA| LinalgWrappers
    LinalgWrappers -->|calls| SciPyMKL

    HubbardDMET -->|solves| SolveCorrelated
    SolveCorrelated -->|plugin| CheMPS2

    %% Core to Data I/O
    HubbardDMET -->|reads| Inputs
    HubbardDMET -->|writes| Results
    start -->|reads| Inputs
    start -->|writes| Results

    %% External setup
    preloadMKL -->|prepares| SciPyMKL

    %% Click Events
    click start "https://github.com/sebwouters/pydmet/blob/master/start.py"
    click LDOS1D "https://github.com/sebwouters/pydmet/blob/master/LDOS1D.py"
    click LDOS2D "https://github.com/sebwouters/pydmet/blob/master/LDOS2D.py"
    click LDDR2D "https://github.com/sebwouters/pydmet/blob/master/LDDR2D.py"
    click HamFull "https://github.com/sebwouters/pydmet/blob/master/src/HamFull.py"
    click HamInterface "https://github.com/sebwouters/pydmet/blob/master/src/HamInterface.py"
    click HubbardDMET "https://github.com/sebwouters/pydmet/blob/master/src/HubbardDMET.py"
    click DMETham "https://github.com/sebwouters/pydmet/blob/master/src/DMETham.py"
    click DMETorbitals "https://github.com/sebwouters/pydmet/blob/master/src/DMETorbitals.py"
    click InsulatingPMguess "https://github.com/sebwouters/pydmet/blob/master/src/InsulatingPMguess.py"
    click DIIS "https://github.com/sebwouters/pydmet/blob/master/src/DIIS.py"
    click MinimizeCostFunction "https://github.com/sebwouters/pydmet/blob/master/src/MinimizeCostFunction.py"
    click LinalgWrappers "https://github.com/sebwouters/pydmet/blob/master/src/LinalgWrappers.py"
    click SolveCorrelated "https://github.com/sebwouters/pydmet/blob/master/src/SolveCorrelated.py"
    click preloadMKL "https://github.com/sebwouters/pydmet/blob/master/preloadmkl.sh"

    %% Styles
    classDef ui fill:#a8d0e6,stroke:#000,stroke-width:1px
    classDef core fill:#b8e994,stroke:#000,stroke-width:1px
    classDef ext fill:#ffcc80,stroke:#000,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#000,stroke-width:1px
```
