⚙️Installation guide

How to install cryoSTAR on your computer?

Dear users,

We are thrilled to provide you with cryoSTAR, which is based on Python. However, to run this program, you should have the following requirements:

• A high-performance Linux machine equipped with GPU

• Knowledge of basic command line operations

Below, we would like to guide you through the steps of installing Miniconda, cloning the project using git, and then installing the project using pip. If you are very familiar with Linux, python environment, etc., you can directly jump to Install cryoSTAR.

Check GPU Availability

Before you start, remember that this program requires you to have a high-performance Linux machine in possession, which is equipped with a GPU. To confirm your machine is equipped with a GPU, you can use the nvidia-smi command in your terminal. This produces a detailed snapshot of the current GPU state. Here's how you do it:

$ nvidia-smi

These details include the GPU name, total memory, memory used, and the current active processes utilizing the GPU. Here is an expected output:

Tue Nov 14 10:53:05 2023       
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 470.129.06   Driver Version: 470.129.06   CUDA Version: 11.4     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  Tesla V100-SXM2...  On   | 00000000:B1:00.0 Off |                    0 |
| N/A   38C    P0    71W / 300W |      0MiB / 32510MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
|   1  Tesla V100-SXM2...  On   | 00000000:B2:00.0 Off |                    0 |
| N/A   43C    P0    71W / 300W |      0MiB / 32510MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
                                                                               
+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

In case you encounter an error message or no useful information coming out after running nvidia-smi, it might indicate that no GPU is available on your machine. Here is an example of an error message:

command not found: nvidia-smi

Install Miniconda3

We strongly recommend using environment management software like conda to keep your system environment resilient and organized. In particular, we advocate for the conda environment manager. Below is a guide on installing Miniconda on a Linux system.

Go to Miniconda's official website to download the installer appropriate for your system. Once you've downloaded the installer, open your terminal, navigate to the location where the installer is saved, and run the following command to install Miniconda:

$ bash Miniconda3-latest-Linux-x86_64.sh

Please replace Miniconda3-latest-Linux-x86_64.sh with the name of the file you downloaded. The installer will display a license agreement, which you have to agree to. Then you confirm the install location (or choose your own). You'll need to follow the prompts in the terminal to complete your installation.

After that, it is critical to initialize conda to configure your shell to use conda without any issues. This configuration will modify your shell scripts (like .bashrc ), which might change shell behavior.

If you are using the Bash shell, you can initialize conda through the following command:

$ ~/miniconda3/bin/conda init bash

Install cryoSTAR

Configure the Conda Environment

Set up a new conda environment named cryostar using Python 3.9:

$ conda create -n cryostar python=3.9 -y

Activate the environment:

$ conda activate cryostar

Download cryoSTAR

There are two approaches to downloading the cryoSTAR software. You can download through browser via this link and unzip the file to your machine. If your machine has git installed, we recommend you download it by cloning the repository:

$ git clone https://github.com/bytedance/cryostar.git

NOTE:

• If you encounter an error message such as git: command not found, you may need to install the git software. We recommend trying this command first as it usually works for most users, particularly if your system is Ubuntu/Debian: sudo apt install git . If it does not work, detailed installation guide can be found at this link.

Install CryoSTAR

Navigate into the cryostar directory (or cryostar-master if you download it through the browser) where you can find the file setup.py :

(cryostar)$ cd cryostar

Install cryostar using pip, the python package installer:

(cryostar)$ pip install .

NOTE:

• Please note the dot at the end of the installation command. It's crucial to input pip install . instead of pip install! The dot is not a typographical error; it refers to the current directory.

• Make sure you are in the directory where you can find the file setup.py !

🎊 Congratulations! You now have cryostar installed in your machine. If your internet connection is good, the entire installation process will be completed within 10 minutes. If any issues arise during the installation, feel free to visit the post questions via github issues!