# grimme-lab/xtb architecture

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

- Interactive diagram: https://gitdiagram.com/grimme-lab/xtb
- Repository: https://github.com/grimme-lab/xtb

## Overview

This project is the official “xtb” repository for a Semiempirical Extended Tight-Binding Program Package used primarily in computational chemistry research. The project provides both a command‐line executable and a callable library to perform tight-binding calculations along with auxiliary methods like GFN-FF, solvation models, metadynamics, and more. Its architecture is highly modular – developed in Fortran – with significant emphasis on numerical algorithms, modular subroutines, and flexibility with two build systems (CMake and Meson).

##### Main Components
- Core Engine:
- Central “xtb” module (located in src/xtb) that implements the core tight-binding calculations.
- “main” driver component (src/main) which sets up the runtime environment, reads configurations, and drives the execution.
- API Layer:
- API subdirectory (src/api) that provides interfaces (modules like calculator.f90, molecule.f90, results.f90, etc.) allowing external programs to integrate or invoke xtb functionality.
- Domain-Specific Modules:
- And include specialized components, such as:
- “gfnff” submodule (src/gfnff) for force-field type calculations.
- “mctc” (src/mctc) modules that handle matrix operations, linear algebra, and mathematical utilities.
- “docking”, “solv”, “ptb” modules that support various physical models, solvation methods, and extended methods.
- Other modeling modules (e.g., “dftd3”, “dftd4” in src/disp) and modules managing geometry, forces, and optimizers (e.g., “bfgs” in src/).
- I/O Subsystem:
- Modules under src/io for input readers and output writers. These handle various file formats including Gaussian, VASP, ORCA, and others.
- Build and Configuration Systems:
- A separate section for configuration/build, indicating the dual support for Meson (meson.build, meson/README.adoc) and CMake (CMakeLists.txt, cmake/ subdirectory). Show how these components interact with the source code to generate the final binaries.
- Testing and Documentation:
- “test” directory and note that unit tests and API examples exist to validate many of the modules.
- Extra support areas such as the “assets” (inputs, logo, templates) and “man” pages that provide user and developer guidance.
- External Dependencies/Subprojects:
- External modules wrapped as “subprojects” (e.g., cpx.wrap, dftd4.wrap, mctc-lib.wrap) which are integrated into the build process.

##### Relationships and Interactions
- Data flow from the Input layer (I/O modules, configuration files, and test data in assets) into the Core Engine.
- Inter-module dependencies: for example, the main driver calls the API, which in turn makes use of various specialized components (gfnff, mctc, docking, etc.).
- Interactions with external libraries or subprojects that are wrapped and integrated via the build system.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that each functional block (e.g., FE calculation, solvation model, optimization routine) is encapsulated in its own directory and set of modules.
- Layered Architecture: Divide the system between low-level computational kernels (numerical routines in src) and high-level control APIs and interfaces (src/api and src/main).
- Extensibility: The structure (with multiple subdirectories and external “subprojects”) demonstrates a plug-in like architecture where additional methods or corrections (e.g., dispersion corrections, solvation models) can be added.

##### Key Technologies and Frameworks
- Fortran for core computational routines, with modern practices (modular design, use of Fortran 90/95 standards).
- Use of build systems (CMake and Meson) – include these as infrastructure components that compile and link Fortran code and optionally integrate with external C/C++ dependencies.
- Testing frameworks: Indicate that the “test” folder includes unit tests written in Fortran and even some C API examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & External Subgraph
    subgraph "Build & External"
        CMake["CMake Build"]:::build
        Meson["Meson Build"]:::build
        External["External Dependencies"]:::build
    end

    %% Core Processing Subgraph
    subgraph "Core Processing"
        MainDriver["Main Driver"]:::driver
        API["API Interface"]:::api
        CoreEngine["Core Engine (xtb)"]:::core
        subgraph "Domain Modules"
            GFNFF["gfnff Module"]:::domain
            MCTC["mctc Module"]:::domain
            Docking["Docking Module"]:::domain
            Solvation["Solvation Models"]:::domain
            PTB["ptb Module"]:::domain
            Dispersion["Dispersion Modeling"]:::domain
            Geometry["Geometry & Optimizers"]:::domain
        end
    end

    %% I/O and Support Subgraph
    subgraph "I/O and Support"
        IO["I/O Manager"]:::io
        Testing["Testing Framework"]:::testing
        Documentation["Documentation"]:::support
        Assets["Assets"]:::support
    end

    %% Relationships
    Documentation -->|"coverage"| IO
    Assets -->|"inputs"| IO
    IO -->|"config_input"| MainDriver
    CMake -->|"builds"| MainDriver
    Meson -->|"builds"| MainDriver
    External -->|"integrates"| CoreEngine
    Testing -->|"validates"| MainDriver
    MainDriver -->|"calls_API"| API
    API -->|"invokes"| CoreEngine
    API -->|"invokes"| GFNFF
    API -->|"invokes"| MCTC
    API -->|"invokes"| Docking
    API -->|"invokes"| Solvation
    API -->|"invokes"| PTB
    API -->|"invokes"| Dispersion
    API -->|"invokes"| Geometry
    GFNFF -->|"returns"| CoreEngine
    MCTC -->|"returns"| CoreEngine
    Docking -->|"returns"| CoreEngine
    Solvation -->|"returns"| CoreEngine
    PTB -->|"returns"| CoreEngine
    Dispersion -->|"returns"| CoreEngine
    Geometry -->|"returns"| CoreEngine
    CoreEngine -->|"outputs"| IO

    %% Styles
    classDef core fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef driver fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef api fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef io fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef build fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef testing fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef support fill:#d1f7d1,stroke:#28a745,stroke-width:2px;

    %% Click Events
    click CoreEngine "https://github.com/grimme-lab/xtb/tree/main/src/xtb"
    click MainDriver "https://github.com/grimme-lab/xtb/tree/main/src/main"
    click API "https://github.com/grimme-lab/xtb/tree/main/src/api"
    click GFNFF "https://github.com/grimme-lab/xtb/tree/main/src/gfnff"
    click MCTC "https://github.com/grimme-lab/xtb/tree/main/src/mctc"
    click Docking "https://github.com/grimme-lab/xtb/tree/main/src/docking"
    click Solvation "https://github.com/grimme-lab/xtb/tree/main/src/solv"
    click PTB "https://github.com/grimme-lab/xtb/tree/main/src/ptb"
    click Dispersion "https://github.com/grimme-lab/xtb/tree/main/src/disp"
    click Geometry "https://github.com/grimme-lab/xtb/blob/main/src/bfgs.f90"
    click IO "https://github.com/grimme-lab/xtb/tree/main/src/io"
    click CMake "https://github.com/grimme-lab/xtb/blob/main/CMakeLists.txt"
    click Meson "https://github.com/grimme-lab/xtb/blob/main/meson.build"
    click Testing "https://github.com/grimme-lab/xtb/tree/main/test/"
    click Documentation "https://github.com/grimme-lab/xtb/tree/main/man/"
    click Assets "https://github.com/grimme-lab/xtb/tree/main/assets/"
    click External "https://github.com/grimme-lab/xtb/tree/main/subprojects/"
```
