HPC
HPC Getting Started Tutorial
Running gromacs scientific computing jobs on HyperAI
This tutorial uses gromacs software as an example to introduce how to run computational tasks on a supercomputing platform from scratch and explains related commands.
Create Container
- Click "High Performance Computing" on the left sidebar and create a new container
- Select the required computing resources
- Select the desired payment method under "Billing Method"
- Select the required software under "Select Image", using "gromacs" as an example here
- Enter a valid container name under "Container Name"
- Select the data repository to bind or execute under "Data Binding"
- Configure port mapping according to your needs
- Click "Execute"
- Wait for the container to allocate resources. Once the status changes to "Running", click "Open Workspace".
Running gromacs Tasks from Command Line
This case demonstrates how to use gromacs to perform molecular dynamics simulation calculations. The complete task takes approximately 10 hours to run; only relevant command explanations are provided here.
Prepare Input Files and Scripts
For molecular dynamics calculations, you need to prepare the following 6 key files (available for download from Public Resources or directly input):
laki.pdb (protein), ions.mdp, md.mdp, minim.mdp, npt.mdp, nvt.mdp
(mdp files define parameters for molecular dynamics simulations, containing a series of options to control various aspects of the simulation, such as time step, temperature coupling, pressure coupling, and simulation type)
Upload Input Files
- Method 1: Upload to your own dataset in advance and directly input when starting the container. For details, refer to Container Data Binding
- Method 2: After the container starts, upload directly in the "Workspace" or drag files into the corresponding directory on the left, as shown below
:::info Creating text files with vim
Text files can be created using vim in the working directory. For example, to create a text file in the dataset "gromacs preparation files mdp calculation files" bound to input0:
Open a terminal and first switch to your dataset directory, here switching to the input0 directory:
cd /openbayes/input/input0
Enter vim in the terminal to enter the vim editor, as shown below:
(base) root@liangzhong-4ay9ej85pxvd-main:/openbayes/input/input0# ls
1aki.pdb(base) root@liangzhong-4ay9ej85pxvd-main:/openbayes/input/input0# vim test.txt
Common Vim commands:
- Press i to enter insert mode
- Press Esc to exit insert mode
- Type :wq to save and exit
:::
### Using Software
#### Software Invocation
Taking gromacs as an example, configure environment variables. For other software, simply replace the corresponding path "/data/app/gromacs/bin" in this command:
`export PATH=/data/app/gromacs/bin:$PATH`
#### Job Submission Command
Use nohup to ensure that gromacs' mdrun command runs in the background. It will use GPU for neighbor searching, CPU for PME calculations, and save all output to the "log.txt" file:
`nohup gmx_mpi mdrun -deffnm md_0_1 -v -nb gpu -pme cpu > log.txt &`
Script explanation:
- After entering this code, the computation task will begin. To avoid the terminal continuously displaying runtime logs during task execution, which would prevent other operations, you can add "> log.txt &" at the end of the code so that the log report is no longer displayed in the terminal but is automatically written to the "log.txt" text file.
- `gmx_mpi mdrun -deffnm md_0_1 -v -nb gpu -pme cpu` can be replaced with other commands, such as bash, sh, py execution files. The following is a detailed explanation of the above command:
- `nohup`: This command ignores all hang-up signals, meaning the specified command will continue to execute even if the user exits the terminal session.
- `gmx_mpi mdrun`: This is the MPI version command in gromacs software for executing molecular dynamics simulations. gmx_mpi is the MPI version of gromacs, used for running simulations in parallel on multi-processor systems.
- `-deffnm md_0_1`: This option specifies the default output filename for the simulation. Here, md_0_1 is the base name for output files, and gromacs will generate a series of output files based on this name, such as energy files, log files, etc.
- `-v`: This option makes the mdrun command output detailed information during execution, including progress, performance statistics, etc.
- `-nb gpu`: This option specifies that the neighbor search algorithm should be executed on the GPU. nb stands for "neighbor searching," which is a critical step in molecular dynamics simulations for determining interactions between atoms.
- `-pme cpu`: This option specifies that the PME (Particle Mesh Ewald) algorithm, used for handling long-range charge interactions, should be executed on the CPU. PME is a commonly used method for efficiently calculating charge interactions while maintaining periodic boundary conditions.
- `log.txt`: This part redirects the command's standard output to the file log.txt. This means all output printed by the mdrun command to the console will be saved in this file.
- `&`: This symbol indicates that the command will run in the background. The command will continue to execute even if the user exits the terminal session.
{/*  */}
## Viewing Compute Task (Job) Status
Command to view job status in command line:
`jobs -l`
{/*  */}
Use tail to view real-time output:
`tail -f log.txt`
{/*  */}
:::info
tail is a reader that reads the end of text and can continuously display new content based on real-time updates to "log.txt". Press Ctrl + C to exit the "log.txt" text.
:::
To cancel a job, use the command:
`kill -9 process_id`
{/*  */}
## Downloading Calculation Result Files
After the calculation task is completed, you can close the container to avoid billing.
"Open Container" - "Execution Records" - "Workspace Directory" - "Select files to download" to download result files to your local machine, as shown in the following figure:
Here you can choose "Download Current Directory" or download individual files directly.
{/*  */}
{/*  */}
If the results are saved in the previously used input dataset, you can directly open the corresponding dataset in "Data Repository":
{/*  */}
Here you can see your data. Click "Download Current Directory" to get all files in the current directory to your local computer:
{/*  */}
Or select a specific file you need, download the current file / view .png and other image files online.
{/*  */}
After the gromacs task is completed, simply download the generated images and data.
## Remote SSH Connection
This section introduces how to use remote SSH to connect locally.
After the workspace is successfully created, SSH login information will appear on the page, and a password will be created for the container. This password can be used to complete SSH authentication without any other steps.
{/*  */}
### Method 1: Connect to the server in an SSH-supported client
For detailed documentation, see [Connect to Running Jupyter Workspace via SSH](/docs/gear/ssh).
### Method 2: X-shell (requires registration and download of genuine software with your own email)
Open X-shell locally and create a new SSH connection (as shown below):
{/*  */}
Enter the following platform container information in the connection interface:
- Name: (enter a valid name here)
- Protocol: SSH
- Host: openbayes.com
- Port Number: 31977 (you need to enter the corresponding port number of the started container here)
{/*  */}
Accept the host key
{/*  */}
Enter username: root
Enter custom password
{/*  */}
Connection successful (as shown below):
{/*  */}
## FAQ
### Where is the software located?
The software app is located in the data/app directory.
{/*  */}
### What is the time zone in the container?
The container displays UTC time by default, which is time zone 0, so the estimated completion time for computing tasks provided in the server needs to add 8 hours to get Beijing time.
For example: The figure below shows that the job task will be completed at 1:55:34 on December 24, 2024, so the actual completion time is approximately 9:55:34 Beijing time on December 24, 2024.
{/*  */}
## Tutorial Example
[GROMACS Beginner Tutorial - Molecular Dynamics Simulation Using "Lysozyme in Water" as an Example](https://app.hyper.ai/console/public/tutorials/jJnbW35wL3j)