Binning¶

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:

• RecursiveBinMapper, for nesting one set of bins within another.

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 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.binning.assign.BinMapper¶

hashfunc()¶

Returns a sha256 hash object; optionally initialized with a string

construct_bins(type_=<class 'westpa.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.binning.assign.NopMapper¶

Put everything into one bin.

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

class westpa.binning.assign.RectilinearBinMapper(boundaries)¶

Bin into a rectangular grid based on tuples of float values

boundaries¶

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

class westpa.binning.assign.PiecewiseBinMapper(functions)¶

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.binning.assign.FuncBinMapper(func, nbins, args=None, kwargs=None)¶

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

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

class westpa.binning.assign.VectorizingFuncBinMapper(func, nbins, args=None, kwargs=None)¶

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

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

class westpa.binning.assign.VoronoiBinMapper(dfunc, centers, dfargs=None, dfkwargs=None)¶

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.binning.bins.Bin(iterable=None, label=None)¶

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

YAMLCFG¶

YAML-based configuration files for WESTPA

exception westpa.yamlcfg.ConfigValueWarning¶

westpa.yamlcfg.warn_dubious_config_entry(entry, value, expected_type=None, category=<class 'westpa.yamlcfg.ConfigValueWarning'>, stacklevel=1)¶

westpa.yamlcfg.check_bool(value, action='warn')¶

Check that the given value is boolean in type. If not, either raise a warning (if action=='warn') or an exception (action=='raise').

exception westpa.yamlcfg.ConfigItemMissing(key, message=None)¶

exception westpa.yamlcfg.ConfigItemTypeError(key, expected_type, message=None)¶

exception westpa.yamlcfg.ConfigValueError(key, value, message=None)¶

class westpa.yamlcfg.YAMLConfig¶

preload_config_files = ['/etc/westpa/westrc', '/home/boltzmann/.westrc']¶

update_from_file(file, required=True)¶

require(key, type_=None)¶

Ensure that a configuration item with the given key is present. If the optional type_ is given, additionally require that the item has that type.

require_type_if_present(key, type_)¶

Ensure that the configuration item with the given key has the given type.

coerce_type_if_present(key, type_)¶

get(key, default=None)¶

get_typed(key, type_, default=<object object>)¶

get_path(key, default=<object object>, expandvars=True, expanduser=True, realpath=True, abspath=True)¶

get_pathlist(key, default=<object object>, sep=':', expandvars=True, expanduser=True, realpath=True, abspath=True)¶

get_python_object(key, default=<object object>, path=None)¶

get_choice(key, choices, default=<object object>, value_transform=None)¶

class westpa.yamlcfg.YAMLSystem(rc=None)¶

A description of the system being simulated, including the dimensionality and data type of the progress coordinate, the number of progress coordinate entries expected from each segment, and binning. To construct a simulation, the user must subclass WESTSystem and set several instance variables.

At a minimum, the user must subclass WESTSystem and override :method:`initialize` to set the data type and dimensionality of progress coordinate data and define a bin mapper.

Variables:

pcoord_ndim – The number of dimensions in the progress coordinate. Defaults to 1 (i.e. a one-dimensional progress coordinate). pcoord_dtype – The data type of the progress coordinate, which must be callable (e.g. numpy.float32 and long will work, but '<f4' and '<i8' will not). Defaults to numpy.float64. pcoord_len – The length of the progress coordinate time series generated by each segment, including both the initial and final values. Defaults to 2 (i.e. only the initial and final progress coordinate values for a segment are returned from propagation). bin_mapper – A bin mapper describing the progress coordinate space. bin_target_counts – A vector of target counts, one per bin.

bin_target_counts¶

initialize()¶

Prepare this system object for use in simulation or analysis, creating a bin space, setting replicas per bin, and so on. This function is called whenever a WEST tool creates an instance of the system driver.

prepare_run()¶

Prepare this system for use in a simulation run. Called by w_run in all worker processes.

finalize_run()¶

A hook for system-specific processing for the end of a simulation run (as defined by such things as maximum wallclock time, rather than perhaps more scientifically-significant definitions of “the end of a simulation run”)

new_pcoord_array(pcoord_len=None)¶

Return an appropriately-sized and -typed pcoord array for a timepoint, segment, or number of segments. If pcoord_len is not specified (or None), then a length appropriate for a segment is returned.

new_region_set()¶

RC¶

class westpa._rc.WESTRC¶

A class, an instance of which is accessible as westpa.rc, to handle global issues for WEST-PA code, such as loading modules and plugins, writing output based on verbosity level, adding default command line options, and so on.

ENV_RUNTIME_CONFIG = 'WESTRC'¶

RC_DEFAULT_FILENAME = 'west.cfg'¶

add_args(parser)¶

config_logging()¶

data_manager¶

debug_mode¶

get_data_manager()¶

get_propagator()¶

get_sim_manager()¶

get_system_driver()¶

get_we_driver()¶

get_work_manager()¶

new_data_manager()¶

new_propagator()¶

new_sim_manager()¶

new_system_driver()¶

Returns a new system object either from the driver OR from the YAML file. Currently builds off of system then updates with YAML overwriting the previous settings if both are specified.

There are no default settings, all settings MUST be specified in the config YAML file OR the system driver.

Settings that are specified here are:

Progress coordinate settings:

Progress coordinate dimensionality Progress coordinate length/number of data points in each tau Progress coordinate data type

Bin settings:

Bin mapper type Bins Target simulation counts for each bin

Generic setting for flexibility:

Both paths allow for generic attribute setting for future flexibility.

new_we_driver()¶

overwrite_option(system, key, value)¶

pflush()¶

process_args(args, config_required=True)¶

process_config()¶

propagator¶

pstatus(*args, **kwargs)¶

pstatus_term(*args, **kwargs)¶

quiet_mode¶

read_config(filename=None)¶

sim_manager¶

system¶

system_from_yaml(system_dict)¶

System builder directly from the config YAML file.

Parameters:	system_dict (dict) – Parsed YAML file as a dictionary, parsed by PyYAML by default.
Returns:	A modified WESTSystem object as defined in yamlcfg.py with the parsed settings from the config file.

update_from_yaml(init_system, system_dict)¶

Updates the system built from the driver with the options from the YAML file. For now it overwrites everything specified in the system driver.

Parameters:	system_dict (dict) – Parsed YAML file as a dictionary, parsed by PyYAML by default. init_system (WESTSystem) – System returned by the driver.
Returns:	A modified WESTSystem object with settings from the system driver and the config YAML file.

verbose_mode¶

we_driver¶