.. _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. | +---------------+---------------------------------------------------------+ | .. _user-section-initial-path-kick: The kick method --------------- The kick method is used to generate new initial paths for the path ensembles in a simulation. As an example, consider the path ensemble :math:`[i^+]`. Associated with this path ensemble is the interface :math:`\lambda_i` and the kick method starts by searching for a crossing with this interface. Given that the system is in a phase point, say :math:`x`, this method will search for the crossing by: 1. Modify the velocities (e.g. new velocities are generated from a Maxwellian distribution). 2. Integrate the equations of motion one step forward in time. This results in a new phase point, say :math:`y`. 3. If :math:`y` is closer to the interface :math:`\lambda_i` compared to :math:`x`, then we update :math:`x = y` and repeat the steps. Otherwise, the steps are just repeated without updating :math:`x`. When the crossing is found, the algorithm has produced two phase points, one immediately before the interface and one immediately after. A full path is then generated by integrating the equations of motion forward in time from the point immediately after the interfaces and backward in time from the point immediately before the interfaces. 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 will load previous paths from 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| | Generate a new path by the kick method from the | | | loaded data. | +-----------------+--------------------------------------------------------+ | |load_folder| | Selects the directory where the paths we will load are | | | stored. | +-----------------+--------------------------------------------------------+ .. _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 The use of ``load_and_kick`` initialization method if the keyword is set to True. .. _user-section-initial-load-load-folder: Keyword load_folder ................... .. pyretis-keyword:: load_folder string The ``load_folder`` keyword specifies a directory containing the initial paths to start from. In this folder there are two possibilities: -- UNFORMATTED/LOAD GENERIC FILES OPTION -- When only a trajectory or/and some frames are available, they can be copied in the ``load folder``. The load function will copy all the trajectories and frames files from such a folder into the respective folders for each ensemble (e.g. 000 001 etc). Thereafter, the order parameter and the energy will be computed and stored in the files ``order.txt`` and ``energy.txt``, respectively. A third file, ``traj.txt`` containing the list of the frames to be used by PyRETIS, will be then also generated. Only the frames and the parts of the trajectories relevant for each ensemble will be considered by the load function. In the case that different trajectories are to be used to initialize different ensembles, the relevant files can be stored in the respective ensemble subfolders (e.g. '000', '001', etc) contained in the ``load folder``. The load function searches in the ``load folder``\ [`000`, `001`, `002`, etc.] for usable files. For each ensemble subfolder, if the files ``order.txt``, ``energy.txt`` and ``traj.txt`` are present, they will be loaded, otherwise they will be re-generated. Note that if the .txt files will be loaded, a direct correspondence with the trajectory/frame files is expected (as in the forthcoming resume option section). -- FORMATTED/RESUME OPTION -- Previous output can be copy and pasted in the load folder, or the here described files generated with the proper formatting. This option is usefull when simulations need to be restarted but some settings need to be changed, or when the restart files are corrupted. The presence of subfolders named ``000``, ``001`` etc. and that these folders contains the paths we are to load. The paths should be given as: * For internal engines: 1. A ``traj.txt`` file containing the full path (positions and velocities). 2. A ``order.txt`` file containing the order parameters for the path. If this file is not given, the order parameters will be re-calculated. 3. A ``energy.txt`` file containing the energies. If this file is not given, the energies along the path will be ignored. * For external engines: 1. A ``traj.txt`` file with the path. 2. A ``accepted`` folder containing the files referenced in the ``traj.txt`` file. 3. A ``order.txt`` file containing the order parameters for the path. If this file is not given, the order parameters will be re-calculated. 4. A ``energy.txt`` file containing the energies. If this file is not given, the energies along the path will be ignored. Default: The default value is ``load_folder = load``. | .. _user-section-initial-path-restart: The restart method ------------------ The ``restart`` method is used to continue simulations. Keywords for the restart method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the restart method, the following keywords can be set: .. |restart_method| replace:: :ref:`method ` .. _table-keyword-restart: .. table:: Keywords for the restart method. :class: table-striped table-hover +------------------+-------------------------------------------------------+ | Keyword | Description | +==================+=======================================================+ | |restart_method| | Selects the restart method. | +------------------+-------------------------------------------------------+ .. _user-section-initial-restart-method: Keyword method .............. .. pyretis-keyword:: method restart :specific: yes The ``method`` keyword selects the restart initialization. Here, we load path and ensemble data from the restart files for each ensemble. These restart files are named ``ensemble.restart`` and there is one 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.