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 |
|---|---|---|
|
|
deprecated |
|
|
deprecated |
|
|
deprecated alias |
(clean run artefacts) |
|
– |
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, default1). The environment variablePYRETIS_WORKERSoverrides it, for scripts that prefer not to edit the TOML.wmdrun– an optional list of per-workergmx mdruncommands (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
nullmovesandswapsimulin its RETIS section andtrajectory-filein its output section: remove these lines. This check comes before the translation.An
Ensemblesection 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
rgenother thanpcg64(an input of PyRETIS 3 often setsrgen = rgen-borgin its simulation, system, TIS and engine sections) and aseedof the TIS or engine section that differs from the seed of the simulation (a TISseedof 0 is accepted): remove thergenlines, 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 = Positionis nowclass = pyretis_position, and likewise for the others. This check comes after the translation: correct the.rstand remove theretis.tomlit left, or correctretis.tomland 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
.rstsection 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,ensembleandpotential– 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_movesgives one move per ensemble, except on abiretisrun, which refuses it) and the interfaces into[simulation] interfaces(andinterfaces_bof abiretisrun). Amake-tis-filesinput 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-filestays"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 |
|---|---|
|
a top-level |
|
|
|
|
|
|
|
|
|
|
(topology flags: explore / single_tis) |
an inferred |
|
|
|
the same keys and sections (the keyword reference) |
|
|
the |
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 oforder.txtorenergy.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] endcycleor, 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¶
The runner section reference – every
[runner]keyword.The infinite-swapping example – a worked parallel run.
Examples – the full example index.