batchtools_lsf(): help + add template script

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: future.batchtools
-Version: 0.12.2-9921
+Version: 0.12.2-9922
 Depends:
     R (>= 3.2.0),
     parallelly,

NEWS.md

@@ -3,7 +3,7 @@
 ## Significant Changes
 
  * **future.batchtools** now implements the FutureBackend API
-   introduced in **future** 1.40.0.
+   introduced in **future** 1.40.0 (2025-04-10).
 
 ## New Features
 
@@ -13,6 +13,8 @@
 
  * Canceling batchtools futures will now interrupt them by default,
    if the backend supports it.
+   
+ * Add built-in template job script for LSF.
 
 ## Documentation
 

R/batchtools_lsf.R

@@ -0,0 +1,63 @@
+#' @export
+BatchtoolsLsfFutureBackend <- function(...) {
+  core <- BatchtoolsTemplateFutureBackend(..., type = "lsf")
+  core[["futureClasses"]] <- c("BatchtoolsLsfFuture", core[["futureClasses"]])
+  core <- structure(core, class = c("BatchtoolsLsfFutureBackend", class(core)))
+  core
+}
+
+
+#' A batchtools LSF backend resolves futures in parallel via a LSF job scheduler
+#'
+#' @inheritParams BatchtoolsFutureBackend
+#' @inheritParams BatchtoolsTemplateFutureBackend
+#'
+#' @param template (optional) Name of job-script template to be searched
+#' for by [batchtools::findTemplateFile()]. If not found, it defaults to
+#' the `templates/lsf.tmpl` part of this package (see below).
+#'
+#' @param \ldots Not used.
+#'
+#' @details
+#' Batchtools lsf futures use \pkg{batchtools} cluster functions
+#' created by [batchtools::makeClusterFunctionsLSF()], which requires
+#' that LSF commands `bsub`, `bjobs`, and `bkill` are installed on
+#' the current machine.
+#'
+#' The default template script `templates/lsf.tmpl` can be found in:
+#'
+#' ```r
+#' system.file("templates", "lsf.tmpl", package = "future.batchtools")
+#' ```
+#'
+#' and comprise:
+#'
+#' `r paste(c("\x60\x60\x60bash", readLines("inst/templates/lsf.tmpl"), "\x60\x60\x60"), collapse = "\n")`
+#'
+#' @examplesIf interactive()
+#' # Limit runtime to 3 minutes and memory to 200 MiB per future
+#' plan(batchtools_lsf, resources = list(W = "00:03:00", M = "200"))
+#'
+#' message("Main process ID: ", Sys.getpid())
+#'
+#' f <- future(Sys.getpid())
+#' pid <- value(f)
+#' message("Worker process ID: ", pid)
+#' 
+#' @export
+batchtools_lsf <- function(..., template = "lsf") {
+ stop("INTERNAL ERROR: The future.batchtools::batchtools_lsf() must never be called directly")
+}
+class(batchtools_lsf) <- c(
+  "batchtools_lsf", "batchtools_template",
+  "batchtools_multiprocess", "batchtools",
+  "multiprocess", "future", "function"
+)
+attr(batchtools_lsf, "tweakable") <- c(
+  "workers",
+  "finalize",
+  ## Arguments to batchtools::makeClusterFunctionsLSF()
+  "scheduler.latency", "fs.latency"
+)
+attr(batchtools_lsf, "init") <- TRUE
+attr(batchtools_lsf, "factory") <- BatchtoolsLsfFutureBackend

R/batchtools_template.R

@@ -32,7 +32,7 @@
 #'    [TORQUE](https://en.wikipedia.org/wiki/TORQUE) / PBS
 #'
 #' @aliases BatchtoolsLsfFutureBackend BatchtoolsOpenLavaFutureBackend BatchtoolsSGEFutureBackend BatchtoolsSlurmFutureBackend BatchtoolsTorqueFutureBackend
-#' @aliases batchtools_lsf batchtools_openlava
+#' @aliases batchtools_openlava
 #'     
 #' @importFrom batchtools makeClusterFunctionsLSF
 #' @importFrom batchtools makeClusterFunctionsOpenLava
@@ -86,33 +86,6 @@ BatchtoolsTemplateFutureBackend <- function(..., template = NULL, type = c("lsf"
 }
 
 
-#' @export
-BatchtoolsLsfFutureBackend <- function(...) {
-  core <- BatchtoolsTemplateFutureBackend(..., type = "lsf")
-  core[["futureClasses"]] <- c("BatchtoolsLsfFuture", core[["futureClasses"]])
-  core <- structure(core, class = c("BatchtoolsLsfFutureBackend", class(core)))
-  core
-}
-
-#' @export
-batchtools_lsf <- function(...) {
- stop("INTERNAL ERROR: The future.batchtools::batchtools_lsf() must never be called directly")
-}
-class(batchtools_lsf) <- c(
-  "batchtools_lsf", "batchtools_template",
-  "batchtools_multiprocess", "batchtools",
-  "multiprocess", "future", "function"
-)
-attr(batchtools_lsf, "tweakable") <- c(
-  "workers",
-  "finalize",
-  ## Arguments to batchtools::makeClusterFunctionsLSF()
-  "scheduler.latency", "fs.latency"
-)
-attr(batchtools_lsf, "init") <- TRUE
-attr(batchtools_lsf, "factory") <- BatchtoolsLsfFutureBackend
-
-
 #' @export
 BatchtoolsOpenLavaFutureBackend <- function(...) {
   core <- BatchtoolsTemplateFutureBackend(..., type = "openlava")

inst/templates/lsf.tmpl

@@ -0,0 +1,41 @@
+#!/bin/bash
+######################################################################
+# A batchtools launch script template for LSF
+#
+# Author: Henrik Bengtsson 
+######################################################################
+
+## Job name:
+#BSUB -J <%= job.name %>
+
+## Direct streams to logfile:
+#BSUB -o <%= log.file %>
+
+## Resources needed:
+<% if (length(resources) > 0) {
+  opts <- unlist(resources, use.names = TRUE)
+  opts <- sprintf("-%s=%s", names(opts), opts)
+  cat(sprintf("#BSUB %s\n", opts))
+<% } %>
+
+echo "Batchtools job name: '<%= job.name %>'"
+
+echo "Session information:"
+date
+hostname
+which Rscript
+Rscript --version
+Rscript -e ".libPaths()"
+
+## Launch R and evaluate the batchtools R job
+echo "Command: Rscript -e 'batchtools::doJobCollection("<%= uri %>")' ..."
+Rscript -e 'batchtools::doJobCollection("<%= uri %>")'
+res=$?
+echo " - exit code: ${res}"
+echo "Command: Rscript -e 'batchtools::doJobCollection("<%= uri %>")' ... done"
+
+## End-of-job summary
+bjobs -l "${LSB_JOBID}"
+
+## Relay the exit code from Rscript
+exit "${res}"