.. _user-guide-initial-paths: Getting the initial path ======================== Before a TIS, RETIS or REPPTIS simulation can start, every path ensemble needs **one valid initial path** — a trajectory that already satisfies the ensemble's interface conditions. Generating these starting paths is a step in its own right, and |pyretis| offers four routes, summarised here and configured through the :ref:`initial-path section `. Which route to use: * **No trajectory yet, simple system** → :ref:`kick `. * **No trajectory yet, hard-to-reach barrier** → :ref:`explore ` first to map the order parameter, then kick or load. * **You already have a trajectory (MD or a previous run)** → :ref:`load ` (and its :ref:`sparse variants `). * **Continuing an interrupted run** → :ref:`restart ` (see the reference). .. _initpath-kick: Kick: MC + MD generation from a single configuration ---------------------------------------------------- The ``kick`` method builds initial paths from scratch, needing only a single starting configuration. For each ensemble it randomises the velocities (a Monte-Carlo *kick*), integrates the dynamics (MD) one step, and accepts the move when it gets closer to the ensemble's middle interface — repeating until a crossing is found, then shooting forward and backward to complete the path. .. code-block:: toml [initial-path] method = "kick" kick-from = "previous" The ``kick-from`` option controls how multi-ensemble runs are seeded: * ``kick-from = "initial"`` (default) — every ensemble is kicked from the same user configuration. Simple, but ensembles whose interface lies far from the start may need many iterations. * ``kick-from = "previous"`` (recommended for RETIS) — only the first ensemble starts from the user configuration; each later ensemble is kicked from the frame of the previously generated path closest to (and left of) the next interface, propagating the seed through interface space. The full keyword list is in the :ref:`kick reference `. Every standard 1D tutorial uses kick, e.g. :ref:`TIS in a 1D potential ` and :ref:`RETIS in a 1D potential `. .. _initpath-explore: Explore: mapping the order parameter first ------------------------------------------ When a good order parameter or a sensible interface placement is not yet known, the ``explore`` task runs an exploratory simulation that wanders the order-parameter space without enforcing interface conditions. Its output (the visited order-parameter range and the trajectories) helps you place interfaces sensibly before committing to a TIS/RETIS run, and the generated trajectories can themselves be loaded as initial paths. .. code-block:: toml [simulation] task = "explore" [initial-path] method = "kick" See the :ref:`explore tutorial ` for a runnable 1D double-well example. .. _initpath-load: Load: reusing an existing trajectory ------------------------------------ The ``load`` method initialises the ensembles from trajectory data you already have — a molecular-dynamics run or a previous (P)RETIS simulation — instead of generating paths from scratch. |pyretis| distributes the frames across the ensemble subfolders, **recomputes the order parameter from the atomic positions** (so you can change the order parameter definition without regenerating trajectories), and validates / cleans each path. .. code-block:: toml [initial-path] method = "load" load_folder = "load" Two folder layouts are supported — a single shared trajectory placed directly in ``load_folder``, or per-ensemble ``000/``, ``001/``, … subfolders. With ``load_and_kick = True`` the loaded frames become a seed pool: if they cannot form a valid path, |pyretis| falls back to a kick from the nearest frame. The layouts and all keywords are documented in the :ref:`load reference `. .. _initpath-load-sparse: Load (sparse): loading only the frames you kept ----------------------------------------------- You do not need the full, densely sampled trajectory on disk. A *sparse* load reconstructs each path from a small set of stored frames plus a ``traj.txt`` index, with |pyretis| recomputing the order parameter and filling in the path bookkeeping. This is the common case when reusing trajectories where only selected frames were saved. Two runnable references with the internal engine ship under the test suite: * `load-traj `__ — a shared trajectory referenced from ``traj.txt``. * `load-frames `__ — individual per-ensemble frame files. Both run with ``pyretisrun -i retis.toml -p`` exactly like the load method above; they differ only in how the kept frames are laid out. .. _initpath-restart: Restart: continue an interrupted run ------------------------------------ ``restart`` does not construct new paths at all — it resumes a simulation from the ``pyretis.restart`` state file a previous run wrote, picking the sampling up exactly where it stopped (the same active paths, random-number state and cycle counter). Use it to extend a finished run to more cycles, or to recover one that was interrupted: .. code-block:: toml [initial-path] method = "restart" ``flexible_restart = True`` relaxes the consistency checks when the restart settings have changed (for example a different cycle target). The full keyword list is in the :ref:`restart reference `. .. seealso:: The complete keyword reference for every method (including ``restart`` and ``flexible_restart``) is in the :ref:`initial-path section ` of the input documentation.