Setup¶

Defining and Calculating Progress Coordinates¶

Binning¶

The Weighted Ensemble method enhances sampling by partitioning the space defined by the progress coordinates into non-overlapping bins. WESTPA provides a number of pre-defined types of bins that the user must parameterize within the system.py file, which are detailed below.

Users are also free to implement their own mappers. A bin mapper must implement, at least, an assign(coords, mask=None, output=None) method, which is responsible for mapping each of the vector of coordinate tuples coords to an integer (numpy.uint16) indicating what bin that coordinate tuple falls into. The optional mask (a numpy bool array) specifies that some coordinates are to be skipped; this is used, for instance, by the recursive (nested) bin mapper to minimize the number of calculations required to definitively assign a coordinate tuple to a bin. Similarly, the optional output must be an integer (uint16) array of the same length as coords, into which assignments are written. The assign() function must return a reference to output. (This is used to avoid allocating many temporary output arrays in complex binning scenarios.)

A user-defined bin mapper must also make an nbins property available, containing the total number of bins within the mapper.

self.bin_mapper = RectilinearBinMapper(boundaries)

bounds = [-float('inf'), 0.0, 1.0, 2.0, 3.0, float('inf')]
self.bin_mapper = RectilinearBinMapper([bounds])

boundaries = [(-1,-0.5,0,0.5,1), (-1,-0.5,0,0.5,1)]
self.bin_mapper = RectilinearBinMapper(boundaries)

self.bin_mapper = VoronoiBinMapper(dfunc, centers, dfargs=None, dfkwargs=None)

self.bin_mapper = FuncBinMapper(func, nbins, args=None, kwargs=None)

def func(coords, mask, output, *args, **kwargs)
    ....

def func(coords, mask, output, s):
    output[coords[:,0] + coords[:,1] < s*0.5] = 0
    output[coords[:,0] + coords[:,1] >= s*0.5] = 1

....

self.bin_mapper = FuncBinMapper(func, 2, args=(1.5,))

self.bin_mapper = VectorizingFuncBinMapper(func, nbins, args=None, kwargs=None)

def func(coords, *args, **kwargs)
    ....

def func(coords, s):
    if coords[0] + coords[1] < s*0.5:
        return 0
    else:
        return 1
....

self.bin_mapper = VectorizingFuncBinMapper(func, 2, args=(1.5,))

self.bin_mapper = RecursiveBinMapper(base_mapper, start_index=0)

'''
             0                            1                      2
             +----------------------------+----------------------+
             |            0.5             |                      |
             | +-----------+------------+ |                      |
             | |           |            | |                      |
             | |     1     |     2      | |          0           |
             | |           |            | |                      |
             | |           |            | |                      |
             | +-----------+------------+ |                      |prettyprint
             +---------------------------------------------------+
'''

def fn1(coords, mask, output):
    test = coords[:,0] < 1
    output[mask & test] = 0
    output[mask & ~test] = 1

def fn2(coords, mask, output):
    test = coords[:,0] < 0.5
    output[mask & test] = 0
    output[mask & ~test] = 1

outer_mapper = FuncBinMapper(fn1,2)
inner_mapper = FuncBinMapper(fn2,2)
rmapper = RecursiveBinMapper(outer_mapper)
rmapper.add_mapper(inner_mapper, [0.5])

Initial/Basis States¶

A WESTPA simulation is initialized using w_init with an initial distribution of replicas generated from a set of basis states. These basis states are used to generate initial states for new trajectories, either at the beginning of the simulation or due to recycling. Basis states are specified when running w_init either in a file specified with --bstates-from, or by one or more --bstate arguments. If neither --bstates-from nor at least one --bstate argument is provided, then a default basis state of probability one identified by the state ID zero and label “basis” will be created (a warning will be printed in this case, to remind you of this behavior, in case it is not what you wanted).

When using a file passed to w_init using --bstates-from, each line in that file defines a state, and contains a label, the probability, and optionally a data reference, separated by whitespace, as in::

unbound    1.0

or:

unbound_0    0.6        state0.pdb
unbound_1    0.4        state1.pdb

Basis states can also be supplied at the command line using one or more --bstate flags, where the argument matches the format used in the state file above. The total probability summed over all basis states should equal unity, however WESTPA will renormalize the distribution if this condition is not met.

Initial states are the generated from the basis states by optionally applying some perturbation or modification to the basis state. For example if WESTPA was being used to simulate ligand binding, one might want to have a basis state where the ligand was some set distance from the binding partner, and initial states are generated by randomly orienting the ligand at that distance. When using the executable propagator, this is done using the script specified under the gen_istate section of the executable configuration. Otherwise, if defining a custom propagator, the user must override the gen_istate method of WESTPropagator.

When using the executable propagator, the the script specified by gen_istate should take the data supplied by the environmental variable $WEST_BSTATE_DATA_REF and return the generated initial state to $WEST_ISTATE_DATA_REF. If no transform need be performed, the user may simply copy the data directly without modification. This data will then be available via $WEST_PARENT_DATA_REF if $WEST_CURRENT_SEG_INITPOINT_TYPE is SEG_INITPOINT_NEWTRAJ.

Target States¶

WESTPA can be run in a recycling mode in which replicas reaching a target state are removed from the simulation and their weights are assigned to new replicas created from one of the initial states. This mode creates a non-equilibrium steady-state that isolates members of the trajectory ensemble originating in the set of initial states and transitioning to the target states. The flux of probability into the target state is then inversely proportional to the mean first passage time (MFPT) of the transition.

Target states are defined when initializing a WESTPA simulation when calling w_init. Target states are specified either in a file specified with --tstates-from, or by one or more --tstate arguments. If neither --tstates-from nor at least one --tstate argument is provided, then an equilibrium simulation (without any sinks) will be performed.

Target states can be defined using a text file, where each line defines a state, and contains a label followed by a representative progress coordinate value, separated by whitespace, as in::

bound     0.02

for a single target and one-dimensional progress coordinates or::

bound    2.7    0.0
drift    100    50.0

for two targets and a two-dimensional progress coordinate.

The argument associated with --tstate is a string of the form 'label, pcoord0 [,pcoord1[,...]]', similar to a line in the example target state definition file above. This argument may be specified more than once, in which case the given states are appended to the list of target states for the simulation in the order they appear on the command line, after those that are specified by --tstates-from, if any.

WESTPA uses the representative progress coordinate of a target-state and converts the entire bin containing that progress coordinate into a recycling sink.

Propagators¶

Configuration File¶

The configuration of a WESTPA simulation is specified using a plain text file written in YAML. This file specifies, among many other things, the length of the simulation, which modules should be loaded for specifying the system, how external data should be organized on the file system, and which plugins should used. YAML is a hierarchical format and WESTPA organizes the configuration settings into blocks for each component. While below, the configuration file will be referred to as west.cfg, the user is free to name the configuration file something else. Most of the scripts and tools that WESTPA provides, however, require that the name of the configuration file be specified if the default name is not used.

The top most heading in west.cfg should be specified as::

---
west:
    ...

with all sub-section specified below it. A complete example can be found for the NaCl example: https://github.com/westpa/westpa/blob/master/lib/examples/nacl_gmx/west.cfg

In the following section, the specifications for each section of the file can be found, along with default parameters and descriptions. Required parameters are indicated as REQUIRED.:

---
west:
    ...
    system:
        driver: REQUIRED
        module_path: []

The driver parameter must be set to a subclass of WESTSystem, and given in the form module.class. The module_path parameter is appended to the system path and indicates where the class is defined.:

---
west:
    ...
    we:
        adjust_counts: True
        weight_split_threshold: 2.0
        weight_merge_cutoff: 1.0

The we section section specifies parameters related to the Huber and Kim resampling algorithm. WESTPA implements a variation of the method, in which setting adust_counts to True strictly enforces that the number of replicas per bin is exactly system.bin_target_counts. Otherwise, the number of replicas per is allowed to fluctuate as in the original implementation of the algorithm. Adjusting the counts can improve load balancing for parallel simulations. Replicas with weights greater than weight_split_threshold times the ideal weight per bin are tagged as candidates for splitting. Replicas with weights less than weight_merge_cutoff times the ideal weight per bin are candidates for merging.:

---
west:
    ...
    propagation:
        gen_istates: False
        block_size: 1
        save_transition_matrices: False
        max_run_wallclock: None
        max_total_iterations: None

• gen_istates: Boolean specifying whether to generate initial states from the basis states. The executable propagator defines a specific configuration block (add internal link to other section), and custom propagators should override the WESTPropagator.gen_istate() method.

• block_size: An integer defining how many segments should be passed to a worker at a time. When using the serial work manager, this value should be set to the maximum number of segments per iteration to avoid significant overhead incurred by the locking mechanism in the WMFutures framework. Parallel work managers might benefit from setting this value greater than one in some instances to decrease network communication load.

• save_transition_matrices:

• max_run_wallclock: A time in dd:hh:mm:ss or hh:mm:ss specifying the maximum wallclock time of a particular WESTPA run. If running on a batch queuing system, this time should be set to less than the job allocation time to ensure that WESTPA shuts down cleanly.

• max_total_iterations: An integer value specifying the number of iterations to run. This parameter is checked against the last completed iteration stored in the HDF5 file, not the number of iterations completed for a specific run. The default value of None only stops upon external termination of the code.:

  ---
  west:
      ...
      data:
          west_data_file: REQUIRED
          aux_compression_threshold: 1048576
          iter_prec: 8
          datasets:
              -name: REQUIRED
               h5path:
               store: True
               load: False
               dtype:
               scaleoffset: None
               compression: None
               chunks: None
          data_refs:
              segment:
              basis_state:
              initial_state:
  

• west_data_file: The name of the main HDF5 data storage file for the WESTPA simulation.

• aux_compression_threshold: The threshold in bytes for compressing the auxiliary data in a dataset on an iteration-by-iteration basis.

• iter_prec: The length of the iteration index with zero-padding. For the default value, iteration 1 would be specified as iter_00000001.

• datasets:

• data_refs:

• plugins

• executable

Environmental Variables¶

There are a number of environmental variables that can be set by the user in order to configure a WESTPA simulation:

• WEST_ROOT: path to the base directory containing the WESTPA install
• WEST_SIM_ROOT: path to the base directory of the WESTPA simulation
• WEST_PYTHON: path to python executable to run the WESTPA simulation
• WEST_PYTHONPATH: path to any additional modules that WESTPA will require to run the simulation
• WEST_KERNPROF: path to kernprof.py script to perform line-by-line profiling of a WESTPA simulation (see python line_profiler). This is only required for users who need to profile specific methods in a running WESTPA simulation.

Work manager related environmental variables:

• WM_WORK_MANAGER
• WM_N_WORKERS

WESTPA makes available to any script executed by it (e.g. runseg.sh), a number of environmental variables that are set dynamically by the executable propagator from the running simulation.

data:
    ...
    datasets: # dataset storage options
      - name: energy

Plugins¶

WESTPA has a extensible plugin architecture that allows the user to manipulate the simulation at specified points during an iteration.

• Activating plugins in the config file
• Plugin execution order/priority

Weighted Ensemble Algorithm (Resampling)¶