% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-submit.R
\name{htc_submit}
\alias{htc_submit}
\title{Submit an HTCondor job from a remote submit node}
\usage{
htc_submit(
  submit_file = "job.sub",
  remote_path = "~/",
  config = NULL,
  dry_run = FALSE,
  verbose = FALSE
)
}
\arguments{
\item{submit_file}{A character string. Name of the submit file on the
remote node, e.g. \code{"job.sub"}. Must end in \code{".sub"}. Defaults to
\code{"job.sub"}.}

\item{remote_path}{A character string. The directory on the submit node
where the submit file was uploaded. Defaults to \code{"~/"}. Must match the
\code{remote_path} used in the preceding call to \code{\link[=htc_upload]{htc_upload()}}.}

\item{config}{A named list as returned by \code{\link[=htc_config]{htc_config()}}. Must contain
\code{username} and \code{server}. If \code{NULL}, the function errors with instructions
to call \code{\link[=htc_config]{htc_config()}} first.}

\item{dry_run}{Logical. If \code{TRUE}, prints the SSH command that would be
executed without running it. Useful for verifying the command before
submitting. Defaults to \code{FALSE}.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages and the
\code{condor_submit} output. Defaults to \code{FALSE}.}
}
\value{
The cluster ID assigned by HTCondor as a character string,
returned invisibly. Pass it directly to \code{\link[=htc_status]{htc_status()}} to monitor
job progress. Returns \code{invisible(NULL)} if the cluster ID cannot be
parsed from the \code{condor_submit} output.
}
\description{
\code{htc_submit()} connects to an HTC submit node via SSH and runs
\code{condor_submit} on a submit file that has already been uploaded with
\code{\link[=htc_upload]{htc_upload()}}. It changes into the remote directory before submitting
so that relative paths in the submit file resolve correctly.
}
\section{Workflow}{

\code{htc_submit()} is the second system-facing step in the submitr workflow.
Call it after uploading your files with \code{\link[=htc_upload]{htc_upload()}}. The returned
cluster ID can be passed directly to \code{\link[=htc_status]{htc_status()}}.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{cfg <- htc_config()

htc_upload(
  files  = c("job.sub", "job.sh", "analysis.R"),
  config = cfg
)

cluster_id <- htc_submit(submit_file = "job.sub", config = cfg)
htc_status(cluster_id = cluster_id, config = cfg, watch = TRUE)
}\if{html}{\out{</div>}}
}

\section{Why \code{remote_path} must match \code{htc_upload()}}{

\code{htc_submit()} runs \verb{cd remote_path && condor_submit submit_file} on the
submit node. HTCondor resolves all paths in the submit file relative to
the directory where \code{condor_submit} is called. If \code{remote_path} does not
match the directory where files were uploaded, HTCondor will not find the
executable, input files, or output destinations and the job will fail.
}

\section{SSH connection reuse}{

Each call to \code{htc_submit()} opens a new SSH connection. If you have not
configured ControlMaster in your \verb{~/.ssh/config}, this will trigger a
Duo MFA prompt. Run \code{\link[=htc_config]{htc_config()}} for setup guidance.
}

\examples{
\donttest{
# Preview the SSH command without connecting to CHTC
cfg <- list(username = "netid", server = "ap2002.chtc.wisc.edu")
htc_submit(submit_file = "job.sub", config = cfg, dry_run = TRUE)
}

\dontrun{
# All remaining examples require a live CHTC connection
cfg <- htc_config()

# Submit using default remote path
htc_submit(submit_file = "job.sub", config = cfg)

# Submit from a specific remote directory
htc_submit(
  submit_file = "analysis.sub",
  remote_path = "~/projects/penguins/",
  config      = cfg
)

# Submit with verbose output to see condor_submit response
htc_submit(
  submit_file = "job.sub",
  config      = cfg,
  verbose     = TRUE
)
}
}
