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 status                    # per-ensemble sampling summary
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 status is described in Monitoring a running simulation, and can be run while a simulation is still going. 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 50 and Table 51.

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 write debug messages to the log file (a run that stops on an error then also shows its traceback on the screen):
```
pyretis run -i test.toml -l DEBUG
```
To run the simulation defined in a file named input.toml, write only warnings and errors to a log file named mylog.log and display a progress bar:
```
pyretis run -i input.toml -l WARNING -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 WARNING --progress --log_file mylog.log

The log level sets what the log file receives; apart from that traceback at DEBUG, the messages on the screen do not change with it. At CRITICAL the log file receives no warnings or errors, not even the traceback of a run that stops on an error.

Soft exit¶

How you stop a running simulation, keeping what it has done, depends on its task.

A path-sampling run (task "tis", "retis", "pptis", "repptis" or "explore") stops when you press Ctrl+C, or when it receives SIGTERM, as a queue system sends at the end of the wall time. It prints Termination signal received; stopped the scheduler cleanly. and exits with status 130. The GROMACS, LAMMPS or CP2K run of a worker ([engine] class = "gromacs", "lammps" or "cp2k") is stopped with it: SIGTERM, and SIGKILL to what still runs 5 s later. The kick that makes the initial paths runs in the PyRETIS process itself (every kick but the parallel kick, [initial-path] kick-parallel = true with kick-from = initial), and its LAMMPS or CP2K run goes on after the stop until its steps are done: stop it by its process id before you start the run again. SIGKILL (kill -9) stops the PyRETIS process alone: its workers go on with the moves or kicks they run, and with the MD programs of their legs, and do not exit; stop them and their MD programs by their process ids. The cycles that were still running are lost; every completed cycle is kept in output.toml, and

pyretis run -i output.toml

continues the run from there (see Quickstart). A run stopped while it generates its initial paths has no output.toml yet: start it again from your input.

While it samples, a path-sampling run does not look for an EXIT file: creating one does not stop it, and the file left behind stops the next pyretis run until you remove it. An EXIT file created while the run generates its initial paths can stop it with an error; remove the file and start the run again from your input.

A molecular dynamics run (task "md-nve", "md-flux" or "md") and an umbrella sampling window (task "umbrellawindow") stop softly when you press 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. SIGTERM, as a queue system sends at the end of the wall time, ends these runs at once, without a soft exit.

Whatever the task, if EXIT is already present before pyretis run starts, the program will stop and ask you to remove it first.

Input arguments¶

Table 50 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	Name of the log file of the run (default: the [output] log_file keyword, or pyretis.log). The workers of a path-sampling run follow the keyword, not this option.
-l LOG_LEVEL, –log_level LOG_LEVEL	Specify log level for the log file (see Table 51).
-p, –progress	Display a progress bar: over the steps of an MD run, in place of its text output, or over the cycles of a path-sampling run. A restarted run’s bar starts at the step or cycle it resumes from.

Table 51 Possible settings for the `LOG_LEVEL`.¶
LOG_LEVEL	What the log file receives
CRITICAL	Only critical messages.
ERROR	Critical and error messages.
WARNING	Critical and error messages and warnings.
INFO	All of the above and some info messages (the default).
DEBUG	All of the above and additional debug messages.

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

Table 52 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.
SUCCESS	28	Completion messages (“Simulation done”) shown in blue.
REPORT	29	The report text that `pyretis analyse` writes.

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 iterations of a run are numbered from step_0/ whatever [infinit] cstep is, and a run with cstep above 0 starts from the interfaces of its input file and the paths of its starting library. When any step_<i>/ of the run already holds files, left by an earlier run of the driver in the same working directory, the driver stops before its first iteration and names each of these directories; remove them, or use a new working directory.

The input file must contain an [infinit] section and, next to it, a starting path library — one numbered sub-directory per ensemble under the [simulation] load_dir (default load). The [infinit] section takes:

steps_per_iter (required) — a list with one entry per iteration: the number of steps of that iteration’s simulation, each at least the number of [runner] workers.
pL (default 0.3) — the local crossing probability each ensemble should carry, between 0 and 1.
skip (default 0.1) — the fraction of each iteration’s cycles, from its start, that the crossing-probability estimate leaves out (at least 0, below 1).
lamres (default 0.001, at least 1e-5) — the interface resolution: the new interfaces are rounded down to a multiple of it.
cstep (default 0) — the entry of steps_per_iter to start from; the entries before it are not run.

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).