.. _tutorials-example-01-helloworld:

Example 1: Basic Serial Batch Job
=================================

This example introduces the basic structure of a Slurm batch job. It runs a
small shell script on one compute node and writes the output to a Slurm log
file.

Use this example first if you are new to ``sbatch``. Later examples show the
standard CoSTAR pattern for running research software inside containers.

1. Connect to the CoSTAR cluster
--------------------------------

Open a terminal and connect to the CoSTAR login node:

.. code-block:: bash

   ssh ab1234@costar-login01

Replace ``ab1234`` with your University username.

2. Create the submission script
-------------------------------

Download the example file, or create a file called
``example-01-helloworld.sh`` in your working directory and copy in the script
below.

* :download:`example-01-helloworld.sh <source_files/example-01-helloworld.sh>`

.. dropdown:: example-01-helloworld.sh (click to collapse / view)
   :color: primary
   :open:
   :icon: file-code

   .. literalinclude:: source_files/example-01-helloworld.sh
      :language: bash
      :linenos:

The ``#SBATCH`` lines tell Slurm what resources the job needs. The commands
after those lines are run on the allocated compute node.

.. note::

   This example uses ``--ntasks=1`` and ``--cpus-per-task=1`` because it runs
   one simple serial shell script.

   ``--ntasks`` is the number of separate tasks or processes Slurm should
   start. This is usually increased for MPI jobs, where the same program runs
   as multiple communicating processes.

   ``--cpus-per-task`` is the number of CPU cores assigned to each task. This
   is usually increased for threaded programs, for example software that uses
   OpenMP, Python multiprocessing, or other multi-threaded libraries.

   For this hello-world example, do not increase either value. Requesting more
   tasks or CPU cores would not make the job run faster; it would only reserve
   resources that the script does not use.

3. Submit the job
-----------------

Submit the script with ``sbatch``:

.. code-block:: bash

   sbatch example-01-helloworld.sh

Slurm will print a job ID:

.. code-block:: console

   Submitted batch job 123456

You can check the job status with:

.. code-block:: bash

   squeue --me

4. Check the output
-------------------

When the job finishes, Slurm writes the standard output and error streams to
files in the submission directory:

* ``slurm-<job_id>.out`` contains normal output from the job.
* ``slurm-<job_id>.err`` contains error messages, if any were produced.

For this example, the output file should contain the hostname of the compute
node and a short ``Hello from CoSTAR`` message.

For example, ``slurm-123456.out`` might contain:

.. code-block:: text

   Hello from CoSTAR
   Job ID: 123456
   Running on node: costar01

5. What to change next
----------------------

For your own work, keep the same job-script structure and adjust:

* ``--job-name`` to describe your job.
* ``--time`` to set the maximum runtime.
* ``--cpus-per-task`` for the number of CPU cores needed by one process.
* ``--mem`` for the memory required by the job.
* The final commands so they run your own program.

Do not run heavy calculations on the login node. Use ``sbatch`` or an
interactive Slurm session to run work on compute nodes.