# lolle2001/ampt-fhmpf architecture

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

- Interactive diagram: https://gitdiagram.com/lolle2001/ampt-fhmpf
- Repository: https://github.com/lolle2001/ampt-fhmpf

## Overview

The AMPT-FHMPF project is a specialized framework developed in C++ (with integrated Fortran components) to run the AMPT (A Multi-Phase Transport) simulation model in a multi-core, file-handling accelerated environment. In essence, it provides a wrapper around different versions of the AMPT code (original, animation-enabled, and hijing-only) by using a combination of C++ (for orchestration, file management, and multi-threading/processing) and legacy Fortran (for the simulation engines). Additionally, there is a Python utility for generating input files based on centrality tables and simulation parameters.

- User Interface / Execution Layer:
- Command-line executable (ampt-mp) that is the main entry point.
- Shell scripts (like compile-ampt-mp.sh and those in the server folder) used for compilation, simulation execution, and file synchronization.

- Core Processing/Manager Module:
- The C++ library files (found in the lib folder) contain key classes such as InstanceManager, Manager, Messenger, Timer, and Utilities. These pieces are responsible for managing simulation instances, messaging between threads/processes, tracking progress, and providing utility functions.

- Simulation Engines:
- The Fortran codes are organized within the src directory into multiple subdirectories (original, animation, and hijing-only), each representing a different compiled variant of the AMPT simulation. They interact with the C++ orchestrator via file input/output.

- File and Data Handling:
- The “input” directory holds parameter files for configuration.
- The “data” directory is designated for storing simulation outputs from various runs.

- Build and Deployment:
- Makefiles (in the make folder and within src subdirectories) outline the compilation steps for both the C++ wrapper and Fortran simulation codes.
- The server folder includes scripts for handling remote file operations (upload/download), which can be conceptualized as a deployment or data management module.

- Input Generation Utility:
- A Python script in the “utils” folder (ampt-input-gen.py) alongside a collection of centrality tables (subfolder centrality_tables) is used to generate and possibly batch-create simulation input files.

##### Relationships and Data Flow
- The command-line interface (CLI) receives user commands to compile or run simulations.
- The orchestration layer (C++ in lib) uses its manager classes to launch simulation processes (Fortran executables compiled from src).
- Data flows from input files (in “input”) to simulation execution and is subsequently written to the “data” directory.
- For build/deployment, Makefiles coordinate with the compilation scripts (e.g. compile-ampt-mp.sh) to connect the different code bases.
- The Python input generator (from utils) provides dynamically created parameter files that are then used by the simulation processes.
- The external server scripts connect the local file management system with remote servers for data transfer, thus interacting with the file handling subsystem.

##### Architectural Patterns/Technologies
- The separation of concerns is clear: the project is divided into a CLI controller, a core orchestration module managing simulation instances, legacy simulation engines, and auxiliary utilities (Python and shell scripts).
- Use of modern C++ (C++17 standard) with external libraries such as fmt (for formatting), argparse (for command-line parsing), and OpenMP (for multiprocessing), showcasing an approach that combines legacy simulation code (Fortran) with modern orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / Execution Layer
    subgraph "User Interface / Execution Layer"
        CLI["CLI (ampt-mp)"]:::cli
        COMPILE["Shell Script: compile-ampt-mp.sh"]:::cli
        SERVER_SHELL["Shell Scripts: Server Operations"]:::build
    end

    %% Core Processing / Manager Module
    subgraph "Core Processing / Manager Module"
        CPPManager["C++ Simulation Manager (lib)"]:::cpp
        externals["External Libs:(fmt, argparse, OpenMP)"]:::cpp
    end

    %% Simulation Engines (Fortran)
    subgraph "Simulation Engines (Fortran)"
        orig["Original Simulation (src/original)"]:::fortran
        anim["Animation-enabled Simulation (src/animation)"]:::fortran
        hijing["Hijing-only Simulation (src/hijing-only)"]:::fortran
    end

    %% File and Data Handling
    subgraph "File and Data Handling"
        input["Input Files (input)"]:::file
        output["Output/Data (data)"]:::file
    end

    %% Build and Deployment
    subgraph "Build and Deployment"
        MAKE["Makefiles & Build Scripts (make)"]:::build
        SERVER["Deployment/Server Scripts (server)"]:::build
    end

    %% Input Generation Utility
    subgraph "Input Generation Utility"
        python["Python Input Generator (utils/ampt-input-gen.py)"]:::utility
        centrality["Centrality Tables (utils/centrality_tables)"]:::utility
    end

    %% Relationships and Data Flow
    CLI -->|"triggers"| CPPManager
    COMPILE -->|"initiates-build"| MAKE
    CLI -->|"calls"| SERVER_SHELL
    SERVER_SHELL -->|"manages-sync"| SERVER

    externals --- CPPManager

    CPPManager -->|"dispatches"| orig
    CPPManager -->|"dispatches"| anim
    CPPManager -->|"dispatches"| hijing
    CPPManager -.->|"handles-multi-core"| orig

    input -->|"provides-params"| orig
    input -->|"provides-params"| anim
    input -->|"provides-params"| hijing

    orig -->|"writes-output"| output
    anim -->|"writes-output"| output
    hijing -->|"writes-output"| output

    python -->|"generates"| input
    centrality --> python

    MAKE -->|"compiles"| CPPManager
    MAKE -->|"compiles"| orig
    MAKE -->|"compiles"| anim
    MAKE -->|"compiles"| hijing

    SERVER -->|"syncs-data"| output
    SERVER -->|"syncs-build"| MAKE

    %% Click Events
    click COMPILE "https://github.com/lolle2001/ampt-fhmpf/blob/stable/compile-ampt-mp.sh"
    click SERVER_SHELL "https://github.com/lolle2001/ampt-fhmpf/blob/stable/server/fetchfromserver.sh"
    click CPPManager "https://github.com/lolle2001/ampt-fhmpf/blob/stable/lib/InstanceManager.cpp"
    click orig "https://github.com/lolle2001/ampt-fhmpf/tree/stable/src/original"
    click anim "https://github.com/lolle2001/ampt-fhmpf/tree/stable/src/animation"
    click hijing "https://github.com/lolle2001/ampt-fhmpf/tree/stable/src/hijing-only"
    click input "https://github.com/lolle2001/ampt-fhmpf/blob/stable/input/ampt@default.par"
    click output "https://github.com/lolle2001/ampt-fhmpf/tree/stable/data"
    click MAKE "https://github.com/lolle2001/ampt-fhmpf/tree/stable/make/Makefile"
    click SERVER "https://github.com/lolle2001/ampt-fhmpf/tree/stable/server"
    click python "https://github.com/lolle2001/ampt-fhmpf/blob/stable/utils/ampt-input-gen.py"
    click centrality "https://github.com/lolle2001/ampt-fhmpf/tree/stable/utils/centrality_tables"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef cpp fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef fortran fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef file fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef utility fill:#e2d6f7,stroke:#6f42c1,stroke-width:2px;
```
