# yigongqin/cupf architecture

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

- Interactive diagram: https://gitdiagram.com/yigongqin/cupf
- Repository: https://github.com/yigongqin/cupf

## Overview

##### Project Type and Purpose
- This is a high-performance computing (HPC) scientific simulation toolkit (“cuPF”) for phase-field modeling of microstructure evolution in metals.
- Core components include C++/CUDA solvers (2D/3D, grain-scale and dendrite-scale), Python scripts for orchestration, input generation, post-processing, and MPI integration for multi-GPU scaling.

##### File Structure Analysis
- Top-level modules:
- 2DdendriteMPI (DNS & line solvers)
- 2Dgrain (various 2D grain-scale solvers and ML-grain submodules)
- 3Dgrain (single-GPU 3D solver)
- 3DgrainMPI (CUDA-aware MPI 3D solver with Python front-end)
- AdditiveManufacturing (MPI-enabled 3D melt-pool simulation)
- Each module follows the same pattern:
- C++/CUDA source (main.cpp or *.cu) + headers
- Makefile for build (variables for CXX, CUDA_PATH, HDF5, MPICXX, MPI_INC)
- Python scripts for input/parameter setups and data transformation (e.g., grains3D.py, saveVTKdata.py)
- Slurm batch scripts (.slurm) under ML_Grain and MPI modules for job submission
- Common dependencies:
- CUDA runtime and Toolkit
- MPI with CUDA-awareness (e.g., MVAPICH2-GDR)
- HDF5 library for output
- Python libraries (requirements.txt)

##### Key Insights from README
- Build workflow revolves around Makefiles—set environment variables, run make.
- Runtime workflows:
- Direct binary invocation for non-MPI modules (e.g., ./phase_field input_file).
- Python front-end (.py scripts) that set up parameters, invoke MPI-enabled binaries, capture HDF5 output.
- Post-processing via saveVTKdata.py → VTK files → visualization in ParaView.

##### Components
a. Main Components
- Development Environment: source code, Makefiles, Python scripts
- Build Toolchain: CXX/CUDA compiler, MPI compiler wrapper, HDF5 includes/libs
- Runtime Environment: HPC cluster (multi-node, multi-GPU), job scheduler (Slurm)
- Simulation Engines:
- 2D solvers (2DdendriteMPI, 2Dgrain)
- 3D solvers (3Dgrain, 3DgrainMPI, AdditiveManufacturing)
- Orchestration Layer: Python scripts for input generation, parameter sweeps, MPI invocation
- Data Layer:
- HDF5 output files
- VTK conversion (saveVTKdata.py)
- Visualization tools (ParaView)
b. Relationships and Interactions
- Developers write/edit C++/CUDA & Python code → build via Makefile → produce executables.
- Python front-end triggers the executables with command-line parameters (material properties, geometry).
- In MPI modules, Python invokes mpirun/mpiexec across GPUs.
- Executables link to CUDA, MPI, HDF5 libraries → write simulation results to HDF5.
- Post-processing Python reads HDF5 → outputs VTK → external viewer.
- Slurm scripts wrap Python/binary calls for batch submission.
c. Architectural Patterns & Principles
- Modular codebase: separate modules for 2D vs. 3D vs. additive manufacturing.
- Layered architecture:
1. Source layer (C++/CUDA + Python)
2. Build layer (Makefiles, environment variables)
3. Execution layer (HPC cluster, MPI, job scheduler)
4. Data layer (HDF5, VTK, visualization)
- Plugin-style parameterization: Python scripts encapsulate geometry and simulation options.
- Reusable core solvers extended by domain-specific wrappers (e.g., lineModel, DNS, moving-domain).
d. Key Technologies and Libraries
- CUDA Toolkit (cuBLAS, custom devicefunc.cu_inl)
- MPI (CUDA-aware variants: MVAPICH2-GDR)
- HDF5 (data serialization)
- Python (NumPy, h5py, argparse)
- Slurm (batch scheduling)
- ParaView (visualization)

##### Detailed Capture of Essential Architectural Elements
- Parallel execution via MPI and domain decomposition (multi-GPU).
- How Python scripts abstract simulation parameters and call underlying solvers.
- Both “2DdendriteMPI” and “AdditiveManufacturing” as representative modules.
- End-to-end workflow: from source code through visualization.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Layer
    subgraph "Source Layer"
        direction TB
        DND_DNS["2DdendriteMPI DNS Solver"]:::code
        DND_Line["2DdendriteMPI Line Solver"]:::code
        GRAIN_DNS["2Dgrain DNS & Nucleation Solver"]:::code
        GRAIN_ML["2Dgrain ML-Grain Submodules"]:::code
        GRAIN_MP["2Dgrain Multi-PF Solver"]:::code
        G3D["3Dgrain Single-GPU Solver"]:::code
        G3D_MPI["3DgrainMPI CUDA-Aware MPI Solver"]:::code
        AM["AdditiveManufacturing MPI Melt-Pool Sim"]:::code
        PY_ORCH["Python Orchestration & Post-Processing"]:::code
    end

    %% Build Layer
    subgraph "Build Layer"
        direction TB
        COMPILERS["CXX/CUDA & MPI Compiler"]:::build
        MAKEFILES["Makefiles (Module Roots)"]:::build
    end

    %% Execution Layer
    subgraph "Execution Layer"
        direction TB
        SLURM["Slurm Scheduler"]:::infra
        HPC["HPC Cluster (Multi-node GPU)"]:::infra
        DIRECT["Direct Binary Run"]:::infra
        MPIRUN["mpirun/mpiexec"]:::infra
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        HDF5["HDF5 Output Files"]:::data
        VTK["VTK Conversion (saveVTKdata.py)"]:::data
        PARA["ParaView Visualization"]:::data
    end

    %% Connections Source -> Build
    DND_DNS -->|compile via| MAKEFILES
    DND_Line -->|compile via| MAKEFILES
    GRAIN_DNS -->|compile via| MAKEFILES
    GRAIN_ML -->|compile via| MAKEFILES
    GRAIN_MP -->|compile via| MAKEFILES
    G3D -->|compile via| MAKEFILES
    G3D_MPI -->|compile via| MAKEFILES
    AM -->|compile via| MAKEFILES
    MAKEFILES -->|use| COMPILERS

    %% Build -> Execution
    COMPILERS -->|deploy to| HPC
    PY_ORCH -->|invoke| DIRECT
    PY_ORCH -->|invoke| MPIRUN
    SLURM -->|submit jobs to| HPC
    SLURM -->|wraps calls to| PY_ORCH

    %% Execution to Data
    DIRECT -->|executes binary writes| HDF5
    MPIRUN -->|executes parallel binary writes| HDF5
    PY_ORCH -->|post-process| VTK
    VTK -->|load into| PARA
    HDF5 -->|read by| PY_ORCH

    %% Execution contexts
    HPC -->|runs| DIRECT
    HPC -->|runs| MPIRUN

    %% Click Events
    click DND_DNS "https://github.com/yigongqin/cupf/tree/main/2DdendriteMPI/DNS"
    click DND_Line "https://github.com/yigongqin/cupf/tree/main/2DdendriteMPI/line_model"
    click GRAIN_DNS "https://github.com/yigongqin/cupf/tree/main/2Dgrain/DNS_nucl"
    click GRAIN_ML "https://github.com/yigongqin/cupf/tree/main/2Dgrain/ML_Grain"
    click GRAIN_MP "https://github.com/yigongqin/cupf/tree/main/2Dgrain/multi_PF"
    click G3D "https://github.com/yigongqin/cupf/tree/main/3Dgrain"
    click G3D_MPI "https://github.com/yigongqin/cupf/tree/main/3DgrainMPI"
    click AM "https://github.com/yigongqin/cupf/tree/main/AdditiveManufacturing"
    click PY_ORCH "https://github.com/yigongqin/cupf/blob/main/requirements.txt"

    %% Styles
    classDef code fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef build fill:#A9DFBF,stroke:#196F3D,color:#1B2631
    classDef data fill:#FAD7A0,stroke:#B9770E,color:#1B2631
    classDef infra fill:#D2B4DE,stroke:#6C3483,color:#1B2631
```
