# mantevo/minimd architecture

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

- Interactive diagram: https://gitdiagram.com/mantevo/minimd
- Repository: https://github.com/mantevo/minimd

## Overview

##### Project type and purpose
- miniMD is a micro-application for parallel molecular-dynamics (MD) simulation.
- It’s written in C++ and designed for benchmarking and portability experiments on CPUs, GPUs, and other architectures.
- The top-level has four self-contained variants (ref, kokkos, mpi-spec, target), a test harness, and formatting utilities.

##### File structure
- Top-level directories:
- ref        – reference MPI+OpenMP variant
- kokkos     – MPI + Kokkos backends (Pthreads/OpenMP/CUDA) variant
- mpi-spec   – specification snapshot of the ref code
- target     – production-tuned build with offload, intrinsics, and extra headers
- tests      – test scripts and reference outputs
- util       – code formatting tool
- Common modules in each variant:
- atom.*, types.h, variant.h           – data structures for atoms
- input.cpp                            – parse input scripts
- setup.cpp                            – initialize domain decomposition, neighbor bins
- neighbor.*                           – build neighbor lists
- force_eam.*, force_lj.*, force.h     – compute pairwise or EAM interactions
- integrate.*                          – advance positions/velocities
- comm.*                               – exchange ghost atoms via MPI
- thermo.*                             – compute thermodynamic properties
- timer.*                              – high-precision timing
- output.*                             – write logs, performance summary
- Build/configuration:
- Makefile(.default, .<platform>) or CMakeLists.txt (in kokkos)
- MPI-Stubs for non-MPI builds
- Platform flags: MPI, OpenMP, CUDA, KNC, AVX, etc.
- Testing:
- run_one_test, run_tests scripts invoke the built binary, run sample inputs, compare to reference_output.

##### Key insights from the README
- Parallelism: domain (spatial) decomposition with MPI ranks; optional intra-rank threading (OpenMP or Kokkos).
- Two force styles: Lennard-Jones (LJ) and Embedded Atom Method (EAM).
- Designed for weak scaling; minimal feature set for performance studies.
- Multiple build options to target CPU cores, Intel Xeon Phi, GPUs via CUDA or OpenCL (kokkos variant).

##### Detail without over-splitting
- Every module in the main simulation engine.
- How variants reuse the same modules but swap in different backends (e.g., MPI+OpenMP vs. MPI+Kokkos).
- Loop structure of the MD timestep and where timers and thermodynamics hooks insert.
- Test harness as an integral component for regression and performance validation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Config Layer
    subgraph "Build & Config Layer"
        direction TB
        Ref_Makefiles["ref Makefiles"]:::build
        Kokkos_Build["kokkos Build Files"]:::build
        MPISpec_Build["mpi-spec Build Files"]:::build
        Target_Build["target Build Files"]:::build
    end

    %% Variants Layer
    subgraph "Variant Builds"
        direction TB
        Ref_Var["Reference Variant (ref/)"]:::build
        Kokkos_Var["Kokkos Variant (kokkos/)"]:::build
        MPISpec_Var["MPI-Spec Variant (mpi-spec/)"]:::build
        Target_Var["Target Variant (target/)"]:::build
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        direction TB
        DataStruct["Data Structures Module"]:::core
        InputParser["Input Parser Module"]:::core
        Setup["Setup & Decomp Module"]:::core
        Neighbor["Neighbor List Module"]:::core
        Force_LJ["Force LJ Module"]:::core
        Force_EAM["Force EAM Module"]:::core
        Integrate["Integration Module"]:::core
        Comm["Communication Module"]:::core
        Thermo["Thermodynamics Module"]:::core
        Timer["Timing Module"]:::core
        OutputMod["Output & Logging Module"]:::core
    end

    %% Parallel Runtime
    subgraph "Parallel Runtime"
        direction TB
        MPI_Stubs["MPI-Stubs"]:::runtime
        Thread_Backend["Thread/Device Backend"]:::runtime
    end

    %% I/O and Testing
    subgraph "I/O & Testing"
        direction TB
        External_IO["External Input/Output Files"]:::io
        Test_Harness["Test Harness"]:::io
        Reference_Data["Reference Output Data"]:::io
    end

    %% Formatting Utility
    Util["Formatting Utility"]:::build

    %% Connections
    Build_Config_Layer -->|configures| Ref_Var
    Build_Config_Layer -->|configures| Kokkos_Var
    Build_Config_Layer -->|configures| MPISpec_Var
    Build_Config_Layer -->|configures| Target_Var

    Ref_Var -->|uses modules| DataStruct
    Kokkos_Var -->|uses modules| DataStruct
    MPISpec_Var -->|uses modules| DataStruct
    Target_Var -->|uses modules| DataStruct

    DataStruct --> InputParser --> Setup --> Neighbor --> Force_LJ --> Integrate --> Thermo --> OutputMod
    Neighbor --> Force_EAM
    Comm -->|ghost-exchange| Neighbor
    Comm -->|ghost-exchange| Force_LJ
    Comm -->|ghost-exchange| Force_EAM
    Timer -->|timing hooks| OutputMod

    DataStruct --> MPI_Stubs
    Comm --> MPI_Stubs
    Neighbor --> Thread_Backend
    Force_LJ --> Thread_Backend
    Force_EAM --> Thread_Backend

    InputParser --> External_IO
    OutputMod --> External_IO

    Test_Harness -->|executes binary| Ref_Var
    Test_Harness -->|executes binary| Kokkos_Var
    Test_Harness -->|executes binary| MPISpec_Var
    Test_Harness -->|executes binary| Target_Var
    Test_Harness -->|compares output| Reference_Data

    Util -->|formats code| Ref_Var
    Util -->|formats code| Kokkos_Var
    Util -->|formats code| MPISpec_Var
    Util -->|formats code| Target_Var

    %% Click Events for Build & Config
    click Kokkos_Build "https://github.com/mantevo/minimd/blob/master/kokkos/CMakeLists.txt"
    click Kokkos_Build "https://github.com/mantevo/minimd/tree/master/kokkos/Makefile"
    click Kokkos_Build "https://github.com/mantevo/minimd/blob/master/kokkos/Makefile.no-mpi"
    click Ref_Makefiles "https://github.com/mantevo/minimd/blob/master/ref/Makefile.default"
    click Ref_Makefiles "https://github.com/mantevo/minimd/blob/master/ref/Makefile.openmpi"
    click Ref_Makefiles "https://github.com/mantevo/minimd/blob/master/ref/Makefile.intel"
    click Ref_Makefiles "https://github.com/mantevo/minimd/blob/master/ref/Makefile.cray"
    click Ref_Makefiles "https://github.com/mantevo/minimd/blob/master/ref/build-win.bat"
    click MPISpec_Build "https://github.com/mantevo/minimd/tree/master/mpi-spec/Makefile"
    click MPISpec_Build "https://github.com/mantevo/minimd/blob/master/mpi-spec/Makefile.no-mpi"
    click MPISpec_Build "https://github.com/mantevo/minimd/blob/master/mpi-spec/create_spec_snapshot.sh"
    click Target_Build "https://github.com/mantevo/minimd/tree/master/target/Makefile"
    click Target_Build "https://github.com/mantevo/minimd/blob/master/target/.clang-format"

    %% Click Events for Variants
    click Ref_Var "https://github.com/mantevo/minimd/tree/master/ref/"
    click Kokkos_Var "https://github.com/mantevo/minimd/tree/master/kokkos/"
    click MPISpec_Var "https://github.com/mantevo/minimd/tree/master/mpi-spec/"
    click Target_Var "https://github.com/mantevo/minimd/tree/master/target/"

    %% Click Events for Core Engine Modules (kokkos paths)
    click DataStruct "https://github.com/mantevo/minimd/blob/master/kokkos/atom.cpp"
    click DataStruct "https://github.com/mantevo/minimd/blob/master/kokkos/atom.h"
    click DataStruct "https://github.com/mantevo/minimd/blob/master/kokkos/types.h"
    click DataStruct "https://github.com/mantevo/minimd/blob/master/kokkos/variant.h"
    click InputParser "https://github.com/mantevo/minimd/blob/master/kokkos/input.cpp"
    click Setup "https://github.com/mantevo/minimd/blob/master/kokkos/setup.cpp"
    click Neighbor "https://github.com/mantevo/minimd/blob/master/kokkos/neighbor.cpp"
    click Neighbor "https://github.com/mantevo/minimd/blob/master/kokkos/neighbor.h"
    click Force_LJ "https://github.com/mantevo/minimd/blob/master/kokkos/force_lj.cpp"
    click Force_LJ "https://github.com/mantevo/minimd/blob/master/kokkos/force_lj.h"
    click Force_EAM "https://github.com/mantevo/minimd/blob/master/kokkos/force_eam.cpp"
    click Force_EAM "https://github.com/mantevo/minimd/blob/master/kokkos/force_eam.h"
    click Comm "https://github.com/mantevo/minimd/blob/master/kokkos/comm.cpp"
    click Comm "https://github.com/mantevo/minimd/blob/master/kokkos/comm.h"
    click Thermo "https://github.com/mantevo/minimd/blob/master/kokkos/thermo.cpp"
    click Thermo "https://github.com/mantevo/minimd/blob/master/kokkos/thermo.h"
    click Timer "https://github.com/mantevo/minimd/blob/master/kokkos/timer.cpp"
    click Timer "https://github.com/mantevo/minimd/blob/master/kokkos/timer.h"
    click OutputMod "https://github.com/mantevo/minimd/blob/master/kokkos/output.cpp"

    %% Click Events for Runtime
    click MPI_Stubs "https://github.com/mantevo/minimd/tree/master/kokkos/MPI-Stubs/"
    click MPI_Stubs "https://github.com/mantevo/minimd/tree/master/mpi-spec/MPI-Stubs/"
    click MPI_Stubs "https://github.com/mantevo/minimd/tree/master/target/MPI-Stubs/"

    %% Click Events for I/O & Testing
    click External_IO "https://github.com/mantevo/minimd/blob/master/kokkos/in.lj.miniMD"
    click External_IO "https://github.com/mantevo/minimd/blob/master/kokkos/in.eam.miniMD"
    click Test_Harness "https://github.com/mantevo/minimd/tree/master/kokkos/run_one_test"
    click Test_Harness "https://github.com/mantevo/minimd/tree/master/kokkos/run_tests"
    click Reference_Data "https://github.com/mantevo/minimd/tree/master/kokkos/reference_output/"

    %% Click Event for Formatting Utility
    click Util "https://github.com/mantevo/minimd/tree/master/util/p-clang-format/"

    %% Styles
    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#aaddff,stroke:#333,stroke-width:1px
    classDef runtime fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef io fill:#ffdd99,stroke:#333,stroke-width:1px
```
