How donghuison/amrvac works
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