Chaste Docker镜像文档

![Chaste logo]([***]

Chaste的Docker镜像

![Docker拉取次数]([] ![MIT许可证]([] ![DOI]([] ![构建chaste/base]([]

快速开始

1. 安装Docker 并分配至少4GB内存
2. docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 这是你在Chaste中的终端：chaste@301291afbedf:~$ 祝你使用愉快！;)

简介

Docker是一种轻量级虚拟化技术，允许应用程序及其所有依赖项以平台无关的方式快速轻松地运行。本项目提供包含Chaste（以及一些便捷脚本）的镜像，可通过单条命令启动，为癌症、心脏和软组织模拟提供跨多个操作系统和无数硬件配置的便携式、同构计算环境。

Docker允许从纯文本Dockerfile构建和运行计算环境。这类似于从源代码编译可执行文件（相当于使用docker build从Dockerfile生成镜像），然后将其作为运行程序执行（类似于使用docker run运行容器）。这种类比的步骤如Nüst等人2020年的下图所示。

Docker容器类比

更广泛地说，Docker还有一个存储预构建镜像的镜像仓库：[]docker push）并下载他人的镜像（例如使用docker pull），包括容器化应用（如Python和WordPress）以及基础镜像（如Ubuntu和Alpine），用于构建自己的镜像。Docker架构和更广泛的生态系统如此处所示。

有关介绍Docker以及如何使用此Chaste镜像的研讨会幻灯片可在此处找到。

开始使用

前提条件

安装Docker并将其配置为至少有4GB内存和尽可能多的核心（超过四个核心需要更多内存）。

:warning: 为Docker分配至少4GB内存，否则编译将因奇怪的错误而失败！

[推荐] 使用预构建镜像

1. 如果你想使用最新版本，完全编译并随时可用，安装并配置Docker后只需运行：

   docker run --init -it --rm -v chaste_data:/home/chaste chaste/release
   

   如果需要，还可以在镜像名称中指定可用标签，格式为chaste/release:<tag>，以拉取特定版本（例如chaste/release:2024.1），而不是默认的最新版本。
2. 或者，如果你想使用develop分支的最新开发代码，使用以下命令拉取并运行最新的chaste/develop镜像：

   docker run --init -it --rm -v chaste_data:/home/chaste chaste/develop
   

容器成功启动后，你应该看到类似于以下的命令提示符：

chaste@301291afbedf:~$

这是隔离的Docker容器（基于ubuntu）中的bash提示符，包含开始构建自己的Chaste项目所需的所有依赖项和预编译代码。在这里，你可以构建和测试项目，而不会干扰系统的其他部分。

:information_source: 要查看运行中容器的系统资源使用情况，请打开另一个终端并运行docker stats。

如果你还没有项目，只需使用提供的脚本new_project.sh在~/projects中创建项目模板作为起点。可在以下位置找到许多项目教程：[***]

准备好构建项目后，使用脚本build_project.sh <TestMyProject> c（将<TestMyProject>替换为你的项目名称），输出将在~/output中找到（仅当创建新文件时才需要c参数）。

:information_source: 要在Docker容器和主机之间轻松共享数据（例如output目录），可以向命令添加绑定挂载参数：-v /host/path/to/output:/home/chaste/output。有关更多详细信息，请参见绑定挂载说明。

当你使用完容器后，只需输入exit或按Ctrl+D关闭它（如有必要，先按Ctrl+C停止任何运行中的进程）。重新启动容器时，/home/chaste中所做的任何更改都将保留，但是如果容器被删除，其他所有内容（例如已安装的软件包、对系统文件的更改）都将重置为首次使用镜像时的状态。

[替代方案] 使用VS Code开发容器

如果你使用VS Code并已安装Docker，只需克隆Chaste代码仓库并在VS Code中打开它（如果提示，安装Remote Development扩展包）。最后，当扩展提示时，点击"在容器中重新打开"。这将无缝地为你拉取、运行和挂载最新的chaste/develop镜像。

:information_source: 注意，这会将本地克隆的Chaste代码副本挂载到容器中，覆盖镜像中已包含的副本。虽然预编译的二进制文件是基于镜像的内部代码副本构建的，但它们将相对最新，因此重新编译以与你对本地克隆代码所做的更改同步不会花费太长时间。

容器目录结构

启动后，容器将在chaste用户的主目录/home/chaste中启动，结构如下：

bash
.
|-- build
|-- projects -> /home/chaste/src/projects
|-- scripts
|-- src
`-- output

这些文件夹包含以下类型的数据：

• build：预编译的Chaste二进制文件和库
• projects：指向/home/chaste/src/projects的符号链接，用于用户项目
• scripts：用于创建、构建和测试项目的便捷脚本
• src：Chaste源代码
• output：项目测试框架的输出文件夹（由$CHASTE_TEST_OUTPUT设置）

还设置了相应的环境变量如下：

• CHASTE_DIR="/home/chaste"
• CHASTE_BUILD_DIR="${CHASTE_DIR}/build"
• CHASTE_PROJECTS_DIR="${CHASTE_DIR}/src/projects"
• CHASTE_SOURCE_DIR="${CHASTE_DIR}/src"
• CHASTE_TEST_OUTPUT="${CHASTE_DIR}/output"

:information_source: 如果构建自己的镜像，可以在构建时使用构建参数更改CHASTE_DIR路径，例如--build-arg CHASTE_DIR=/path/to/alternative，然后其他目录将相对于该路径设置。

主文件夹（/home/chaste）中所做的任何更改将在重新启动容器之间保持，因为它被指定为VOLUME。此外，可以将特定文件夹挂载到这些子文件夹中的任何一个上，例如，访问测试输出以在ParaView中可视化，或挂载不同版本的Chaste源代码。通常，数据应保留在（命名的）卷中，因为这样文件I/O性能最佳。但是，绑定挂载主机目录可能很方便（例如访问输出文件），下面将进行说明。

:warning: Docker容器本质上是临时性的，退出后不会保存任何更改（除了卷中或从主机绑定挂载的文件夹中的文件）。容器主目录的内容（包括Chaste源代码和二进制文件）存储在Docker VOLUME中，因此将在容器实例之间保持。但是，如果重置Docker，所有卷及其包含的数据都将丢失，因此请确保定期将项目推送到远程git仓库！

主机与容器间共享数据

此镜像设置为将Chaste源代码、编译的库和脚本存储在Docker卷中，因为这是推荐的数据持久化机制，并在多个平台上提供最佳的文件I/O性能。

这种挂载类型的一个缺点是更难从主机访问内容。但是，要直接访问容器的output等内容，或与容器共享主机上的数据集，可以使用绑定挂载（如果需要，甚至可以覆盖卷中的目录）。

有关Docker挂载选项的更多详细信息和说明，请参见存储文档。

绑定挂载

可以挂载任何主机目录（使用绝对路径指定，例如/path/to/output）到容器中（例如output目录）。或者，导航到主机上包含这些目录的文件夹（例如Windows上的C:\Users\$USERNAME\chaste或Linux/macOS上的~/chaste），并如下所示使用$(pwd)/output。在以下示例中，为简单起见，假设镜像名称（最后一个参数）为chaste/release，而不是chaste/develop或chaste/release:2024.1等。

docker run -it --init --rm -v chaste_data:/home/chaste -v "${PWD}"/output:/home/chaste/output chaste/release

复制数据进出容器

在macOS和Windows上（但不是Linux），从主机读取和写入绑定挂载中的文件比Docker卷中的文件有更大的开销。这可能会减慢在这些文件夹（例如output）中有大量文件I/O的模拟，因此在这种情况下应谨慎使用绑定挂载。更快的替代方法是将文件留在卷中，并在模拟结束时使用docker cp将它们复制出来（或将修改后的文件复制进去）。

例如，使用以下命令复制整个src文件夹，其中容器已使用以docker run --name chaste ...开头的命令标记为chaste：

bash
docker cp chaste:/home/chaste/src .  # 复制出来
# 在此处修改源文件
docker cp src/. chaste:/home/chaste/src  # 复制进去

在容器内开发代码

我们建议使用VS Code和"Remote Development"扩展，该扩展允许直接访问、编辑和搜索容器内的文件，就像它们在主机系统上一样，同时保持将文件保存在卷中的性能优势。

:information_source: 这些步骤与当前推荐的预构建镜像方法相关。如果你使用新的VS Code开发容器说明，这些步骤会自动完成。

1. 从终端使用给定的命令启动容器
2. 在VS Code中选择"Remote-Containers: Attach to Running Container..."（远程容器：附加到运行中的容器...）
3. 选择chaste-docker容器（除非你通过在运行命令中添加--name <name>来启动它，否则它将有一个随机名称）
4. 使用VS Code的内置文件浏览器打开文件夹/home/chaste，你将能够访问上面描述的文件和目录。

替代方法 [点击展开]

1. 虽然最好将代码留在卷中以获得更好的性能，但你可能希望使用另一个绑定挂载将卷的~/src文件夹与包含Chaste源代码的主机目录覆盖，例如-v /path/to/chaste_code:/home/chaste/src。然后可能需要在容器内使用build_chaste.sh <branch/tag>重新编译Chaste，或者如果你已在挂载的主机文件夹中有代码，可以在重新编译前跳过克隆，使用build_chaste.sh .。这将使相同的源文件可直接在主机和Docker容器中访问，避免来回复制文件或使用VS Code的需要。这可能导致比存储在Docker卷中时更慢的I/O，但是在macOS上，可以使用delegated选项缓解此问题，例如--mount type=bind,source="$(pwd)"/chaste_code,destination=/home/chaste/src,consistency=delegated。

2. 或者，使用工具docker-sync：[***]

:information_source: 如需从终端对代码进行小的编辑，镜像中安装了nano以便使用，同时还安装了git用于推送更改。

安装额外软件

如果你想使用镜像中未安装的软件包，可以使用以下命令安装：

sudo apt-get update && sudo apt