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.

Verification status: documentation only.

Command migration

The single pyretis executable dispatches sub-commands (pyretis.bin.cli); the old standalone executables are kept as deprecated aliases that print a warning and then call the same code.

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. An infinite-swapping run is launched through the same pyretis run command and selected from the input (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 – pyretis run routes an input to the scheduler when it either sets an infinite-swapping task or carries a [runner] section. The minimal addition that turns a single-worker RETIS input into a parallel run is:

[runner]
workers = 4

The keys, as translated by pyretis.inout.config_adapter.to_scheduler_config(), 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 MD-launch command overrides (one string per worker; used by external engines such as GROMACS for MPI/GPU pinning). Absent for the in-process engines.

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

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 (pyretis.tools.convert_legacy_schema.convert_legacy_document()). The input is reshaped into the canonical schema 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 conversion is then checked: the scheduler configuration of the input is compared with the one the key table builds from the 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 every default 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. The run stops with a ValueError, before it writes anything, when the input file is that output.toml: rename the input file 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.

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, reading its settings under the names of the input through the key table.

The reshaping (pyretis.inout.config_adapter.normalize_legacy_schema()):

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