WEST Tools
The command line tools included with the WESTPA software package are broadly separable into two categories: Tools for initializing a simulation and tools for analyzing results.
Command function can be user defined and modified. The particular parameters of different command line tools are specified, in order of precedence, by:
User specified command line arguments
User defined environmental variables
Package defaults
This page focuses on outlining the general functionality of the command line tools and providing an overview of command line arguments that are shared by multiple tools. See the index of command-line tools for a more comprehensive overview of each tool.
Overview
All tools are located in the $WEST_ROOT/bin
directory, where the shell
variable WEST_ROOT
points to the path where the WESTPA package is located
on your machine.
You may wish to set this variable automatically by adding the following to your
~/.bashrc
or ~/.profile
file:
export WEST_ROOT="$HOME/westpa"
where the path to the westpa suite is modified accordingly.
Tools for setting up and running a simulation
Use the following commands to initialize, configure, and run a weighted ensemble simulation. Command line arguments or environmental variables can be set to specify the work managers for running the simulation, where configuration data is read from, and the HDF5 file in which results are stored.
Command |
Function |
---|---|
Initializes simulation configuration files and environment. Always run this command before starting a new simulation. |
|
Set up binning, progress coordinate |
|
Launches a simulation. Command arguments/environmental variables can be included to specify the work managers and simulation parameters |
|
Truncates the weighted ensemble simulation from a given iteration. |
Tools for analyzing simulation results
The following command line tools are provided for analysis after running a weighted ensemble simulation (and collecting the results in an HDF5 file).
With the exception of the plotting tool plothist
, all analysis tools read
from and write to HDF5 type files.
Command |
Function |
---|---|
Assign walkers to bins and macrostates (using simulation output as input). Must be done before some other analysis tools (e.g. w_kinetics, w_kinavg) |
|
Trace the path of a given walker segment over a user-specified number of simulation iterations. |
|
Calculate average probability flux into user-defined ‘target’ state with relevant statistics. |
|
Construct a probability distribution of results (e.g. progress coordinate membership) for subsequent plotting with plothist. |
|
Tool to plot output from other analysis tools (e.g. w_pdist). |
General Command Line Options
The following arguments are shared by all command line tools:
-r config file, --rcfile config file
Use config file as the configuration file (Default: File named west.cfg)
--quiet, --verbose, --debug
Specify command tool output verbosity (Default: 'quiet' mode)
--version
Print WESTPA version number and exit
-h, --help
Output the help information for this command line tool and exit
A note on specifying a configuration file
A configuration file, which should be stored in your simulation root directory, is read by all command line tools. The configuration file specifies parameters for general simulation setup, as well as the hdf5 file name where simulation data is stored and read by analysis tools.
If not specified, the default configuration file is assumed to be named west.cfg.
You can override this to use configuration file file by either:
Setting the environmental variable
WESTRC
equal to file:export WESTRC=/path/to/westrcfile
Including the command line argument
-r /path/to/westrcfile
Work Manager Options
Note: See wwmgr overview for a more detailed explanation of the work manager framework.
Work managers a used by a number of command-line tools to process more complex tasks, especially in setting up and running simulations (i.e. w_init and w_run) - in general, work managers are involved in tasks that require multiprocessing and/or tasks distributed over multiple nodes in a cluster.
Overview
The following command-line tools make use of work managers:
General work manager options
The following are general options used for specifying the type of work manager and number of cores:
--wm-work-manager work_manager
Specify which type of work manager to use, where the possible choices for
work_manager are: {processes, gcserial, threads, mpi, or zmq}. See the
wwmgr overview page <wwmgr>_ for more information on the different types of
work managers (Default: gcprocesses)
--wm-n-workers n_workers
Specify the number of cores to use as gcn_workers, if the work manager you
selected supports this option (work managers that do not will ignore this
option). If using an gcmpi or zmq work manager, specify gc--wm-n-workers=0
for a dedicated server (Default: Number of cores available on machine)
The mpi
work manager is generally sufficient for most tasks that make use
of multiple nodes on a cluster. The zmq
work manager is preferable if the
mpi
work manager does not work properly on your cluster or if you prefer to
have more explicit control over the distribution of communication tasks on your
cluster.
ZeroMQ (‘zmq’) work manager
The ZeroMQ work manager offers a number of additional options (all of which are optional and have default values). All of these options focus on whether the zmq work manager is set up as a server (i.e. task distributor/ventilator) or client (task processor):
--wm-zmq-mode mode
Options: {server or client}. Specify whether the ZMQ work manager on this
node will operate as a server or a client (Default: server)
--wm-zmq-info-file info_file
Specify the name of a temporary file to write (as a server) or read (as a
client) socket connection endpoints (Default: server_x.json, where x is a
unique identifier string)
--wm-zmq-task-endpoint task_endpoint
Explicitly use task_endpoint to bind to (as server) or connect to (as
client) for task distribution (Default: A randomly determined endpoint that
is written or read from the specified info_file)
--wm-zmq-result-endpoint result_endpoint
Explicitly use result_endpoint to bind to (as server) or connect to (as
client) to distribute and collect task results (Default: A randomly
determined endpoint that is written to or read from the specified
info_file)
--wm-zmq-announce-endpoint announce_endpoint
Explicitly use announce_endpoint to bind to (as server) or connect to (as
client) to distribute central announcements (Default: A randomly determined
endpoint that is written to or read from the specified info_file)
--wm-zmq-heartbeat-interval interval
If a server, send an Im alive ping to connected clients every interval
seconds; If a client, expect to hear a server ping every approximately
interval seconds, or else assume the server has crashed and shutdown
(Default: 600 seconds)
--wm-zmq-task-timeout timeout
Kill worker processes/jobs after that take longer than timeout seconds to
complete (Default: no time limit)
--wm-zmq-client-comm-mode mode
Use the communication mode, mode, (options: {ipc for Unix sockets, or tcp
for TCP/IP sockets}) to communicate with worker processes (Default: ipc)
Initializing/Running Simulations
For a more complete overview of all the files necessary for setting up a simulation, see the user guide for setting up a simulation