.. _sec_menufile:

The menu file and ``pymule batch``
==================================

To avoid having to run dozens of jobs manually, McMule uses :term:`menu files<menu file>`.
These files list all McMule jobs that need to be executed which is done by pymule.
Currently pymule supports two :term:`executors<executor>`: ``shell`` for running on a single machine and ``slurm`` for running on a SLURM cluster.
To run a :term:`menu file`, one either runs

.. code:: bash

   pymule batch shell -np <number of cores> menu-m2enng.menu  # using shell executor

   pymule batch slurm menu-m2enng.menu # using slurm executor as part of a SLURM script


Menu file syntax
----------------

:term:`Menu files<menu file>` use a :term:`DSL` to minimise effort.
Statements are separated by line breaks similar to python or bash.
Blocks are indented, again similar to python.
Variables are indicated with dollar signs, eg. ``$x``

``conf </path/to/config.toml>``
    loads the variables of a :term:`config file` to use in the following runs.
    :term:`config file` can be (partially) overridden with a second ``conf`` call

``image <image name>``
    loads the docker :term:`image` to run in

``mode <mode>``
    sets the running mode of McMule.
    Currently only ``vegas`` is supported

``user <path/to/user.so>``
    sets the measurement function to be executed

``run <seed> <xic> <piece> [optional arguments..]``
    executes ``mcmule`` with the currently active variables for the specified :term:`which_piece`.

``let <var> = <val>``
    sets the variable ``var`` to the value ``val`` in all following commands.
    Note that ``var`` does not contain a dollar sign here

``for <var> in <a> <b> <c>...``
    executes the body of this block with ``$var = a``, ``$var = b``, ``$var = c``.

``if <$var> <op> <value>``
    executes the body of this block only if the expression evaluates to true.
    valid operators are ``==``, ``<=``, ``<``, ``>``, ``>=``, and ``!=``.

An example can be found in Listing

.. code:: bash
   :name: lst_dsl

    let a = 3
    conf ../manual/example2/m2enng.toml
    mode vegas

    run $a 0.3 m2enng0 0

    for b in 0.1 0.2 0.3 0.4
        run $a $b m2enngR 0
        if $b == 0.3
            run $a $b m2enngR 1

Configuration file
------------------
The :term:`config file` is written using :term:`TOML` and can be used to set arbitrary variables.
However, most commonly used to set statistics and the name of the ``mcmule`` executable.