Migration guide: legacy commands and inputs to the unified CLI

PyRETIS 4 unifies every entry point behind a single pyretis command and standardises on TOML input. The older commands and the .rst input format still work, each with a deprecation warning, and are scheduled for removal in PyRETIS 5. This page is the one-stop reference for moving an existing project forward. Nothing here needs to be done in a hurry: the deprecated paths keep running until v5, once an input of PyRETIS 3 has the changes described below.

Verification status: documentation only.

Command migration

The single pyretis executable runs every sub-command; the old standalone executables are kept as deprecated aliases that print a warning and then run the same command.

Legacy command	Replacement	Status
pyretisrun -i input.toml	pyretis run -i input.toml	deprecated
pyretisanalyse -i input.toml	pyretis analyse -i input.toml	deprecated
pyretis clean	pyretis tools clean	deprecated alias
(clean run artefacts)	pyretis tools clean	–

pyretis analyze (US spelling) is accepted as an alias of pyretis analyse. Every path-sampling run (task = "tis", "retis", "explore", "pptis" or "repptis") is started with pyretis run and runs on the infinite-swapping scheduler (see the runner section below).

Running a deprecated executable prints, verbatim:

"pyretisrun" is deprecated and will be removed in PyRETIS 5; use "pyretis run" instead.

(and the pyretisanalyse analogue). The message is emitted both as a Python DeprecationWarning and, when a run logger is active, at WARNING level so it is visible on screen and in the run log.

infinite swapping: [runner]

The infinite-swapping (parallel replica-exchange) sampler is not a separate command, and no key selects it: pyretis run runs every path-sampling task (tis, retis, explore, pptis and repptis) on it, with one worker when the input has no [runner] section. A canonical input that sets task = "infinite_swapping" (or "infswap" or "infretis") is refused: set the path-sampling task instead, e.g. task = "retis". The minimal addition that runs a RETIS input on four workers is:

[runner]
workers = 4

The keys are:

• workers – the number of parallel MD worker processes (integer, default 1). The environment variable PYRETIS_WORKERS overrides it, for scripts that prefer not to edit the TOML.

• wmdrun – an optional list of per-worker gmx mdrun commands (one string per worker, for MPI/GPU pinning), for the GROMACS engines only: the workers of a LAMMPS or CP2K engine run the command of the engine section (lmp, cp2k), and the AMS, ASE, TurtleMD, OpenMM and internal engines launch no command, so leave it out for them.

The runner section reference documents the full behaviour; the infinite-swapping example is the worked walkthrough.

Input-format migration: .rst to TOML

TOML is the canonical input format; the .rst frontend is deprecated and will be removed in PyRETIS 5. A legacy .rst path-sampling input (a retis, tis, explore, pptis or repptis task) is translated and run automatically. pyretis run -i retis.rst writes a same-stem retis.toml next to the input, logs a warning, and runs that translated file through the infinite-swapping scheduler:

The legacy input "retis.rst" was translated to "retis.toml" and the
run proceeds from the translated file (the .rst frontend is
deprecated). Use "-i retis.toml" directly next time.

An input of PyRETIS 3 usually needs a few changes first; the run stops before it samples, with a message that names what to change:

• A keyword that takes no effect on the run is refused (see Keywords that take no effect on a run). The RETIS input of PyRETIS 3, for instance, sets nullmoves and swapsimul in its RETIS section and trajectory-file in its output section: remove these lines. This check comes before the translation.

• A path-sampling run draws every random number, the kicks of its initial paths included, from numpy’s PCG64 generator seeded with [simulation] seed. It refuses an rgen other than pcg64 (an input of PyRETIS 3 often sets rgen = rgen-borg in its simulation, system, TIS and engine sections) and a seed of the TIS or engine section that differs from the seed of the simulation (a TIS seed of 0 is accepted): remove the rgen lines, and give the seed of the run to [simulation] seed. The run draws other random numbers than PyRETIS 3, so its paths differ.

• The built-in order parameters carry the prefix pyretis_: class = Position is now class = pyretis_position, and likewise for the others. This check comes after the translation: correct the .rst and remove the retis.toml it left, or correct retis.toml and run that.

An existing retis.toml twin is reused only when it matches the translation; a twin that differs aborts the run with a ValueError (run pyretis run -i retis.toml to use it, or delete it to regenerate). Molecular-dynamics .rst inputs (md, md-flux) are not auto-translated: they still run in place and only emit a deprecation warning pointing at the manual converter.

A path-sampling input that sets flexible_restart = True in its initial-path section is refused. A run of this version continues with [simulation] allow_setting_change = true; a run of PyRETIS 3 holds no output.toml and cannot be continued. To change the interfaces or the number of ensembles, or to go on from a run of PyRETIS 3, start a new simulation from its paths with [initial-path] method = "load" (see flexible_restart).

To convert a .rst ahead of time – or for the inputs that are not auto-translated – run the converter yourself:

python -m pyretis.tools.convert_settings YOUR.rst

The converter writes YOUR.toml next to the input and verifies the conversion with a settings round-trip before trusting it. The mapping it applies:

• Each .rst section header becomes a TOML table; the table name is the first word of the header, lower-cased (Simulation -> [simulation]).

• Sections that may appear more than once – collective-variable, ensemble and potential – become TOML arrays-of-tables ([[ensemble]]). The settings parse of a TOML input of a path-sampling task (tis, retis, pptis, repptis, explore) refuses an [[ensemble]] section: the scheduler gives every ensemble the settings of the general sections, so the path-sampling settings go into [tis] and [retis] ([tis] shooting_moves gives one move per ensemble) and the interfaces into [simulation] interfaces. A make-tis-files input keeps its [[ensemble]] sections: it writes the settings of each one into the TIS input of its ensemble, tis-001.toml, ….

• Hyphenated keywords are quoted (order-file stays "order-file"); the decorative heading block is dropped.

Input-schema migration: legacy-runner TOML to canonical

Some runner-style TOML inputs originally created for infRETIS use a different schema – a [runner] section and the path-sampling parameters under [simulation.tis_set], with no [simulation] task. This schema is deprecated: PyRETIS 4 converts such an input to its canonical form when it reads it, and PyRETIS 5 will not read it. pyretis run, pyretis analyse, the scheduler set-up of a programmatic run (pyretis.bin.pyretisrun.run_infinite_swapping()) and the interface optimiser convert it the same way, and each logs one deprecation notice, at WARNING level and as a DeprecationWarning:

input.toml is an input of the legacy-runner schema ([runner],
[simulation.tis_set], no [simulation] task), which is deprecated:
PyRETIS converts it to the canonical schema when it reads it, and
PyRETIS 5 will not read it. Write its canonical form once with
'python -m pyretis.tools.convert_legacy_schema input.toml' and use
that file (docs/examples/examples-migration.rst gives the mapping).

The converter writes the canonical form to a file:

python -m pyretis.tools.convert_legacy_schema input.toml

By default the file is converted in place (canonical syntax is still .toml); pass an explicit output path to write elsewhere, --force to overwrite, and --no-validate to skip the check.

The conversion is the same when PyRETIS reads the input and when the converter writes it. The input is reshaped into the canonical schema (the table below) and parsed as every canonical input is, so a key that takes no effect on the run is refused, named in the canonical input and in the legacy-runner input, e.g. [tis] nullmoves ([simulation.tis_set] nullmoves of the legacy-runner input) = true. The reshaping leaves some keys out instead, and the run does without them: the keys the table marks as left out; [output] delete_old, delete_old_all and keep_maxop_trajs, with a warning of pyretis run and pyretis analyse (a replaced path always moves to the archive; [output] archive_every bounds it); and [output] pattern, native_compat and [runner] files, without one (the run writes no pattern.txt). The converter prints none of these warnings: compare the file it writes with the input. The conversion is then checked: the settings the run takes from the input are compared with those of its canonical form, and a difference stops the conversion with a RuntimeError that names each setting that differs. The converter then leaves the output path as it was, and a run stops before it writes a file.

A run of a legacy-runner input (pyretis run -i input.toml) records the canonical form, with its defaults resolved, in output.toml of the run directory, and the scheduler records its state there with it, as for a run of a canonical input: no file the run writes holds the legacy shape. pyretis run -i output.toml resumes the run, pyretis analyse -i output.toml analyses it, and the canonical form with [initial-path] method = "restart" continues it. A legacy-runner input file that is itself named output.toml, in the directory the run is started from, is refused before the run writes anything, because the record of the run would replace it: rename it, for example to legacy-input.toml, and run it under the new name.

The legacy-runner schema has no [initial-path] section: a run of a legacy-runner input starts from the initial paths staged in the run directory under [simulation] load_dir. The canonical form takes the initiation of the canonical input, [initial-path] method = "kick", which its record names. A new run of the canonical form therefore generates its initial paths, and stops before it writes a file when the run directory holds staged paths. A canonical input reads existing paths with [initial-path] method = "load", from a load_folder in one of the layouts of the load method, which recomputes and checks each path before the run. The paths staged for a legacy-runner input (<load_dir>/0, <load_dir>/1, …) are in none of these layouts: a run that starts from them is a run of the legacy-runner input.

A state file of the scheduler configuration that an earlier PyRETIS wrote (an output.toml or restart.toml with [simulation.tis_set] and [current]) is not an input, and is read as it is: pyretis run -i refuses it, the canonical input of the run with [initial-path] method = "restart" continues it, and pyretis analyse -i output.toml analyses it.

A LAMMPS run with order_mode = "pyretis" that an earlier PyRETIS started stored order values that the frames of its paths may not give (see order_mode): a restart stops with a ValueError when they differ. Start a new run from its paths with [initial-path] method = "load".

A run that an earlier PyRETIS sampled with an integrator a path-sampling run refuses (a GROMACS integrator other than md-vv, an OpenMM integrator other than a CustomIntegrator, TurtleMD verlet, LAMMPS fix langevin with gjf vhalf; see the integrator of a path-sampling run) has cycles sampled with that integrator: [initial-path] method = "restart" and pyretis run -i output.toml refuse it, before they write a file. Start a new run from its paths with [initial-path] method = "load" and the integrator the message advises. The same holds for a run whose input has a thermostat, a barostat or a change of the velocities that a path-sampling run refuses (as GROMACS tcoupl = nose-hoover, LAMMPS fix nvt, CP2K ENSEMBLE NVT with TYPE NOSE; see the thermostats and barostats of a path-sampling run): start a new run from its paths with method = "load" and the dynamics the message advises.

The pyretis.restart file of an md task with a LAMMPS engine that an earlier PyRETIS wrote holds no state of the random generator of the task, which seeds the LAMMPS runs (see the LAMMPS page): a restart with [simulation] restart stops with a ValueError. Start a new md task from the last configuration of the run.

The reshaping of a legacy-runner input, key by key:

legacy-runner	canonical
[simulation.tis_set] (the TIS parameters)	a top-level [tis] table
[simulation.tis_set] lambda_minus_one	[simulation] zero_left
[simulation.tis_set] permeability	[simulation] permeability
[simulation] shooting_moves	[tis] shooting_moves (one move per ensemble)
[simulation] zeroswap	[retis] swapfreq of a retis run; a tis or explore run, which attempts no swap, leaves it out with a warning
[simulation] relative_shoots	[retis] relative_shoots
(topology flags: explore / single_tis)	an inferred [simulation] task (default "retis")
[output] order_file / energy_file	order-file / energy-file (hyphenated)
[simulation] ensemble_engines and the engine sections it names	the same keys and sections (the keyword reference)
temperature of a TurtleMD or ASE engine section ([engine] and each such engine section of a pool)	[system] temperature, with a warning; a TurtleMD [engine.integrator.settings] beta equal to 1 / (boltzmann * temperature) is left out. Another beta, or engine sections at different temperatures, stop the conversion with a message that names them
the [output] keys of the in-process output (backup, trajectory-file, …)	left out, with a warning

A few shapes are refused by the conversion with a ValueError rather than a silent mistranslation, because no in-repo fixture exercises their translation: the PPTIS/REPPTIS topology flags ([simulation] repptis, pptis_no_minus, pptis_no_zero_plus), whose canonical input is written by hand with task = "pptis" or "repptis", and a bare [simulation] noswap, whose message names the canonical tis task when one samples the same ensembles.

See also

• The runner section reference – every [runner] keyword.

• The infinite-swapping example – a worked parallel run.

• Examples – the full example index.