System class

Code author: Niklaus Johner <niklaus.johner@a3.epfl.ch>

This module contains the System object as well as a function to Load a System from a file.

LoadSystem(filename)

Loads a System object from a file (using pickle)

Parameters:filename (str) – The path to the file. A ”.pkl” extension will be added automatically to the filename.

class System(basedir, cv_list, init_input_fname, run_input_fname, init_job_fname, run_job_fname, data_filename, init_nstep, run_nstep, n_data, max_E1, max_E2, temperature, check_fnames=[], target_cv_vals=[], adapt_spring_constants=True, adapt_window_centers=True, check_free_energy=True)

The System is the top class in the hierarchical description of a PMF calculation by umbrella sampling (System contains Window comprising several Phase, which each have one Job). The corresponding simulations will be carried out in a corresponding hierarchy of directories. The System contains all the information about the current status of the simulations and is therefore the only object needed to restart a SiPMF calculation.

Parameters:

• basedir (str) – The root directory in which the PMF calculation will be performed. Windows and phases will correspond to subdirectories of basedir.
• cv_list (list (CollectiveVariable)) – List of the collective variables (CV) used in the umbrella sampling
• init_input_fname (str) – basedir/init_input_fname is the MD input file used for initializing new windows.
• run_input_fname (str) – basedir/run_input_fname is the MD input file used to sample a window.
• init_job_fname (str) – basedir/init_job_fname is the job file used to submit initialization runs to the cluster
• run_job_fname (str) – basedir/run_job_fname is the job file used to submit sampling runs to the cluster
• data_filename (str) – is the name of the file containing the values of the CVs. One such file should be generated for each sampling phase of every window by the corresponding job and be found in the corresponding directory.
• init_nstep (int) – The number of steps for initialization phases
• run_nstep (int) – The number of steps for sampling phases
• n_data (int) – The number of data wanted for each window.
• max_E1 (float) – Lower boundary of free energy threshold to decide whether to extend the simulation to neighboring windows or not.
• max_E2 (float) – Upper boundary of free energy threshold to decide whether to extend the simulation to neighboring windows or not.
• temperature (float) – The temperature at which WHAM is performed.
• check_fnames (list (str)) – Filenames that file be checked to exist to determine whether a phase has finished properly
• target_cv_vals (list (tuple (float ) )) – Target values of the CVs. Once the system has reached these values it will only use max_E1 as energy threshold to generate new windows.
• adapt_spring_constants – If spring constants should be automatically adapted for each window.
• adapt_window_centers – If window centers should be automatically adapted for each window.
• check_free_energy (float) – Only generate new windows from windows that have free energy below max_E1

AddWindow(cv_values, spring_constants, shifts=None, parent_window=None)

Add a new window to the system

Parameters:

• cv_values (list (float)) – Values of the collective variables for this window
• spring_constants (list (float)) – Spring constants for the constraining potentials
• parent_window (Window) – Window from which the new window should be created

CalculateDiffusionConstants(dt_per_step, masses, new_only=False)

CalculatePMF(environment, wham_tolerance=0.001)

Calculate the PMF. The function generates the meta file listing all the data files and their corresponding CV values and spring constants and then calls WHAM.

Parameters:environment (Environment) – The environment used to call WHAM

CalculatePMFConvergence(environment, n_skip_list, n_tot_list, max_E)

This function generates a set of PMFs from subsets of the whole data, defined by n_skip_list and n_tot_list and calculates their convergence. The last PMF of the set is used as reference. Only points of the PMF with an energy below max_E are used in the calculation.

Parameters:

• n_skip_list (list (int)) – List of the number of data points to skip.
• n_tot_list (list (int)) – List of the total number of data points used to calculate the PMF.
• max_E (float) – maximal energy of considered points.

CalculateWindowsHistConvergence(environment, n_skip_list, n_tot_list, update_data_files=True, pool_windows=False)

FindPhase(cv_values, phase_name, spring_constants=None)

FindWindow(cv_values, spring_constants=None)

Find window with given values of the cvs

Parameters:cv_values (list (float)) – Values of the collective variables for the window

FindWindows(cv_values, spring_constants=None)

Find windows with given values of the cvs

Parameters:cv_values (list (float)) – Values of the collective variables for the window

GenerateNewWindows(environment)

Generates new windows expected to have low free energy from windows with low free energy themselves. The function first updates the PMF (UpdatePMF) and then goes through all the windows in the system to find potential new windows to generate. Specifically it will start with a maximal free energy threshold of max_E1, go through all the windows and for those with free energy below the current threshold, it will look at all potential neighbor windows. It estimates the free of each potential new window and if it is below the free energy threshold, it adds that window to the system. If no new window was generated, it increases the threshold in 5 steps up to max_E2, each time repeating the procedure described above. If a new window can be generated from several windows, the one with lowest free energy will be used as parent.

Parameters:environment (Environment) – The environment used to call WHAM

GetPathToInitInputFile()

Get the path to the MD input file used to generate new windows (initialization phase)

GetPathToInitJobFile()

Get the path to the job submission file for initialization phases

GetPathToRunInputFile()

Get the path to the MD input file used to sample windows (run phase)

GetPathToRunJobFile()

Get the path to the job submission file for run phases

Initialize(cv_values, spring_constants, init_restartdir)

Generate the first window.

Parameters:

• cv_values (list (float)) – The values to which the collective variables should be restrained for this window.
• spring_constants (list (float)) – The spring constants used to restrain the collective variables
• init_restartdir (str) – basedir/init_restartdir should point to the directory containing the files from which the simulation of the first phase of this window should be restarted.

PlotHistogram(fname_extension='')

Plots the histogram of the accumulated data.

PlotPMF(fname_extension='')

Plot the PMF.

ReadPMFFile()

Read the PMF file generated by the CalculatePMF function.

Save(filename)

Save the System to a file using pickle.

Parameters:filename (str) – The System will be saved to basedir/filename.pkl

SetNewBaseDir(basedir)

ShiftWindowFreeEnergies(min_val=0)

Shift the free energies of the windows such that the window with the lowest free energy has a free energy of min_val.

Parameters:min_val (float) – the free energy assigned to the window with lowest free energy

SubmitNewJobs(environment)

Submit the next series of jobs. This does not create new windows, only go through the existing windows and submit the next job (initialization or run) for that window if necessary (if not enough data has been collected yet for that window).

Parameters:environment (Environment) – The environment used to submit the jobs

UpdateDataCounts()

Update the total number of data accumulated for every window (sum over the data in each phase of the window).

UpdateDataFiles(n_skip=0, n_tot=-1, new_only=True)

Updates the datafiles of all windows. For each window, it takes the data from all the run phases and writes it into a datafile, skipping the first n_skip data points and adding a maximum of n_tot data points for each window. n_tot=-1 means there is no maximal number of data points.

Parameters:

• n_skip (int) – The number of data points to skip.
• n_tot (int) – The total number of data points used to calculate the PMF.
• new_only (bool) – Only add the data from phases that have not yet been added to the data files.

UpdatePMF(environment, n_skip=0, n_tot=-1, new_only=True, fname_extension='', wham_tolerance=0.001)

Calculates the PMF (CalculatePMF), then reads the ouput PMF file (ReadPMFFile) and plots the new PMF. Finally, using the PMF, it assigns a free energy value to each window.

Parameters:environment (Environment) – The environment used to call WHAM

UpdateUnfinishedJobList(environment)

Check whether running jobs are still in the queue and update the list of unfinished jobs and updated windows.

Parameters:environment (Environment) – The environment used to check the job status

RebuildWindowsAndPhasesFromDirectoryTree(system)

This function can be used to rebuild the list of windows and phases from the directory tree. It also adds the window parents and phase parents. This is meant to be used only in case something went very wrong and the state file cannot be used for some reason.

Parameters:system (System) – The system, which should have been initialized with the same cv_list and such. You also need to manually set the system.init_restartdir before passing the system to this function. This is the restart directory of the initial phase of the calculation.