CryoSPARC

bc_cryosparc_standalone

Overview

This repo contains components to install a CryoSPARC interactive app for use with Open OnDemand on HPC.

CryoSPARC is installed in a shared Singularity image using the --standalone install option where the master and worker nodes are on the same node.

bc_cryosparc_standalone is an Open OnDemand Batch Connect app that launches CryoSPARC as an interactive session on HPC clusters. It is designed for researchers and students who need CryoSPARC processing on a GPU node.

The singularity --fakeroot option is needed if root privileges are unavailable. The --fakeroot option is hardcoded in the INSTALL/build_cryosparc4ood.sh script.

Screenshots

Features

• Launches CryoSPARC via VNC desktop on compute nodes
• Supports CPU and GPU execution but most CryoSPARC jobs require a GPU
• Configurable memory, cores, and wall time via the launch form
• Containerized via Singularity/Apptainer; build script included
• Lmod .lua file included for interacting with the CryoSPARC session via command line
• A database is created for each user using the email field and the first 8 characters of the user's License ID as the password

Requirements

Compute Node Software

• Singularity or Apptainer
• XFCE Windows Manager
• Firefox module; or reconfigure to use SSH tunneling

Open OnDemand

• Open OnDemand minimum version 4.0.1+ for dynamic labels
• Scheduler: Slurm
• Lmod. The provided module file is needed for interactive CLI commands but not required to launch the GUI.

Optional

• The CryoSPARC GUI is launched using Firefox but can be reconfigured if SSH tunneling is allowed on your HPC

App Installation

Run the INSTALL/build_cryosparc4ood.sh script to generate the Singularity image. (build_cryosparc.sh --help)

• Singularity image installation requires a GPU and internet access.

1. Clone the repository

# Batch Connect apps:
cd /var/www/ood/apps/sys

git clone https://github.com/tamu-edu/bc_cryosparc_standalone.git
cd bc_cryosparc_standalone

# Pin to a release (recommended)
git checkout v1.0.0

2. Configure for your site

form.yml Attributes

Edit form.yml and update these values for your cluster:

Attribute	Description	Default
cluster	Target cluster ID	"my_cluster"
version	CryoSPARC version	"4.7.1"
num_hours	Maximum wall time (hours)	1
num_cores	Number of cores	1
mem_per_node	GB memory for one node	"64"

manifest.yml Attributes

Edit manifest.yml and update these values for your organization:

Attribute	Change to
description	Your cluster and your documentation

Environment variables

Variable	Required	Description
SINGULARITYENV_http_proxy	No	proxy IP if needed by compute nodes
SINGULARITYENV_https_proxy	No	proxy IP if needed by compute nodes

3. Verify

No OOD restart is needed (Batch Connect apps are detected automatically). Visit your OOD dashboard and look for CryoSPARC under Interactive Apps > Imaging.

Troubleshooting

Job starts but app doesn't appear (Batch Connect)

1. Check the job's output.log in ~/ondemand/data/sys/bc_cryosparc_standalone/
2. Verify the Firefox module loads correctly: module load Firefox
3. For VNC apps, verify the window manager is installed: which xfwm4

"Module not found" error

The module name in form.yml doesn't match your system. Run module spider software to find the correct name and update the modules attribute.

Connection timeout

The app may need more time to start. Increase the connection timeout or check that the compute node can open the required port.

Testing

Site	OOD Version	Scheduler	Status
Texas A&M University	4.0.1	Slurm 25.05.6	Tested

To verify your installation:

1. Launch the app from the OOD dashboard with default settings
2. Confirm the application loads in the browser
3. Run one of the built-in CryoSPARC benchmark jobs

Known Limitations

• Multi-node jobs are not supported
• A new database is created for each major.minor version (one 4.7 db used for v4.7.0 and v4.7.1) to reduce the chance of databases not updating properly when using a newer CryoSPARC major.minor version.

Contributing

Contributions are welcome. To contribute:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/my-improvement)
3. Submit a pull request with a description of your changes

For bugs or feature requests, open an issue.

This app is part of the OOD Appverse. Join the Appverse Affinity Group to connect with other contributors.

References

• CryoSPARC — the application launched by this OOD app
• Open OnDemand — the HPC portal framework

Software Installation

The INSTALL/build_cryosparc4ood.sh script will create a Singularity image which will be used by all users but each user will have their own copy of the database and log files which will be stored in their $SCRATCH directory. Run "build_cryosparc4ood -h" for usage.

Prerequisites

You will need to review and update any of the following as needed

1. In the template/script.sh file:
   1. Update the http_proxy variable if your compute nodes do not have internet access.
   2. Update the singularity_image= value to the path of the singulairty image.sif file
   3. Update the user_cryosparc_directory variable if your cluster does not use $SCRATCH
   4. the $TMPDIR is used on the compute node to write the .lock files which are automatically removed when the $TMPDIR is deleted after a job ends
   5. configure the ssdquota and quotamax variables
2. In the INSTALL/build_cryosparc4ood.sh script
   1. update nvidia/cuda base image version as needed from https://hub.docker.com/r/nvidia/cuda
   2. update the nvidia-driver and nvidia-dkms package versions if needed
   3. remove the --fakeroot singularity option if you do not have it enabled on your cluster

License

MIT License

Acknowledgments

This work is supported by NSF award number 2112356.