pyretis.initiation package¶
This package defines methods for initiating path ensembles.
Package structure¶
Modules¶
- __init__.py
- This file, imports from the other modules and defines some helper methods for the initiation.
- initiate_kick.py (
pyretis.initiation.initiate_kick
) - Methods for initiating using the
kick
method. - initiate_load.py (
pyretis.initiation.initiate_load
) - Methods for initiating by loading already existing paths from files.
- initiate_restart.py (
pyretis.initiation.initiate_restart
) - Methods for initiating by loading PyRETIS restart files.
Important methods defined in this package¶
- get_initiation_method (
get_initiation_method()
) - Method to select initiation method from settings.
- initiate_path_simulation (
initiate_path_simulation()
) - Method to initiate a path simulation.
-
pyretis.initiation.
get_initiation_method
(settings)[source]¶ Return the initiation method from given settings.
Parameters: settings (dict) – This dictionary contains the settings for the initiation. Returns: out (callable) – The method to be used for the initiation.
-
pyretis.initiation.
initiate_path_simulation
(simulation, settings)[source]¶ Initialise a path simulation.
Parameters: - simulation (object like
PathSimulation
) – The simulation we are doing the initiation for. - settings (dict) – A dictionary with settings for the initiation.
Returns: out (callable) – The method to be used for the initiation.
- simulation (object like
List of submodules¶
pyretis.initiation.initiate_kick module¶
This file contains functions used for initiation of paths.
Important methods defined here¶
- generate_initial_path_kick (
generate_initial_path_kick()
) - Function for generating an initial path by repeatedly kicking a phase point.
- initiate_kick (
initiate_kick()
) - Helper method, selects either
initiate_kicki()
orinitiate_kick_max()
. - initiate_kicki (
initiate_kicki()
) - A method for initiating a path ensemble by repeatedly modifying velocities to find the crossing with the interfaces.
- initiate_kick_max (
initiate_kick_max()
) - A method similar to py:meth:.initiate_kick. Here, if possible, we will use points from the previous paths, closest to the target interface.
- initiate_path_ensemble_kick (
initiate_path_ensemble_kick()
) - Method to initiate a single path ensemble.
- fix_path_by_tis (
fix_path_by_tis()
) - Method to fix an initial path that starts and ends at the wrong interface via TIS moves.
-
pyretis.initiation.initiate_kick.
_get_help
(start_cond, interfaces)[source]¶ Define some helper methods for
fix_path_by_tis()
.This method returns two methods that
fix_path_by_tis()
can use to determine if a new path is an improvement compared to the current path and if the “fixing” is done.Parameters: - start_cond (string) – The starting condition (from the TIS settings). Left or Right.
- interfaces (list of floats) – The interfaces, on form
[left, middle, right]
.
Returns: - out[0] (method) – The method which determines if a new path represents an improvement over the current path.
- out[1] (method) – The method which determines if we are done, that is if we can accept the current path.
-
pyretis.initiation.initiate_kick.
fix_path_by_tis
(initial_path, ensemble, tis_settings)[source]¶ Fix a path that starts and ends at the wrong interfaces.
The given path is amended by performing TIS moves (shooting and time reversal). Note that this function is intended to be used in connection with the initialisation.
Parameters: initial_path (object like
PathBase
) – This is the initial path to fix. It starts & ends at the wrong interface.ensemble (dict.) – It contains:
- path_ensemble : object like
PathEnsemble
The path ensemble to create an initial path for. - system : object like
System
System is used here since we need access to the temperature and to the particle list. - order_function : object like
OrderParameter
The class used for obtaining the order parameter(s). - engine : object like
EngineBase
The engine to use for propagating a path. - rgen : object like
RandomGenerator
This is the random generator that will be used.
- path_ensemble : object like
tis_settings (dict) – Settings for TIS method, here we explicitly use:
- start_cond: string which defines the start condition.
- maxlength: integer which gives the maximum allowed path length.
Note that we here explicitly set some local TIS settings for use in the make_tis_step function.
Returns: out (object like
PathBase
) – The amended path.
-
pyretis.initiation.initiate_kick.
generate_initial_path_kick
(ensemble, tis_settings)[source]¶ Generate an initial path with the kicking method.
This function will generate an initial path by repeatedly kicking a phase-space point until the middle interface is crossed. The point before and after kicking are stored, so when the middle interface is crossed we have two points we can integrate forward and backward in time. This function is intended for use with TIS. For use with RETIS one should set the appropriate tis_settings so that the starting conditions are fine (i.e. for the [0^-] ensemble it might be different for the other ensembles).
Parameters: - ensemble (dict.) – It contains:
- path_ensemble : object like
PathEnsemble
The path ensemble to create an initial path for. - system : object like
System
System is used here since we need access to the temperature and to the particle list. - order_function : object like
OrderParameter
The class used for obtaining the order parameter(s). - engine : object like
EngineBase
The engine to use for propagating a path. - rgen : object like
RandomGenerator
This is the random generator that will be used.
- path_ensemble : object like
- tis_settings (dict) – This dictionary contains settings for TIS. Explicitly used here:
- start_cond: string, starting condition, ‘L’eft or ‘R’ight.
- maxlength: integer, maximum allowed length of paths.
Yields: - out[0] (boolean) – True if we are finished.
- out[1] (string) – The current status of this method.
- out[2] (object like
PathBase
or None) – If we are finished (and successful) this is the generated initial path. Otherwise, this is equal to None.
- ensemble (dict.) – It contains:
-
pyretis.initiation.initiate_kick.
initiate_kick
(simulation, settings, cycle)[source]¶ Run the initiation method for several ensembles.
Please see documentation for
initiate_path_ensemble_kick()
.
-
pyretis.initiation.initiate_kick.
initiate_kick_max
(simulation, settings, cycle)[source]¶ Run the initiation for several ensembles.
This method is similar to
initiate_kick()
, but here we update the initial point for an ensemble to use that of the previous path (if this exists).Please see documentation for
initiate_path_ensemble_kick()
.
-
pyretis.initiation.initiate_kick.
initiate_kicki
(simulation, settings, cycle)[source]¶ Run the initialization for several ensembles.
Please see documentation for
initiate_path_ensemble_kick()
.
-
pyretis.initiation.initiate_kick.
initiate_path_ensemble_kick
(ensemble, tis_settings, cycle)[source]¶ Run the “kick” initiate for a given ensemble.
Parameters: - ensemble (dict) – It contains:
- path_ensemble : object like
PathEnsemble
The path ensemble to create an initial path for. - system : object like
System
The system is used here since we need access to the temperature and to the particle list. - order_function : object like
OrderParameter
The class used for obtaining the order parameter(s). - engine : object like
EngineBase
The engine to use for propagating a path. - rgen : object like
RandomGenerator
This is the random generator that will be used.
- path_ensemble : object like
- tis_settings (dict) – This dictionary contains the TIS settings.
- cycle (integer, optional) – The cycle number we are initiating at, typically this will be 0 which is the default value.
Returns: - out[0] (boolean) – True if the initial path was accepted.
- out[1] (object like py:class:.PathBase) – The initial path.
- out[2] (string) – The status of the path.
- ensemble (dict) – It contains:
pyretis.initiation.initiate_load module¶
Method for initiating paths by loading from previous simulation(s).
Important methods defined here¶
- initiate_load (
initiate_load()
) - A method that will get the initial path from the output of a previous simulation.
-
pyretis.initiation.initiate_load.
_check_path
(path, path_ensemble, warning=True)[source]¶ Run some checks for the path.
Parameters: - path (object like
PathBase
) – The path we are to set up/fill. - path_ensemble (object like
PathEnsemble
) – The path ensemble the path could be added to. - warning (boolean, optional) – If True, it output warnings, else only debug info.
- path (object like
-
pyretis.initiation.initiate_load.
_do_the_dirty_load_job
(mainfolder, edir)[source]¶ Copy the files to a place where PyRETIS expects them to be.
The function checks if in the destination folder some suitable files are already present. If not, it tries to copy them from the main load folder.
Parameters: - mainfolder (string) – The path of the main load directory with frame/trajectory files.
- edir (string) – The path of the path ensemble load directory with frame/trajectory files.
-
pyretis.initiation.initiate_load.
_generate_traj_txt_from_ext
(dirname, system, accepted=True)[source]¶ Generate a traj.txt file in the path ensemble folder.
Parameters: - dirname (string) – The path of the path ensemble directory with trajectory files.
- system (object like
System
) – A system object we can use when calculating the order parameter(s). - accepted (boolean, optional) – It controls where the traj files shall be located, if True in the accepted folder, if False in the main folder.
-
pyretis.initiation.initiate_load.
_load_energies_for_path
(path, dirname)[source]¶ Load energy data for a path.
Parameters: - path (object like
PathBase
) – The path we are to set up/fill. - dirname (string) – The path to the directory with the input files.
Returns: None, but may add energies to the path.
- path (object like
-
pyretis.initiation.initiate_load.
_load_external_trajectory
(dirname, engine, copy=True)[source]¶ Load an external trajectory.
Here, we also do some moving of files to set up for a path simulation (if copy=True).
Parameters: - dirname (string) – The directory where we can find the trajectory file(s).
- engine (object like
ExternalMDEngine
) – The engine we use, here it is used to access the directories for the new simulation. - copy (boolean, opt) – If true, it copies the files to the main ensemble folders.
Returns: traj (dict) – A dictionary containing the trajectory information. Here, the trajectory information is a list of files with indices and information about velocity direction.
-
pyretis.initiation.initiate_load.
_load_order_parameters
(traj, dirname, system, order_function)[source]¶ Load or recalculate the order parameters.
Parameters: - traj (dictionary) – The trajectory we have loaded. Used here if we are re-calculating the order parameter(s).
- dirname (string) – The path to the directory with the input files.
- system (object like
System
) – A system object we can use when calculating the order parameter(s). - order_function (object like
OrderParameter
) – This can be used to re-calculate order parameters in case they are not given.
Returns: out (list) – The order parameters, each item in the list corresponds to a time frame.
-
pyretis.initiation.initiate_load.
_load_order_parameters_ext
(traj, dirname, order_function, engine)[source]¶ Load or re-calculate the order parameters.
For external trajectories, dumping of specific frames from a trajectory might be expensive and we here do slightly more work than just dumping the frames.
Parameters: - traj (dictionary) – The trajectory we have loaded. Used here if we are re-calculating the order parameter(s).
- dirname (string) – The path to the directory with the input files.
- order_function (object like
OrderParameter
) – This can be used to re-calculate order parameters in case they are not given. - system (object like
System
) – A system object we can use when calculating the order parameter(s).
Returns: out (list) – The order parameters, each item in the list corresponds to a time frame.
-
pyretis.initiation.initiate_load.
_load_trajectory
(dirname, filename='traj.txt')[source]¶ Load a trajectory from a file.
Parameters: - dirname (string) – The directory where we can find the trajectory file(s).
- filename (string) – The name of the trajectory file.
Returns: traj (dict) – A dictionary containing the trajectory information. That is, position and velocity for each frame.
-
pyretis.initiation.initiate_load.
clean_path
(path, path_ensemble, simtype='retis')[source]¶ Remove useless frames from a path.
This function removes phasepoints from a path that are not needed (e.g. the one in stable states)
Parameters: - path (object like
PathBase
) – The path we try to fix. - path_ensemble (object like
PathEnsembleExt
) – The path ensemble the path could be added to. - simtype (string) – The simulation type. ‘retis’, ‘repptis’, ‘pptis’
- path (object like
-
pyretis.initiation.initiate_load.
initiate_load
(simulation, settings, cycle, plot_loads=False)[source]¶ Initialise paths by loading already generated ones.
Parameters: - simulation (object like
Simulation
) – The simulation we are setting up. - cycle (integer) – The simulation cycles we are starting at.
- settings (dictionary) – A dictionary with settings for the initiation.
- simulation (object like
-
pyretis.initiation.initiate_load.
read_path_files
(path, dirname, ensemble)[source]¶ Read data needed for a path from a directory.
Parameters: - path (object like
PathBase
) – The path we are to set up/fill. - dirname (string) – The path to the directory with the input files.
- ensemble (dictionary of objects) – It contains:
- path_ensemble: object like
PathEnsemble
This is the path ensemble to perform the initialization. - order_function: object like
OrderParameter
The class used for obtaining the order parameter(s). - engine: object like
EngineBase
The engine to use for propagating a path. - system: object like
System
A system object we can use when calculating the order parameter(s).
- path_ensemble: object like
- path (object like
-
pyretis.initiation.initiate_load.
read_path_files_ext
(path, dirname, ensemble)[source]¶ Read data needed for a path from a directory.
Parameters: - path (object like
Path
) – The path we are to set up/fill. - path_ensemble (object like
PathEnsembleExt
) – The path ensemble the path could be added to. - dirname (string) – The path to the directory with the input files.
- ensemble (dictionary of objects) – It contains:
- path_ensemble: object like
PathEnsemble
This is the path ensemble to perform the initialization. - order_function: object like
OrderParameter
The class used for obtaining the order parameter(s). - engine: object like
EngineBase
The engine to use for propagating a path. - system: object like
System
A system object we can use when calculating the order parameter(s).
- path_ensemble: object like
- path (object like
-
pyretis.initiation.initiate_load.
reorderframes
(path, path_ensemble)[source]¶ Re-order the phase points in the input path.
This function assumes that the path needs to be fixed. It checks for the validity of the path and keeps only the frames that are useful for the region to explore e.g. [0^-].
Parameters: - path (object like
PathBase
) – The path we try to fix. - path_ensemble (object like
PathEnsembleExt
) – The path ensemble the path could be added to.
- path (object like
pyretis.initiation.initiate_restart module¶
This file contains functions used for initiation of paths.
Important methods defined here¶
- initiate_restart (
initiate_restart()
) - A method that will get the initial path from the output from a previous simulation.
-
pyretis.initiation.initiate_restart.
initiate_restart
(simulation, settings, cycle)[source]¶ Initialise paths by loading restart data.
Parameters: - simulation (object like
Simulation
) – The simulation we are setting up. - settings (dictionary) – A dictionary with settings for the initiation.
- cycle (integer) – The simulation cycles we are starting at.
- simulation (object like