# Installation guide

Dear users,&#x20;

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](https://docs.conda.io/projects/miniconda/en/latest/), 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](#install-cryostar "mention").

## 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:

```sh
$ nvidia-smi
```

These details include the GPU name, total memory, memory used, and the current active processes utilizing the GPU. Here is an <mark style="color:green;">**expected output**</mark>:

```
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 <mark style="color:red;">**error message**</mark>:

```
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](https://docs.conda.io/projects/miniconda/en/latest/) 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
$ 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:

<pre class="language-bash"><code class="lang-bash"><strong>$ ~/miniconda3/bin/conda init bash
</strong></code></pre>

## Install cryoSTAR

### Configure the Conda Environment

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

```bash
$ conda create -n cryostar python=3.9 -y
```

Activate the environment:

```bash
$ conda activate cryostar
```

### Download cryoSTAR

There are two approaches to downloading the cryoSTAR software. You can [download through browser via this link](https://github.com/bytedance/cryostar/archive/refs/heads/master.zip) and unzip the file to your machine. If your machine has `git` installed, we recommend you download it by cloning the repository:

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

**NOTE:**&#x20;

* 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](https://github.com/git-guides/install-git).

### 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` :

```bash
(cryostar)$ cd cryostar
```

Install `cryostar` using `pip`, the python package installer:&#x20;

```sh
(cryostar)$ pip install .
```

**NOTE:**&#x20;

* 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` !

<figure><img src="https://3161905052-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft6ysULOaJNRifZxaZhLa%2Fuploads%2FDkjcorHDYcG7Obfwfmyg%2Fimage.png?alt=media&#x26;token=8f996908-056f-42c3-a4ec-c37341c985c4" alt="" width="375"><figcaption></figcaption></figure>

🎊 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](https://github.com/bytedance/cryostar)!
