The initial-path section¶
The initial-path
section specifies how the initial
path for a TIS/RETIS simulation should be generated.
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:
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. |
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 . Associated with this path ensemble is the interface and the kick method starts by searching for a crossing with this interface. Given that the system is in a phase point, say , this method will search for the crossing by:
- Modify the velocities (e.g. new velocities are generated from a Maxwellian distribution).
- Integrate the equations of motion one step forward in time. This results in a new phase point, say .
- If is closer to the interface compared to , then we update and repeat the steps. Otherwise, the steps are just repeated without updating .
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:
Keyword | Description |
---|---|
method | Selects the kick method. |
kick-from | Modify how the initial point for the kick method is picked. |
Keyword method¶
method
keyword selects the kick initialization.Keyword kick-from¶
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
.
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:
Keyword | Description |
---|---|
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. |
Keyword method¶
method
keyword selects the load initialization.Keyword load_and_kick¶
load_and_kick
initialization method
if the keyword is set to True. The method will select the loaded
frame closest to the interface to be crossed and feeds it as
starting point for the kicking initialization procedure.
Once the kicking procedure will be completed,
a new trajectory will be generated with 2 way shooting,
fully replacing the loaded frames/trajectory.Keyword load_folder¶
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 ones for each ensemble (e.g. 000 001 etc).
Thereafter, the order parameter will be computed and stored in the file
order.txt
. A second 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.
The unstructured load checks if the loaded frames compose a trajectory that
satisfies the relative ensemble definition. If not, the frames are sorted
according to their order parameter and the ensemble definition is checked
again.
If the new sorted sequence still do not compose a formally valid
trajectory, but some frames are present such that the ensemble definition
could be satisfied, the path is mirrored in order to obtain
a L to L or R to R path. This is a bookkeeping procedure to generate
a formally valid path for a given ensemble.
At the end of the procedure, all the frames that are not useful for the
sampling are removed. The procedure will keep the two closest frames,
before and after the first interface, and all the frames between the
interface defining the ensemble and the last interface. In the case
that this last group has no entries, the frames with the highest order
parameter is kept in order to allow the load_and_kick procedure.
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 useful 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:
- A
traj.txt
file containing the full path (positions and velocities). - A
order.txt
file containing the order parameters for the path. If this file is not given, the order parameters will be re-calculated. - A
energy.txt
file containing the energies. If this file is not given, the energies along the path will be ignored.
- A
- For external engines:
- A
traj.txt
file with the path. - A
accepted
folder containing the files referenced in thetraj.txt
file. - A
order.txt
file containing the order parameters for the path. If this file is not given, the order parameters will be re-calculated. - A
energy.txt
file containing the energies. If this file is not given, the energies along the path will be ignored.
- A
- Default:
- The default value is
load_folder = load
.
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:
Keyword | Description |
---|---|
method | Selects the restart method. |
flexible-restart | Allow the modification of input before restarts. |
Keyword method¶
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.Keyword method¶
If True
, the settings included in the input file will be read and used
(e.g. change the number of interfaces, their position, etc).
Note 1) If the settings are changed in a restart, the new options
must be consistent in respect to the detail balance. If not,
the pathensemble.txt files should be discarded.
Note 2) If some interfaces are removed, the ensemble folders have to be
relabeled by the user. PyRETIS expects a series of subfolders with
a continuous numbering scheme that contains the relative ensembles.
Note 3) If some ensemble have to be added, the priority_shooting
option
in the retis
section might be considered to focus the sampling in the
new ensembles.
- Default:
- The default value is
flexible_restart = False
.