# amd/mumps-build architecture

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

- Interactive diagram: https://gitdiagram.com/amd/mumps-build
- Repository: https://github.com/amd/mumps-build

## Overview

##### Main Components
- Core Build System: At the heart is the CMake build system, which manages configuration, external dependency fetching (e.g., the MUMPS tarball, AOCL libraries, Metis, and Boost) and build generation via Ninja.
- MUMPS Source Integration: The project downloads the upstream MUMPS tarball, injects custom CMakeLists (in directories like “cmake” and “PORD”) to patch and integrate the MUMPS source with additional build scripts.
- Dependency Management: CMake modules that search and configure dependencies (FindLAPACK.cmake, FindMETIS.cmake, etc.) and user-specified paths (e.g., paths for AOCL-BLAS, AOCL-LAPACK, Scalapack, Metis, Intel compilers, and Boost).
- CI/CD Pipeline: The .github/workflows directory shows multiple CI configurations (for Windows and oneapi environments) which ensure continuous integration and testing.
- Testing / Examples: Directories such as “test” and “example” house sample codes and test harnesses (like amd_mumps.cpp and simple.c) to verify the solver build and performance.
- Additional Wrappers & Integration: Directories such as “libseq” (for sequential library building) and “matlab” (for MATLAB interface examples) indicate the project supports multiple usage scenarios.

##### Component Relationships and Interactions
- The CMake front-end acts as the orchestrator that:
- Downloads the MUMPS source tarball.
- Configures external dependencies by referring to user inputs and internal CMake modules.
- Directs the build process using Ninja and integration tests.
- The CI/CD pipelines (defined in the GitHub workflows) automatically trigger build and test jobs to validate configurations and compiler choices.
- External tools (e.g., Intel oneAPI compilers, prebuilt AOCL libraries, Metis from SuiteSparse, and Boost) link into the build process as specified by the user through a rich set of CMake options.
- The test applications and examples layer on top of the built libraries to check for performance (e.g., running an MPI test invocation) and correctness.

##### Architectural Patterns and Design Principles
- Modular Build Configuration: The project leverages multiple CMake modules and configuration scripts to maintain a clean separation of concerns (i.e., dependency discovery vs. compile-time configuration).
- External Dependency Injection: Instead of bundling MUMPS sources, the system downloads and patches them, making the build process highly configurable.
- Cross-Platform & CI Integration: With dedicated workflows for different platforms (Windows and oneAPI environments), the design ensures the build process is both reproducible and automated.
- Extensibility: The clear separation between core solver integration (“src”, “PORD”) and ancillary functionalities (testing, MATLAB integration, sequential version build in “libseq”) allows for future enhancement without significant refactoring.

##### Technologies, Frameworks, and Tools
- Build Technology: CMake, Ninja, GitHub Actions.
- Compilers: Intel oneAPI suite (C, C++ and Fortran compilers).
- Libraries: AOCL (BLAS, LAPACK, Scalapack), Boost, external reordering libraries (Metis, optionally Scotch) and MPI.
- Scripting and Packaging: Custom CMake modules and scripts (Python for patching, batch and PowerShell scripts in workflows).

##### Final Suggestions
- Reinforce connections between the build orchestration (CMake and all its custom modules) and the CI configurations (GitHub workflows), as these are critical to understanding how changes propagate through the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Flow Between Subsystems
    CI["CI/CD Pipeline"]:::ci
    CMS["CMake Build System"]:::build
    MSI["MUMPS Source Integration"]:::integration
    DM["Dependency Management"]:::dep
    TE["Testing / Examples"]:::test
    AWI["Additional Wrappers & Integration"]:::wrap

    CI -->|"triggers"| CMS
    CMS -->|"integrates"| MSI
    CMS -->|"configures"| DM
    CMS -->|"produces"| TE
    CMS -->|"supports"| AWI

    %% CI/CD Pipeline Subgraph
    subgraph "CI/CD Pipeline Components"
        direction TB
        CI1[".github/workflows/ci.yml"]:::ci
        CI2[".github/workflows/ci_windows.yml"]:::ci
        CI3[".github/workflows/intel-oneapi.yml"]:::ci
        CI4[".github/workflows/oneapi-windows.yml"]:::ci
        CI5[".github/workflows/oneapi_cache_exclude_windows.ps1"]:::ci
        CI6[".github/workflows/oneapi_install_windows.bat"]:::ci
        CI7[".github/workflows/oneapi_run_windows.bat"]:::ci
        CI --- CI1
        CI --- CI2
        CI --- CI3
        CI --- CI4
        CI --- CI5
        CI --- CI6
        CI --- CI7
    end

    %% Core Build System Subgraph
    subgraph "Core Build System Components"
        direction TB
        CMS1["CMakeLists.txt"]:::build
        CMS2["CMakePresets.json"]:::build
        CMS3["cmake/"]:::build
        CMS --- CMS1
        CMS --- CMS2
        CMS --- CMS3
    end

    %% MUMPS Source Integration Subgraph
    subgraph "MUMPS Source Integration Components"
        direction TB
        MSI1["PORD"]:::integration
        MSI2["cmake/mumps_patch.cmake"]:::integration
        MSI3["cmake/mumps_src.cmake"]:::integration
        MSI --- MSI1
        MSI --- MSI2
        MSI --- MSI3
    end

    %% Dependency Management Subgraph
    subgraph "Dependency Management Components"
        direction TB
        DM1["cmake/FindLAPACK.cmake"]:::dep
        DM2["cmake/FindMETIS.cmake"]:::dep
        DM3["cmake/FindMUMPS.cmake"]:::dep
        DM4["cmake/FindSCALAPACK.cmake"]:::dep
        DM5["cmake/FindScotch.cmake"]:::dep
        DM6["cmake/libseq.cmake"]:::dep
        DM7["cmake/matlab.cmake"]:::dep
        DM --- DM1
        DM --- DM2
        DM --- DM3
        DM --- DM4
        DM --- DM5
        DM --- DM6
        DM --- DM7
    end

    %% Testing / Examples Subgraph
    subgraph "Testing / Examples Components"
        direction TB
        TE1["test/CMakeLists.txt"]:::test
        TE2["amd_mumps.cpp"]:::test
        TE3["simple.c"]:::test
        TE4["example/CMakeLists.txt"]:::test
        TE5["d_example.c"]:::test
        TE6["z_example.c"]:::test
        TE7["run_ex.cmake"]:::test
        TE --- TE1
        TE --- TE2
        TE --- TE3
        TE --- TE4
        TE --- TE5
        TE --- TE6
        TE --- TE7
    end

    %% Additional Wrappers & Integration Subgraph
    subgraph "Additional Wrappers & Integration Components"
        direction TB
        AWI1["libseq/CMakeLists.txt"]:::wrap
        AWI2["matlab/CMakeLists.txt"]:::wrap
        AWI3["matlab/example.m"]:::wrap
        AWI --- AWI1
        AWI --- AWI2
        AWI --- AWI3
    end

    %% Click Events for CI/CD Pipeline
    click CI1 "https://github.com/amd/mumps-build/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/amd/mumps-build/blob/main/.github/workflows/ci_windows.yml"
    click CI3 "https://github.com/amd/mumps-build/blob/main/.github/workflows/intel-oneapi.yml"
    click CI4 "https://github.com/amd/mumps-build/blob/main/.github/workflows/oneapi-windows.yml"
    click CI5 "https://github.com/amd/mumps-build/blob/main/.github/workflows/oneapi_cache_exclude_windows.ps1"
    click CI6 "https://github.com/amd/mumps-build/blob/main/.github/workflows/oneapi_install_windows.bat"
    click CI7 "https://github.com/amd/mumps-build/blob/main/.github/workflows/oneapi_run_windows.bat"

    %% Click Events for Core Build System
    click CMS1 "https://github.com/amd/mumps-build/blob/main/CMakeLists.txt"
    click CMS2 "https://github.com/amd/mumps-build/blob/main/CMakePresets.json"
    click CMS3 "https://github.com/amd/mumps-build/tree/main/cmake"

    %% Click Events for MUMPS Source Integration
    click MSI1 "https://github.com/amd/mumps-build/tree/main/PORD"
    click MSI2 "https://github.com/amd/mumps-build/blob/main/cmake/mumps_patch.cmake"
    click MSI3 "https://github.com/amd/mumps-build/blob/main/cmake/mumps_src.cmake"

    %% Click Events for Dependency Management
    click DM1 "https://github.com/amd/mumps-build/blob/main/cmake/FindLAPACK.cmake"
    click DM2 "https://github.com/amd/mumps-build/blob/main/cmake/FindMETIS.cmake"
    click DM3 "https://github.com/amd/mumps-build/blob/main/cmake/FindMUMPS.cmake"
    click DM4 "https://github.com/amd/mumps-build/blob/main/cmake/FindSCALAPACK.cmake"
    click DM5 "https://github.com/amd/mumps-build/blob/main/cmake/FindScotch.cmake"
    click DM6 "https://github.com/amd/mumps-build/blob/main/cmake/libseq.cmake"
    click DM7 "https://github.com/amd/mumps-build/blob/main/cmake/matlab.cmake"

    %% Click Events for Testing / Examples
    click TE1 "https://github.com/amd/mumps-build/blob/main/test/CMakeLists.txt"
    click TE2 "https://github.com/amd/mumps-build/blob/main/test/amd_mumps.cpp"
    click TE3 "https://github.com/amd/mumps-build/blob/main/test/simple.c"
    click TE4 "https://github.com/amd/mumps-build/blob/main/example/CMakeLists.txt"
    click TE5 "https://github.com/amd/mumps-build/blob/main/example/d_example.c"
    click TE6 "https://github.com/amd/mumps-build/blob/main/example/z_example.c"
    click TE7 "https://github.com/amd/mumps-build/blob/main/example/run_ex.cmake"

    %% Click Events for Additional Wrappers & Integration
    click AWI1 "https://github.com/amd/mumps-build/blob/main/libseq/CMakeLists.txt"
    click AWI2 "https://github.com/amd/mumps-build/blob/main/matlab/CMakeLists.txt"
    click AWI3 "https://github.com/amd/mumps-build/blob/main/matlab/example.m"

    %% Class Styles
    classDef ci fill:#ADD8E6,stroke:#000000,stroke-width:1px;
    classDef build fill:#90EE90,stroke:#000000,stroke-width:1px;
    classDef integration fill:#98FB98,stroke:#000000,stroke-width:1px;
    classDef dep fill:#F0E68C,stroke:#000000,stroke-width:1px;
    classDef test fill:#FFB6C1,stroke:#000000,stroke-width:1px;
    classDef wrap fill:#D3D3D3,stroke:#000000,stroke-width:1px;
```
