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

infretisrun (no such executable)

pyretis run -i input.toml (with a [runner] section)

see below

(clean run artefacts)

pyretis clean

–

pyretis analyze (US spelling) is accepted as an alias of pyretis analyse. There has never been an infretisrun executable in PyRETIS – an infinite-swapping run is launched through the same pyretis run 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.native_to_infswap_config(), are:

  • workers – the number of parallel MD worker processes (integer, default 1). The environment variable PYRETIS_NATIVE_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. A legacy .rst input still parses, with a deprecation warning that embeds the exact conversion command:

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

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

Input-dialect migration: infretis-flavour TOML to native

Some TOML inputs ported from infretis use a different dialect – a [runner] section and the path-sampling parameters under [simulation.tis_set], with no [simulation] task. These still run (through the same shared parse/translate pipeline the native inputs use), with a deprecation warning that now points at the automated converter:

python -m pyretis.tools.convert_infretis_dialect input.toml

By default the file is converted in place (native syntax is still .toml); pass an explicit output path to write elsewhere, --force to overwrite, and --no-validate to skip the safety check. Like the .rst converter, it verifies the conversion before writing by comparing the coordinator configuration built from the original against the one built from the converted file, and aborts on any mismatch.

The reshaping it performs (pyretis.inout.config_adapter.normalize_infretis_dialect()):

infretis-flavour

native

[simulation.tis_set] (the TIS parameters)

a top-level [tis] table

[simulation] lambda_minus_one

[simulation] zero_left

(topology flags: explore / single_tis)

an inferred [simulation] task (default "retis")

[output] order_file / energy_file

order-file / energy-file (hyphenated)

A few shapes are refused outright, with a ValueError rather than a silent mistranslation, because no in-repo fixture exercises them: PPTIS/REPPTIS inputs and an explicit, non-quantis ensemble_engines pool. Convert those by hand.

See also