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, 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, repptis or biretis 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.

  • An Ensemble section is refused: the run gives every ensemble the settings of the general sections (see the [[ensemble]] sections below). 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, biretis) 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, except on a biretis run, which refuses it) and the interfaces into [simulation] interfaces (and interfaces_b of a biretis run). 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, …, and refuses a setting that the TIS run of the ensemble refuses, unless it repeats the general sections or the default.

  • 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 keys of the legacy-runner schema that the canonical input has no key for are refused in the same message, each but at the value that states what the run does, which the reshaping leaves out: [output] pattern (accepted false or 0: the run writes no pattern.txt), native_compat (accepted true: the run writes the output of each ensemble), delete_old, delete_old_all and keep_maxop_trajs (accepted false: a replaced path always moves to the archive, which [output] archive_every bounds) and [runner] files (accepted []: pyretis tools init alone copies the files). 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, 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, which a tis or explore run refuses: it attempts no swap

[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 an ASE engine section ([engine] and each such engine section of a pool)

[system] temperature, with a warning; 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, …)

the same keys, which a path-sampling run refuses

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.

The analysis of an md-flux run of PyRETIS 3

pyretis analyse of an md-flux run that PyRETIS 3 made gives other results than PyRETIS 3 gave for these runs:

  • a run with four or more interfaces: the last interface bounds the state \(B\) (PyRETIS 3 took the third); the times in the states and the fluxes differ (see the md-flux keyword interfaces);

  • a run that starts between \(A\) and \(B\), or, with one or two interfaces, to the right of the first interface: the analysis counts it from its first entry into \(A\) or \(B\) (into \(A\), without \(B\)); PyRETIS 3 counted it in the overall state \(A\) from its first step;

  • a run whose time in the overall state \(A\) is not a whole number of skipcross windows: the last window holds the steps that remain, and the flux is the number of effective crossings over the whole time. PyRETIS 3 counted the crossings after the last full window and left out its steps, so its flux was too high;

  • a run whose interfaces are not in increasing order, and a run with [output] cross-file above 1: no flux, with a message; the other analyses complete;

  • a run that stopped before [simulation] steps: its files hold no line that marks where it ends, and the analysis ends at its last row of order.txt or energy.txt, with a note (see the files of an earlier version). PyRETIS 3 counted the time of the run up to the end its settings give, [simulation] endcycle or, without one, steps, whatever step the run reached;

  • the files of a run that was continued from its restart file, or started again, in the folder of the run: PyRETIS 3 wrote no line that marks the parts of a run, and the analysis stops, with a message, when the files show more than one part (see when the analysis stops); run the simulation again with this version of PyRETIS, or analyse each part in a folder of its own.

A continuation of the restart file of an md-flux run of PyRETIS 3 is refused: the restart file keeps no state of the run (see restarting an md task).

The energy.txt of a run of the Langevin engine with high_friction = true that PyRETIS 3 made holds, at each step after the first, the energies of the positions of the step before (see high_friction): its energy analysis is the analysis of those energies. Run the input again with this version of PyRETIS for the energies of the positions of each step.

See also