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

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

Input-dialect migration: legacy-runner TOML to native

Some runner-style TOML inputs originally created for 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_legacy_dialect 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 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_legacy_dialect()):

legacy-runner

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 by the converter itself (normalize_legacy_dialect), with a ValueError rather than a silent mistranslation, because no in-repo fixture exercises the translation. PPTIS/REPPTIS inputs must still be run via the legacy legacy runner dialect (the converter declines them). An explicit, non-quantis ensemble_engines multi-engine pool is also declined by the converter, but it no longer needs hand conversion: pyretis run detects an explicit [simulation] ensemble_engines and dispatches it straight to the replica-exchange scheduler untranslated (via run_legacy_runner_config), so a multi-engine pool such as examples/tutorials/path_sampling/gromacs/H2/infinite_swapping_multi_engine runs as-is.

See also