.. interface: Interface ========= Automacs execution is controlled almost entirely by text files which hold :ref:`experiments `. There are a few commands that run the experiments which are executed by a very peculiar, overloaded ``Makefile`` which routes user commands to the appropriate python codes using the :any:`makeface ` functions. We use this scheme because `make `_ is ubiquitous on many computer systems, it often includes automatic completion, and it's easy to remember. The interface is extremely generic: *almost any python function can be exposed to the interface*. To see which ``make`` sub-commands are available, simply run ``make`` without arguments. .. code-block :: bash make targets │ ├──back ├──clean ├──cluster ├──config ├──docs ├──download ├──flag_search ├──gitcheck ├──gitpull ├──go ├──gromacs_config ├──layout ├──locate ├──look ├──metarun ├──notebook ├──prep ├──prep? ├──qsub ├──quick ├──run ├──set ├──setup ├──upload └──watch Commands -------- As we discused in the :ref:`procedures section `, users can run experiments using :any:`make go `. To see which experiments are available, use :any:`make prep ` which lists them. These are the two most important commands. The :any:`make go ` command will run :any:`make clean sure ` if you send it the ``reset`` flag, (this will clear any old data from the directory, so be careful) and then immediately run one of the execution commands, depending on the type of experiment, using :any:`make run `, :any:`make metarun `, or :any:`make quick `. Additions --------- In the :any:`configuration ` section we mentioned that the ``commands`` key in ``config.py`` tells automacs where to find new functions. Any paths set in the ``commands`` list are scanned by the :any:`makeface ` module for python functions. These function names become sub-commands for ``make``. Arguments are passed from the ``makefile`` to the python code according to a few simple rules. The functions cannot use ``*args`` or ``**kwargs`` because the interface code performs introspection to send arguments to the function. You can use ``key="value"`` pairs to specify both arguments and keyword arguments. Sending a single flag (e.g. ``sure`` in :any:`make clean sure `) will send ``sure=True`` as a boolean to the function. Order only matters if you are passing arguments (for obvious reasons). The safest bet is to use keyword arguments to avoid mistakes, however functions are straightforward because they only take one argument e.g. :any:`make go `. Most of the automacs utility functions are found in the :any:`command-line interface ` module and the :any:`control ` module. Tricks ------ The :ref:`experiment files ` provide execution instructions to automacs depending on their format. These formats are specified in the :any:`controlspec code `, which determines the control flow for the execution. The remainder of the interface functions are really just helper functions that make some tasks easier. The following lists covers a few useful functions. 1. :any:`make back ` will help you run simulations in the background. 2. :any:`make watch ` will monitor the newest log file in your simulation. 3. :any:`make locate ` will help you find a specific function. 4. :any:`make upload ` will upload files to a cluster. 5. :any:`make download ` will download your files from the same cluster. 6. :any:`make notebook ` will generate a `Jupyter `_ notebook from an experiment.