.. _li_mgo_appendix:

*********************************
Appendix: creating a Slurm script
*********************************

.. caution:: If you intend to use the Slurm script illustrated in this section of the tutorial,
   the account name and Chemshell file paths will need to be redefined. 


This section of the tutorial illustrates how to create a Slurm script to run Py-ChemShell taskfarming
calculations on HPC facilities. This section is of relevance only if you do not already have a submission script
for running Py-ChemShell calculations. 

Slurm is a resource manager and job scheduler used on most high-performance computing (HPC) platforms. 
To run a job using the Slurm scheduler, a submission script needs to be created with allocated resources 
for the calculation. Here an example submission script that can be used to run taskfarmed Py-ChemShell 
calculations is shown. 

.. literalinclude:: ../../samples/li_mgo/appendix_slurm/submission.script
   :lines: 1-19

Here, the #SBATCH options specify the resources for the calculation. Subsequently, Py-ChemShell and 
the other modules are loaded.
To run the calculation, the Py-ChemShell runtime script file located in ``bin/intel/chemsh`` or
``bin/gnu/chemsh`` of your installation is specified. Additional options can then be specified of 
which a few are highlighted below.

* ``-np`` specifies the number of processors. Here ``$SLURM_NTASKS`` is 40, therefore the calculation is
  run with 40 processors.
* ``-nwg`` specifies the number of workgroups. Here 4 workgroups are requested, so the 40 processors are
  divided into 4 groups of 10 processors.
* ``-npmm`` requests the number of processes within a workgroup for the MM calculation. In this case, it is
  not specified so 1 process is used on each processor (``-npmm 10``).
 

The following line ``example.py > example_output.log`` specifies to run the script ``example.py`` and 
stores the ChemShell output in a file called ``example_output.log``. After this, ``2>&1`` is added. 
This is simply shell notation for redirecting your normal and error outputs to the same stream.

More information on how to setup Slurm submission scripts is readily available on most HPC
websites (e.g: `1 <https://supercomputingwales.github.io/SCW-tutorial/04-running-jobs/>`_ , 
`2 <https://help.rc.ufl.edu/doc/Sample_SLURM_Scripts>`_ ).