.. _user-section-runner: The Runner section (infinite swapping) ====================================== The ``[runner]`` section configures the **infinite-swapping** sampler -- the asynchronous, parallel reformulation of replica exchange described in :ref:`the moves guide `. It is only used by the infinite-swapping route; the in-process simulation flow ignores it. This page documents how the two |pyretis| execution routes are selected from the input, the keywords of the ``[runner]`` section, and the environment variables that override the routing. For a worked example see the :ref:`infinite-swapping tutorial ` and the runnable inputs under :file:`examples/infswap/`. .. note:: The infinite-swapping inputs use the **TOML** input format (``pyretisrun -i infswap.toml``), not the classic ``.rst`` input. A complete annotated input is shipped at :file:`examples/infswap/turtlemd/double_well/infswap.toml`. .. _user-section-runner-routes: The two execution routes ------------------------ Every RETIS-family run is driven through the single ``pyretisrun`` command. |pyretis| inspects the input TOML and selects one of two routes: * The **infinite-swapping scheduler** -- a central coordinator hands work to a pool of parallel workers and combines the result with the :ref:`WHAM analysis `. It is selected when the input carries a ``[runner]`` section **or** an explicit infinite-swapping task (``task = "infinite_swapping"``, ``"infswap"`` or ``"infretis"``). * The **native in-process loop** -- the classic single-process ``PathSimulation`` loop, used for everything else. As of the current release a native ``task = "retis"`` TOML with an internal (in-process) MD engine is **also run through the scheduler** at a single worker, because the infinite-swapping scheduler reproduces the native RETIS loop one-to-one for that family. Native ``task = "tis"``, ``"explore"``, ``"pptis"`` and ``"repptis"``, the external-engine retis runs, and any retis config that hits a scheduler *port gap* keep the in-process loop. These routing decisions can be overridden with the :ref:`environment variables ` below. .. _user-section-runner-keywords: Keywords of the runner section ------------------------------ .. pyretis-input-example:: Runner .. code-block:: rst [runner] workers = 4 files = ["orderp.py"] This requests four parallel workers and copies the custom order-parameter module ``orderp.py`` into each worker's run directory. .. |runner_workers| replace:: :ref:`workers ` .. |runner_files| replace:: :ref:`files ` .. |runner_wmdrun| replace:: :ref:`wmdrun ` .. _table-keywords-runner: .. table:: Keywords for the runner section. :class: table-striped table-hover +------------------+-------------------------------------------------------+ | Keyword | Description | +==================+=======================================================+ | |runner_workers| | Number of parallel workers in the scheduler pool. | +------------------+-------------------------------------------------------+ | |runner_files| | Auxiliary files copied into every worker directory. | +------------------+-------------------------------------------------------+ | |runner_wmdrun| | Per-worker external-engine MD run commands. | +------------------+-------------------------------------------------------+ .. _user-section-runner-keyword-workers: Keyword workers ^^^^^^^^^^^^^^^ .. pyretis-keyword:: workers integer The number of parallel workers the scheduler drives. Each worker propagates one trajectory at a time and is handed new work as soon as it frees up, so the wall-clock time scales close to linearly with the number of workers. ``workers`` should not exceed the number of path ensembles (a worker per ensemble is the natural maximum). Default The default is ``workers = 1`` (a single-worker run, which reproduces the native RETIS loop). .. _user-section-runner-keyword-files: Keyword files ^^^^^^^^^^^^^ .. pyretis-keyword:: files list of strings Auxiliary files that each worker needs in its run directory, resolved relative to the input file. The most common entry is a custom order-parameter module referenced from the :ref:`orderparameter section `, e.g. ``files = ["orderp.py"]``. Default The default is an empty list (no auxiliary files are copied). .. _user-section-runner-keyword-wmdrun: Keyword wmdrun ^^^^^^^^^^^^^^ .. pyretis-keyword:: wmdrun list of strings For external MD engines (GROMACS / LAMMPS / CP2K), the per-worker command used to launch the engine. The list has one entry per worker and is indexed by the worker's pin, so different workers can run on different devices or with different launch wrappers. It is not used by the internal in-process engines. Default The default is unset (the engine's own run command is used). .. _user-section-runner-env: Environment overrides --------------------- A few environment variables override the routing decision without editing the input file. They are reversible escape hatches, primarily for debugging and for native-vs-scheduler reference comparisons: .. list-table:: Environment variables controlling the route. :header-rows: 1 :widths: 35 65 :class: table-striped table-hover * - Variable - Effect * - ``PYRETIS_NATIVE_LOOP=1`` - Force native ``tis`` / ``retis`` to keep the in-process loop instead of the scheduler. * - ``PYRETIS_NATIVE_WORKERS=N`` - Number of workers for the native retis scheduler route (default ``1``). * - ``PYRETIS_NATIVE_VIA_INFSWAP=1`` - Opt a native config into the scheduler for the permeability (mirror / target swap) moves, whose references are not yet regenerated for the scheduler route. .. _user-section-runner-output: Output and analysis ------------------- The scheduler writes its swap statistics to ``infswap_data.txt`` in the :ref:`output data directory `. Setting ``native_compat = true`` in the ``[output]`` section additionally makes the coordinator emit the native per-ensemble ``pathensemble.txt`` / ``order.txt`` / ``energy.txt`` files, so the standard :ref:`pyretisanalyse ` tooling can analyse a scheduler run exactly as it would a native one. Because the trajectories are no longer collected from fixed, independent ensembles, the per-interface crossing probabilities and the final rate constant are combined with the **Weighted Histogram Analysis Method** (WHAM) rather than by simple per-ensemble averaging. See the :ref:`analysis guide ` for how to run the WHAM crossing-probability analysis.