Skip to contents

Create an NLME Parallel Host Configuration

hostParams.Rd

This helper function simplifies the creation and configuration of an NlmeParallelHost object, which defines the environment for running NLME jobs.

Usage

hostParams(
  sharedDirectory,
  installationDirectory = NULL,
  hostName = Sys.info()[["nodename"]],
  machineName = "127.0.0.1",
  hostType = Sys.info()[["sysname"]],
  numCores = 4,
  parallelMethod = "LOCAL_MPI",
  mpiCoresPerJob = NA_integer_,
  userName = "",
  privateKeyFile = NULL,
  userPassword = "",
  scriptPath = "",
  rLocation = "",
  isLocal = TRUE,
  gridQueue = "",
  gridWalltime = NA_integer_,
  gridMemory = "",
  gridJobNamePrefix = "",
  gridResourceExtra = ""
)

Arguments

sharedDirectory

character. The directory where temporary run folders are created. Defaults to the current working directory for local runs and to "~" for remote runs.

installationDirectory

character. The directory containing NLME libraries/scripts. Defaults to the INSTALLDIR environment variable for local runs and to file.path(sharedDirectory, "InstallDirNLME") for remote runs.

hostName

character. A display name for the host. Defaults to the system's network name (from Sys.info()[["nodename"]]) for local runs and to machineName for remote runs.

machineName

character. The IP address or network name of the host. Defaults to "127.0.0.1".

hostType

character. The host operating system. Defaults to the current OS (Sys.info()[["sysname"]]) for local runs and to "linux" for remote runs. While "windows" or "linux" are valid for local runs, for remote Linux hosts the following are officially supported: "RHEL" (for RHEL 8 and 9) and "UBUNTU" (for Ubuntu 22.04 and 24.04). Specifying one of these values correctly sets the PML_BIN_DIR variable.

numCores

numeric. The number of CPU cores to utilize. Defaults to 4.

parallelMethod

character. The parallel execution method. Options include: "None", "Multicore", "Multicore_MPI", "LOCAL_MPI", "SGE", "SGE_MPI", "TORQUE", "TORQUE_MPI", "LSF", "LSF_MPI", "SLURM", "SLURM_MPI". Defaults to "LOCAL_MPI".

mpiCoresPerJob

integer, optional. Per-scenario MPI rank for the "Multicore_MPI" parallel method. Leave at the default NA_integer_ to let NLME8 size the rank from the current batch (engine-aware auto policy). Set a positive integer to fix the per-job MPI width; it must divide numCores evenly. Ignored (with a warning) for other methods.

userName

character. The username for remote host authentication.

privateKeyFile

character. The path to an SSH private key file for remote authentication. See ssh::ssh_connect() for more details.

userPassword

character or function. The password or a callback function for remote authentication. See ssh::ssh_connect() for details.

scriptPath

character. The path to a script to run on a remote host before the main job starts. Ignored for local runs.

rLocation

character. The path to the Rscript executable on a remote host. Ignored for local runs.

isLocal

logical. Set to TRUE for a local host or FALSE for a remote host. Defaults to TRUE.

gridQueue

character, optional. Scheduler queue or partition to route grid jobs to (e.g. "bg.q" on SGE, "batch" on SLURM). This is the scheduler's queue/partition name for CPU jobs; it does not imply GPU or graphical execution. Empty (default) uses the cluster default queue. Used only by grid parallel methods ("SGE", "TORQUE", "LSF", "SLURM", and their _MPI variants); ignored (with a warning) otherwise.

gridWalltime

integer, optional. Wall-clock limit in seconds for grid jobs. Defaults to NA_integer_, which imposes no limit so long-running bootstrap/covariate-search work is not capped. Grid methods only.

gridMemory

character, optional. Memory request for grid jobs (e.g. "16G", mapped to SGE h_vmem / TORQUE vmem / SLURM --mem). Empty (default) requests no explicit memory. Grid methods only.

gridJobNamePrefix

character, optional. Prefix for the scheduler job name shown in qstat/squeue. Empty (default) derives a name from the workflow and job type. Restricted to letters, digits, and underscores. Grid methods only.

gridResourceExtra

character, optional. Additional site-specific resource request, emitted verbatim using each scheduler's native syntax: appended to a resource list for the PBS-style schedulers (SGE #$ -l <value>, TORQUE #PBS -l <value>, e.g. "h_data=4G"), or rendered as a standalone directive for SLURM (#SBATCH <value>, e.g. "--gres=gpu:1") and LSF (#BSUB <value>, e.g. "-R rusage[mem=4096]"). Empty (default) adds nothing. Grid methods only.

Value

An NlmeParallelHost object configured with the specified parameters.

Details

Remote Windows hosts are not supported. Background execution (runInBackground = TRUE on fitmodel() and the other job wrappers) is available only on Linux hosts (local or remote); on Windows hosts use runInBackground = FALSE.

Examples

host <- hostParams(sharedDirectory = tempdir(),
                   parallelMethod = "LOCAL_MPI",
                   hostName = "Local",
                   numCores = 4)

# Local hybrid: run several models concurrently, each with its own MPI ranks.
# numCores = 10 with mpiCoresPerJob = 2 fits up to 5 models at a time,
# 2 MPI ranks each.
hybridHost <- hostParams(sharedDirectory = tempdir(),
                         parallelMethod = "Multicore_MPI",
                         hostName = "LocalHybrid",
                         numCores = 10,
                         mpiCoresPerJob = 2)

# Omit mpiCoresPerJob to let NLME8 size the per-job rank from the batch.
autoHybridHost <- hostParams(sharedDirectory = tempdir(),
                             parallelMethod = "Multicore_MPI",
                             hostName = "LocalHybridAuto",
                             numCores = 10)

# Grid host routing long batch work to a non-interactive queue, with an
# informative job name shown in qstat/squeue.
gridHost <- hostParams(sharedDirectory = "~",
                       parallelMethod = "SGE_MPI",
                       hostName = "sge",
                       numCores = 32,
                       gridQueue = "bg.q",
                       gridMemory = "16G",
                       gridJobNamePrefix = "BOOT_prod",
                       isLocal = FALSE)