# ddemidov/amgcl architecture

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

- Interactive diagram: https://gitdiagram.com/ddemidov/amgcl
- Repository: https://github.com/ddemidov/amgcl

## Overview

##### Project Type and Purpose
- AMGCL is an open-source, header-only C++ library implementing algebraic multigrid (AMG) solvers for large sparse linear systems.
- It provides a modular framework—core AMG algorithm, adapters, backends, solvers, preconditioners, MPI support, I/O routines, profiling, and language bindings (Python, Fortran, Delphi).

##### File-Structure Analysis
- Top-level sources:
- amgcl/… – core modules (adapter, backend, coarsening, solver, relaxation, preconditioner, MPI, I/O, profiling, utilities).
- lib/ – compiled C++ DLL/stubs for library distribution.
- pyamgcl/ – Python binding via pybind11.
- delphi/, fortran/ – language-specific examples/bindings.
- examples/, tutorial/ – usage demos (single-node and MPI).
- docs/ – Sphinx-based API docs, design notes, benchmarks.
- CMakeLists.txt, cmake/ – build configuration; Dockerfiles under docker/.
- tests/ – unit and integration tests.

##### Key README Insights
- Header-only design; CPU builds AMG hierarchy, backends handle acceleration (OpenCL, CUDA, OpenMP, external libraries).
- Users can inject custom backends/adapters, leveraging policy-based, template metaprogramming.
- The library is typically used as a preconditioner within iterative solvers (CG, BiCGStab, GMRES).

- User Application – client code or examples that invoke AMGCL APIs.
- Adapter Layer – translates user data structures (Eigen, uBLAS, CRS tuple) into AMGCL’s internal CSR format.
- Core AMG Engine – modules for coarsening, interpolation (prolongation), relaxation, solver runtime; constructs AMG hierarchy.
- Backend Layer – pluggable compute backends (builtin CPU, OpenMP, CUDA, OpenCL, VexCL, ViennaCL, MKL).
- Preconditioners & Solvers – high-level solver factory (make_solver), preconditioners (deflated, CPR, Schur), iterative methods.
- MPI Layer – distributed AMG and solvers, matrix partitioning, interprocess communication.
- I/O & Profiling – reading/writing matrices, performance counters, logging.
- Language Bindings – Python (pyamgcl), Fortran, Delphi wrappers.
- Build & Deployment – CMake, Docker, cmake modules, CI configs.

- User Application → Adapter Layer: supplies sparse matrix, right-hand side, solver parameters.
- Adapter Layer → Core AMG Engine: provides CSR matrix.
- Core AMG Engine ↔ Backend Layer: hierarchy construction on CPU; solver phase offloaded to backend.
- Core AMG Engine → Preconditioners & Solvers: instantiates solver pipelines.
- MPI Layer sits around Core + Backend: splits data, calls local AMG on each rank, coordinates communication.
- I/O & Profiling attach to all layers: collect metrics, read/write intermediate data.
- Language Bindings → Public API: expose make_solver, solve interfaces to Python/Fortran/Delphi.
- Build & Deployment → All Components: orchestrates compile, test, package.

c. Architectural Patterns & Principles:
- Policy-based design: core algorithms decoupled from data representation and execution platform.
- Header-only distribution: maximum compile-time flexibility, no central binary.
- Layered modularity: clear separation of concerns (adapters, core, backends, MPI, I/O).
- Pluggable backends/adapters: runtime and compile-time switching via templates and factory functions.
- Extensibility: users can add custom adapters, backends, solvers without modifying core.

d. Key Technologies & Frameworks:
- C++17 templates, metaprogramming
- CMake build system, CI (Travis, AppVeyor)
- OpenMP, CUDA, OpenCL for acceleration
- MPI for distributed computing
- pybind11 for Python bindings
- Sphinx (docs), Docker for reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "User Application" 
        direction TB
        UA["Client Code / Examples"]:::app
    end

    subgraph "Adapter Layer" 
        direction TB
        Adapter["Adapter Layer"]:::adapter
    end

    subgraph "Core AMG Engine" 
        direction TB
        Core["Core AMG Engine"]:::core
    end

    subgraph "Backend Layer"
        direction TB
        Backend["Backend Layer"]:::backend
    end

    subgraph "Preconditioners & Solvers"
        direction TB
        Precond["Preconditioners & Solvers"]:::backend
    end

    subgraph "MPI Layer"
        direction TB
        MPI["MPI Layer"]:::backend
    end

    subgraph "I/O & Profiling"
        direction TB
        IO["I/O & Profiling"]:::infra
    end

    subgraph "Language Bindings"
        direction TB
        LangPy["Python Binding"]:::lang
        LangFortran["Fortran Binding"]:::lang
        LangDelphi["Delphi Binding"]:::lang
    end

    subgraph "Build & Deployment"
        direction TB
        Build["Build & Deployment"]:::infra
    end

    %% Connections
    UA -->|"supplies matrix, RHS, params"| Adapter
    Adapter -->|"provides CSR matrix"| Core
    Core ---|"constructs hierarchy"| Backend
    Core ---|"offloads solver phase"| Backend
    Core -->|"instantiates solvers"| Precond
    MPI -->|"wraps & distributes"| Core
    MPI -->|"wraps & distributes"| Backend
    IO -->|"reads/writes data"| Adapter
    IO -->|"collects metrics"| Core
    IO -->|"collects metrics"| Backend
    LangPy -->|"exposes API"| Core
    LangFortran -->|"exposes API"| Core
    LangDelphi -->|"exposes API"| Core
    Build -.->|"orchestrates build/test/package"| Adapter
    Build -.->|"orchestrates build/test/package"| Core
    Build -.->|"orchestrates build/test/package"| Backend
    Build -.->|"orchestrates build/test/package"| MPI
    Build -.->|"orchestrates build/test/package"| IO
    Build -.->|"orchestrates build/test/package"| LangPy

    %% Click Events
    click Adapter "https://github.com/ddemidov/amgcl/tree/master/amgcl/adapter"
    click Core "https://github.com/ddemidov/amgcl/blob/master/amgcl/amg.hpp"
    click Backend "https://github.com/ddemidov/amgcl/tree/master/amgcl/backend"
    click MPI "https://github.com/ddemidov/amgcl/tree/master/amgcl/mpi"
    click IO "https://github.com/ddemidov/amgcl/tree/master/amgcl/io"
    click LangPy "https://github.com/ddemidov/amgcl/blob/master/pyamgcl/pyamgcl.cpp"
    click LangFortran "https://github.com/ddemidov/amgcl/blob/master/fortran/amgcl.f90"
    click LangDelphi "https://github.com/ddemidov/amgcl/blob/master/delphi/amgcl.pas"
    click Build "https://github.com/ddemidov/amgcl/blob/master/CMakeLists.txt"

    %% Styles
    classDef app fill:#ffe0b2,stroke:#bf360c,color:#000
    classDef adapter fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef infra fill:#f5f5f5,stroke:#9e9e9e,color:#000
    classDef lang fill:#d1c4e9,stroke:#4a148c,color:#000
```
