.. _examples-migration: 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. .. list-table:: :header-rows: 1 :widths: 40 40 20 * - 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 :ref:`the runner section ` below). Running a deprecated executable prints, verbatim: .. code-block:: text "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 :class:`DeprecationWarning` and, when a run logger is active, at ``WARNING`` level so it is visible on screen and in the run log. .. _examples-migration-runner: 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: .. code-block:: toml [runner] workers = 4 The keys, as translated by :func:`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 :ref:`runner section reference ` documents the full behaviour; the :ref:`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: .. code-block:: text 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: .. code-block:: text 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 (:func:`pyretis.inout.config_adapter.normalize_infretis_dialect`): .. list-table:: :header-rows: 1 :widths: 50 50 * - 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 -------- * :ref:`The runner section reference ` -- every ``[runner]`` keyword. * :ref:`The infinite-swapping example ` -- a worked parallel run. * :ref:`examples-index` -- the full example index.