westpa.core.binning package

westpa.core.binning module

class westpa.core.binning.NopMapper

Bases: BinMapper

Put everything into one bin.

assign(coords, mask=None, output=None)
class westpa.core.binning.FuncBinMapper(func, nbins, args=None, kwargs=None)

Bases: BinMapper

Binning using a custom function which must iterate over input coordinate sets itself.

assign(coords, mask=None, output=None)
class westpa.core.binning.PiecewiseBinMapper(functions)

Bases: BinMapper

Binning using a set of functions returing boolean values; if the Nth function returns True for a coordinate tuple, then that coordinate is in the Nth bin.

assign(coords, mask=None, output=None)
class westpa.core.binning.RectilinearBinMapper(boundaries)

Bases: BinMapper

Bin into a rectangular grid based on tuples of float values

property boundaries
assign(coords, mask=None, output=None)
class westpa.core.binning.RecursiveBinMapper(base_mapper, start_index=0)

Bases: BinMapper

Nest mappers one within another.

property labels
property start_index
add_mapper(mapper, replaces_bin_at)

Replace the bin containing the coordinate tuple replaces_bin_at with the specified mapper.

assign(coords, mask=None, output=None)
class westpa.core.binning.VectorizingFuncBinMapper(func, nbins, args=None, kwargs=None)

Bases: BinMapper

Binning using a custom function which is evaluated once for each (unmasked) coordinate tuple provided.

assign(coords, mask=None, output=None)
class westpa.core.binning.VoronoiBinMapper(dfunc, centers, dfargs=None, dfkwargs=None)

Bases: BinMapper

A one-dimensional mapper which assigns a multidimensional pcoord to the closest center based on a distance metric. Both the list of centers and the distance function must be supplied.

assign(coords, mask=None, output=None)
westpa.core.binning.map_mab(coords, mask, output, *args, **kwargs)

Binning which adaptively places bins based on the positions of extrema segments and bottleneck segments, which are where the difference in probability is the greatest along the progress coordinate. Operates per dimension and places a fixed number of evenly spaced bins between the segments with the min and max pcoord values. Extrema and bottleneck segments are assigned their own bins.

westpa.core.binning.map_binless(coords, mask, output, *args, **kwargs)

Adaptively groups walkers according to a user-defined grouping function that is defined externally. Very general implementation but limited to only a two dimensional progress coordinate (for now).

class westpa.core.binning.MABBinMapper(nbins, direction=None, skip=None, bottleneck=True, pca=False, mab_log=False, bin_log=False)

Bases: FuncBinMapper

Adaptively place bins in between minimum and maximum segments along the progress coordinte. Extrema and bottleneck segments are assigned to their own bins.

class westpa.core.binning.BinlessMapper(ngroups, ndims, group_function, **group_function_kwargs)

Bases: FuncBinMapper

Adaptively group walkers according to a user-defined grouping function that is defined externally.

class westpa.core.binning.MABDriver(rc=None, system=None)

Bases: WEDriver

assign(segments, initializing=False)

Assign segments to initial and final bins, and update the (internal) lists of used and available initial states. This function is adapted to the MAB scheme, so that the inital and final segments are sent to the bin mapper at the same time, otherwise the inital and final bin boundaries can be inconsistent.

class westpa.core.binning.MABSimManager(rc=None)

Bases: WESimManager

initialize_simulation(basis_states, target_states, start_states, segs_per_state=1, suppress_we=False)

Initialize a new weighted ensemble simulation, taking segs_per_state initial states from each of the given basis_states.

w_init is the forward-facing version of this function

propagate()
prepare_iteration()
class westpa.core.binning.BinlessDriver(rc=None, system=None)

Bases: WEDriver

assign(segments, initializing=False)

Assign segments to initial and final bins, and update the (internal) lists of used and available initial states. This function is adapted to the MAB scheme, so that the inital and final segments are sent to the bin mapper at the same time, otherwise the inital and final bin boundaries can be inconsistent.

class westpa.core.binning.BinlessSimManager(rc=None)

Bases: WESimManager

initialize_simulation(basis_states, target_states, start_states, segs_per_state=1, suppress_we=False)

Initialize a new weighted ensemble simulation, taking segs_per_state initial states from each of the given basis_states.

w_init is the forward-facing version of this function

propagate()
prepare_iteration()
westpa.core.binning.accumulate_labeled_populations(weights, bin_assignments, label_assignments, labeled_bin_pops)

For a set of segments in one iteration, calculate the average population in each bin, with separation by last-visited macrostate.

westpa.core.binning.assign_and_label(nsegs_lb, nsegs_ub, parent_ids, assign, nstates, state_map, last_labels, pcoords, subsample)

Assign trajectories to bins and last-visted macrostates for each timepoint.

westpa.core.binning.accumulate_state_populations_from_labeled(labeled_bin_pops, state_map, state_pops, check_state_map=True)
westpa.core.binning.assignments_list_to_table(nsegs, nbins, assignments)

Convert a list of bin assignments (integers) to a boolean table indicating indicating if a given segment is in a given bin

westpa.core.binning.coord_dtype

alias of float32

westpa.core.binning.index_dtype

alias of uint16

class westpa.core.binning.Bin(iterable=None, label=None)

Bases: set

property weight

Total weight of all walkers in this bin

reweight(new_weight)

Reweight all walkers in this bin so that the total weight is new_weight

westpa.core.binning.assign module

Bin assignment for WEST simulations. This module defines “bin mappers” which take vectors of coordinates (or rather, coordinate tuples), and assign each a definite integer value identifying a bin. Critical portions are implemented in a Cython extension module.

A number of pre-defined bin mappers are available here:

  • RectilinearBinMapper, for bins divided by N-dimensional grids

  • FuncBinMapper, for functions which directly calculate bin assignments for a number of coordinate values. This is best used with C/Cython/Numba functions, or intellegently-tuned numpy-based Python functions.

  • VectorizingFuncBinMapper, for functions which calculate a bin assignment for a single coordinate value. This is best used for arbitrary Python functions.

  • PiecewiseBinMapper, for using a set of boolean-valued functions, one per bin, to determine assignments. This is likely to be much slower than a FuncBinMapper or VectorizingFuncBinMapper equipped with an appropriate function, and its use is discouraged.

One “super-mapper” is available, for assembling more complex bin spaces from simpler components:

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 (np.uint16) indicating a 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.

class westpa.core.binning.assign.Bin(iterable=None, label=None)

Bases: set

property weight

Total weight of all walkers in this bin

reweight(new_weight)

Reweight all walkers in this bin so that the total weight is new_weight

westpa.core.binning.assign.output_map(output, omap, mask)

For each output for which mask is true, execute output[i] = omap[output[i]]

westpa.core.binning.assign.apply_down(func, args, kwargs, coords, mask, output)

Apply func(coord, *args, **kwargs) to each input coordinate tuple, skipping any for which mask is false and writing results to output.

westpa.core.binning.assign.apply_down_argmin_across(func, args, kwargs, func_output_len, coords, mask, output)

Apply func(coord, *args, **kwargs) to each input coordinate tuple, skipping any for which mask is false and writing results to output.

westpa.core.binning.assign.rectilinear_assign(coords, mask, output, boundaries, boundlens)

For bins delimited by sets boundaries on a rectilinear grid (boundaries), assign coordinates to bins, assuming C ordering of indices within the grid. boundlens is the number of boundaries in each dimension.

westpa.core.binning.assign.index_dtype

alias of uint16

westpa.core.binning.assign.coord_dtype

alias of float32

class westpa.core.binning.assign.BinMapper

Bases: object

hashfunc(*, usedforsecurity=True)

Returns a sha256 hash object; optionally initialized with a string

construct_bins(type_=<class 'westpa.core.binning.bins.Bin'>)

Construct and return an array of bins of type type

pickle_and_hash()

Pickle this mapper and calculate a hash of the result (thus identifying the contents of the pickled data), returning a tuple (pickled_data, hash). This will raise PickleError if this mapper cannot be pickled, in which case code that would otherwise rely on detecting a topology change must assume a topology change happened, even if one did not.

class westpa.core.binning.assign.NopMapper

Bases: BinMapper

Put everything into one bin.

assign(coords, mask=None, output=None)
class westpa.core.binning.assign.RectilinearBinMapper(boundaries)

Bases: BinMapper

Bin into a rectangular grid based on tuples of float values

property boundaries
assign(coords, mask=None, output=None)
class westpa.core.binning.assign.PiecewiseBinMapper(functions)

Bases: BinMapper

Binning using a set of functions returing boolean values; if the Nth function returns True for a coordinate tuple, then that coordinate is in the Nth bin.

assign(coords, mask=None, output=None)
class westpa.core.binning.assign.FuncBinMapper(func, nbins, args=None, kwargs=None)

Bases: BinMapper

Binning using a custom function which must iterate over input coordinate sets itself.

assign(coords, mask=None, output=None)
class westpa.core.binning.assign.VectorizingFuncBinMapper(func, nbins, args=None, kwargs=None)

Bases: BinMapper

Binning using a custom function which is evaluated once for each (unmasked) coordinate tuple provided.

assign(coords, mask=None, output=None)
class westpa.core.binning.assign.VoronoiBinMapper(dfunc, centers, dfargs=None, dfkwargs=None)

Bases: BinMapper

A one-dimensional mapper which assigns a multidimensional pcoord to the closest center based on a distance metric. Both the list of centers and the distance function must be supplied.

assign(coords, mask=None, output=None)
class westpa.core.binning.assign.RecursiveBinMapper(base_mapper, start_index=0)

Bases: BinMapper

Nest mappers one within another.

property labels
property start_index
add_mapper(mapper, replaces_bin_at)

Replace the bin containing the coordinate tuple replaces_bin_at with the specified mapper.

assign(coords, mask=None, output=None)

westpa.core.binning.bins module

class westpa.core.binning.bins.Bin(iterable=None, label=None)

Bases: set

property weight

Total weight of all walkers in this bin

reweight(new_weight)

Reweight all walkers in this bin so that the total weight is new_weight

Minimal Adaptive Binning (MAB) Scheme

westpa.core.binning.mab module

class westpa.core.binning.mab.FuncBinMapper(func, nbins, args=None, kwargs=None)

Bases: BinMapper

Binning using a custom function which must iterate over input coordinate sets itself.

assign(coords, mask=None, output=None)
westpa.core.binning.mab.expandvars(path)

Expand shell variables of form $var and ${var}. Unknown variables are left unchanged.

westpa.core.binning.mab.map_mab(coords, mask, output, *args, **kwargs)

Binning which adaptively places bins based on the positions of extrema segments and bottleneck segments, which are where the difference in probability is the greatest along the progress coordinate. Operates per dimension and places a fixed number of evenly spaced bins between the segments with the min and max pcoord values. Extrema and bottleneck segments are assigned their own bins.

class westpa.core.binning.mab.MABBinMapper(nbins, direction=None, skip=None, bottleneck=True, pca=False, mab_log=False, bin_log=False)

Bases: FuncBinMapper

Adaptively place bins in between minimum and maximum segments along the progress coordinte. Extrema and bottleneck segments are assigned to their own bins.

westpa.core.binning.mab_driver

class westpa.core.binning.mab_driver.WEDriver(rc=None, system=None)

Bases: object

A class implemented Huber & Kim’s weighted ensemble algorithm over Segment objects. This class handles all binning, recycling, and preparation of new Segment objects for the next iteration. Binning is accomplished using system.bin_mapper, and per-bin target counts are from system.bin_target_counts.

The workflow is as follows:

  1. Call new_iteration() every new iteration, providing any recycling targets that are in force and any available initial states for recycling.

  2. Call assign() to assign segments to bins based on their initial and end points. This returns the number of walkers that were recycled.

  3. Call run_we(), optionally providing a set of initial states that will be used to recycle walkers.

Note the presence of flux_matrix, transition_matrix, current_iter_segments, next_iter_segments, recycling_segments, initial_binning, final_binning, next_iter_binning, and new_weights (to be documented soon).

weight_split_threshold = 2.0
weight_merge_cutoff = 1.0
largest_allowed_weight = 1.0
smallest_allowed_weight = 1e-310
process_config()
property next_iter_segments

Newly-created segments for the next iteration

property current_iter_segments

Segments for the current iteration

property next_iter_assignments

Bin assignments (indices) for initial points of next iteration.

property current_iter_assignments

Bin assignments (indices) for endpoints of current iteration.

property recycling_segments

Segments designated for recycling

property n_recycled_segs

Number of segments recycled this iteration

property n_istates_needed

Number of initial states needed to support recycling for this iteration

check_threshold_configs()

Check to see if weight thresholds parameters are valid

clear()

Explicitly delete all Segment-related state.

new_iteration(initial_states=None, target_states=None, new_weights=None, bin_mapper=None, bin_target_counts=None)

Prepare for a new iteration. initial_states is a sequence of all InitialState objects valid for use in to generating new segments for the next iteration (after the one being begun with the call to new_iteration); that is, these are states available to recycle to. Target states which generate recycling events are specified in target_states, a sequence of TargetState objects. Both initial_states and target_states may be empty as required.

The optional new_weights is a sequence of NewWeightEntry objects which will be used to construct the initial flux matrix.

The given bin_mapper will be used for assignment, and bin_target_counts used for splitting/merging target counts; each will be obtained from the system object if omitted or None.

add_initial_states(initial_states)

Add newly-prepared initial states to the pool available for recycling.

property all_initial_states

Return an iterator over all initial states (available or used)

assign(segments, initializing=False)

Assign segments to initial and final bins, and update the (internal) lists of used and available initial states. If initializing is True, then the “final” bin assignments will be identical to the initial bin assignments, a condition required for seeding a new iteration from pre-existing segments.

populate_initial(initial_states, weights, system=None)

Create walkers for a new weighted ensemble simulation.

One segment is created for each provided initial state, then binned and split/merged as necessary. After this function is called, next_iter_segments will yield the new segments to create, used_initial_states will contain data about which of the provided initial states were used, and avail_initial_states will contain data about which initial states were unused (because their corresponding walkers were merged out of existence).

rebin_current(parent_segments)

Reconstruct walkers for the current iteration based on (presumably) new binning. The previous iteration’s segments must be provided (as parent_segments) in order to update endpoint types appropriately.

construct_next()

Construct walkers for the next iteration, by running weighted ensemble recycling and bin/split/merge on the segments previously assigned to bins using assign. Enough unused initial states must be present in self.avail_initial_states for every recycled walker to be assigned an initial state.

After this function completes, self.flux_matrix contains a valid flux matrix for this iteration (including any contributions from recycling from the previous iteration), and self.next_iter_segments contains a list of segments ready for the next iteration, with appropriate values set for weight, endpoint type, parent walkers, and so on.

class westpa.core.binning.mab_driver.MABDriver(rc=None, system=None)

Bases: WEDriver

assign(segments, initializing=False)

Assign segments to initial and final bins, and update the (internal) lists of used and available initial states. This function is adapted to the MAB scheme, so that the inital and final segments are sent to the bin mapper at the same time, otherwise the inital and final bin boundaries can be inconsistent.

westpa.core.binning.mab_manager

class westpa.core.binning.mab_manager.MABBinMapper(nbins, direction=None, skip=None, bottleneck=True, pca=False, mab_log=False, bin_log=False)

Bases: FuncBinMapper

Adaptively place bins in between minimum and maximum segments along the progress coordinte. Extrema and bottleneck segments are assigned to their own bins.

class westpa.core.binning.mab_manager.WESimManager(rc=None)

Bases: object

process_config()
register_callback(hook, function, priority=0)

Registers a callback to execute during the given hook into the simulation loop. The optional priority is used to order when the function is called relative to other registered callbacks.

invoke_callbacks(hook, *args, **kwargs)
load_plugins(plugins=None)
report_bin_statistics(bins, target_states, save_summary=False)
get_bstate_pcoords(basis_states, label='basis')

For each of the given basis_states, calculate progress coordinate values as necessary. The HDF5 file is not updated.

report_basis_states(basis_states, label='basis')
report_target_states(target_states)
initialize_simulation(basis_states, target_states, start_states, segs_per_state=1, suppress_we=False)

Initialize a new weighted ensemble simulation, taking segs_per_state initial states from each of the given basis_states.

w_init is the forward-facing version of this function

prepare_iteration()
finalize_iteration()

Clean up after an iteration and prepare for the next.

get_istate_futures()

Add n_states initial states to the internal list of initial states assigned to recycled particles. Spare states are used if available, otherwise new states are created. If created new initial states requires generation, then a set of futures is returned representing work manager tasks corresponding to the necessary generation work.

propagate()
save_bin_data()

Calculate and write flux and transition count matrices to HDF5. Population and rate matrices are likely useless at the single-tau level and are no longer written.

check_propagation()

Check for failures in propagation or initial state generation, and raise an exception if any are found.

run_we()

Run the weighted ensemble algorithm based on the binning in self.final_bins and the recycled particles in self.to_recycle, creating and committing the next iteration’s segments to storage as well.

prepare_new_iteration()

Commit data for the coming iteration to the HDF5 file.

run()
prepare_run()

Prepare a new run.

finalize_run()

Perform cleanup at the normal end of a run

pre_propagation()
post_propagation()
pre_we()
post_we()
westpa.core.binning.mab_manager.grouper(n, iterable, fillvalue=None)

Collect data into fixed-length chunks or blocks

class westpa.core.binning.mab_manager.InitialState(state_id, basis_state_id, iter_created, iter_used=None, istate_type=None, istate_status=None, pcoord=None, basis_state=None, basis_auxref=None)

Bases: object

Describes an initial state for a new trajectory. These are generally constructed by appropriate modification of a basis state.

Variables:
  • state_id – Integer identifier of this state, usually set by the data manager.

  • basis_state_id – Identifier of the basis state from which this state was generated, or None.

  • basis_state – The BasisState from which this state was generated, or None.

  • iter_created – Iteration in which this state was generated (0 for simulation initialization).

  • iter_used – Iteration in which this state was used to initiate a trajectory (None for unused).

  • istate_type – Integer describing the type of this initial state (ISTATE_TYPE_BASIS for direct use of a basis state, ISTATE_TYPE_GENERATED for a state generated from a basis state, ISTATE_TYPE_RESTART for a state corresponding to the endpoint of a segment in another simulation, or ISTATE_TYPE_START for a state generated from a start state).

  • istate_status – Integer describing whether this initial state has been properly prepared.

  • pcoord – The representative progress coordinate of this state.

ISTATE_TYPE_UNSET = 0
ISTATE_TYPE_BASIS = 1
ISTATE_TYPE_GENERATED = 2
ISTATE_TYPE_RESTART = 3
ISTATE_TYPE_START = 4
ISTATE_UNUSED = 0
ISTATE_STATUS_PENDING = 0
ISTATE_STATUS_PREPARED = 1
ISTATE_STATUS_FAILED = 2
istate_types = {'ISTATE_TYPE_BASIS': 1, 'ISTATE_TYPE_GENERATED': 2, 'ISTATE_TYPE_RESTART': 3, 'ISTATE_TYPE_START': 4, 'ISTATE_TYPE_UNSET': 0}
istate_type_names = {0: 'ISTATE_TYPE_UNSET', 1: 'ISTATE_TYPE_BASIS', 2: 'ISTATE_TYPE_GENERATED', 3: 'ISTATE_TYPE_RESTART', 4: 'ISTATE_TYPE_START'}
istate_statuses = {'ISTATE_STATUS_FAILED': 2, 'ISTATE_STATUS_PENDING': 0, 'ISTATE_STATUS_PREPARED': 1}
istate_status_names = {0: 'ISTATE_STATUS_PENDING', 1: 'ISTATE_STATUS_PREPARED', 2: 'ISTATE_STATUS_FAILED'}
as_numpy_record()
westpa.core.binning.mab_manager.pare_basis_initial_states(basis_states, initial_states, segments=None)

Given iterables of basis and initial states (and optionally segments that use them), return minimal sets (as in __builtins__.set) of states needed to describe the history of the given segments an initial states.

class westpa.core.binning.mab_manager.Segment(n_iter=None, seg_id=None, weight=None, endpoint_type=None, parent_id=None, wtg_parent_ids=None, pcoord=None, status=None, walltime=None, cputime=None, data=None)

Bases: object

A class wrapping segment data that must be passed through the work manager or data manager. Most fields are self-explanatory. One item worth noting is that a negative parent ID means that the segment starts from the initial state with ID -(segment.parent_id+1)

SEG_STATUS_UNSET = 0
SEG_STATUS_PREPARED = 1
SEG_STATUS_COMPLETE = 2
SEG_STATUS_FAILED = 3
SEG_INITPOINT_UNSET = 0
SEG_INITPOINT_CONTINUES = 1
SEG_INITPOINT_NEWTRAJ = 2
SEG_ENDPOINT_UNSET = 0
SEG_ENDPOINT_CONTINUES = 1
SEG_ENDPOINT_MERGED = 2
SEG_ENDPOINT_RECYCLED = 3
statuses = {'SEG_STATUS_COMPLETE': 2, 'SEG_STATUS_FAILED': 3, 'SEG_STATUS_PREPARED': 1, 'SEG_STATUS_UNSET': 0}
initpoint_types = {'SEG_INITPOINT_CONTINUES': 1, 'SEG_INITPOINT_NEWTRAJ': 2, 'SEG_INITPOINT_UNSET': 0}
endpoint_types = {'SEG_ENDPOINT_CONTINUES': 1, 'SEG_ENDPOINT_MERGED': 2, 'SEG_ENDPOINT_RECYCLED': 3, 'SEG_ENDPOINT_UNSET': 0}
status_names = {0: 'SEG_STATUS_UNSET', 1: 'SEG_STATUS_PREPARED', 2: 'SEG_STATUS_COMPLETE', 3: 'SEG_STATUS_FAILED'}
initpoint_type_names = {0: 'SEG_INITPOINT_UNSET', 1: 'SEG_INITPOINT_CONTINUES', 2: 'SEG_INITPOINT_NEWTRAJ'}
endpoint_type_names = {0: 'SEG_ENDPOINT_UNSET', 1: 'SEG_ENDPOINT_CONTINUES', 2: 'SEG_ENDPOINT_MERGED', 3: 'SEG_ENDPOINT_RECYCLED'}
static initial_pcoord(segment)

Return the initial progress coordinate point of this segment.

static final_pcoord(segment)

Return the final progress coordinate point of this segment.

property initpoint_type
property initial_state_id
property status_text
property endpoint_type_text
class westpa.core.binning.mab_manager.MABSimManager(rc=None)

Bases: WESimManager

initialize_simulation(basis_states, target_states, start_states, segs_per_state=1, suppress_we=False)

Initialize a new weighted ensemble simulation, taking segs_per_state initial states from each of the given basis_states.

w_init is the forward-facing version of this function

propagate()
prepare_iteration()