Merge branch 'add_cs_docs' into 'master'

Add CS doc page

See merge request !398

content/open_ondemand/_index.md

@@ -13,6 +13,7 @@ This guide covers the following HCC OnDemand topics and functions:
 - [Job Management and Submission]({{< relref "job_management_and_submission" >}})
 - [Shell Access]({{< relref "shell_access" >}})
 - [Virtual Desktop and Interactive Apps]({{< relref "virtual_desktop_and_interactive_apps" >}})
+- [CryoSPARC Interactive App]({{< relref "cryosparc_interactive_app" >}})
 
 *Open OnDemand was developed at the Ohio Supercomputer Center and is funded by the National Science Foundation.  For more information about the Open OnDemand project, please visit their [website](https://openondemand.org/).*
 

content/open_ondemand/cryosparc_interactive_app.md

++++
+title = "CryoSPARC Interactive App"
+description = "CryoSPARC Interactive App"
+weight=60
++++
+
+[CryoSPARC](https://cryosparc.com/) is a complete software solution for processing cryo-electron microscopy (cryo-EM) data. 
+On HCC resources, CryoSPARC can be accessed as an Interactive GUI App via the [Swan Open OnDemand (OOD) portal](https://swan-ood.unl.edu).
+
+Launching CryoSPARC via the Open OnDemand portal starts an interactive Desktop that runs the CryoSPARC _"master"_ process along with a single
+worker process on the allocated compute node. This is very similar to a Single Workstation install as described in the CryoSPARC documentation on a 
+machine with modest resources.
+While one can use the interactive Desktop to perform CryoSPARC analyses, the Desktop is mostly used to submit computationally intensive (including GPU) CryoSPARC jobs to the cluster via SLURM.
+Therefore, launching the Desktop does not require significant CPU or RAM resources, nor a GPU node.
+On the other hand, the submitted CryoSPARC jobs can take a full advantage of GPU nodes.
+The particular Swan GPU nodes used for the submitted CryoSPARC jobs can be set using the _Show advanced settings..._ checkbox in the CryoSPARC OOD Form.
+
+The CryoSPARC App and submitted tasks run as SLURM jobs under your personal HCC account.
+Similar to any other SLURM job, you have a full control over the processes and the data files.
+The CryoSPARC projects and data files on Swan can only be accessed by you, unless you explicitly choose to share them.
+
+
+#### Basic usage
+- Navigate to the [Swan OOD portal](https://swan-ood.unl.edu) and login with your HCC credentials.
+- Click "Interactive Apps" followed by CrysoSPARC.
+
+{{< figure src="/images/OOD_CS_app_tab.png" width="700" class="img-border">}}
+
+- This will open a form that needs to be filled with information regarding CryoSPARC and the resources requested. Below is explanation of some of the required fields to launch the CryoSPARC App:
+    - **CryoSPARC License ID**: To start CryoSPARC you will need to have a license ID. **Each user must have their own license ID**.  They may not be shared, even within a lab group.  Attempting to 
+share a license ID will cause jobs to fail.  If you have multiple CryoSPARC sessions running at the same time, then you will need different license ID for each session. CryoSPARC license IDs are free for non-profit academic use and can be obtained from [here](https://cryosparc.com/download).
+    - **Start a new CryoSPARC session?**: The default location of the CryoSPARC database is `$WORK/cryosparc`. If you select this checkbox, all the existing database and configuration files in the CryoSPARC session location will be erased. *Please select this checkbox only if needed.*
+    - **Number of cores**: This parameter defines the cores needed for the CryoSPARC _"master"_ process. The _"master"_ process does not require many resources, so requesting <ins>1-2 cores</ins> should be sufficient. 
+    - **Running time in hours**: This parameter defines the runtime of the CryoSPARC _"master"_ process. The _"master"_ process should be running while the CryoSPARC SLURM jobs are running. If you are not sure how long the submitted jobs will be running for, please <ins>select the maximum runtime of 168 hours (7 days)</ins> to avoid any issues if the CryoSPARC _"master"_ process finishes before the submitted jobs. While the CryoSPARC _"master"_ process is running and the GPU CryoSPARC jobs are submitted to the cluster, you don't need to have the CryoSPARC OOD App open. 
+    - **Requested RAM in GBs**: This parameter defines the RAM memory needed for the CryoSPARC _"master"_ process. The _"master"_ process does not require many resources, so requesting <ins>8GBs</ins> for example should be sufficient. 
+    - **Partition selection**: This parameter defines the partition used for the CryoSPARC _"master"_ process. The _"master"_ process *does not require GPUs*, so you can you use a CPU partition, such as `batch`, or any other leased partition you have access to. 
+
+- In addition to the basic fields, there are two advanced settings you can set under the _Show advanced settings..._ checkbox in the CryoSPARC OOD Form:
+    - **CryoSPARC session path**: The default location of the CryoSPARC database and configuration files is `$WORK/cryosparc`. You can change this location using the *Select Path* button. You can select any of the [available file systems on Swan]({{< relref "../handling_data/data_storage/" >}}) aside from the `$HOME` filesystem.  _We do not recommend using `$HOME` for the session folder_.  Please note that each file system has its own advantages and disadvantages.
+    - **Specify partition for CryoSPARC GPU jobs**: This parameter defines the GPU partition used for the GPU CryoSPARC jobs submitted to the cluster via SLURM through the interactive Desktop. If not specified, by default, these jobs are submitted to the general `gpu` partition. If you have access to a priority access partition with GPU resources, you may specify that partition here to reduce queue time.
+
+{{< figure src="/images/OOD_CS_advanced_settings.png" width="30%" height="30%" class="img-border">}}
+
+After selecting the needed resources and pressing "Launch", the CryoSPARC App will start. 
+Depending on the requested resources, this process should take a few minutes.  
+When the App is ready, the CryoSPARC OOD Info Card will show information about the email and password needed to login to CryoSPARC, as well as some other useful information, such as the Login URL and a few auxiliary programs. 
+The email address value to use is `<username>@swan.unl.edu`, where `<username>` is replaced with your HCC username.  _Please note that this is not a functioning email address, and is only used for logging into CryoSPARC on Swan._
+Once the session is ready, you will see a "Launch CryoSPARC:Swan" button.
+This button will start the CryoSPARC interactive Desktop and open the Firefox browser to the CryoSPARC login page.
+Please use the provided email and password to login to the CryoSPARC Firefox session and start using CryoSPARC.
+
+{{< figure src="/images/OOD_CS_info_card.png" width="50%" height="50%" class="img-border">}}
+
+
+#### CryoSPARC SLURM jobs 
+Once you create CryoSPARC Job and are ready to `Queue` it, you can select one of the two available lanes to run the job on - `default` or `swan`. 
+
+{{< figure src="/images/OOD_CS_job_queue.png" width="30%" height="30%" class="img-border">}}
+
+- `Lane default (node)` uses the current compute node to run the job on. This job will use the resources and partition selected in the CryoSPARC OOD Form. This will usually be a modest amount of resources (1-2 cores and 8GBs of RAM), so the `default lane` should only be used for short-running, light tasks.
+- `Lane swan (cluster)` uses SLURM to submit the CryoSPARC job to the cluster. These jobs have a maximum runtime of 7 days, use the number of CPUs or GPUs you have specified when creating the CryoSPARC job and use the partition you have selected under the _Show advanced settings..._ checkbox in the CryoSPARC OOD Form. The submitted CryoSPARC jobs will run in the background, and depending on the requested resources and partition utilization, sometimes it may take a bit before they start running. The `swan` lane should be used for the majority of the computing tasks.
+
+Please note that the _"master"_ process should be running while the submitted CryoSPARC jobs are queued and running.
+
+
+#### CryoSPARC auxiliary programs
+In addition to CryoSPARC, the CryoSPARC OOD App provides a few auxiliary programs, such as wrapper scripts for **Topaz** and **deepEMhancer**. 
+The executable paths to these scripts need to be set manually on a project-level. 
+Once this is done, the set location will apply to all future newly created jobs.
+- The location of the wrapper script for Topaz is: `/usr/local/bin/topaz.sh`
+- The location of the wrapper script for deepEMhancer is: `/usr/local/bin/deepemhancer.sh`
+- The location of the deepEMhancer models is: `/usr/local/share/deepemhancer_models/`
+
+
+#### CryoSPARC database 
+The default location of the CryoSPARC database is `$WORK/cryosparc`. 
+- If you need to move this database elsewhere, please change the **CryoSPARC session path** using **Select Path** under the _Show advanced settings..._ checkbox. 
+- If you want to store the CryoSPARC session folder (database and configuration files) elsewhere, please change the **CryoSPARC session path** before you start the CryoSPARC session.
+
+#### CryoSPARC example 
+If you want to test the CryoSPARC OOD App, you can use the [CryoSPARC Introductory Tutorial](https://guide.cryosparc.com/processing-data/get-started-with-cryosparc-introductory-tutorial).
+
+
+#### Tips
+- The _"master"_ process should be running while the submitted CryoSPARC jobs as part of the workflow are queued and running. The _"master"_ process can be terminated if: 
+    - the requested runtime set via the **Running time in hours** field has been reached
+    - the Linux Desktop environment is exited by choosing `Log Out` from either via the deskop menu in the upper left, or the account name in the upper right
+    - the interactive App has been terminated via the`"Delete"` button on OOD. 
+- If you are not sure how long the jobs will be running for, please set **Running time in hours** to 168 hours (7 days) to avoid any issues.
+- In order for CryoSPARC to shut down gracefully, please end your session by choosing `Log Out` from the main desktop menu in the upper left corner within the CryoSPARC App when _all jobs are no longer running or queued_.  You may then start the App again later and resume your progress.
+- The optimal number of GPUs needed for the submitted CryoSPARC SLURM jobs that utilize GPUs is 2 to 4 GPUs, so please adjust this value as part of the **Project -> Job Builder** accordingly. 
+- You can only run one CryoSPARC instance at a time with the same license ID and database directory. If you need to run multiple CryoSPARC sessions at the same time, please request a different license and change the CryoSPARC session directory by selecting the _Show advanced settings..._ checkbox.  We do not generally recommend this approach however.  Jobs submitted to SLURM will not complete faster by using multiple instances.
+- If you are unable to start a new CryoSPARC instance there is a chance that your previous submitted CryoSPARC jobs didn't complete successfully. Please make sure all your running CryoSPARC jobs are cancelled with [scancel]({{< relref "../submitting_jobs#removing-the-job" >}}) and if necessary, delete any `*.lock` files in the used CryoSPARC session directory. 
+- If you accidentally close the Firefox browser inside the CryoSPARC OOD App, the `Login URL` is printed on the CryoSPARC OOD Info Card. 
+- Depending on the partition utilization, sometimes it may take a bit before the submitted CryoSPARC jobs start running. 
+- If you need to transfer data to/from Swan as part of your CryoSPARC workflow please see the [Data Transfer]({{< relref "../handling_data/data_transfer/" >}}) page.
+
+
+If you have any questions or encounter any issues with the CryoSPARC OOD App, please email {{< icon name="envelope" >}} hcc-support@unl.edu.