Doc.Installation.Singularity.HPC

Instructions for Installing and Running X-SCAPE on a HPC Grid

These instructions are specifically for installing X-SCAPE using Singularity on an HPC grid where the user does not have root privileges. It is assumed that Singularity is already installed and available on the HPC and that the user has logged into an interactive Linux shell.

(If you are using the Wayne State University HPC, you cannot run computational tasks on the login warrior node, and therefore need to request an interactive node. This is a SLURM command and might not apply to other facilities with other workload managers.)

srun -c 2 -q debug --mem=4G -t 2:0:0 --pty bash

Load the Singularity Module

This step might not be necessary if Singularity is loaded by default on your specific HPC system.

module load singularity

To check that Singularity is available, check the version number with the following command:

singularity --version

Install X-SCAPE Using a Singularity Container

This command creates the Singularity container with the required software prerequisites to run X-SCAPE. The .sif file will be large (approximately 2 GB). Ensure sufficient space is available in your user directory. If space is limited, an HPC facility might designate scratch space for your use. This .sif file could be placed there.

cd ~
singularity build jet.sif docker://jetscape/base:stable

Shell into the newly built container. $HOME is mounted by default. You can type pwd to see the path to your current location.

singularity shell jet.sif
cd /<path to your HPC account home folder>
mkdir jetscape
cd jetscape
git clone https://github.com/JETSCAPE/X-SCAPE.git

CD into the cloned repository. Create a directory called build. CD into the build directory and build X-SCAPE.

cd X-SCAPE
mkdir build
cd build
cmake ..
make -j4  # Builds using 4 cores; adapt as appropriate

Run X-SCAPE

Without leaving the Singularity container, run X-SCAPE passing in the jetscape_user_PP_1910.05481.xml file from the config directory to test the installation.

./runJetscape ../config/publications_config/arXiv_1910.05481/jetscape_user_PP_1910.05481.xml

Note that when using Singularity with external modules such as SMASH, some environment variables that specify directory paths such as SMASH_DIR might need to be updated with paths relevant to your system. The default values provided in the image are intended for use with Docker on one's local machine and may differ with Singularity. See the external_packages README for details about which environment variables are needed and how to set them.