# 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**: 5
- **Created**: 2025-09-04
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

# REST Installation

Readers can refer to the [REST User's Guide]( https://rest-doc.readthedocs.io/) for a comprehensive overview of REST installation and basic usage. The following instructions provide a brief summary of the installation process via Conda and Docker image as the most common methods for the workshop participants. For Windows users, it is recommended to install [WSL](https://learn.microsoft.com/zh-cn/windows/wsl/install) (Windows Subsystem for Linux) at first and then follow the Linux installation instructions.

## Conda Installation
First, create a new conda environment (recommended):
```sh
conda create -n rest python=3.11 -c conda-forge
```
Here, `rest` is the name of the new environment (you may customize it), and `python=3.11` specifies Python version 3.11 (other Python versions are not currently supported). The `-c conda-forge` option specifies conda-forge as the installation channel. 

Then, activate the environment and install REST:
```sh
conda activate rest
conda install rest -c restgroup -c mokit -c conda-forge
```
The `-c` options specify the channels where the REST program and the external library `mokit` are hosted. If you wish to install additional Python libraries or tools in the current environment (`rest`), use the `conda install [package_name] -c conda-forge` command. It is recommended to give priority to conda-forge as the installation channel to avoid dependency conflicts.

After installation, verify that REST is installed successfully (make sure the corresponding Conda environment is activated):
```sh
which rest 
rest -h
```

## REST from Docker Image
### Install Docker via Docker Desktop
Install the Docker Desktop by Docker Desktop Installer (for Users on Windows), you can download manually at [Docker Homepage](https://www.docker.com/).

### Load from built image
The REST Docker image is provided as the `rest_workshop.tar.gz` file, which can also be downloaded from the [Group Homepage](https://restgroup.github.io/igor_group). The image is built based on Ubuntu 20.04 and includes the REST binary file as well as other dependencies needed for excuting the workshop examples.

To load the image, follow these steps:
1. Open your terminal and switch to the path to image file.
2. Run the command:
   ```sh
   docker load -i rest_workshop.tar.gz
   ``` 
3. Verify the image has been loaded properly:
   ```sh
   docker images
   ```
   and you may find certain image repositry named as rest_workshop and with version tag like dev or v1.0.


# Run the workshop examples with REST 
The workshop materials contain REST input files for running the calculations, and sripts for necessary post data processing and analysis. The materials are organized as fundamental examples `01-fundamentals` for basic REST usage, and advanced examples `02-advanced` involving comprehensive and complex REST workflows for a typical research scenario and topic. 

To run the examples, clone this repository to your local machine:
```sh
git clone https://gitee.com/restgroup/workshop_for_rest.git
```
Afterwards, you can run the REST calculations with the input files provided in each example directory. If you install REST via Conda, simply run 
```sh
rest -i ctrl.in [> output]
```
to execute the calculation, where `ctrl.in` is the input file, ensure this exists in your work directory and the corresponding Conda environment is activated. 

## Run REST in Docker with workshop examples
Most advanced examples in `02-advanced` require additional post-processing and analysis scripts, please follow the instructions in the README file of each example directory for detailed guidance on running the calculations and analyzing the results. Some of the examples may require additional software tools for processing the output data, which is not included in the REST installation via Conda, nor in the workshop repository. Instead, we provide these tools in the Docker image, so it is recommended to run the advanced examples in the Docker container for the full experience. The following instructions will guide you through running the examples in the Docker container.

### Basic Usage in Docker Container
In terminal, run the command to bind workshop repository into the rest_workshop container:
```sh
docker run --rm -it -v [/path/to/rest_workshop]:/opt/rest_workshop -w /opt rest_workshop:[tag] /bin/bash 
```
this will start a rest_workshop container with example directory appearing at the /opt/rest_workshop path.
And you can run those input files by the command
```sh
rest -i ctrl.in [> output]
```
as what you do in the Conda environment.

<!-- ### Enhanced Visualization Support
In the new workshop release, we've added visualization capabilities based on `pymol` and other software tools 
for editing molecular stuctures, orbitals and othe rgraphical representations.

To enable these visualization features, you need to connect the Docker container to your host systems' 
X11 display server using the `-v /tmp/.X11-unit` and `-e DISPLAY` parameters:
- **For all users**:
	```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 
	```
- **Additional setup for Windows users**:
	Windows users need to install and run VcXsrv X11 server:
	1. Download and install VcXsrv from https://sourceforge.net/projects/vcxsrv/
	2. Launch XLaunch from Start Menu
	3. Choose "Multiple windows" and set Display number to 0
	4. Choose "Start no client"
	5. Check "Disable access control" (important!)
	6. Finish the setup
	After VcXsrv is running, use this specific command for Windows:
	```sh
	# For Windows users, specify the variable of DISPLAY in PowerShell as first
	$DISPLAY = "host.docker.internal:0"
	```
	The key change here is to define `DISPLAY` as `host.docker.internal:0` -->

<!-- # Try those examples and have fun!

## Switch to previous workshop data
If you want to check the previous workshop data (e.g., data at the first conference) on the Gitee repository webpage, you can achieve this by switching the tag (标签) to like `v1.0`. If you have already cloned the repository, you can use the following commands in your terminal:
```sh
git checkout v1.0
``` 
or you may want to develop based on that previous data, run:
```sh
git checkout -b my_branch v1.0
```
This will create a new branch named `my_branch` based on the `v1.0` tag, allowing you to make changes without affecting the original data. -->