Command Line Hermes¶

Commands¶

All available commands can also be seen by using the help function hermes -h

Available commands:

exec -f file: execute the specified Hermesfile.
exec -e command: execute the specified command. __Not supported yet!__
exec -n name: give the execution file a name to make the results directory more human readable.
create: create an example Hermes files
help command: show a detailed help of the specified command.
-ho: show help for hermes options used in .hermes files (also see below)

Hermes Settings¶

Settings in this context means something that is not set for a particular execution/hermesfile, but for the git repository that is currently used. The settings are saved in the root if the repository in the .hermes_settings file. The current settings (with the default value if there is no settings file) are:

path_to_experiment (‘./’): specifies the path where store the results of the experiment in.
threads (1): specifies how many of the specified jobs should be executed parallel.

The syntax is as follows: setting:value and only one setting should be specified per line.

Hermes Options¶

For each job, different Hermes options can be specified. Currently, these options are:

-ca file: the file is copied to the experiment folder after the execution of the job.
-cb file: the file is copied to the experiment folder before the execution of the job.
-ma file: the file is moved to the experiment folder after the execution of the job.
-l/--log (True | False): if True the stdout and stderr of the job will not be printed to console, but stored in log files. Defaults to True.

Hermesfiles¶

Hermesfiles specifiy which experiments should be ran. Hermesfiles use the suffix .hermes. Each file is typicaaly divided into 4 sections.

1. PRE In the PRE part of the Hermesfile, the settings can be adjustet for the given Hermesfile only. So if you generally want to process the files by using two threads, and therefore specified so in the .hermes_settings file, you can change this for the current hermesfile only by specifying it in the PRE section. This is done linewise per setting. The syntax is the same as for the settings file.

2. STD-H Sometimes, some Hermes options should be applied to all jobs of the Hermes file. Hermes-options specified in the STD-H section will be applied to all jobs. The syntax is one Hermes-option per line with -flag file

3. STD-E Also, there sometimes are script arguments that should be applied to all jobs while just a few are about to be varied. Such arguments specified in the STD-E section will be applied to all jobs. The syntax in one argument per line, e.g. -ne 100 or -n.

This standard arguments will be added before the arguments specified in the exec lines. Note that this order may be important for your script.

4. EXEC In this section the jobs are specified with the following syntax:

[[args],[Hermes-options]]

where args are the command-line arguments for calling the script, separated by commas, e.g. python, script_name.py, -alpha 0.01. The Hermes-options are also separated by comma. In each line, one job can be specified. All settings that should be saved automatically must be set in the cmd.

Directives¶

Because writing an individual line for each script call can sometimes feel like an unnecessary inconvenience, Hermes also knows some execution directives that can be compiled into execution lines.

PROD¶

If you wish to execute the same script with all possible combinations that can be generated for some sets of arguments and respective values, the PROD (product) directive might come in handy. For instance, let’s assume you wish to run script.py which takes options -a <int> and -b <float>, with values for a in [100,500,1000] and b in [0.005, 0.01] with all possible option combinations, then

EXEC
PROD([python, script.py, -a {a}, -b {b}],[]], a=[100,500,1000], b=[0.005, 0.01])

will be equivalent to

EXEC
[[python, script.py, -a 100, -b 0.005],[]]
[[python, script.py, -a 100, -b 0.01],[]]
[[python, script.py, -a 500, -b 0.005],[]]
[[python, script.py, -a 500, -b 0.01],[]]
[[python, script.py, -a 1000, -b 0.005],[]]
[[python, script.py, -a 1000, -b 0.01],[]]

Note that this also works with script names and hermes options.

ZIP¶

ZIP works similarly to PROD, but instead of generating all possible combinations, it just aligns (zips) the given values for each targeted argument. That also means you have to give the same number of values for each targeted argument. For instance,

EXEC
ZIP([python, script.py, -a {a}, -b {b}],[]], a=[100,500,1000], b=[0.005, 0.01, 0.1])

will be equivalent to

EXEC
[[python, script.py, -a 100, -b 0.005],[]]
[[python, script.py, -a 500, -b 0.01],[]]
[[python, script.py, -a 1000, -b 0.1],[]]

Storage¶

All files will be saved in the directory experiments/script_name/experiment_name/hermes_identifier, where

script_name is the name of the script specified in the job
hermes_identifier is the unique combination of date and time

and the experiments directory will be created on the first call in the directory as specified in the settings.

If during the execution of the script new files or directories will be created, they are automatically moved to the storage if they include the unique_name. How this name is given to the script will be specified in the next section.

Additionally, in the future there will be an overview file giving detailed information about all the made experiments.

Script Compatibility¶

For your script to be compatible with Hermes, there are basically two things you need to consider:

All the parameters that should be saved must be specified by command line. If you want to save additional parameters, make sure to specify it by archiving the files by using the Hermes-options.
This is the only strong requirement: As its first argument, the executed script must accept the unique identifier, that is determined by Hermes. You must not do anything with that identifier except for saving additional files as specified in the Storage section.