Install

Before you begin

After registering to use cryoSPARC, you should have received an email containing a single bash command that can be used for installation. The command is

1

bash -c "$(curl -sSL https://cryosparc.download?license=xxxxxxxxxx)"

where the license parameter is your unique license ID. This command will download cryosparc and its dependencies, install them, and configure cryosparc for use.

Before running the command, please make sure that you know the following information:

• Which machine will you run cryoSPARC on?

  The machine running cryoSPARC (called the cryoSPARC host) must have GPUs, a local SSD, and must be accessible over your network by other computers from which you plan to use the cryoSPARC user interface (clients). The host can also be its own client, for example if it is a desktop workstation. You should run the install command above on the host machine.

• Where do you want cryoSPARC to be installed?

  During installation, the cryoSPARC installer will ask you where to install cryoSPARC (on the host machine). This location is where cryoSPARC will store its internal database, and by default is the ~/cryosparc folder in your home directory. The location you select should ideally be on redundant, safe storage. Avoid using a location that resides on your local SSD.

• Where do you want cryoSPARC to write output data?

  As you use cryoSPARC, it will internally keep track of your datasets, experiments, parameters, plots, etc. Result files generated by cryoSPARC (3-D maps, meta data files), however, are not stored internally but will be stored at a location you must specify during installation. Ideally, you should select a location on your cluster or shared filesystem, or on local redundant spinning hard drives. Avoid using a location that resides on your local SSD.

• Where are your datasets stored?

  Many labs have centralized storage servers or cluster file systems where large cryo-EM datasets are stored. These are usually mounted on each server or workstation somewhere in the filesystem for user access. During configuration, you will need to know these locations to be able to point cryoSPARC so it can find necessary files.

• Where is your local SSD in the filesystem?

  CryoSPARC has a caching layer built in that will automatically copy data onto your local SSD and remove old cached data when space is required. During installation, you will need to know a path to a location that resides on your local SSD. The df -h command can be helpful for identifying drives and paths.

• Do you have sudo/root access?

  Root access is not necessary to install cryoSPARC, but there is a hardware/RAM tuning configuration step that requires sudo. If you do not have sudo you can ask your sysadmin to complete the tuning step.

• Do you have CUDA installed?

  The cryoSPARC installer assumes that you have CUDA and the NVIDIA drivers for your GPUs already set up. This is likely the case if you have been using any other GPU accelerated software. To double check, the command which nvcc should report a path to a NVIDIA binary, and echo $LD_LIBRARY_PATH should report a path similar to /usr/local/cuda/lib64. You can add lines to your local ~/.bashrc file to ensure this is the case. If nvcc is not in your PATH at the time of installation, cryoSPARC will attempt to locate it within the /usr/ directory.

  We have put together a system setup script for Ubuntu that installs CUDA and the NVIDIA drivers and sets up the machine for running cryoSPARC. The script requires root access and can be found here.

Install cryoSPARC

Once you have gathered the necessary information above, ssh into the host machine and run the installation command that you received in your registration email. You should see the following output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

$ bash -c "$(curl -sSL https://cryosparc.download?license=xxxxxxxxxx)"

======================================================
 cryoSPARC Download Script
======================================================

CryoSPARC by default will install to your home directory
at the following path:
  /home/installtest/cryosparc
Ideally, this path should be on reliable redundant storage
because this is where cryoSPARC will store its internal
database. Result data files (maps, micrographs, etc) will
be stored at a different location that you can select
later during configuration. You will also be asked for a
path to an SSD cache directory during configuration.

Continue installation at
  /home/installtest/cryosparc
1) Yes
2) Change
#?

Follow the on screen instructions to proceed through installation, entering the required information as requested.
The download script will fetch the latest version of cryoSPARC, extract it, and begin the installation process.
Subsequently, the cryoSPARC configuration utility will begin.

Troubleshooting:

• Incorrect NVCC found during installation
• Errors during npm install with gcc version

Configure data input directories

After installation, cryoSPARC will have been automatically configured with a single bulk directory from which input files can be read. This single default bulk directory is the root directory / and is named local_fs in the cryoSPARC interface.

You should use the cryosparc configure utility to add other bulk directories that contain user data. This can be done like so:

cryosparc configure bulk add <path> <name>

This is especially useful for adding remotely mounted drives so that they are easily accessible in the cryoSPARC interface.

Tips:

• How to move installation and output directories

Configure GPUs

By defauly, cryoSPARC will utilize all available GPUs. If you want to restrict the cryoSPARC scheduler to only use certain GPUs, use the cryosparc configure gpu list and cryosparc configure gpu enable and cryosparc configure gpu disable commands.

Tips and FAQs:

• How many GPUs does cryoSPARC use for a single job?
• [Multi-node installation]
• Select GPU for a cryoSPARC run
• Using multiple GPUs with cryoSPARC

Performance Tuning

After installing cryoSPARC, it can be important to tune your system’s GPU settings and RAM caching for optimal performance. If you have sudo or root access, you can run the cryosparc tuning command to automatically set configurations correctly. If you do not have root access, as your system administrator to add the following lines to the root user’s crontab:

1
2

* * * * *  sync && echo 3 > /proc/sys/vm/drop_caches
@reboot nvidia-smi -pm 1

Launch

Once cryoSPARC is installed, it must be started, using the following command:

1

cryosparc start

Note that this command will become available after you re-start your terminal or shell after installing.

Troubleshooting:

• CentOS SELinux configuration for cryoSPARC
• Internet access required for license checking

Access, local and remote

Once cryoSPARC is started, it can be accessed from the host machine itself at the following web address in the Google Chrome browser:

1

http://localhost:38000

From other machines that are connected via network, cryoSPARC can be accessed at:

1

http://<host-machine-name>:38000

When you first navigate to this address, you will be presented with a set of welcome screens.

Each user in your lab that will be using cryoSPARC should create a new user account after navigating to the cryoSPARC address.

Tips:

• Access the cryoSPARC UI remotely via SSH-tunneling
• Floating a license
• SSD caching and automatic job scheduling in cryoSPARC