Skip to content
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
R
docs
inst
man-roxygen
man
paper
tests
vignettes
.Rbuildignore
.gitignore
.travis.yml
CODE_OF_CONDUCT.md
DESCRIPTION
LICENSE
LICENSE.md
NAMESPACE
NEWS.md
README.Rmd
README.md
_pkgdown.yml
codecov.yml
comparing-hpc-tools.ods
sluRm.Rproj

README.md

Travis build status codecov lifecycle DOI

sluRm: A Lightweight Wrapper for Slurm

Slurm Workload Manager is a popular HPC cluster job scheduler found in many of the top 500 super computers. The sluRm R package provides an R wrapper to it that matches the parallel package’s syntax, this is, just like parallel provides the parLapply, clusterMap, parSapply, etc., sluRm provides Slurm_lapply, Slurm_Map, Slurm_sapply, etc.

While there are other alternatives such as future.batchtools, batchtools, clustermq, and rslurm, this R package has the following goals:

  1. It is dependency free, which means that it works out-of-the-box

  2. Puts an emphasis on been similar to the workflow in the R package parallel

  3. It provides a general framework for the user to create its own wrappers without using template files.

  4. Is specialized on Slurm, meaning more flexibility (no need to modify template files), and, in the future, better debuging tools (e.g. job resubmission).

Checkout the VS section section for comparing sluRm with other R packages.

Installation

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("USCbiostats/sluRm")

Citation


To cite sluRm in publications use:

  Vega Yon et al., (2019). sluRm: A lightweight wrapper for HPC with
  Slurm. Journal of Open Source Software, 4(39), 1493,
  https://doi.org/10.21105/joss.01493

A BibTeX entry for LaTeX users is

  @Article{,
    title = {sluRm: A lightweight wrapper for HPC with Slurm},
    author = {George {Vega Yon} and Paul Marjoram},
    journal = {The Journal of Open Source Software},
    year = {2019},
    month = {jul},
    volume = {4},
    number = {39},
    doi = {10.21105/joss.01493},
    url = {https://doi.org/10.21105/joss.01493},
  }

Example 1: Computing means (and looking under the hood)

library(sluRm)
#  On load, `sluRm` sets default options for your jobs (`tmp_path`, which is the default directory where sluRm will use to create the auxiliar files, and `job-name`, which is the option of the same name in Slurm. You can view/set these at:
#     ?opts_sluRm
#  or you could just type
#     "opts_sluRm".

# Suppose that we have 100 vectors of length 50 ~ Unif(0,1)
set.seed(881)
x <- replicate(100, runif(50), simplify = FALSE)

We can use the function Slurm_lapply to distribute computations

ans <- Slurm_lapply(x, mean, plan = "none")
#  Warning: [submit = FALSE] The job hasn't been submitted yet. Use sbatch() to submit the job, or you can submit it via command line using the following:
#  sbatch --job-name=sluRm-job-364b5c7ebb51 /home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/01-bash.sh
Slurm_clean(ans) # Cleaning after you

Notice the plan = "none" option, this tells Slurm_lapply to only create the job object, but do nothing with it, i.e., skip submission. To get more info, we can actually set the verbose mode on

opts_sluRm$verbose_on()
ans <- Slurm_lapply(x, mean, plan = "none")
#  
#  --------------------------------------------------------------------------------
#  [VERBOSE MODE ON] The R script that will be used is located at:
#  /home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/00-rscript.r
#  and has the following contents:
#  --------------------------------------------------------------------------------
#  .libPaths(c("/usr/local/lib/R/site-library", "/usr/lib/R/site-library", "/usr/lib/R/library"))
#  Slurm_env <- function (x) 
#  {
#      y <- Sys.getenv(x)
#      if ((x == "SLURM_ARRAY_TASK_ID") && y == "") {
#          return(1)
#      }
#      y
#  }
#  ARRAY_ID         <- as.integer(Slurm_env("SLURM_ARRAY_TASK_ID"))
#  INDICES          <- readRDS("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/INDICES.rds")
#  X                <- readRDS(sprintf("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/X_%04d.rds", ARRAY_ID))
#  FUN              <- readRDS("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/FUN.rds")
#  mc.cores         <- readRDS("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/mc.cores.rds")
#  seeds            <- readRDS("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/seeds.rds")
#  set.seed(seeds[ARRAY_ID], kind = NULL, normal.kind = NULL)
#  ans <- parallel::mclapply(
#      X                = X,
#      FUN              = FUN,
#      mc.cores         = mc.cores
#  )
#  saveRDS(ans, sprintf("/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/03-answer-%03i.rds", ARRAY_ID), compress = TRUE)
#  
#  --------------------------------------------------------------------------------
#  The bash file that will be used is located at:
#  /home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/01-bash.sh
#  and has the following contents:
#  --------------------------------------------------------------------------------
#  #!/bin/sh
#  #SBATCH --job-name=sluRm-job-364b5c7ebb51
#  #SBATCH --output=/home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/02-output-%A-%a.out
#  #SBATCH --array=1-2
#  #SBATCH --ntasks=1
#  #SBATCH --cpus-per-task=1
#  export OMP_NUM_THREADS=1
#  /usr/lib/R/bin/Rscript --vanilla /home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/00-rscript.r
#  
#  --------------------------------------------------------------------------------
#  EOF
#  --------------------------------------------------------------------------------
#  Warning: [submit = FALSE] The job hasn't been submitted yet. Use sbatch() to submit the job, or you can submit it via command line using the following:
#  sbatch --job-name=sluRm-job-364b5c7ebb51 /home/vegayon/Documents/sluRm/sluRm-job-364b5c7ebb51/01-bash.sh
Slurm_clean(ans) # Cleaning after you

Example 2: Job resubmission

The following example from the package’s manual.

# Submitting a simple job
job <- Slurm_EvalQ(sluRm::WhoAmI(), njobs = 20, plan = "submit")

# Checking the status of the job (we can simply print)
job
state(job) # or use the state function
sacct(job) # or get more info with the sactt wrapper.

# Suppose some of the jobs are taking too long to complete (say 1, 2, and 15 through 20)
# we can stop it and resubmit the job as follows:
scancel(job)

# Resubmitting only 
sbatch(job, array = "1,2,15-20") # A new jobid will be assigned

# Once its done, we can collect all the results at once
res <- Slurm_collect(job)

# And clean up if we don't need to use it again
Slurm_clean(res)

Take a look at the vignette here.

VS

There are several ways to enhance R for HPC. Depending on what are your goals/restrictions/preferences, you can use any of the following:

Package

Rerun (1)

apply family (2)

Slurm options

Focus on [blank]

System [blank]

Dependencies (3)

Status

drake

yes

no

by template

workflows

agnostic

5/9

active

sluRm

yes

yes

on the fly

calls

specific

0/0

active

rslurm

no

no

on the fly

calls

specific

1/1

inactive (since 2017)

future.batchtools

no

yes

by template

calls

agnostic

2/24

active

batchtools

yes

yes

by template

calls

agnostic

12/20

active

clustermq

no

no

by template

calls

agnostic

6/16

active

[1] After errors, the part or the entire job can be resubmitted.

[2] Functionality similar to the apply family in base R.

[3] Number of directed/recursive dependencies. As reported in https://tinyverse.netlify.com/status/ (June 4th, 2019)

Contributing

We welcome contributions to sluRm. Whether it is reporting a bug, starting a discussion by asking a question, or proposing/requesting a new feature, please go by creating a new issue here so that we can talk about it.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Funding

Supported by National Cancer Institute Grant #1P01CA196596.

You can’t perform that action at this time.