.. _submit-command-examples:

Examples for ``submit_file``
===============================

In this section we present several examples that you can use to set the ``submit_file`` parameter in your :ref:`Execution Scenario <running_scenario-generation>`. Notice that the *Running* module is agnostic to the execution environment, so you can create other submission commands for your specific system.

We recommend to use a ``bash`` script to encapsulate the submission command. This script will recieve the following parameters, and in this specific order:

- ``cmd``: Command that will be executed
- ``name``: Name of the submitted job
- ``cpu_seconds``: Job CPU limit in seconds
- ``mem``: Job Memory limit (in MB)
- ``slots``: Number of slots consumed by the job
- ``output``: Path where the job's output will be stored
- ``err``: Path where the job's error will be stored
- Remaining args for ``cmd``

To ease job management it is recommended to use a queue manager. In the following we present examples for *Task Spooler* (to run experiments in local) and for *SGE* (to run experiments in a cluster).

Task Spooler
------------

Task Spooler (``tsp``) :cite:p:`tsp2021` is a simple unix batch system. This is an example script that can be passed to ``submit_file`` to run experiments in a local machine through ``tsp``:

.. code-block:: bash

    #!/bin/bash

    cmd=$1
    name=$2
    slots=$3
    output=$4
    err=$5
    shift 5

    EXECUTING_COMMAND="${cmd} ${@} > ${output} 2> ${err}"
    tsp -L $name -n -N ${slots} sh -c "$EXECUTING_COMMAND"

.. warning::
    Task Spooler will not enforce time or memory limits, so it is required to set the ``runsolver`` parameter to ``True`` in the :ref:`Scenario generation constructor <running_scenario-generation>`.

SGE
---

Sun Grid Engine (``SGE``) :cite:p:`sge-10.5555/560889.792378` is a batch-queuing system usually used in computer clusters. You can use the following script as ``submit_file`` to run experiments in a cluster:

.. code-block:: bash

    #!/bin/bash

    cmd=$1
    name=$2
    slots=$3
    output=$4
    err=$5
    shift 5

    RQUEUE=<YOUR-QUEUE-NAME>

    EXECUTING_COMMAND="${cmd} ${@}"

    echo "${EXECUTING_COMMAND}"     \
        | qsub -cwd -V -q ${RQUEUE} \
        -pe smp ${slots}            \
        -N $name -o $output -e $err

.. note::
    ``SGE`` automatically enforces the required time and memory limits, so the usage of ``runsolver`` in the :ref:`Scenario generation constructor <running_scenario-generation>` is not required.

    Notice also that you must specify in the script the name of the queue in ``SGE`` where the jobs will be submitted.