w_ipa

The w_ipa is a (beta) WESTPA tool that automates analysis using analysis schemes and enables interactive analysis of WESTPA simulation data. The tool can do a variety of different types of analysis, including the following: * Calculate fluxes and rate constants * Adjust and use alternate state definitions * Trace trajectory segments, including statistical weights, position along the progress coordinate, and other auxiliary data * Plot all of the above in the terminal!

If you are using w_ipa for kinetics automated kinetics analysis, keep in mind that w_ipa is running w_assign and w_direct using the scheme designated in your west.cfg file. For more diverse kinetics analysis options, consider using w_assign and w_direct manually. This can be useful if you’d like to use auxiliary coordinates that aren’t your progress coordinate, in one or two dimension options.

usage:

w_ipa [-h] [-r RCFILE] [--quiet] [--verbose] [--version] [--max-queue-length MAX_QUEUE_LENGTH]
            [-W WEST_H5FILE] [--analysis-only] [--reanalyze] [--ignore-hash] [--debug] [--terminal]
            [--serial | --parallel | --work-manager WORK_MANAGER] [--n-workers N_WORKERS]
            [--zmq-mode MODE] [--zmq-comm-mode COMM_MODE] [--zmq-write-host-info INFO_FILE]
            [--zmq-read-host-info INFO_FILE] [--zmq-upstream-rr-endpoint ENDPOINT]
            [--zmq-upstream-ann-endpoint ENDPOINT] [--zmq-downstream-rr-endpoint ENDPOINT]
            [--zmq-downstream-ann-endpoint ENDPOINT] [--zmq-master-heartbeat MASTER_HEARTBEAT]
            [--zmq-worker-heartbeat WORKER_HEARTBEAT] [--zmq-timeout-factor FACTOR]
            [--zmq-startup-timeout STARTUP_TIMEOUT] [--zmq-shutdown-timeout SHUTDOWN_TIMEOUT]

optional arguments:

-h, --help            show this help message and exit

general options:

-r RCFILE, --rcfile RCFILE: use RCFILE as the WEST run-time configuration file (default: west.cfg)
--quiet: emit only essential information
--verbose: emit extra information
--version: show program’s version number and exit

parallelization options:

--max-queue-length MAX_QUEUE_LENGTH
                      Maximum number of tasks that can be queued. Useful to limit RAM use for tasks that
                      have very large requests/response. Default: no limit.

WEST input data options:

-W WEST_H5FILE, --west-data WEST_H5FILE: Take WEST data from WEST_H5FILE (default: read from the HDF5 file specified in west.cfg).

runtime options:

--analysis-only, -ao  Use this flag to run the analysis and return to the terminal.
--reanalyze, -ra      Use this flag to delete the existing files and reanalyze.
--ignore-hash, -ih    Ignore hash and don't regenerate files.
--debug, -d           Debug output largely intended for development.
--terminal, -t        Plot output in terminal.

parallelization options:

--serial              run in serial mode
--parallel            run in parallel mode (using processes)
--work-manager WORK_MANAGER
                      use the given work manager for parallel task distribution. Available work managers
                      are ('serial', 'threads', 'processes', 'zmq'); default is 'processes'
--n-workers N_WORKERS
                      Use up to N_WORKERS on this host, for work managers which support this option. Use
                      0 for a dedicated server. (Ignored by work managers which do not support this
                      option.)

options for ZeroMQ (“zmq”) work manager (master or node):

--zmq-mode MODE       Operate as a master (server) or a node (workers/client). "server" is a deprecated
                      synonym for "master" and "client" is a deprecated synonym for "node".
--zmq-comm-mode COMM_MODE
                      Use the given communication mode -- TCP or IPC (Unix-domain) -- sockets for
                      communication within a node. IPC (the default) may be more efficient but is not
                      available on (exceptionally rare) systems without node-local storage (e.g. /tmp);
                      on such systems, TCP may be used instead.
--zmq-write-host-info INFO_FILE
                      Store hostname and port information needed to connect to this instance in
                      INFO_FILE. This allows the master and nodes assisting in coordinating the
                      communication of other nodes to choose ports randomly. Downstream nodes read this
                      file with --zmq-read-host-info and know where how to connect.
--zmq-read-host-info INFO_FILE
                      Read hostname and port information needed to connect to the master (or other
                      coordinating node) from INFO_FILE. This allows the master and nodes assisting in
                      coordinating the communication of other nodes to choose ports randomly, writing
                      that information with --zmq-write-host-info for this instance to read.
--zmq-upstream-rr-endpoint ENDPOINT
                      ZeroMQ endpoint to which to send request/response (task and result) traffic toward
                      the master.
--zmq-upstream-ann-endpoint ENDPOINT
                      ZeroMQ endpoint on which to receive announcement (heartbeat and shutdown
                      notification) traffic from the master.
--zmq-downstream-rr-endpoint ENDPOINT
                      ZeroMQ endpoint on which to listen for request/response (task and result) traffic
                      from subsidiary workers.
--zmq-downstream-ann-endpoint ENDPOINT
                      ZeroMQ endpoint on which to send announcement (heartbeat and shutdown
                      notification) traffic toward workers.
--zmq-master-heartbeat MASTER_HEARTBEAT
                      Every MASTER_HEARTBEAT seconds, the master announces its presence to workers.
--zmq-worker-heartbeat WORKER_HEARTBEAT
                      Every WORKER_HEARTBEAT seconds, workers announce their presence to the master.
--zmq-timeout-factor FACTOR
                      Scaling factor for heartbeat timeouts. If the master doesn't hear from a worker in
                      WORKER_HEARTBEAT*FACTOR, the worker is assumed to have crashed. If a worker
                      doesn't hear from the master in MASTER_HEARTBEAT*FACTOR seconds, the master is
                      assumed to have crashed. Both cases result in shutdown.
--zmq-startup-timeout STARTUP_TIMEOUT
                      Amount of time (in seconds) to wait for communication between the master and at
                      least one worker. This may need to be changed on very large, heavily-loaded
                      computer systems that start all processes simultaneously.
--zmq-shutdown-timeout SHUTDOWN_TIMEOUT
                      Amount of time (in seconds) to wait for workers to shut down.

westpa.cli.tools.w_ipa module

class westpa.cli.tools.w_ipa.WESTParallelTool(wm_env=None)

Bases: WESTTool

Base class for command-line tools parallelized with wwmgr. This automatically adds and processes wwmgr command-line arguments and creates a work manager at self.work_manager.

add_args(parser): Add arguments specific to this tool to the given argparse parser.

go(): Perform the analysis associated with this tool.

main(): A convenience function to make a parser, parse and process arguments, then run self.go() in the master process.

make_parser_and_process(prog=None, usage=None, description=None, epilog=None, args=None): A convenience function to create a parser, call add_all_args(), and then call process_all_args(). The argument namespace is returned.

process_args(args): Take argparse-processed arguments associated with this tool and deal with them appropriately (setting instance variables, etc)

class westpa.cli.tools.w_ipa.WESTDataReader

Bases: WESTToolComponent

Tool for reading data from WEST-related HDF5 files. Coordinates finding the main HDF5 file from west.cfg or command line arguments, caching of certain kinds of data (eventually), and retrieving auxiliary data sets from various places.

add_args(parser): Add arguments specific to this component to the given argparse parser.

close()

open(mode='r')

property parent_id_dsspec

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

property weight_dsspec

class westpa.cli.tools.w_ipa.ProgressIndicatorComponent

Bases: WESTToolComponent

add_args(parser): Add arguments specific to this component to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)

class westpa.cli.tools.w_ipa.Plotter(h5file, h5key, iteration=-1, interface='matplotlib')

Bases: object

This is a semi-generic plotting interface that has a built in curses based terminal plotter. It’s fairly specific to what we’re using it for here, but we could (and maybe should) build it out into a little library that we can use via the command line to plot things. Might be useful for looking at data later. That would also cut the size of this tool down by a good bit.

plot(i=0, j=1, tau=1, iteration=None, dim=0, interface=None)

class westpa.cli.tools.w_ipa.WIPIDataset(raw, key)

Bases: object

keys()

class westpa.cli.tools.w_ipa.WIPIScheme(scheme, name, parent, settings)

Bases: object

property assign

property bin_labels

property current: The current iteration. See help for __get_data_for_iteration__

property direct: The output from w_direct.py from the current scheme.

property iteration

property list_schemes

Lists what schemes are configured in west.cfg file. Schemes should be structured as follows, in west.cfg:

west:

system:

analysis:

directory: analysis analysis_schemes:

scheme.1:
enabled: True states:

label: unbound coords: [[7.0]]

label: bound coords: [[2.7]]

bins:

type: RectilinearBinMapper boundaries: [[0.0, 2.80, 7, 10000]]

property past: The previous iteration. See help for __get_data_for_iteration__

property reweight

property scheme

property state_labels

property west

class westpa.cli.tools.w_ipa.WIPI

Bases: WESTParallelTool

Welcome to w_ipa (WESTPA Interactive Python Analysis)! From here, you can run traces, look at weights, progress coordinates, etc. This is considered a ‘stateful’ tool; that is, the data you are pulling is always pulled from the current analysis scheme and iteration. By default, the first analysis scheme in west.cfg is used, and you are set at iteration 1.

ALL PROPERTIES ARE ACCESSED VIA w or west To see the current iteration, try:

w.iteration OR west.iteration

to set it, simply plug in a new value.

w.iteration = 100

To change/list the current analysis schemes:

w.list_schemes w.scheme = OUTPUT FROM w.list_schemes

To see the states and bins defined in the current analysis scheme:

w.states w.bin_labels

All information about the current iteration is available in an object called ‘current’:

w.current walkers, summary, states, seg_id, weights, parents, kinavg, pcoord, bins, populations, and auxdata, if it exists.

In addition, the function w.trace(seg_id) will run a trace over a seg_id in the current iteration and return a dictionary containing all pertinent information about that seg_id’s history. It’s best to store this, as the trace can be expensive.

Run help on any function or property for more information!

Happy analyzing!

add_args(parser): Add arguments specific to this tool to the given argparse parser.

process_args(args): Take argparse-processed arguments associated with this tool and deal with them appropriately (setting instance variables, etc)

hash_args(args, extra=None, path=None): Create unique hash stamp to determine if arguments/file is different from before.

stamp_hash(h5file_name, new_hash): Loads a file, stamps it, and returns the opened file in read only

analysis_structure()

Run automatically on startup. Parses through the configuration file, and loads up all the data files from the different analysis schematics. If they don’t exist, it creates them automatically by hooking in to existing analysis routines and going from there.

It does this by calling in the make_parser_and_process function for w_{assign,reweight,direct} using a custom built list of args. The user can specify everything in the configuration file that would have been specified on the command line.

For instance, were one to call w_direct as follows:

w_direct –evolution cumulative –step-iter 1 –disable-correl

the west.cfg would look as follows:

west:

analysis:

w_direct:: evolution: cumulative step_iter: 1 extra: [‘disable-correl’]

Alternatively, if one wishes to use the same options for both w_direct and w_reweight, the key ‘w_direct’ can be replaced with ‘kinetics’.

property assign

property direct: The output from w_kinavg.py from the current scheme.

property state_labels

property bin_labels

property west

property reweight

property scheme: Returns and sets what scheme is currently in use. To see what schemes are available, run:

w.list_schemes

property list_schemes

Lists what schemes are configured in west.cfg file. Schemes should be structured as follows, in west.cfg:

west:

system:

analysis:

directory: analysis analysis_schemes:

scheme.1:
enabled: True states:

label: unbound coords: [[7.0]]

label: bound coords: [[2.7]]

bins:

type: RectilinearBinMapper boundaries: [[0.0, 2.80, 7, 10000]]

property iteration: Returns/sets the current iteration.

property current: The current iteration. See help for __get_data_for_iteration__

property past: The previous iteration. See help for __get_data_for_iteration__

trace(seg_id)

Runs a trace on a seg_id within the current iteration, all the way back to the beginning, returning a dictionary containing all interesting information:

seg_id, pcoord, states, bins, weights, iteration, auxdata (optional)

sorted in chronological order.

Call with a seg_id.

property future: Similar to current/past, but keyed differently and returns different datasets. See help for Future.

class Future(raw, key): Bases: WIPIDataset

go(): Function automatically called by main() when launched via the command line interface. Generally, call main, not this function.

property introduction: Just spits out an introduction, in case someone doesn’t call help.

property help: Just a minor function to call help on itself. Only in here to really help someone get help.

westpa.cli.tools.w_ipa.entry_point()