% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-gen-submit.R
\name{htc_gen_submit}
\alias{htc_gen_submit}
\title{Generate an HTCondor submit file for a containerized R job}
\usage{
htc_gen_submit(
  output_file = "job.sub",
  container_image = NULL,
  executable = NULL,
  input_files = NULL,
  output_files = NULL,
  mode = "single",
  queue = 1L,
  queue_from = NULL,
  resources = "small",
  custom_resources = NULL,
  gpu = FALSE,
  gpu_options = NULL,
  verbose = FALSE,
  comments = FALSE,
  output = "."
)
}
\arguments{
\item{output_file}{A character string. Name of the submit file to write.
Must end in \code{".sub"}. Defaults to \code{"job.sub"}.}

\item{container_image}{A character string. The container image to use,
including the registry prefix, e.g.
\code{"docker://registry.doit.wisc.edu/netid/myimage"}. Defaults to \code{NULL},
which writes a placeholder comment in the submit file.}

\item{executable}{A character string. The shell script that HTCondor will
run inside the container, e.g. \code{"analysis.sh"}. Defaults to \code{NULL},
which writes a placeholder comment in the submit file.}

\item{input_files}{A character vector. Files to transfer to the job's
working directory before execution, e.g. \code{c("analysis.R", "data.csv")}.
In \code{"multiple"} mode, the per-job subset file is added automatically
from the manifest; use this argument for files shared across all jobs
(e.g. the analysis script). Defaults to \code{NULL}.}

\item{output_files}{A character vector. Files to transfer back from the
job's working directory after execution. In \code{"multiple"} mode, this
defaults to \code{"$(file)-results.tar.gz"} if not supplied. Defaults to
\code{NULL}.}

\item{mode}{A character string. Submission mode. \code{"single"} (the default)
submits one job. \code{"multiple"} submits one job per row in the manifest
supplied to \code{queue_from}, passing each subset file as a positional
argument to the executable via \verb{arguments = $(file)}.}

\item{queue}{A positive integer. Number of identical jobs to submit.
Only used when \code{mode = "single"}. Defaults to \code{1}.}

\item{queue_from}{A character string. Path to the manifest file produced
by \code{toolero::write_by_group(manifest = TRUE)}. Required when
\code{mode = "multiple"}. The \code{file_path} column is extracted and written
alongside the submit file as \code{subdatasets.csv}, which HTCondor reads
to generate one job per subset file.}

\item{resources}{A character string. Compute resource preset. One of
\code{"small"}, \code{"medium"}, \code{"large"}, or \code{"custom"} (requires
\code{custom_resources}). Default preset values reflect CHTC recommendations
and are loaded from \code{inst/extdata/htc-resources.yaml}. A local
\code{htc-resources.yaml} in the working directory takes precedence over the
package default, allowing per-project customization. Defaults to
\code{"small"}.}

\item{custom_resources}{A named list. Required when \code{resources = "custom"}.
Must contain \code{cpus} (integer), \code{memory} (character, e.g. \code{"8GB"}), and
\code{disk} (character, e.g. \code{"4GB"}). Ignored when \code{resources} is not
\code{"custom"}.}

\item{gpu}{Logical. If \code{TRUE}, adds GPU resource requests to the submit
file. Defaults to \code{FALSE}.}

\item{gpu_options}{A named list or \code{NULL}. Fine-grained GPU options applied
when \code{gpu = TRUE}. Supported keys: \code{request_gpus} (integer, default
\code{1}), \code{want_gpu_lab} (logical, default \code{TRUE}), \code{min_capability}
(numeric, e.g. \code{8.0} for A100; \code{NULL} to omit), \code{min_memory_mb}
(integer in MB, e.g. \code{40000}; \code{NULL} to omit). When \code{gpu = TRUE} and
\code{gpu_options = NULL}, CHTC defaults are used.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages as each
section of the submit file is written. Defaults to \code{FALSE}.}

\item{comments}{Logical. If \code{TRUE}, annotates each section with an
explanatory comment describing what the section does and how to use it.
Defaults to \code{FALSE}.}

\item{output}{A character string. Directory where the submit file (and,
in \code{"multiple"} mode, \code{subdatasets.csv}) will be written. Defaults to
\code{"."} (current working directory).}
}
\value{
Called for its side effects. Writes an HTCondor submit file to
\code{file.path(output, output_file)}. In \code{"multiple"} mode also writes
\code{subdatasets.csv} to \code{output}. Returns \code{invisible(NULL)}.
}
\description{
\code{htc_gen_submit()} writes a ready-to-use HTCondor submit file (\code{.sub})
for running a containerized R job on an HTC cluster such as CHTC. It
supports both single-job and multiple-job submission modes.
}
\section{Multiple-job mode and positional arguments}{

When \code{mode = "multiple"}, HTCondor passes each subset filename to the
executable as a positional argument via \verb{arguments = $(file)}. Your R
script must be written to accept and use this argument. The recommended
approach is to use \code{toolero::detect_execution_context()} in your analysis
script, which resolves the input file path correctly across interactive,
Quarto, and Rscript execution contexts:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{context <- toolero::detect_execution_context()

input_file <- switch(context,
  interactive = "data/penguins.csv",
  quarto      = params$input_file,
  rscript     = commandArgs(trailingOnly = TRUE)[1]
)

data <- readr::read_csv(input_file)
}\if{html}{\out{</div>}}

The typical workflow is:
\enumerate{
\item Write and develop your analysis in \code{analysis.qmd} using
\code{toolero::detect_execution_context()} for data loading.
\item Split your dataset with \code{toolero::write_by_group(manifest = TRUE)} to
produce subset CSV files and a \code{manifest.csv}.
\item Strip \code{analysis.qmd} to \code{analysis.R} with \code{knitr::purl()}.
\item Call \code{htc_gen_submit(mode = "multiple", queue_from = "manifest.csv")}
to produce the submit file and \code{subdatasets.csv}.
\item Copy \code{analysis.R}, the subset data files, \code{analysis.sub},
\code{analysis.sh}, and \code{subdatasets.csv} to CHTC and submit.
}
}

\section{Resource presets}{

Resource presets are loaded at runtime from \code{inst/extdata/htc-resources.yaml}.
To customize presets for a specific project, copy that file to your project
directory as \code{htc-resources.yaml} and edit the values. \code{htc_gen_submit()}
checks for a local \code{htc-resources.yaml} in the working directory first,
falling back to the package default if none is found.
}

\examples{
# Single-job submit file with default resource preset
htc_gen_submit(output = tempdir())

# Single-job submit file with medium resources and file transfer
htc_gen_submit(
  output_file     = "analysis.sub",
  container_image = "docker://registry.doit.wisc.edu/netid/myimage",
  executable      = "analysis.sh",
  input_files     = "analysis.R",
  output_files    = "results.tar.gz",
  resources       = "medium",
  output          = tempdir()
)

# Annotated submit file useful for learning HTCondor syntax
htc_gen_submit(
  output_file = "annotated.sub",
  comments    = TRUE,
  verbose     = TRUE,
  output      = tempdir()
)

# Custom resource request
htc_gen_submit(
  resources        = "custom",
  custom_resources = list(cpus = 2, memory = "8GB", disk = "4GB"),
  output           = tempdir()
)

\dontrun{
# Multiple-job submit file driven by a write_by_group() manifest
htc_gen_submit(
  output_file     = "analysis.sub",
  container_image = "docker://registry.doit.wisc.edu/netid/myimage",
  executable      = "analysis.sh",
  input_files     = "analysis.R",
  mode            = "multiple",
  queue_from      = "data/manifest.csv",
  resources       = "medium",
  output          = "."
)
}
}
