The PyRETIS application¶

PyRETIS ships a single command, pyretis, with sub-commands:

pyretis run -i input.toml         # run a simulation
pyretis analyse -i input.toml     # analyse the output
pyretis tools init -i input.toml  # place the interfaces automatically
pyretis tools clean               # remove run artifacts

Run pyretis <command> -h for the options of a command; pyretis analyse is described in The PyRETIS analysis application, pyretis tools clean in Cleaning run artifacts, and pyretis tools init in Placing the interfaces automatically (pyretis tools init).

Run pyretis with no command (or pyretis -h) to print the logo and this usage summary; pyretis -v (or --version) prints the version.

Note

The standalone pyretisrun and pyretisanalyse commands still work but are deprecated: they print a deprecation warning and will be removed in PyRETIS 5, where only pyretis run and pyretis analyse will be supported. Likewise pyretis clean is a deprecated alias of pyretis tools clean.

The pyretis run sub-command is used to execute simulations defined in input files. The general syntax for executing is:

pyretis run [-h] -i INPUT [-V] [-f LOG_FILE] [-l LOG_LEVEL] [-p]

where the different arguments are described in Table 46 and Table 47.

Example use¶

Here are some examples of the use of the application:

To run the simulation defined in a file named retis.toml, make a log file for output named retis.log and display a progress bar:
```
pyretis run -i retis.toml -f retis.log -p
```
To run the simulation defined in a file named test.toml and display debug messages:
```
pyretis run -i test.toml -l DEBUG
```
To run the simulation defined in a file named input.toml, display only critical messages, write to a log file named mylog.log and display a progress bar:
```
pyretis run -i input.toml -l CRITICAL -p -f mylog.log
```

The long version of the arguments may also be used, for instance, the previous example can also be written more verbose as

pyretis run --input input.toml --log_level CRITICAL --progress --log_file mylog.log

Soft exit¶

Running simulations can be stopped softly by pressing Ctrl+C. Instead of terminating immediately, PyRETIS creates a file named EXIT in the run directory. The simulation checks for this file between simulation steps, writes restart information, closes output files and then exits.

The same mechanism can be triggered manually by creating the EXIT file in the run directory:

touch EXIT

After a completed soft exit, pyretis run removes the EXIT file automatically so that a subsequent restart does not stop immediately. If EXIT is already present before pyretis run starts, the program will stop and ask you to remove it first.

Input arguments¶

Table 46 Description of input arguments for PyRETIS.¶
Argument	Description
-h, –help	Show the help message and exit
-i INPUT, –input INPUT	Location of the input file.
-V, –version	Show the version number and exit.
-f LOG_FILE, –log_file LOG_FILE	Specify location of log file to write.
-l LOG_LEVEL, –log_level LOG_LEVEL	Specify log level for the log file (see Table 47).
-p, –progress	Display a progress meter instead of text output.

Table 47 Possible settings for the `LOG_LEVEL`.¶
LOG_LEVEL	Description
CRITICAL	Only display critical messages.
ERROR	Display critical and error messages.
WARNING	Display critical and error messages and warnings.
INFO	Display all of the above and some info messages.
DEBUG	Display all of the above and additional debug messages.

PyRETIS also defines three custom levels used internally for console output (they are not intended as -l arguments but are listed here for completeness):

Table 48 Custom PyRETIS log levels.¶
LOG_LEVEL	Value	Description
PROGRESS	25	Progress messages shown on the console (default level).
BANNER	26	Logo and header messages displayed in cyan at startup.
REFERENCE	27	Citation and URL messages displayed at startup/shutdown.

Placing the interfaces automatically (`pyretis tools init`)¶

By default you place the TIS/RETIS interfaces yourself, as the [simulation] interfaces list in the input file. pyretis tools init instead places them automatically, with the iterative infinit driver:

pyretis tools init -i input.toml

Each iteration

runs a short infinite-swapping simulation with the current interfaces;
re-estimates the crossing probability with binless WHAM;
re-places the interfaces so every ensemble carries roughly the same local crossing probability (equal per-ensemble acceptance);
re-selects the most-decorrelated active paths as the next iteration’s initial paths,

repeating for the configured number of iterations. Each iteration runs in its own step_<i>/ sub-directory and the interface evolution is written to infinit.log; the final interface set is printed at the end.

The input file must contain an [infinit] section (controlling the number of iterations, the target per-ensemble crossing probability, and the interface resolution) and, next to it, a starting path library — one numbered sub-directory per ensemble under the [simulation] load_dir (default load).

pyretis tools init [-h] -i FILE [-w DIR]

-i, --input — the starting config (.toml) carrying the [infinit] section (required).
-w, --workdir — directory for the per-iteration step_<i> sub-directories (default: the current directory).