# workshop_for_rest

**Repository Path**: restgroup/workshop_for_rest

## Basic Information

- **Project Name**: workshop_for_rest
- **Description**: REST 研讨会系列：从基础到进阶应用；历届研讨会记录
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2025-09-04
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[**EN**](README.en.md) | **中文**

# REST 安装

读者可参考 [REST 用户指南](https://rest-doc.readthedocs.io/zh_CN) 了解 REST 的安装和基本使用。以下说明简要介绍了通过 Conda 和 Docker 镜像安装的过程，这是 workshop 推荐的常用方法。Windows 用户建议先安装 [WSL](https://learn.microsoft.com/zh-cn/windows/wsl/install)（Windows Subsystem for Linux），然后按照 Linux 安装说明进行操作。

## Conda 安装

首先，创建一个新的 conda 环境（推荐）：

```sh
conda create -n rest python=3.11 -c conda-forge
```

其中，`rest` 是新环境的名称（可自定义），`python=3.11` 指定 Python 版本为 3.11（目前不支持其他 Python 版本）。`-c conda-forge` 选项指定 conda-forge 作为安装通道。

然后，激活环境并安装 REST：

```sh
conda activate rest
conda install rest -c restgroup -c mokit -c conda-forge
```

`-c` 选项指定 REST 程序及其外部库 `mokit` 所在的通道。如果希望在当前环境（`rest`）中安装额外的 Python 库或工具，请使用 `conda install [package_name] -c conda-forge` 命令。建议优先使用 conda-forge 作为安装通道，以避免依赖冲突。

安装完成后，验证 REST 是否安装成功（确保已激活相应的 Conda 环境）：

```sh
which rest
rest -h
```

## 通过 Docker 镜像使用 REST

### 通过 Docker Desktop 安装 Docker

通过 Docker Desktop Installer 安装 Docker Desktop（Windows 用户），可前往 [Docker 官网](https://www.docker.com/) 手动下载。

### 加载已构建的镜像

REST Docker 镜像以 `rest_workshop.tar.gz` 文件形式提供，也可从[课题组主页](https://restgroup.github.io/igor_group)下载。该镜像基于 Ubuntu 20.04 构建，包含 REST 可执行文件以及运行 workshop 示例所需的其他依赖项。

加载镜像的步骤如下：

1. 打开终端并切换到镜像文件所在路径。
2. 运行命令：
   ```sh
   docker load -i rest_workshop.tar.gz
   ```
3. 验证镜像是否已正确加载：
   ```sh
   docker images
   ```
   您将看到名为 `rest_workshop` 的镜像仓库，版本标签为 `dev` 或 `v1.0`。


# 使用 REST 运行 workshop 示例

Workshop 材料包含运行计算所需的 REST 输入文件，以及用于必要后数据处理和分析的脚本。材料组织为基础示例 `01-fundamentals`（涵盖 REST 的基本使用）和高级示例 `02-advanced`（涉及面向典型研究场景和主题的全面复杂的 REST 工作流）。

要运行示例，请将此仓库克隆到本地：

```sh
git clone https://gitee.com/restgroup/workshop_for_rest.git
```

之后，您可以使用每个示例目录中提供的输入文件运行 REST 计算。如果通过 Conda 安装了 REST，只需运行：

```sh
rest -i ctrl.in [> output]
```

即可执行计算，其中 `ctrl.in` 是输入文件，请确保该文件存在于您的工作目录中，并且已激活相应的 Conda 环境。

## 在 Docker 中使用 REST 运行 workshop 示例

`02-advanced` 中的大多数高级示例需要额外的后处理和分析脚本，请按照每个示例目录中 README 文件的说明获取运行计算和分析结果的详细指导。部分示例可能需要额外的软件工具来处理输出数据，这些工具未包含在 Conda 安装的 REST 中，也未包含在 workshop 仓库中。我们在 Docker 镜像中提供了这些工具，因此建议在 Docker 容器中运行高级示例以获得完整体验。以下说明将指导您在 Docker 容器中运行 REST 计算。

### Docker 容器的基本使用

在终端中运行以下命令，将 workshop 仓库绑定到 rest_workshop 容器中：

```sh
docker run --rm -it -v [/path/to/rest_workshop]:/opt/rest_workshop -w /opt rest_workshop:[tag] /bin/bash
```

这将启动一个 rest_workshop 容器，示例目录将出现在 `/opt/rest_workshop` 路径下。您可以像在 Conda 环境中一样，通过以下命令运行输入文件：

```sh
rest -i ctrl.in [> output]
```

<!-- ### 增强的可视化支持
在新的 workshop 版本中，我们添加了基于 `pymol` 和其他软件工具的可视化功能，用于编辑分子结构、轨道及其他图形化表示。

要启用这些可视化功能，您需要使用 `-v /tmp/.X11-unit` 和 `-e DISPLAY` 参数将 Docker 容器连接到宿主机的 X11 显示服务器：
- **所有用户**：
	```sh
	docker run --rm -it -v [/path/to/rest_workshop]:/opt/rest_workshop -w /opt -v /tmp/.X11-unix:/tmp/.X11-unix:rw -e DISPLAY=$DISPLAY rest_workshop:[tag] /bin/bash
	```
- **Windows 用户额外设置**：
	Windows 用户需要安装并运行 VcXsrv X11 服务器：
	1. 从 https://sourceforge.net/projects/vcxsrv/ 下载并安装 VcXsrv
	2. 从开始菜单启动 XLaunch
	3. 选择 "Multiple windows" 并将显示编号设置为 0
	4. 选择 "Start no client"
	5. 勾选 "Disable access control"（重要！）
	6. 完成设置
	VcXsrv 运行后，Windows 用户使用以下特定命令：
	```sh
	# Windows 用户需要在 PowerShell 中先设置 DISPLAY 变量
	$DISPLAY = "host.docker.internal:0"
	```
	关键变化是将 `DISPLAY` 定义为 `host.docker.internal:0` -->


<!-- 
# 查看以往的 workshop 材料

如果您想在 Gitee 仓库网页上查看以往的 workshop 数据（例如第一次会议的数据），可以通过将标签（tag）切换到 `v1.0` 来实现。如果您已经克隆了仓库，可以在终端中使用以下命令：

```sh
git checkout v1.0
```

或者您希望基于以往数据进行开发，请运行：

```sh
git checkout -b my_branch v1.0
```

这将基于 `v1.0` 标签创建一个名为 `my_branch` 的新分支，允许您在不影响原始数据的情况下进行修改。 -->