.. _user-section-initial-path: The initial-path section ======================== The ``initial-path`` section specifies how the initial path for a TIS/RETIS simulation should be generated. .. pyretis-input-example:: initial-path .. code-block:: rst Initial-path settings --------------------- method = kick kick-from = previous The different methods may require different keywords and this is described below for the following supported methods: .. |kick| replace:: :ref:`kick ` .. |load| replace:: :ref:`load ` .. |restart| replace:: :ref:`restart ` .. _table-initial-methods: .. table:: Supported initiation methods in |pyretis| :class: table-striped table-hover +---------------+---------------------------------------------------------+ | Method name | Description | +===============+=========================================================+ | |kick| | For initiating new trajectories from given initial | | | configuration(s). | +---------------+---------------------------------------------------------+ | |load| | For loading previously generated frames/trajectories | +---------------+---------------------------------------------------------+ | |restart| | For restarting |pyretis| simulations. | +---------------+---------------------------------------------------------+ **Choosing a method.** Use |restart| whenever a ``pyretis.restart`` file is available — it is the most faithful continuation and requires no extra setup. Use |load| when you have a molecular dynamics trajectory or a previous run whose restart files are unavailable or whose settings need to change beyond what a restart allows; PyRETIS handles the distribution of frames across ensembles automatically. Use |kick| when no prior trajectory exists and paths must be generated from scratch. | .. _user-section-initial-path-kick: The kick method --------------- The kick method generates initial paths for all path ensembles from scratch, requiring only a single starting configuration from the user. It is recommended when no prior trajectory is available. For each ensemble, the method searches for a crossing of the ensemble's middle interface :math:`\lambda_i` starting from a given phase point :math:`x`: 1. Velocities are randomised (e.g. drawn from a Maxwell–Boltzmann distribution). 2. The equations of motion are integrated one step forward. This gives a new phase point :math:`y`. 3. If :math:`y` is closer to :math:`\lambda_i` than :math:`x`, the update :math:`x \leftarrow y` is accepted and the steps are repeated. Otherwise, the steps are repeated from :math:`x` unchanged. When a crossing is found, two phase points are available: one immediately before the interface and one immediately after. A full path is then generated by integrating forward from the point after the interface and backward from the point before it. **Efficient ensemble population with** ``kick-from = previous``. With ``kick-from = initial`` every ensemble is kicked from the same user-provided configuration, which may require many iterations for ensembles whose interface lies far from the starting point. With ``kick-from = previous`` (recommended for RETIS) only the *first* ensemble is kicked from the provided configuration. For each subsequent ensemble PyRETIS automatically selects the frame from the just-generated path that lies closest to the next interface and is still to the left of it, then kicks from that frame. This propagates the starting point progressively through interface space so that the kicking algorithm is always seeded close to the target interface, greatly reducing the number of iterations needed per ensemble and requiring no additional input from the user. Keywords for the kick method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the ``kick`` method, the following keywords can be set: .. |kick_method| replace:: :ref:`method ` .. |kick_from| replace:: :ref:`kick-from ` .. _table-kick-method: .. table:: Keywords for the kick method. :class: table-striped table-hover +---------------+----------------------------------------------------------+ | Keyword | Description | +===============+==========================================================+ | |kick_method| | Selects the kick method. | +---------------+----------------------------------------------------------+ | |kick_from| | Modify how the initial point for the kick method is | | | picked. | +---------------+----------------------------------------------------------+ .. _user-section-initial-kick-method: Keyword method .............. .. pyretis-keyword:: method kick :specific: yes The ``method`` keyword selects the kick initialization. .. _user-section-initial-kick-kick-from: Keyword kick-from ................. .. pyretis-keyword:: kick-from string The ``kick-from`` keyword specifies what initial point we use for the kick method. This setting is used when several path ensembles are initiated at the same time. It can be set to: * ``kick-from = initial``: In which we will kick from the initial configuration provided. That is, all path ensembles are initiated from the same starting point. * ``kick-from = previous``: In which we kick from the point on the previous path which is closest to the next interface and still left of this interface. The first path ensemble will be initiated using the provided initial configuration for the particles. Default: The default value is ``kick-from = initial``. | .. _user-section-initial-path-load: The load method --------------- The ``load`` method initialises path ensembles from existing trajectory data, avoiding the need to generate paths from scratch via kicking. It is the recommended starting point whenever a prior molecular dynamics trajectory or a previous (P)RETIS run is available. How ensembles are populated ^^^^^^^^^^^^^^^^^^^^^^^^^^^ PyRETIS maps each path ensemble to a numbered subfolder inside ``load_folder`` (``000``, ``001``, ``002``, …, matching the ensemble numbering used during the simulation). For each ensemble in turn the following steps are applied: 1. **Collect frames.** Trajectory or configuration files are read from the load folder (see :ref:`user-section-initial-load-layouts` below for the two supported layouts). 2. **Recompute the order parameter.** The order parameter is *always* recomputed from atomic positions using the order parameter function defined in the simulation input. If an ``order.txt`` file is present it is used as-is; if it is absent it is generated and written to disk. This design means users can change the order parameter definition without regenerating their trajectory files. 3. **Validate and clean the path.** Only frames relevant to the ensemble are kept; the rest are discarded (see :ref:`user-section-initial-load-cleaning` below). 4. **Fall back to kick if needed.** If no valid path can be assembled from the loaded data and ``load_and_kick = True``, PyRETIS automatically kicks from the frame nearest to the ensemble's middle interface. .. _user-section-initial-load-cleaning: Path validation and cleaning ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After collecting frames PyRETIS checks whether the assembled sequence constitutes a formally valid path for the target ensemble. If it does not, the following recovery steps are attempted in order: 1. Frames are **sorted by order parameter** and the validation is repeated. 2. If sorting alone is insufficient, the sequence is **mirrored** to produce an L-to-L or R-to-R path — a valid bookkeeping form that satisfies the ensemble definition. 3. Frames outside the ensemble's relevant region are **discarded**, keeping: * the two frames immediately before and after the first interface, and * all frames between the interface defining the ensemble and the last interface. If this second group is empty, the frame with the highest order parameter is retained so that the ``load_and_kick`` fallback has a useful seed. If all three steps fail and ``load_and_kick = False``, PyRETIS raises an error. .. _user-section-initial-load-layouts: Load folder layouts ^^^^^^^^^^^^^^^^^^^ Two layouts are supported. **Layout 1 — unformatted (single shared trajectory).** Place one or more trajectory or configuration files directly in ``load_folder`` (accepted formats: ``.xyz``, ``.gro``, ``.trr``, ``.g96``, plain-text ``.txt``). PyRETIS will: * distribute the files to each ensemble subfolder, * generate ``traj.txt`` (frame index list) automatically, * recompute and write ``order.txt`` using the order parameter function. Only the frames relevant to each ensemble survive path cleaning. Use this layout when you have a single long trajectory and want PyRETIS to handle the per-ensemble distribution automatically with minimal user effort. **Layout 2 — formatted (per-ensemble subfolders).** Create subfolders ``000``, ``001``, ``002``, … inside ``load_folder`` and place the relevant files for each ensemble there. If ``traj.txt`` or ``order.txt`` are absent they are regenerated automatically. For *internal engines* (positions and velocities stored in PyRETIS format): +---------------+-----------------------------------------------------------+ | File | Notes | +===============+===========================================================+ | ``traj.txt`` | Required. Full path (positions and velocities). | +---------------+-----------------------------------------------------------+ | ``order.txt`` | Optional. Recomputed from atomic positions if absent. | +---------------+-----------------------------------------------------------+ | ``energy.txt``| Optional. Energies are silently ignored if absent. | +---------------+-----------------------------------------------------------+ For *external engines* (GROMACS, CP2K, …): +-------------------+--------------------------------------------------------+ | File / folder | Notes | +===================+========================================================+ | ``traj.txt`` | Required. Frame index file referencing MD files. | +-------------------+--------------------------------------------------------+ | ``accepted/`` | Required. Actual MD trajectory files (``.trr``, | | | ``.gro``, ``.xtc``, ``.g96``, ``.xyz``, …) referenced | | | in ``traj.txt``. | +-------------------+--------------------------------------------------------+ | ``order.txt`` | Optional. Recomputed from atomic positions if absent. | +-------------------+--------------------------------------------------------+ | ``energy.txt`` | Optional. Energies are silently ignored if absent. | +-------------------+--------------------------------------------------------+ Use Layout 2 when different ensembles should start from different trajectories, or when you want to resume from formatted output of a previous (P)RETIS run with changed settings (and no restart file is available). .. note:: **Order parameters are always recomputed from atomic positions** using the order parameter function defined in the simulation input. Placing an ``order.txt`` file in the load folder is a performance shortcut, not a requirement. If it is absent or outdated, PyRETIS regenerates it automatically. This allows users to change the order parameter definition without regenerating trajectory files. Keywords for the load method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the load method, the following keywords can be set: .. |load_method| replace:: :ref:`method ` .. |load_and_kick| replace:: :ref:`load_and_kick ` .. |load_folder| replace:: :ref:`load_folder ` .. _table-keyword-load: .. table:: Keywords for the load method. :class: table-striped table-hover +-----------------+--------------------------------------------------------+ | Keyword | Description | +=================+========================================================+ | |load_method| | Selects the load method. | +-----------------+--------------------------------------------------------+ | |load_and_kick| | Fall back to kick initialisation when loaded data | | | cannot form a valid path. | +-----------------+--------------------------------------------------------+ | |load_folder| | Directory containing the trajectory data to load. | +-----------------+--------------------------------------------------------+ .. _user-section-initial-load-method: Keyword method .............. .. pyretis-keyword:: method load :specific: yes The ``method`` keyword selects the load initialization. .. _user-section-initial-load-and-kick: Keyword load_and_kick ..................... .. pyretis-keyword:: load_and_kick boolean When ``load_and_kick = True``, the loaded trajectory data is used as a pool of candidate frames rather than as a ready-made path. If the loaded frames cannot be assembled into a valid path for the target ensemble — even after sorting and mirroring — PyRETIS: 1. Selects the frame from the loaded data that is closest to the ensemble's middle interface. 2. Uses this frame as the starting configuration for a standard kick initialisation (two-way shooting). 3. The resulting kicked path **fully replaces** the loaded frames; no loaded frames are retained in the final path. This option is particularly useful when the available trajectory does not cross the relevant interface, or when you want a freshly generated, unbiased initial path seeded from a physically relevant region of phase space. If ``load_and_kick = False`` (the default) and no valid path can be assembled from the loaded data, PyRETIS raises an error. Default: The default value is ``load_and_kick = False``. .. _user-section-initial-load-load-folder: Keyword load_folder ................... .. pyretis-keyword:: load_folder string The ``load_folder`` keyword specifies the directory containing trajectory data for load initialisation. See :ref:`user-section-initial-load-layouts` for the two supported layouts (unformatted single trajectory or formatted per-ensemble subfolders). Default: The default value is ``load_folder = load``. | .. _user-section-initial-path-restart: The restart method ------------------ The ``restart`` method is used to *continue* an existing simulation. It is **not** a vehicle for changing the simulation itself — for that, use :ref:`load `. By default, a restart is a strict continuation: all settings are taken from the restart file, so the simulation proceeds exactly as if it had never been interrupted. Three categories of new-input keywords matter on restart: * **Implicit overrides** — a curated set of *runtime* parameters (step count, random seed, output settings, move frequencies, etc.) can be changed in the new input file without any extra flag. PyRETIS detects the change, emits a ``WARNING`` for each modified value, and applies it. See :ref:`user-section-initial-restart-overrides` for the full list. * **Forbidden keywords** — *topology-defining* parameters (interface list, task, zero-ensemble layout, …) cannot be changed by a restart at all. If the new input disagrees with the value stored in the restart file, PyRETIS aborts with a ``ValueError``. See :ref:`user-section-initial-restart-forbidden`. To make such a change, use :ref:`load ` or — when keeping the same saved paths but updating their topology context — set ``flexible_restart = True``. * **Flexible restart** — set ``flexible_restart = True`` to take the entire new input file as the settings, bypassing both the forbidden-keyword check and the override warnings. This is needed for structural changes such as adding or removing interfaces or ensembles. The user is then responsible for ensuring that the modified setup remains consistent with detailed balance. See :ref:`user-section-initial-flexible-restart`. Keywords for the restart method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the restart method, the following keywords can be set: .. |restart_method| replace:: :ref:`method ` .. |flexible_restart| replace:: :ref:`flexible-restart ` .. _table-keyword-restart: .. table:: Keywords for the restart method. :class: table-striped table-hover +--------------------+--------------------------------------------------------------+ | Keyword | Description | +====================+==============================================================+ | |restart_method| | Selects the restart method. | +--------------------+--------------------------------------------------------------+ | |flexible_restart| | Use the new input file for structural changes on restart. | +--------------------+--------------------------------------------------------------+ .. _user-section-initial-restart-method: Keyword method .............. .. pyretis-keyword:: method restart :specific: yes The ``method`` keyword selects the restart initialization. The general simulation information is stored in the file ``pyretis.restart``. The restart file can be specified in the ``simulation`` section with the keyword ``restart`` in the simulation input file. Thereafter, path and ensemble data from restart files for each ensemble are loaded. These restart files are named ``ensemble.restart`` and there is one of such file for each path ensemble, e.g. ``001/ensemble.restart``. Note that when doing a restart, the ``ensemble.restart`` files will be overwritten with new data from the continued simulation. Note: if an ensemble has a lower number of cycles, it is possible to temporaneously prioritize it until it gets the same number of cycles by adding the keyword ``priority_shooting = True`` in the ``retis`` section. .. _user-section-initial-restart-overrides: Implicit parameter overrides ............................ Even without ``flexible_restart``, a curated set of parameters can be changed in the new input file. Whenever a value differs from the one stored in the restart file, PyRETIS logs a ``WARNING`` and applies the new value; all other settings from the restart file are preserved unchanged. The parameters that can be overridden in this way are (also exposed in code as ``pyretis.inout.settings.RESTART_OVERRIDE_KEYWORDS``): * **simulation**: ``steps``, ``seed``, ``priority_shooting`` * **output**: ``screen``, ``backup``, ``trajectory-file``, ``energy-file``, ``order-file``, ``cross-file``, ``restart-file``, ``pathensemble-file`` * **tis**: ``freq``, ``sigma_v``, ``allowmaxlength``, ``maxlength``, ``shooting_move``, ``shooting_moves``, ``high_accept``, ``n_jumps``, ``mirror_freq``, ``target_freq``, ``target_indices``, ``nullmoves`` * **retis**: ``swapfreq``, ``swapsimul``, ``nullmoves`` These cover parameter tuning (step count, random seed, move frequencies, output paths) that does not alter the statistical validity of the accumulated data. For anything beyond this list — including changing interface positions or the number of interfaces — see :ref:`user-section-initial-restart-forbidden` and :ref:`user-section-initial-flexible-restart`. .. _user-section-initial-restart-forbidden: Forbidden keywords (topology lock) ................................... The following keywords describe the *topology* of the simulation — what is being sampled and how — and changing them would silently reinterpret the already-saved paths against a different state space. A restart that finds any disagreement on one of these keys between the new input and the restart file aborts with a ``ValueError``: * **simulation**: ``interfaces``, ``task``, ``zero_left``, ``zero_ensemble``, ``flux``, ``permeability`` The full list is exposed in code as ``pyretis.inout.settings.RESTART_FORBIDDEN_KEYWORDS``. To change any of these you have two correct options: 1. **Start a new simulation from saved trajectories** — use :ref:`load `. This is the safest route whenever the new topology means the saved paths must be re-validated against fresh ensemble definitions. 2. **Reuse the saved paths but rewrite the topology** — set ``flexible_restart = True``. This bypasses the topology lock and takes the entire new input file as the settings; the user is then responsible for keeping detailed balance. See :ref:`user-section-initial-flexible-restart`. Practical examples that *require* one of these two routes (a plain restart will refuse): * changing one or more interface positions, * adding or removing interfaces (and the corresponding ensembles), * turning the ``[0^-]`` ensemble on or off (``zero_ensemble``, ``zero_left``, ``flux``), * switching ``task`` between ``tis`` / ``retis`` / ``repptis`` / ``explore``, * enabling or disabling ``permeability``. .. _user-section-initial-flexible-restart: Keyword flexible_restart ........................ .. pyretis-keyword:: flexible_restart boolean If ``True``, all settings are taken from the new input file instead of from the restart file. Use this when structural changes to the simulation are needed, for example: * changing interface positions or their number, * adding or removing path ensembles. In this mode no ``WARNING`` is emitted for changed values, and no whitelist is enforced — the new input is used as-is. .. warning:: When settings are changed under ``flexible_restart``, the user is responsible for ensuring that the new setup is consistent with detailed balance. If it is not, the ``pathensemble.txt`` files should be discarded before continuing. If some interfaces are removed, the ensemble folders must be relabeled manually. |pyretis| expects a continuous numbering scheme, e.g. ``000/``, ``001/``, ``002/``, … If new ensembles are added, consider setting ``priority_shooting = True`` in the ``retis`` section to focus sampling on the new ensembles until they reach a comparable number of cycles. Default: The default value is ``flexible_restart = False``.