intro-section-apx.tex

\section{Appendix: Cylc Introduction}
\label{Appendix Cylc Introduction}

\note{This Appendix contains extra explanatory material for Section~\ref{Cylc
Introduction}.}

\subsection{The suite.rc File Format}

Cylc suites are defined in a simple human-readable text format, by design,
because complex workflow definitions are best managed like program source code,
with dedicated revision control power tools such as git and subversion that
work with text-based diffs.  This allows proper branch-and-merge collaborative
development of complex workflows.

\subsection{The Minimal Cylc Suite, and Dummy Tasks}

The Hello World suite is not quite the simplest working cylc suite: you can
omit the runtime configuration for a task and cylc will automatically create a
dummy job for it that just prints some information and exits:

\begin{lstlisting}[language=suiterc]
[scheduling]
    [[dependencies]]
        graph = hello
[runtime]
    [[hello]]  # (empty)
\end{lstlisting}

In fact, if all tasks in a suite are dummy tasks, you can omit the entire
runtime section:
\begin{lstlisting}[language=suiterc]
[scheduling]
    [[dependencies]]
        graph = hello
\end{lstlisting}

This can be useful for mocking up suites, and temporarily ``dummying out'' real
tasks.  Note however that tasks without even an empty runtime section heading
will fail strict validation: \lstinline=cylc validate --strict=.  This is to
catch misspelled task names in the graph, which will create accidental ``naked
dummy tasks''.

\subsection{Suite Registration}

\lstinline{cylc-register} just associates a name with a suite definition.  The
reason for this is that most cylc commands interact with a running suite
daemon, by name, rather than a suite.rc file.  Commands that do parse a
suite.rc file (e.g.  \lstinline=cylc validate=) can refer to the suite name or
the file path, whereas commands that connect to a suite daemon must use the
suite name.

\subsection{Suite Daemons}

Some workflow schedulers have a large central server program to run suites
for all users.  These have significant admin overheads (user accounts) and
security requirements (elevated system privileges are required in order to
submit jobs for many users).

\lstinline=cylc run= starts a dedicated light-weight server program just for your
workflow, running under your normal Unix user account, it submits jobs just
as you would. By default it is a Unix {\em daemon} process that detaches from
your terminal and stays alive when you log out. To stop a suite from
daemonizing use \lstinline=cylc run --no-detach=. 


\subsection{rose suite-run}

\lstinline{rose suite-run} will soon be migrated into cylc. It is not
just a convenient short-cut command. More importantly it {\em installs} the
suite into its run directory and registers it there.  This separates the
live suite from its source so you can work on a suite without interfering with
a running instance, and it provides an opportunity to install external
files into the suite at start-up.

\subsection{rose-suite.conf}

\lstinline=rose suite-run= aborts if no rose-suite.conf file is found in the
suite directory.  An empty file will suffice here, but note that you can use it
to supply input variables to the suite definition.  Together with similar
Rose configuration files for tasks, and associated metadata, the generic Rose
config editor can provide, with very little effort, a sophisticated
configuration GUI for a suite and all of its tasks.  See Rose documentation for
more on this.

\subsection{Suite Log Directories}

\begin{lstlisting}[language=bash]
$HOME/cylc-run/hello_world/log/job/1/hello/01/
\end{lstlisting}

The directory path contains the suite name (hello\_world), log type ({\em job}
or {\em suite}), task cycle point (1 for a non-cycling suite), task name
(hello), and task submit number (01). This structure prevents re-submitted jobs
from overwriting their previous logs, and it avoids unmanageable flat log
directories in large or long-running suites.

\subsection{Defining Tasks}

You can run any existing program or script in a cylc task so long as it:
\begin{itemize}
    \item returns standard exit status (zero for success, non-zero
        for error) to allow automatic error detection
    \item waits on any internal processes before exiting (e.g.\ jobs
        submitted internally to a batch scheduler)
\end{itemize}

Shell scripts unfortunately do not abort on error by default, but you can force
them to do so by putting \lstinline=set -e= at the top.  It is also a good idea
to use \lstinline=set -u= to abort if an undefined variable is referenced. 

Scripts that spawn detaching processes internally have to be modified, to make
them wait before exiting - otherwise it is impossible for cylc to determine
when the job is truly finished.

\terminology{A task \underline{job script} is a shell script generated by cylc
    to run a task as defined in the suite.rc file.}

Task job scripts wrap the configured task scripting and environment in
code to automatically trap errors and communicate progress back to the
suite daemon.

Variables from suite.rc task environment section are exported in the job
script, and several scripting items get inserted verbatim into it:

\begin{itemize}
    \item \lstinline=init-script= - runs at the top of job script
    \item \lstinline=env-script= - runs just before task environment variables are exported
    \item \lstinline=pre-script= - runs just before the main \lstinline=script= item
    \item \lstinline=script= - this is the main \lstinline=script= item
    \item \lstinline=post-script= - runs just after the main \lstinline=script= item
\end{itemize}

Multiple script items are provided to allow families of tasks to inherent common
blocks of code as well as having unique main script content.

\subsection{Remote Task Hosts}

Cylc doesn't install files to remote hosts for you because in general it is not
possible to automatically determine what files might be needed. If a task host
does not share a filesystem with the suite host, make sure you install any
files needed by the tasks that run there, or define some initital tasks to do
file installation for you.  Rose can help to automate file installation at
suite start-up.

\subsection{Supported Batch Systems}

As well as background jobs and the simple Unix \lstinline=at= scheduler, cylc
supports various batch systems such as PBS and SLURM, for job submission,
queue interrogation, and job cancellation or kill. These generally require use
of a \lstinline=[[[directives]]]= section too, to select the right queue, set
wall clock limits, and so on.