The simulation section¶

The simulation section defines and selects the simulation PyRETIS will run.

Example Simulation section:

Simulation
----------
task = retis
steps = 20000
interfaces = [-0.9, -0.8, -0.7, -0.6, -0.5, -0.4, -0.3, 1.0]

For this section, the keyword task specifies the type of simulation to run and this will also determine the keyword that can be set in this section. Further, a specific task might also require additional sections to be defined as detailed in the table below:

Table 2 Possible values for the task keyword¶
Task	Description	Keywords	Required sections
`retis`	A replica exchange transition interface sampling simulation.	`task`, `steps`, `interfaces`	`tis`, `retis`
`tis`	A transition interface sampling simulation.	`task`, `steps`, `interfaces`, `ensemble_number`, `detect`	`tis`
`repptis`	A replica exchange partial path transition interface sampling simulation.	`task`, `steps`, `interfaces`	`tis`
`pptis`	A partial path transition interface sampling simulation.	`task`, `steps`, `interfaces`	`tis`
`explore`	A free energy surface exploration simulation.	`task`, `steps`, `interfaces`	`tis`
`md-flux`	A MD FLUX simulation.	`task`, `steps`, `interfaces`
`md-nve`	A MD NVE simulation.	`task`, `steps`

Since the different tasks may require different keywords, these are described below individually. In addition, there are some settings which typically are used in relation to the analysis, or when extending simulations. These are described in the section on common keywords.

The retis task ¶

The retis task defines a replica exchange transition interface sampling simulation.

Example Simulation section for task retis:

Simulation
----------
task = retis
steps = 20000
interfaces = [-0.9, -0.8, -0.7, -0.6, -0.5, -0.4, -0.3, 1.0]

Keywords for the retis task ¶

For the retis task, the following keywords can be set:

Table 3 Keywords for the retis task.¶
Keyword	Description
steps	The number of total retis steps (cycles)
interfaces	The location of the interfaces to consider.
priority_shooting	Prioritize the ensembles with less cycles.

In addition, this task requires that the sections TIS and RETIS are defined.

Keyword steps ¶

steps = integer

The steps keyword defines the number of RETIS cycles to perform. Note that it indicates the goal/final number of the simulation cycles.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation.

Default: Not any, this keyword must be specified.

Note

interfaces is topology-defining: it is locked once the simulation is started. A restart that supplies a different list aborts with a ValueError — use load or flexible_restart to change the interface set.

Keyword priority_shooting ¶

priority_shooting = boolean

If True, ensembles with lower cycle numbers will be prioritized until their cycle numbers equals the others.

This setting simplify the use of PyRETIS in cluster environments in which walltime is rather short. Each ensemble can be, therefore, investigated also if launching several runs.

Default: The default value is priority_shooting = False.

The tis task ¶

The tis task defines a transition interface sampling simulation.

Example Simulation section for task tis (multiple path ensembles):

Simulation
----------
task = tis
steps = 20000
interfaces = [-0.9, -0.8, -0.7, -0.6, -0.5, -0.4, -0.3, 1.0]

Example Simulation section for task tis (a single path ensemble):

Simulation
----------
task = tis
steps = 20000
interfaces = [-0.9, -0.9, 1.0]
detect = -0.8
ensemble_number = 1

Keywords for the tis task ¶

For the tis task, the following keywords can be set:

Table 4 Keywords for the tis task.¶
Keyword	Description
steps	The total number of steps to perform.
interfaces	The interfaces defining the TIS ensemble.
priority_shooting	Prioritize the ensembles with less cycles.
ensemble_number	For defining the ensemble number considered.
detect	The interface used for detecting successful paths.
maxlegth	The maximum number of step allowed for a paths.

In addition, this task requires that the section TIS is defined.

Keyword steps ¶

steps = integer

The steps keyword defines the number of TIS cycles to perform.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation. If the number of interfaces given is 3 or less, a single TIS simulation will be performed, otherwise, input files for several single TIS simulations will be written. These simulations can then be run manually.

Default: Not any, this keyword must be specified.

Note

Keyword priority_shooting ¶

priority_shooting = boolean

If True, ensembles with lower cycle numbers will be prioritized until their cycle numbers equals the others.

This setting simplify the use of PyRETIS in cluster environments in which walltime is rather short. Each ensemble can be, therefore, investigated also if launching several runs.

Default: The default value is priority_shooting = False.

Keyword ensemble_number ¶

ensemble_number = integer

A number specifying the path ensemble we are simulating, ensemble_number = 1 corresponds to [0^+], 2 to [1^+] and so on. This is only needed for running a single TIS simulation.

Default: Not any, this keyword must be specified.

Keyword detect ¶

detect = float

A number specifying the interface used for detecting successful paths. This is only needed for a single TIS simulation.

Default: Not any, this keyword must be specified.

The repptis task ¶

The repptis task defines a replica exchange partial path transition interface sampling simulation. Paths between adjacent pptis ensembles can be swapped using the replica exchange move.

Example Simulation section for task repptis:

Simulation
----------
task = repptis
steps = 20000
interfaces = [-0.5, -0.3, 0, 0.3, 0.5]

Keywords for the repptis task ¶

For the repptis task, the following keywords can be set:

Table 5 Keywords for the repptis task.¶
Keyword	Description
steps	The number of total repptis steps (cycles)
interfaces	The location of the interfaces to consider.
priority_shooting	Prioritize the ensembles with less cycles.

In addition, this task requires that the sections TIS and RETIS are defined.

Note that (RE)PPTIS simulations make use of the TIS and RETIS sections in the input RST file. This is because almost all of the keywords are similar. Therefore, REPPTIS or PPTIS sections do not exist in the RST file, but re-use the TIS and RETIS sections.

Keyword steps ¶

steps = integer

The steps keyword defines the number of REPPTIS cycles to perform. Note that it indicates the goal/final number of the simulation cycles.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation.

Default: Not any, this keyword must be specified.

Keyword priority_shooting ¶

priority_shooting = boolean

If True, ensembles with lower cycle numbers will be prioritized until their cycle numbers equals the others.

This setting simplify the use of PyRETIS in cluster environments in which walltime is rather short. Each ensemble can be, therefore, investigated also if launching several runs.

Default: The default value is priority_shooting = False.

The pptis task ¶

The pptis task defines a partial path transition interface sampling simulation. PPTIS ensembles are shorter than TIS ensembles, cutting the paths’ memory requirements. While for (RE)TIS the paths of [i^+] need to start from state A, cross interface i, and either commit to state B or return to state A, PPTIS paths of [i^+-] only need to start and end at interfaces i-1 or i+1, having crossed interface i.

Example Simulation section for task pptis:

Simulation
----------
task = pptis
steps = 20000
interfaces = [-0.5, -0.3, 0, 0.3, 0.5]

Keywords for the pptis task ¶

For the pptis task, the following keywords can be set:

Table 6 Keywords for the pptis task.¶
Keyword	Description
steps	The total number of steps to perform.
interfaces	The interfaces defining the PPTIS ensemble.
priority_shooting	Prioritize the ensembles with less cycles.

In addition, this task requires that the section TIS is defined.

Note that PPTIS simulations use the TIS section, and not the PPTIS section (which does not exist!).

Keyword steps ¶

steps = integer

The steps keyword defines the number of PPTIS cycles to perform.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces to use in the path simulation. If the number of interfaces given is 3 or less, a single PPTIS simulation will be performed, otherwise, input files for several single PPTIS simulations will be written. These simulations can then be run manually.

Default: Not any, this keyword must be specified.

Keyword priority_shooting ¶

priority_shooting = boolean

If True, ensembles with lower cycle numbers will be prioritized until their cycle numbers equals the others.

This setting simplify the use of PyRETIS in cluster environments in which walltime is rather short. Each ensemble can be, therefore, investigated also if launching several runs.

Default: The default value is priority_shooting = False.

The explore task ¶

The explore task is a path sampling simulation designed to map the free energy landscape of a transition without computing rates. It is most useful before a production TIS/RETIS run, to locate local minima, check that paths can cross all interfaces, and generate a pool of initial paths to seed those simulations.

During an explore run every generated trajectory is accepted unconditionally (path status EXP). This means the simulation does not satisfy detailed balance and must not be used to compute crossing probabilities or rate constants.

Two tis-section settings are overridden automatically regardless of what the input file specifies:

freq is forced to 0 — only shooting moves are performed, no time-reversal moves.
allowmaxlength is forced to True — paths that reach maxlegth are treated as valid and accepted.

Setting a short maxlength in the tis section therefore controls how quickly the simulation restarts from a new shooting point and hence how densely the landscape is sampled.

Example Simulation section for task explore:

Simulation
----------
task = explore
steps = 5000
interfaces = [-1.9, -0.7, -0.5, 0.3]

TIS settings
------------
freq = 0.5
maxlength = 100
allowmaxlength = False

Note

freq and allowmaxlength in the tis section are shown here for completeness but are ignored at run time — explore always sets them to 0 and True respectively.

Keywords for the explore task ¶

For the explore task, the following keywords can be set:

Table 7 Keywords for the explore task.¶
Keyword	Description
steps	The total number of shooting steps to perform.
interfaces	The interfaces defining the exploration region.
maxlegth	Maximum path length; shorter values restart the trajectory more often and improve landscape coverage.

In addition, this task requires that the section TIS is defined.

Keyword steps ¶

steps = integer

The steps keyword defines the number of shooting cycles to perform.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies the interfaces that define the exploration region. The first interface acts as the left boundary and the last interface as the right boundary. The path sampler will attempt to generate trajectories that span this region.

The number of interfaces determines the number of path ensembles created: N interfaces yield N - 1 ensembles, analogous to a TIS setup. A larger number of intermediate interfaces gives finer spatial resolution but requires more initial paths.

Default: Not any, this keyword must be specified.

Note

explore is intended as a preparatory step. Once a satisfactory set of paths has been collected, switch task to tis, retis, pptis, or repptis and restart from the saved paths to begin a production run. See the initial-path section for how to load frames from a previous explore run.

The md-flux task ¶

The md-flux task is a molecular dynamics simulation for determining the initial flux for a TIS path simulation.

Example Simulation section for task md-flux:

Simulation
----------
task = md-flux
steps = 10000000
interfaces = [-0.9]

Keywords for the md-flux task ¶

For the md-flux task, the following keywords can be specified:

Table 8 Keywords for the md-flux task¶
Keyword	Description
steps	Defines the number of steps to carry out.
interfaces	Defines the interfaces to consider for the flux simulation.

Keyword steps ¶

steps = integer

The steps keyword specifies the number of MD steps to perform.

Default: Not any, this keyword must be specified.

Keyword interfaces ¶

interfaces = list of floats

The interfaces keyword specifies for which interfaces the initial flux should be obtained. This can be given as a list of floats.

Default: Not any, this keyword must be specified.

The md-nve task ¶

The md-nve task is a NVE molecular dynamics simulation.

Example Simulation section for task md-nve:

Simulation
----------
task = md-nve
steps = 10000000

Keywords for the md-nve task ¶

The following keywords can be specified for the md-nve task:

Table 9 Keywords for the md-nve task¶
Keyword	Description
steps	The number of overall steps to consider for the simulation.

Keyword steps ¶

steps = integer

The steps keyword specifies the number of MD steps to perform.

Default: Not any, this keyword must be specified.

Common keywords ¶

The following keywords are common to all simulation tasks:

Table 10 Common keywords¶
Keyword	Description
endcycle	Specifies the cycle step the simulation ended.
exe-path	Specifies the directory from where the simulation was executed.
restart	Specifies the restart file to use.
startcycle	Specifies the cycle step the simulation should start at.
remove_generate	Specifies if the generated files should be removed after every ensemble TIS move.

Keyword endcycle ¶

endcycle = integer

The endcycle keyword specifies the cycle number at which the simulation ended. If the simulation was stopped before the specified number of steps were reached, the endcycle will be difference from the steps keyword. This keyword will be set and updated by PyRETIS and written to the processed input file.

Default: Not any, note that this keyword will be updated and modified by PyRETIS as part of the output process. This keyword is only used by the analysis program.

Keyword exe-path ¶

exe-path = string

The exe-path keyword specifies the location from where the simulation was executed. This will be set and updated by PyRETIS.

Default: Not any, note that this keyword will be updated and modified by PyRETIS as part of the output process. This keyword does not need to be set in the input file by the user since PyRETIS will update this setting automatically.

Keyword restart ¶

restart = string

The restart keyword specifies the path to the restart file to use for restarting/continuing the selected simulation task. To be used, it requires that method keyword in the initial-path section is set to restart.

Default: The default value is pyretis.restart.

Keyword startcycle ¶

startcycle = integer

The startcycle keyword specifies the cycle number the simulation starts at. This can be used, for instance, when extending a simulation to tell PyRETIS that the simulation should start at a specified step number.

Default: The default value is 0.

Keyword remove_generate ¶

remove_generate = boolean

The remove_generate keyword specifies whether the generated files should be removed after every ensemble TIS move. This is useful when running TIS simulations in a cluster environment, where the generated files can take up a lot of space. If remove_generate = True, the generated files will be removed after every ensemble TIS move. If remove_generate = False, the generated files will only be removed after an entire cycle has finished.

Default: The default value is True.