Generating Submission Scripts
=============================


``orto`` can generate submission scripts for your job scheduler of choice

Currently, only SLURM is supported, though support for additional schedulers may be added in future releases.

Setup
*****

To use the job submission script generation feature, you need to first set the ``orto_orca_load`` environment variable
- this specifies the command used to load the ORCA module on your system.

Typically a module system like Lmod or Environment Modules is used to manage software on HPC systems, and you will need to set this variable accordingly
- for example, when using Environment Modules, this may be set as

.. code-block:: bash

    export orto_orca_load="orca/6.0.1"

We advise that you set this to the version of ORCA you use most frequently.

Alternatively, you can provide the ``--orca_load`` optional argument in ``orto gen job`` to specify the command to load ORCA
for each job submission script - this overrides the environment variable and so can be used to submit jobs with different versions of ORCA.


Usage
*****

To submit a job run

.. code-block:: console

    orto gen job <input_file>

where ``<input_file>`` is the path to your ORCA input file.

.. Caution ::

    You must always have the number of cores and amount of memory specified in the input file.

.. Note::

    ``orto`` is fairly agnostic to the contents of the input file, but edge-cases might not work as expected.
    If you encounter any problems, please head to the :ref:`bugs` page to find how to report them to us.


Cores and Memory
****************

The number of cores and amount of memory must be specified in
the input file and, by default, ``orto`` will read these numbers and use them when submitting a job.

To override this, use the ``--n_procs`` and ``--memory`` optional arguments in ``orto gen job`` -
This may be useful if your submission system imposes per-core memory limits.

NBO
***

If you wish to use NBO within an orca calculation, the ``orto_nbo_load``
environment variable must contain the command to used to load an NBO module -
this is typically done using a module system like Lmod or Environment
Modules - for example, when using Environment Modules, this may be set as

.. code-block:: bash

    export orto_nbo_load="nbo/6.0"

Optional Arguments
******************

Additional command line arguments for ``orto gen job`` can be listed by running 

.. code-block:: console

    orto gen job -h

Example
*******

The following minimal example is a simple ORCA input file for a geometry optimisation of benzene using
the BP86 functional and the def2-svp basis set, with 16 cores and 2000 MB of memory per-core.

.. tabs::

   .. tab:: `benzene.inp`

        .. code-block::

            !BP86 def2-svp OPT
            %PAL NPROCS 16 END
            %maxcore 2000
            *xyzfile 0 1 benzene.xyz

   .. tab:: `benzene.xyz`

        .. code-block::

            12
            Benzene
            H      1.2194     -0.1652      2.1600
            C      0.6825     -0.0924      1.2087
            C     -0.7075     -0.0352      1.1973
            H     -1.2644     -0.0630      2.1393
            C     -1.3898      0.0572     -0.0114
            H     -2.4836      0.1021     -0.0204
            C     -0.6824      0.0925     -1.2088
            H     -1.2194      0.1652     -2.1599
            C      0.7075      0.0352     -1.1973
            H      1.2641      0.0628     -2.1395
            C      1.3899     -0.0572      0.0114
            H      2.4836     -0.1022      0.0205


In this example the structure is located in a separate ``.xyz`` file, but it
could equally be specified directly within the input file itself.

To submit a job for this calculation, simply run

.. code-block:: console

    orto gen job benzene.inp

You should then see an message informing you that a submission script was created
and subsequently submitted.

.. code-block:: console
    Jobscript written to benzene.slm
    Submitted batch job 123456

and run ``squeue`` or similar to check the status of the job.

The job will be given the same name as the input file, and the output file(s)
for this calculation should appear in the current directory when the job starts running - for example

.. code-block:: console

    user@computer ~/benzene $ ls
    benzene.6718675.e  benzene.123456.o  benzene.inp  benzene.out  benzene.slm  benzene.xyz ...