构建 MFIX-Exa

此页面提供了使用 gmake 和 cmake 构建 MFIX-Exa 的通用说明。说明假定您已经下载并解压了 MFIX-Exa 代码到本地 mfix 目录。如果没有，请先访问 下载页面。对于 HPC 集群的特定说明，请参阅 在HPC系统上构建。

使用 gmake 构建

如果您想使用 gmake 构建 MFIX_Exa，您需要将 amrex 和 AMReX-Hydro 克隆到本地目录：

> git clone https://github.com/AMReX-Codes/amrex.git
> git clone https://github.com/AMReX-Codes/AMReX-Hydro.git
> cd mfix/exec

然后，编辑 GNUmakefile （或设置一个环境变量）以定义 AMREX_HOME 和 AMREX_HYDRO_HOME 为您放置 amrex 和 AMReX-Hydro 的目录路径。注意，AMREX_HOME 和 AMREX_HYDRO_HOME 的默认位置是在子项目目录中，这是 cmake 配置可能克隆这些存储库的位置。您可以设置的其他选项包括

选项名称	描述	可能的值	默认值
COMP	编译器（gnu 或 intel）	gnu / intel	gnu
USE_MPI	启用 MPI	TRUE / FALSE	FALSE
USE_OMP	启用 OpenMP	TRUE / FALSE	FALSE
USE_CSG	启用 CSG 几何文件支持	TRUE / FALSE	FALSE
USE_CUDA	启用 CUDA GPU 支持	TRUE / FALSE	FALSE
USE_HIP	启用 HIP GPU 支持	TRUE / FALSE	FALSE
USE_DPCPP	启用 DPCPP GPU 支持	TRUE / FALSE	FALSE
USE_HYPRE	启用 HYPRE 支持	TRUE / FALSE	FALSE
DEBUG	创建一个 DEBUG 可执行文件	TRUE / FALSE	FALSE
PROFILE	包含分析信息	TRUE / FALSE	FALSE
TRACE_PROFILE	包含跟踪分析信息	TRUE / FALSE	FALSE
COMM_PROFILE	包含通信分析信息	TRUE / FALSE	FALSE
TINY_PROFILE	包含微型分析信息	TRUE / FALSE	FALSE
DIM	问题的维度	2 / 3	3

备注

不要同时将 USE_OMP 和 USE_CUDA/ HIP/ DPCPP 设置为 true。

然后输入

> make -j

一个可执行文件将出现；可执行文件的名称将反映上述一些构建选项。

使用 cmake 构建

CMake 构建是一个两步的过程。首先调用 cmake 在选定目录（ builddir ）中创建配置文件和 makefiles。接下来，通过在 builddir 中调用 make 来执行实际构建。如果您是 CMake 的新手，这个简短教程 是一个完美的入门之处。

MFIX-Exa 的 CMake 构建过程概述如下：

>> mkdir /path/to/builddir
>> cd    /path/to/builddir
>> cmake [options] -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel] /path/to/mfix
>> make

在上述代码段中，[options] 表示一个或多个用于构建定制的选项，如本节后面所述。如果省略了选项 CMAKE_BUILD_TYPE，则假定 CMAKE_BUILD_TYPE=Release。

使用 cmake 构建 MFIX-Exa 有两种模式：

o SUPERBUILD（推荐）： 在 MFIX-Exa 构建过程中，AMReX 和 AMReX-Hydro git 仓库作为子项目被克隆和构建，并放置在 mfix/subprojects 目录中。每个仓库可以像常规的 git 仓库一样操作（您可以更改分支、哈希、添加远程等）。强烈建议使用这种方法，因为它确保 MFIX-Exa 的配置选项与检出的 AMReX 和 AMReX-Hydro 哈希兼容。

o STANDALONE： MFIX-Exa 源代码被单独构建并链接到现有的 AMReX 和 AMReX-Hydro 仓库。这对于持续集成服务器（CI）和回归测试应用程序是理想的。AMReX 和 AMReX_Hydro 库版本及配置选项必须满足 MFIX-Exa 的要求。

备注

MFIX-Exa 需要 CMake 3.20 或更高版本。

SUPERBUILD 指南（推荐）

默认情况下，MFIX-Exa CMake 在系统上寻找现有的 AMReX 安装。如果没有找到，它将回退到 SUPERBUILD 模式。在这种模式下，MFIX-Exa CMake 继承了 AMReX CMake 目标和配置选项，即 MFIX-Exa 和 AMReX 被配置和构建为一个单一实体。

假设目标系统上没有有效的 AMReX 安装，并且没有设置 AMReX_ROOT （见 STANDALONE指南），以下代码将在 SUPERBUILD 模式下构建 MFIX-Exa：

> cd mfix/
> mkdir build
> cd build
> cmake [mfix options] [amrex options] -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel] ..
> make -j

上述代码段中的 [amrex options] 是 AMReX 用户指南中列出的任何 AMReX 配置选项的列表， 而 [mfix options] 是 here 中列出的任何配置选项。

例如，要在 MFIX_Exa 中启用 AMReX 分析功能，配置如下：

> cmake [mfix options] -DAMReX_TINY_PROFILE=yes -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel] ..

使用 AMReX 子模块

SUPERBUILD 模式依赖于一个 git 子模块来检出 AMReX git 仓库。 如果 AMReX 子模块未初始化，SUPERBUILD 模式将初始化它并检出子模块指向的 AMReX 提交。 相反，如果 AMReX 子模块已经手动初始化并检出自定义提交，SUPERBUILD 模式将使用该提交。对于 MFIX-Exa 的开发或测试，您可能需要使用 AMReX 的不同分支或版本进行构建。

subprojects/amrex 目录是一个 Git 仓库，因此可以使用所有标准的 Git 命令。可以 cd subprojects/amrex 来在 amrex 目录中运行 Git 命令，或者在 MFIX-Exa 仓库中使用 git -C subprojects/amrex。例如，要使用 AMReX 仓库的 my-amrex-branch 分支进行构建：

> cd /path/to/mfix
> git -C subprojects/amrex checkout my-amrex-branch
> git status
...
modified:   subprojects/amrex (new commits)

然后在构建 MFIX-Exa 时将使用分支 my-amrex-branch。

要恢复到 AMReX 子模块的默认版本，请运行 git submodule update：

> cd /path/to/mfix
> git submodule update

您可以从 subprojects/amrex 编辑、提交、拉取和推送 AMReX 更改。 AMReX 的开发不在本文档的范围内。在顶级 MFix-Exa 仓库中运行 git status，以查看 AMReX 子模块是否有新的提交、修改的文件或未跟踪的文件。

要更新 MFIX-Exa 引用的 AMReX 子模块：

> git -C subprojects/amrex checkout UPDATED_AMREX_COMMIT_SHA1
> git add subprojects/amrex
> git commit -m 'Updating AMReX version'

这将仅更新 MFIX-Exa 引用的 AMReX SHA-1。未提交的 AMReX 更改和在 subprojects/amrex 下的未跟踪 AMReX 文件不会通过 git add subprojects/amrex 添加。（要提交到 AMReX 仓库，请切换到 subprojects/amrex 目录并在那里运行 Git 命令，然后再 git add subprojects/amrex。）

备注

仅在与其他 MFIX-Exa 开发人员协调后更新 AMReX 子模块引用！

STANDALONE指南

构建 AMReX

从官方 Git 仓库克隆 AMReX。 请注意唯一可用的分支是 development：

> git clone https://github.com/AMReX-Codes/amrex.git

接下来，配置、构建和安装 AMReX 如下：

> cd amrex
> mkdir build
> cd build
> cmake -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel] -DAMReX_PARTICLES=yes -DAMReX_EB=yes -DAMReX_PLOTFILE_TOOLS=yes [其他 amrex 选项] -DCMAKE_INSTALL_PREFIX:PATH=/absolute_path_to_amrex_installdir ..
> make install

选项 AMReX_PARTICLES=yes、AMReX_EB=yes 和 AMReX_PLOTFILE_TOOLS=yes 是 MFIX-Exa 所需的。上面的代码片段中的 [其他 amrex 选项] 指除了必需选项之外的任何其他 AMReX 配置选项。请参阅 AMReX 用户指南 以获取有关使用 CMake 构建 AMReX 的更多详细信息。

构建 MFIX-Exa

克隆并构建 MFIX-Exa：

> cd mfix/
> mkdir build
> cd build
> cmake -DCMAKE_BUILD_TYPE=[Debug|Release|RelWithDebInfo|MinSizeRel] [mfix 选项] -DAMReX_ROOT=/absolute/path/to/amrex/installdir ..
> make -j

传递 -DAMReX_ROOT=/absolute/path/to/amrex/installdir 指示 CMake 在搜索系统路径中可用的 AMReX 安装之前搜索 /absolute/path/to/amrex/installdir。 AMReX_ROOT 也可以设置为环境变量，而不是作为命令行选项传递。 [mfix 选项] 表示下表中列出的任何配置选项。

表 1 MFIX-Exa 配置选项

选项名称	描述	可能的值	默认值
CMAKE_CXX_FLAGS	用户定义的 C++ 标志	有效的 C++ 编译器标志	无
CMAKE_CUDA_FLAGS	用户定义的 CUDA 标志	有效的 CUDA 编译器标志	无
MFIX_MPI	启用 MPI 构建	no/yes	yes
MFIX_OMP	启用 OpenMP 构建	no/yes	no
MFIX_GPU_ BACKEND	节点内加速 GPU 后端	NONE,SYSCL,CUDA,HIP	NONE
MFIX_HYPRE	启用 HYPRE 支持	no/yes	no
MFIX_FPE	构建具有浮点异常检查的版本	no/yes	no
MFIX_CSG	构建具有 CSG 支持的版本	no/yes	no
MFIX_MPI_ THREAD_MULTIPLE	从多个线程进行并发 MPI 调用	no/yes	no

使用 cmake 构建 MFIX-Exa 的更多注意事项

系统默认编译器可以通过以下方式覆盖：

> cmake -DCMAKE_CXX_COMPILER=<c++-compiler> [选项]  ..

在使用 module 实用程序的平台上构建时，使用上述命令（包含编译器的完整路径）或以下命令：

> cmake -DCMAKE_CXX_COMPILER=CC [选项] ..

MFIX-Exa 使用与 AMReX 构建相同的编译器标志，除非明确提供了 CMAKE_CXX_FLAGS 或设置了环境变量 CXXFLAGS。

对于 GPU 构建，MFIX-Exa 依赖于 AMReX GPU 构建基础设施。可以通过 AMReX 配置选项 -DAMReX_CUDA_ARCH=<target-architecture> 指定要构建的目标架构，或通过定义 环境变量 AMREX_CUDA_ARCH （全大写）。如果未指定 GPU 架构，CMake 将尝试确定系统支持的 GPU。