# donghuison/amrvac architecture

> Architecture diagram of the GitHub repository donghuison/amrvac, 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/donghuison/amrvac
- Repository: https://github.com/donghuison/amrvac

## Overview

##### Project type and purpose
MPI-AMRVAC is an open-source, high‐performance computational physics code for solving (magneto)hydrodynamics and related PDEs on adaptive meshes. It’s written primarily in Fortran, parallelized with MPI, and extended via user modules. Supplementary Python tools support data conversion, analysis, and visualization.

##### File‐structure overview
- arch/: compiler and MPI build configurations (Makefile fragments, platform‐specific flags)
- lib/: reusable makefile logic
- src/: core Fortran source, organized by functionality—AMR engine (src/amr), physics modules (src/hd, src/mhd, src/ard, etc.), numerical schemes (src/limiter, src/mf), I/O (src/io), common utilities (src/mod_*.t)
- tests/: parameter-file–driven regression and demonstration cases, Makefiles to drive test runs
- tools/: auxiliary scripts and programs—Fortran utilities, Python “amrvac_pytools” package for reading, processing, and plotting simulation data
- doc/: Sphinx/Doxygen documentation sources, markdown guides
- top‐level Makefiles and helper scripts (setup.pl, update_dependencies.sh, vacpp.pl)

a. Build & Configuration subsystem
– arch/ and lib/ provide platform/compiler flags & recipes
– top-level Makefile invokes per-module makefiles in src/ and tests/
– setup.pl configures paths, dependency lists
– External dependencies: MPI library, Fortran compiler, Python for tools

b. Core Solver Engine
– AMR Manager (src/amr): grid hierarchy, refinement, load balancing
– Numerical Schemes (src/limiter, src/mf, src/mod_tvd, src/mod_supertimestepping, etc.)
– Physics Modules (src/hd, src/mhd, src/ard, src/rd, src/rhd, src/twofl, etc.): Riemann solvers, source terms
– I/O Module (src/io): reading par files, writing checkpoints, VTK output, field slicing
– Common Utilities (src/mod_basic_types, src/mod_geometry, src/mod_ghostcells_update, etc.)

c. Executable & Runtime
– ‘amrvac’ binary (built from src/amrvac.t and modules)
– Launched under MPI across compute nodes
– Reads user parameter files (.par) and optional user‐supplied routines (mod_usr.t)

d. Data Post‐Processing & Visualization
– Python toolkit (tools/python/amrvac_pytools): readers, regridding, plotting, VTK interfaces
– Standalone Fortran/Perl utilities for log comparison, format conversion (tools/fortran, tools/aiconvert, tools/lessvac)

e. Testing & Continuous Integration
– tests/ harness: structured test suites per physics case, comparison against reference output
– GitHub Actions workflows (/.github/workflows) run docs build, coverage, and regression tests

f. Documentation
– doc/ content compiled via Doxygen (Doxyfile) and Sphinx/Markdown
– Hosted on amrvac.org

##### Interactions & data flow
– Build subsystem → compiles Core Solver Engine → produces amrvac binary
– Users supply .par files and optional mod_usr modules → amrvac runtime under MPI → generates output data (binary dumps, VTK)
– Post‐processing tools consume simulation output → generate plots, diagnostics
– tests/ harness invokes build & runtime, compares results → CI reports status
– Documentation subsystem documents build, usage, module API

##### Architectural patterns & design principles
– Modular Fortran code: each functional area in its own directory, standard .t templates for code generation
– Layered separation: numerical kernels, physics, mesh management, I/O
– Build configured per‐architecture via Makefile snippets (allows portability across compilers, platforms)
– Extensibility via user modules (mod_usr.t) injected at runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External dependencies
    subgraph "External Dependencies"
        MPI["MPI Library"]:::external
        FC["Fortran Compiler"]:::external
        PY["Python Interpreter"]:::external
        VTK["VTK"]:::external
        Cluster["Compute Cluster (MPI)"]:::external
    end

    %% Build & Configuration
    subgraph "Build & Configuration" 
        direction TB
        ARCH["arch/"]:::build
        LIB["lib/makefile"]:::build
        TOP_MAKE["Makefile"]:::build
        SETUP["setup.pl"]:::build
        UPDATE["update_dependencies.sh"]:::build
        VACPP["vacpp.pl"]:::build
    end

    %% Core Solver Engine
    subgraph "Core Solver Engine"
        direction TB
        subgraph "AMR Manager" 
            AMR["src/amr/"]:::fortran
        end
        subgraph "Numerical Schemes"
            LIM["src/limiter/"]:::fortran
            MF["src/mf/"]:::fortran
            TVD["src/mod_tvd.t"]:::fortran
            STS["src/mod_supertimestepping.t"]:::fortran
        end
        subgraph "Physics Modules"
            HD["src/hd/"]:::fortran
            MHD["src/mhd/"]:::fortran
            ARD["src/ard/"]:::fortran
            RD["src/rd/"]:::fortran
            RHD["src/rhd/"]:::fortran
            TWOFL["src/twofl/"]:::fortran
        end
        subgraph "I/O Module"
            IO["src/io/"]:::fortran
        end
        subgraph "Common Utilities"
            UTIL1["src/mod_basic_types.t"]:::fortran
            UTIL2["src/mod_geometry.t"]:::fortran
            UTIL3["src/mod_ghostcells_update.t"]:::fortran
            UTIL4["src/mod_global_parameters.t"]:::fortran
            UTIL5["src/mod_comm_lib.t"]:::fortran
        end
        subgraph "Executable & Runtime Entry"
            ENTRY1["src/amrvac.t"]:::fortran
            ENTRY2["src/mod_amrvac.t"]:::fortran
            USR["tests/*/mod_usr.t"]:::fortran
        end
    end

    %% Executable & Runtime
    AMRVAC["amrvac Binary"]:::fortran
    AMRVAC -->|runs under MPI| Cluster

    %% Data Storage
    Output["Simulation Output (binary, VTK)"]:::data

    %% Post-Processing Tools
    subgraph "Post-Processing & Visualization"
        direction TB
        PYTOOLS["tools/python/amrvac_pytools/"]:::python
        FORTRAN_UTILS["tools/fortran/"]:::python
        AICONV["tools/aiconvert"]:::python
        LESVAC["tools/lessvac"]:::python
    end

    %% Testing & CI
    subgraph "Testing & Continuous Integration"
        direction TB
        TESTS["tests/"]:::build
        WORKFLOWS[".github/workflows/"]:::build
    end

    %% Documentation
    DOC["doc/"]:::build

    %% Connections
    MPI -->|used by| TOP_MAKE
    FC -->|used by| TOP_MAKE
    TOP_MAKE -->|includes| ARCH
    TOP_MAKE -->|includes| LIB
    TOP_MAKE -->|invokes| SETUP
    TOP_MAKE -->|invokes| UPDATE
    TOP_MAKE -->|invokes| VACPP
    TOP_MAKE -->|builds| AMR
    TOP_MAKE -->|builds| LIM
    TOP_MAKE -->|builds| MF
    TOP_MAKE -->|builds| TVD
    TOP_MAKE -->|builds| STS
    TOP_MAKE -->|builds| HD
    TOP_MAKE -->|builds| MHD
    TOP_MAKE -->|builds| ARD
    TOP_MAKE -->|builds| RD
    TOP_MAKE -->|builds| RHD
    TOP_MAKE -->|builds| TWOFL
    TOP_MAKE -->|builds| IO
    TOP_MAKE -->|builds| UTIL1
    TOP_MAKE -->|builds| UTIL2
    TOP_MAKE -->|builds| UTIL3
    TOP_MAKE -->|builds| UTIL4
    TOP_MAKE -->|builds| UTIL5
    TOP_MAKE -->|builds| ENTRY1
    TOP_MAKE -->|builds| ENTRY2
    ENTRY1 -->|produces| AMRVAC
    ENTRY2 -->|produces| AMRVAC
    USR -->|injected at runtime| AMRVAC
    AMRVAC -->|reads .par input| MPI
    AMRVAC -->|writes| Output
    Output -->|consumed by| PYTOOLS
    Output -->|consumed by| FORTRAN_UTILS
    Output -->|consumed by| AICONV
    Output -->|consumed by| LESVAC
    TESTS -->|invoke| TOP_MAKE
    TESTS -->|invoke| AMRVAC
    TESTS -->|compare against| Output
    WORKFLOWS -->|run| TESTS
    WORKFLOWS -->|run docs build| DOC
    DOC -->|hosted on| cluster

    %% Click Events
    click ARCH "https://github.com/donghuison/amrvac/tree/master/arch/"
    click LIB "https://github.com/donghuison/amrvac/tree/master/lib/makefile"
    click TOP_MAKE "https://github.com/donghuison/amrvac/tree/master/Makefile"
    click SETUP "https://github.com/donghuison/amrvac/blob/master/setup.pl"
    click UPDATE "https://github.com/donghuison/amrvac/blob/master/update_dependencies.sh"
    click VACPP "https://github.com/donghuison/amrvac/blob/master/vacpp.pl"
    click AMR "https://github.com/donghuison/amrvac/tree/master/src/amr/"
    click LIM "https://github.com/donghuison/amrvac/tree/master/src/limiter/"
    click MF "https://github.com/donghuison/amrvac/tree/master/src/mf/"
    click TVD "https://github.com/donghuison/amrvac/blob/master/src/mod_tvd.t"
    click STS "https://github.com/donghuison/amrvac/blob/master/src/mod_supertimestepping.t"
    click HD "https://github.com/donghuison/amrvac/tree/master/src/hd/"
    click MHD "https://github.com/donghuison/amrvac/tree/master/src/mhd/"
    click ARD "https://github.com/donghuison/amrvac/tree/master/src/ard/"
    click RD "https://github.com/donghuison/amrvac/tree/master/src/rd/"
    click RHD "https://github.com/donghuison/amrvac/tree/master/src/rhd/"
    click TWOFL "https://github.com/donghuison/amrvac/tree/master/src/twofl/"
    click IO "https://github.com/donghuison/amrvac/tree/master/src/io/"
    click ENTRY1 "https://github.com/donghuison/amrvac/blob/master/src/amrvac.t"
    click ENTRY2 "https://github.com/donghuison/amrvac/blob/master/src/mod_amrvac.t"
    click USR "https://github.com/donghuison/amrvac/blob/master/tests/*/mod_usr.t"
    click PYTOOLS "https://github.com/donghuison/amrvac/tree/master/tools/python/amrvac_pytools/"
    click FORTRAN_UTILS "https://github.com/donghuison/amrvac/tree/master/tools/fortran/"
    click AICONV "https://github.com/donghuison/amrvac/tree/master/tools/aiconvert"
    click LESVAC "https://github.com/donghuison/amrvac/tree/master/tools/lessvac"
    click TESTS "https://github.com/donghuison/amrvac/tree/master/tests/"
    click WORKFLOWS "https://github.com/donghuison/amrvac/tree/master/.github/workflows/"
    click DOC "https://github.com/donghuison/amrvac/tree/master/doc/"

    %% Styles
    classDef fortran fill:#D0E4F5,stroke:#4B8BBE,color:#333
    classDef python fill:#DFF5E1,stroke:#4CAF50,color:#333
    classDef build fill:#FFE8B5,stroke:#FFB300,color:#333
    classDef external fill:#E0E0E0,stroke:#999,color:#333
    classDef data fill:#F0F0F0,stroke:#666,color:#333,shape:database
```
