# abinit/abipy architecture

> Architecture diagram of the GitHub repository abinit/abipy, 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/abinit/abipy
- Repository: https://github.com/abinit/abipy

## Overview

##### Project type and purpose
- AbiPy is an open‐source Python library that (1) automates and manages workflows for Abinit (a Fortran‐based DFT code), (2) parses and analyzes the Abinit outputs (netCDF, text), and (3) provides plotting and user interfaces (CLI and GUI) for results exploration.

##### Top-level components
A. External Dependencies & Services (gray)
- Abinit executable (shell command)
- Python ecosystem libraries: numpy, scipy, netCDF4, pandas, matplotlib, pymatgen, ipython/jupyter
- HPC job schedulers (SLURM, PBS, etc.) configured via manager.yml
B. Core Library (blue)
1. IO Layer
- abipy.abio: input_tags, inputs, outputs, abivars_db
- abipy.iotools: xsf, cube, visualizer
2. Data Model / Domain Logic
- abipy.core: units, structures, kpoints, symmetries, restapi
- abipy.data: pseudopotentials, CIFs, reference datasets
3. Analysis Modules
- abipy.dfpt: phonons, elastic, QHA
- abipy.electrons: bands, GW, optics
- abipy.eph: electron–phonon coupling
- abipy.dynamics, abipy.embedding, abipy.ml, abipy.waves
4. Workflow Engine
- abipy.flowtk: flows, tasks, scheduler adapters, launcher
5. Visualization & UI
- abipy.display: low‐level plotting utilities
- abipy.panels: GUI widgets (Plotly/Bokeh)
6. Command-Line Scripts
- abicheck.py, abirun.py, abiopen.py, abiview.py, … (in abipy/scripts)
C. Examples, Tests & Documentation (green)
- abipy/examples: ready‐to‐run scripts & notebooks
- abipy/tests & integration_tests: pytest suites
- docs: Sphinx sources, user guides, API references

##### Component relationships and data flows
- Workflow launch: CLI (abirun.py) or Python API → Flowtk Engine → Scheduler Adapter → submit job script to HPC or local shell → invoke Abinit executable.
- Abinit run produces output netCDF/text → IO Layer (abio, iotools) parses files → Domain Model objects (core) → Analysis Modules perform computations → Visualization modules plot or panels GUI updates.
- Data may also flow: Examples → demonstrate API usage → end user / Jupyter notebook.
- External libs supply low‐level functionality (e.g. numpy arrays, pandas DataFrames, matplotlib figures).
- The installer (setup.py, conda) and CI (GitHub Actions, Travis) manage build/test → push docs to GitHub Pages.

##### Architectural patterns & design principles
- Layered architecture: clear separation of IO, domain logic, analysis, workflows, and presentation.
- Plugin / modular structure: each subpackage (dfpt, electrons,… ) can evolve independently.
- Factory pattern: input file generation via abipy.abio.factories.
- Adapter pattern: scheduler adapters decouple Flowtk from specific HPC schedulers.
- Observer / Event pattern: Flowtk events and scheduler error handlers.

##### Essential elements
- All main packages as components.
- External Abinit binary and Python libraries.
- Flow of control from CLI/API down to Abinit and back up to visualization.
- Data stores: pseudopotential files, reference datasets, output netCDF.
- CI/CD and documentation publishing as separate auxiliary components.
- Tests pipeline to show quality‐gate integration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies & Services
    subgraph "External Dependencies & Services"
        direction TB
        AbinitExe(("Abinit Executable")):::external
        PyLibs["Python Libraries\nnumpy, scipy, netCDF4,\npandas, matplotlib,\npymatgen, jupyter"]:::external
        Schedulers["HPC Schedulers\n(manager.yml)"]:::external
    end

    %% Core Library
    subgraph "Core Library"
        direction TB

        subgraph "IO Layer"
            direction TB
            IB["input_tags.py"]:::core
            IN["inputs.py"]:::core
            OB["outputs.py"]:::core
            ABDB["abivars_db.py"]:::core
            FAC["factories.py"]:::core
            subgraph "abipy.iotools"
                direction TB
                XSF["xsf.py"]:::core
                CUBE["cube.py"]:::core
                VIS["visualizer.py"]:::core
            end
        end

        subgraph "Domain Model"
            direction TB
            UNITS["abinit_units.py"]:::core
            STRUCT["structure.py"]:::core
            KPTS["kpoints.py"]:::core
            SYM["symmetries.py"]:::core
            REST["restapi.py"]:::core
            subgraph "abipy.data"
                direction TB
                CIFS["cifs/"]:::core
                PSEUDOS["pseudos/"]:::core
                REFS["refs/"]:::core
            end
        end

        subgraph "Analysis Modules"
            direction TB
            DFPT["abipy.dfpt"]:::core
            ELEC["abipy.electrons"]:::core
            EPH["abipy.eph"]:::core
            DYN["abipy.dynamics"]:::core
            EMB["abipy.embedding"]:::core
            ML["abipy.ml"]:::core
            WAV["abipy.waves"]:::core
        end

        subgraph "Workflow Engine"
            direction TB
            FLOWS["flows.py"]:::core
            TASKS["tasks.py"]:::core
            LAUN["launcher.py"]:::core
            QAD["qadapters.py"]:::core
            ERRH["scheduler_error_handlers.py"]:::core
        end

        subgraph "Visualization & UI"
            direction TB
            UTIL["utils.py"]:::core
            MVTK["mvtk.py"]:::core
            subgraph "abipy.panels"
                direction TB
                PCORE["core.py"]:::core
                PFLOWS["flows.py"]:::core
                PVIEW["viewers.py"]:::core
            end
        end
    end

    %% CLI Tools
    subgraph "Command-Line Interfaces"
        direction TB
        ABIRUN["abirun.py"]:::cli
        ABICHECK["abicheck.py"]:::cli
        ABIOPEN["abiopen.py"]:::cli
        ABIVIEW["abiview.py"]:::cli
    end

    %% Examples, Tests & Documentation
    subgraph "Examples, Tests & Docs"
        direction TB
        EXAMPLES["abipy/examples/"]:::examples
        UNITTESTS["abipy/*/tests/"]:::examples
        INTEGR["abipy/integration_tests/"]:::examples
        DOCS["docs/"]:::examples
    end

    %% CI/CD
    subgraph "CI/CD Workflows"
        direction TB
        GHTEST["test.yml"]:::ci
        GHPAGES["gh-pages.yml"]:::ci
        TRAVIS[".travis.yml"]:::ci
    end

    %% Data & Control Flows
    ABIRUN -->|"control: launch"| FLOWS
    ABICHECK -->|"control: launch"| FLOWS
    ABIOPEN -->|"control: launch"| FLOWS
    ABIVIEW -->|"control: launch"| FLOWS

    FLOWS -->|"uses adapters"| QAD
    QAD -->|"reads config"| Schedulers
    Schedulers -->|"submit job"| AbinitExe

    AbinitExe -->|"netCDF/text output"| IB
    AbinitExe -->|"netCDF/text output"| IN
    IB -->|"Parsed data"| UNITS
    IN -->|"Parsed data"| STRUCT
    OB -->|"Parsed data"| KPTS
    ABDB -->|"Parsed data"| SYM
    XSF -->|"Parsed visual"| UTIL
    CUBE -->|"Parsed visual"| UTIL
    VIS -->|"Parsed visual"| UTIL

    UTIL -->|"low-level plots"| MVTK
    MVTK -->|"figures"| PVIEW

    UNITS -->|"domain objects"| DFPT
    STRUCT -->|"domain objects"| ELEC
    KPTS -->|"domain objects"| EPH
    SYM -->|"domain objects"| DYN
    REST -->|"domain objects"| EMB
    CIFS -->|"datasets"| ML
    PSEUDOS -->|"datasets"| WAV

    DFPT -->|"analysis results"| UTIL
    ELEC -->|"analysis results"| UTIL
    EPH -->|"analysis results"| UTIL

    EXAMPLES -->|"demonstrate API"| FLOWS
    EXAMPLES -->|"demonstrate API"| DFPT

    PyLibs -.-> UNITS
    PyLibs -.-> UTIL
    PyLibs -.-> DFPT

    GHTEST -->|"CI triggers"| UNITTESTS
    TRAVIS -->|"CI triggers"| INTEGR
    GHPAGES -->|"publishes"| DOCS

    %% Click Events
    click Schedulers "https://github.com/abinit/abipy/blob/develop/abipy/data/managers/*.yml"
    click GHTEST "https://github.com/abinit/abipy/blob/develop/.github/workflows/test.yml"
    click GHPAGES "https://github.com/abinit/abipy/blob/develop/.github/workflows/gh-pages.yml"
    click TRAVIS "https://github.com/abinit/abipy/blob/develop/.travis.yml"
    click IB "https://github.com/abinit/abipy/blob/develop/abipy/abio/input_tags.py"
    click IN "https://github.com/abinit/abipy/blob/develop/abipy/abio/inputs.py"
    click OB "https://github.com/abinit/abipy/blob/develop/abipy/abio/outputs.py"
    click ABDB "https://github.com/abinit/abipy/blob/develop/abipy/abio/abivars_db.py"
    click FAC "https://github.com/abinit/abipy/blob/develop/abipy/abio/factories.py"
    click XSF "https://github.com/abinit/abipy/blob/develop/abipy/iotools/xsf.py"
    click CUBE "https://github.com/abinit/abipy/blob/develop/abipy/iotools/cube.py"
    click VIS "https://github.com/abinit/abipy/blob/develop/abipy/iotools/visualizer.py"
    click UNITS "https://github.com/abinit/abipy/blob/develop/abipy/core/abinit_units.py"
    click STRUCT "https://github.com/abinit/abipy/blob/develop/abipy/core/structure.py"
    click KPTS "https://github.com/abinit/abipy/blob/develop/abipy/core/kpoints.py"
    click SYM "https://github.com/abinit/abipy/blob/develop/abipy/core/symmetries.py"
    click REST "https://github.com/abinit/abipy/blob/develop/abipy/core/restapi.py"
    click CIFS "https://github.com/abinit/abipy/tree/develop/abipy/data/cifs"
    click PSEUDOS "https://github.com/abinit/abipy/tree/develop/abipy/data/pseudos"
    click REFS "https://github.com/abinit/abipy/tree/develop/abipy/data/refs"
    click DFPT "https://github.com/abinit/abipy/blob/develop/abipy/dfpt/phonons.py"
    click ELEC "https://github.com/abinit/abipy/blob/develop/abipy/electrons/ebands.py"
    click EPH "https://github.com/abinit/abipy/blob/develop/abipy/eph/sigeph.py"
    click DYN "https://github.com/abinit/abipy/blob/develop/abipy/dynamics/analyzer.py"
    click EMB "https://github.com/abinit/abipy/blob/develop/abipy/embedding/embedding_ifc.py"
    click ML "https://github.com/abinit/abipy/blob/develop/abipy/ml/ml_phonopy.py"
    click WAV "https://github.com/abinit/abipy/blob/develop/abipy/waves/pwwave.py"
    click FLOWS "https://github.com/abinit/abipy/blob/develop/abipy/flowtk/flows.py"
    click TASKS "https://github.com/abinit/abipy/blob/develop/abipy/flowtk/tasks.py"
    click LAUN "https://github.com/abinit/abipy/blob/develop/abipy/flowtk/launcher.py"
    click QAD "https://github.com/abinit/abipy/blob/develop/abipy/flowtk/qadapters.py"
    click ERRH "https://github.com/abinit/abipy/blob/develop/abipy/flowtk/scheduler_error_handlers.py"
    click UTIL "https://github.com/abinit/abipy/blob/develop/abipy/display/utils.py"
    click MVTK "https://github.com/abinit/abipy/blob/develop/abipy/display/mvtk.py"
    click PCORE "https://github.com/abinit/abipy/blob/develop/abipy/panels/core.py"
    click PFLOWS "https://github.com/abinit/abipy/blob/develop/abipy/panels/flows.py"
    click PVIEW "https://github.com/abinit/abipy/blob/develop/abipy/panels/viewers.py"
    click ABIRUN "https://github.com/abinit/abipy/blob/develop/abipy/scripts/abirun.py"
    click ABICHECK "https://github.com/abinit/abipy/blob/develop/abipy/scripts/abicheck.py"
    click ABIOPEN "https://github.com/abinit/abipy/blob/develop/abipy/scripts/abiopen.py"
    click ABIVIEW "https://github.com/abinit/abipy/blob/develop/abipy/scripts/abiview.py"
    click EXAMPLES "https://github.com/abinit/abipy/tree/develop/abipy/examples"
    click UNITTESTS "https://github.com/abinit/abipy/tree/develop/abipy/*/tests/"
    click INTEGR "https://github.com/abinit/abipy/tree/develop/abipy/integration_tests/"
    click DOCS "https://github.com/abinit/abipy/tree/develop/docs/"

    %% Styles
    classDef external fill:#eeeeee,stroke:#888,stroke-width:1px
    classDef core fill:#cfe2f3,stroke:#0367a6,stroke-width:1px
    classDef cli fill:#fbd38d,stroke:#b7791f,stroke-width:1px
    classDef examples fill:#c6f6d5,stroke:#2f855a,stroke-width:1px
    classDef ci fill:#faf089,stroke:#d69e2e,stroke-width:1px
```
