盖亚

[Discord]

没有微小到可以忽视的文字，也没有抽象到无法接受的设计。

-- <cite>何陈安卡</cite>

<img alt="teaser.gif" src="https://yellow-cdn.veclightyear.com/835a84d5/6bba6c4b-57c1-42a5-a511-824cf1c1169b.gif?raw=true" data-hpc="true" class="Box-sc-g0xbh4-0 kzRgrI" height="256px">

盖亚引擎是一个主要用于物理模拟的C++代码库。它可以编译为独立的模拟器，也可以作为第三方模块集成到其他应用程序中。 它提供了一套实用工具，包括强大的三角形/四面体网格数据结构、便捷的参数输入输出模块、一组高效的碰撞检测器，以及可扩展以支持各种求解器的抽象基础物理框架。

盖亚的设计旨在提高开发人员和运行硬件的效率。有时需要做出折衷，因为优化其中一个可能会对另一个产生不利影响。它可能并非在所有方面都有最聪明的设计。但可以肯定的是，盖亚没有任何愚蠢的设计。

安装

获取代码

请使用以下命令下载代码：

git clone git@github.com:AnkaChan/Gaia.git --recursive

依赖项

该算法有以下依赖项：

• MeshFrame2：用于网格处理的几何核心库（已作为子模块包含）
• CuMatrix：用于几何和矩阵计算（已作为子模块包含）
• cmake-git-version-tracking：用于在运行实验时跟踪git版本信息（已作为子模块包含）
• OneTBB（需要安装，已测试版本2021.12.0）
• Eigen3（需要安装，已测试版本3.4.0）
• Embree（需要安装，已测试版本3.13.1，不兼容Embree 4）
• polyscope：如果CMAKE的BUILD_GUI选项开启，则需要此依赖（已作为子模块包含）

确保安装了OneTBB、Eigen3和Embree。然后添加环境变量"Eigen3_DIR"和"embree_DIR"，将它们的值设置为各自的config.cmake路径。这一步对于CMake成功定位它们是必要的。

将GAIA用作独立模拟器

目前提供了基于VBD（顶点块下降法）和XPBD（扩展位置基动力学）的模拟器。独立模拟器的CMakelists.txt分别位于Gaia/Simulator/VBDDynamics和Gaia/Simulator/PBDDynamics。要使用模拟器，你需要使用CMake构建并编译它。目前，兼容性测试仅在Windows和Visual Studio环境下进行。

将GAIA用作模块

盖亚提供了自己的GAIA-config.cmake文件，位于Gaia/Simulator/CMake。要将盖亚作为模块集成到你的项目中，你应该在项目的CMakeLists.txt文件中添加include([GAIA路径]/Simulator/cmake/GAIA-config.cmake)这一行。或者，你可以通过定义名为GAIA_DIR的环境变量，将其值设置为[GAIA路径]/Simulator/cmake/，并使用CMake命令find_package(GAIA)来使盖亚对CMake可见。这两种方法都能让CMake解析GAIA-config.cmake文件。

加载GAIA-config.cmake文件后，你需要添加以下命令将盖亚链接到你的项目：

include_directories(
	${GAIA_INCLUDE_DIRS}
)
SET (YOUR_SRCS 
	${YOUR_SRCS}
	${GAIA_SRCS}
)
add_executable(YouApplication 
	${YOUR_SRCS}
)
target_link_libraries(YouApplication ${GAIA_LIBRARY})

Gaia引擎提供了各种可以启用或禁用的模块，适用于独立模式和模块模式。这个功能通过一系列CMake选项实现： set(GAIA_OPTION ON/OFF)。 你需要在命令include([PATH_TO_GAIA]/Simulator/cmake/GAIA-config.cmake)或find_package(GAIA)之前设置此选项才能生效。 这些选项决定了包含在${GAIA_SRCS}中的源文件，以及包含在${GAIA_LIBRARY}中的静态库。 目前可用的选项有：

• BUILD_PBD：是否构建XPBD相关的源文件。
• BUILD_VBD：是否构建VBD相关的源文件。
• BUILD_GUI：是否构建GUI相关的源文件。如果此选项设置为true，则需要polyscope。
• BUILD_Collision_Detector：是否构建碰撞检测相关的源文件。如果BUILD_PBD或BUILD_VBD为开启状态，此选项将自动开启。

Gaia的VBD（顶点块下降）模拟器

要使用Gaia的VBD模拟器，你需要构建位于Gaia/Simulator/VBDDynamics的项目。

GAIA模拟器接受三个位置命令行参数以及几个可选的关键字参数。以下是运行GAIA模拟器的基本语法：

Path-to-VBDDynamics.exe Models.json Parameters.json output-folder -R [PATH-to-Gaia-Repository]

我已经准备了一些参数，位于/Simulator/VBDDynamics/ParameterGen/Parameters/。运行以下命令，你应该能看到32个模型依次掉入一个盒子的模拟：

Path-to-VBDDynamics.exe [PATH-to-Gaia-Repository]/Simulator/VBDDynamics/ParameterGen/Parameters/S01_Experiment_HybridModelsDrop_sequentiallyAppea/S01_Experiment_HybridModelsDrop_sequentiallyAppear/Models.json [PATH-to-Gaia-Repository]/Simulator/VBDDynamics/ParameterGen/Parameters/S01_Experiment_HybridModelsDrop_sequentiallyAppea/S01_Experiment_HybridModelsDrop_sequentiallyAppear/Parameters.json noOutput -R [PATH-to-Gaia-Repository] --gui

请记得将"[PATH-to-Gaia-Repository]"替换为Gaia仓库的绝对路径。

第一个参数，即"Models.json"文件，指定了要模拟的模型的详细信息，而"Parameters.json"包含了模拟的物理参数。第三个参数"output-folder"指定了存储模拟结果的目录。如果设置为"noOutput"，模拟器将不保存模拟结果。 关键字参数"-R [PATH-to-Gaia-Repository]"用于将"Models.json"和"Parameters.json"中的占位符"${REPO_ROOT}"替换为Gaia仓库的实际路径，简化了加载过程。要了解更多命令行选项，请执行： VBDDyanmics -h。

鉴于手动创建"Models.json"和"Parameters.json"的复杂性，GAIA提供了可以生成这些模拟参数的Python脚本。这些脚本涵盖了我的论文"顶点块下降"中包含的大多数实验。请查看：/Simulator/VBDDynamics/ParameterGen/以获取这些命令。

此外，你可以通过将"run"变量设置为True来使用这些Python脚本运行实验。这提供了一种更直观的方式来调整参数和自动化你的实验。为确保Python脚本识别你的环境，你需要在/Simulator/VBDDynamics/ParameterGen/M02_GenRunningParameters.py中的"machines"字典中添加适当的属性：

    "环境名称": {
        "binaryFile": VBDDynamics.exe的绝对路径,
        "RepoPath": str(pathlib.Path(__file__).parent.parent.parent.parent.resolve()), #不要改变这个
        "OutputDirs": [
            你偏好的输出路径,
        ]
    },

然后将"machineName"变量设置为你环境的名称。Python脚本将能够执行模拟。

Gaia的PBD模拟器

PBD模拟器使用的命令与VBD模拟器类似。但请不要将VBD的参数输入到PBD模拟器中，反之亦然。相反，请使用位于\Simulator\PBDDynamics\ParameterGen的参数。运行Gaia PBD模拟器的语法与VBD模拟器相似：

Path-to-VBDDynamics.exe Models.json Parameters.json output-folder -R [PATH-to-Gaia-Repository]

四面体网格和三角网格着色

着色工具包位于：\Simulator\GraphColoring。 示例用法：

GraphColoring.exe model.t model.vertexColoring.json -v -b

"-v"表示这是顶点着色。"-b"表示它将尝试平衡每种颜色的顶点数量。

常见问题

1. "主机密钥验证失败。致命错误：无法从远程仓库读取。" 这个问题可能是因为Github不在你的~/.ssh/known_hosts文件中。 将GitHub添加到授权主机列表中： ssh-keyscan -H github.com >> ~/.ssh/known_hosts