chaste/base

Chaste Docker镜像文档

!Chaste logo

https://github.com/Chaste/chaste-docker


快速开始

1. 安装Docker 并分配至少4GB内存
2. 执行命令: docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 进入Chaste终端环境:
   `chaste@301291afbedf:~# Chaste Docker镜像文档

!Chaste logo

https://github.com/Chaste/chaste-docker


快速开始

1. 安装Docker 并分配至少4GB内存
2. 执行命令: docker run -it --init --rm -v chaste_data:/home/chaste chaste/release
3. 进入Chaste终端环境:

开始使用吧！

1. 镜像概述和主要用途

1.1 概述

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

1.2 主要用途

• 提供预配置的Chaste运行环境，避免复杂的依赖安装
• 支持跨平台（Linux/macOS/Windows）的一致计算体验
• 简化Chaste项目的开发、编译和测试流程
• 确保模拟结果的可重复性（统一的依赖版本和编译环境）

2. 核心功能和特性

• 完整依赖栈：包含Chaste运行所需的所有系统库和工具
• 预编译环境：最新稳定版Chaste已预编译，可直接运行
• 数据持久化：使用Docker数据卷保存用户数据和项目文件
• 便捷脚本：提供new_project.sh、build_project.sh等脚本简化开发流程
• 多版本支持：通过标签（如:2024.1）支持特定Chaste版本
• 资源优化：针对计算密集型模拟优化的系统配置

3. 使用场景和适用范围

3.1 适用场景

• 学术研究：心脏、癌症和软组织的生物力学模拟
• 教学环境：Chaste用户教程和案例演示
• 跨平台开发：在不同操作系统间保持一致的开发环境
• 可重复研究：确保模拟结果在不同计算环境中的一致性

3.2 硬件要求

• Docker引擎：至少4GB内存（推荐8GB以上）
• 处理器：支持64位架构的多核CPU
• 磁盘空间：至少10GB可用空间（含镜像和数据卷）

4. 详细使用方法和配置说明

4.1 环境准备

4.1.1 Docker安装

根据操作系统选择对应安装方式：

⚠️ 警告：Docker必须分配至少4GB内存，否则编译会失败并出现异常错误！

4.2 启动容器

4.2.1 使用预构建镜像（推荐）

稳定版（最新发布版）：

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

指定版本（如2024.1）：

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

开发版（最新开发分支代码）：

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

4.2.2 容器启动参数说明

• --init：确保容器内进程正确处理信号
• -it：交互式终端模式
• --rm：容器退出后自动删除
• -v chaste_data:/home/chaste：将数据卷chaste_data挂载到容器内/home/chaste目录（持久化用户数据）

4.3 基本操作

4.3.1 创建新项目

容器启动后，使用内置脚本创建项目模板：

bash
new_project.sh MyProject  # 在~/projects目录创建MyProject项目

4.3.2 编译项目

bash
build_project.sh TestMyProject  # 编译TestMyProject项目
# 新增文件时需添加-c参数
build_project.sh TestMyProject c

4.3.3 运行测试

使用test.sh脚本运行测试套件：

bash
test.sh  # 运行连续测试套件
# 或直接使用ctest命令
ctest -j$(nproc) -L Continuous  # 并行运行所有连续测试

4.3.4 检查系统资源

新开终端执行以下命令查看容器资源使用情况：

bash
docker stats

4.4 容器目录结构与环境变量

4.4.1 目录结构

容器启动后，用户主目录/home/chaste包含以下子目录：

/home/chaste/
├── build        # 预编译的Chaste二进制文件和库
├── projects     # 项目目录（链接到src/projects）
├── scripts      # 便捷脚本目录
├── src          # Chaste源代码
└── output       # 测试和模拟输出目录

4.4.2 环境变量

容器内预设以下环境变量：

4.5 主机与容器间的数据共享

4.5.1 使用Docker数据卷（推荐）

默认情况下，/home/chaste目录挂载为Docker数据卷，数据会在容器重启后保留。查看数据卷：

bash
docker volume inspect chaste_data

4.5.2 使用绑定挂载

如需直接访问容器内文件（如输出结果），可使用绑定挂载：

挂载输出目录：

bash
# Linux/macOS
docker run --init -it --rm -v chaste_data:/home/chaste -v $(pwd)/output:/home/chaste/output chaste/release

# Windows (PowerShell)
docker run --init -it --rm -v chaste_data:/home/chaste -v ${PWD}/output:/home/chaste/output chaste/release

挂载本地项目目录：

bash
docker run --init -it --rm -v chaste_data:/home/chaste -v /path/to/local/projects:/home/chaste/src/projects chaste/release

⚠️ 注意：绑定挂载可能影响文件I/O性能，特别是在macOS和Windows系统上。对于大型项目，建议使用数据卷并通过docker cp命令传输文件。

4.6 在容器内开发代码

4.6.1 使用VS Code远程开发（推荐）

1. 安装VS Code及Remote Development扩展包
2. 启动Chaste容器
3. 在VS Code中选择"远程容器：附加到正在运行的容器..."
4. 选择Chaste容器并打开/home/chaste目录

4.6.2 复制文件进出容器

从容器复制文件到主机：

bash
docker cp <容器ID或名称>:/home/chaste/output ./local_output

从主机复制文件到容器：

bash
docker cp ./local_projects <容器ID或名称>:/home/chaste/src/projects

4.7 安装额外软件

容器内可使用sudo安装额外系统包，密码为chaste：

bash
sudo apt-get update && sudo apt-get install <包名>

⚠️ 注意：通过sudo安装的软件在容器删除后会丢失。如需永久保留，建议省略docker run命令中的--rm参数，或构建自定义镜像。

5. 高级用法

5.1 构建自定义镜像

5.1.1 基于最新发布版构建

bash
docker build -t chaste:custom --build-arg GIT_TAG=develop https://github.com/Chaste/chaste-docker.git

5.1.2 基于特定版本构建

bash
# 构建2024.1版本
docker build -t chaste:2024.1 --build-arg GIT_TAG=2024.1 https://github.com/Chaste/chaste-docker.git

5.1.3 构建基础镜像（不含预编译Chaste）

bash
docker build -t chaste:base --build-arg GIT_TAG=- https://github.com/Chaste/chaste-docker.git

5.1.4 自定义构建参数

5.2 使用VS Code DevContainer

1. 安装VS Code及Remote Development扩展包
2. 克隆Chaste代码仓库：

   bash
   git clone https://github.com/Chaste/Chaste.git
   

3. 在VS Code中打开仓库目录
4. 当提示"Reopen in Container"时点击确认，自动构建并启动开发容器

6. 测试验证

6.1 验证基础构建

运行以下命令验证Chaste是否正确编译：

bash
ctest --verbose -R TestChasteBuildInfo$

6.2 运行完整测试套件

从编译目录执行连续测试套件：

bash
cd $CHASTE_BUILD_DIR
ctest -j$(nproc) -L Continuous

7. 引用说明

如果使用本镜像开展研究，请引用以下文献：

Cooper et al., (2020). Chaste: Cancer, Heart and Soft Tissue Environment. Journal of Open Source Software, 5(47), 1848. [***]

BibTeX引用格式：

bibtex
@article{Chaste_2020,
    title = {Chaste: Cancer, Heart and Soft Tissue Environment},
    journal = {Journal of Open Source Software},
    publisher = {The Open Journal},
    year = {2020},
    month = {3},
    volume = {5},
    number = {47},
    pages = {1848},
    author = {Fergus R. Cooper and Ruth E. Baker and Miguel O. Bernabeu and Rafel Bordas and Louise Bowler and Alfonso Bueno-Orovio and Helen M. Byrne and Valentina Carapella and Louie Cardone-Noott and Jonathan Cooper and Sara Dutta and Benjamin D. Evans and Alexander G. Fletcher and James A. Grogan and Wenxian Guo and Daniel G. Harvey and Maurice Hendrix and David Kay and Jochen Kursawe and Philip K. Maini and Beth McMillan and Gary R. Mirams and James M. Osborne and Pras Pathmanathan and Joe M. Pitt-Francis and Martin Robinson and Blanca Rodriguez and Raymond J. Spiteri and David J. Gavaghan},
    doi = {10.21105/joss.01848},
    url = {https://doi.org/10.21105/joss.01848},
}

8. 注意事项

• 数据备份：Docker数据卷在Docker重置时可能丢失，建议定期将项目推送到远程Git仓库
• 内存配置：编译和模拟需要大量内存，建议Docker分配至少4GB内存
• 性能优化：对于大型模拟，优先使用数据卷而非绑定挂载以获得更好的I/O性能
• 版本选择：生产环境建议使用特定版本标签（如:2024.1）而非latest
• 容器生命周期：省略docker run命令中的--rm参数可保留容器状态，使用docker start <容器名>重新启动

更多Chaste使用教程请访问：[***]