w_trace
usage:
w_trace [-h] [-r RCFILE] [--quiet | --verbose | --debug] [--version] [-W WEST_H5FILE]
[-d DSNAME] [--output-pattern OUTPUT_PATTERN] [-o OUTPUT]
N_ITER:SEG_ID [N_ITER:SEG_ID ...]
Trace individual WEST trajectories and emit (or calculate) quantities along the trajectory.
Trajectories are specified as N_ITER:SEG_ID pairs. Each segment is traced back to its initial point, and then various quantities (notably n_iter and seg_id) are printed in order from initial point up until the given segment in the given iteration.
Output is stored in several files, all named according to the pattern given by the -o/–output-pattern parameter. The default output pattern is “traj_%d_%d”, where the printf-style format codes are replaced by the iteration number and segment ID of the terminal segment of the trajectory being traced.
Individual datasets can be selected for writing using the -d/--dataset
option
(which may be specified more than once). The simplest form is -d dsname
,
which causes data from dataset dsname
along the trace to be stored to
HDF5. The dataset is assumed to be stored on a per-iteration basis, with
the first dimension corresponding to seg_id and the second dimension
corresponding to time within the segment. Further options are specified
as comma-separated key=value pairs after the data set name, as in:
-d dsname,alias=newname,index=idsname,file=otherfile.h5,slice=[100,...]
The following options for datasets are supported:
alias=newname
When writing this data to HDF5 or text files, use ``newname``
instead of ``dsname`` to identify the dataset. This is mostly of
use in conjunction with the ``slice`` option in order, e.g., to
retrieve two different slices of a dataset and store then with
different names for future use.
index=idsname
The dataset is not stored on a per-iteration basis for all
segments, but instead is stored as a single dataset whose
first dimension indexes n_iter/seg_id pairs. The index to
these n_iter/seg_id pairs is ``idsname``.
file=otherfile.h5
Instead of reading data from the main WEST HDF5 file (usually
``west.h5``), read data from ``otherfile.h5``.
slice=[100,...]
Retrieve only the given slice from the dataset. This can be
used to pick a subset of interest to minimize I/O.
positional arguments
N_ITER:SEG_ID Trace trajectory ending (or at least alive at) N_ITER:SEG_ID.
optional arguments
-h, --help show this help message and exit
-d DSNAME, --dataset DSNAME
Include the dataset named DSNAME in trace output. An extended form like
DSNAME[,alias=ALIAS][,index=INDEX][,file=FILE][,slice=SLICE] will obtain the
dataset from the given FILE instead of the main WEST HDF5 file, slice it by
SLICE, call it ALIAS in output, and/or access per-segment data by a
n_iter,seg_id INDEX instead of a seg_id indexed dataset in the group for
n_iter.
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
--debug enable extra checks and emit copious information
--version show program's version number and exit
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).
output options
--output-pattern OUTPUT_PATTERN
Write per-trajectory data to output files/HDF5 groups whose names begin with
OUTPUT_PATTERN, which must contain two printf-style format flags which will be
replaced with the iteration number and segment ID of the terminal segment of
the trajectory being traced. (Default: traj_%d_%d.)
-o OUTPUT, --output OUTPUT
Store intermediate data and analysis results to OUTPUT (default: trajs.h5).
westpa.cli.tools.w_trace module
- class westpa.cli.tools.w_trace.WESTTool
Bases:
WESTToolComponent
Base class for WEST command line tools
- prog = None
- usage = None
- description = None
- epilog = None
- 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)
- make_parser(prog=None, usage=None, description=None, epilog=None, args=None)
- 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.
- go()
Perform the analysis associated with this tool.
- main()
A convenience function to make a parser, parse and process arguments, then call self.go()
- class westpa.cli.tools.w_trace.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.
- process_args(args)
Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)
- open(mode='r')
- close()
- property weight_dsspec
- property parent_id_dsspec
- class westpa.cli.tools.w_trace.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.cli.tools.w_trace.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.cli.tools.w_trace.weight_dtype
alias of
float64
- westpa.cli.tools.w_trace.n_iter_dtype
alias of
uint32
- westpa.cli.tools.w_trace.seg_id_dtype
alias of
int64
- westpa.cli.tools.w_trace.utime_dtype
alias of
float64
- class westpa.cli.tools.w_trace.Trace(summary, endpoint_type, basis_state, initial_state, data_manager=None)
Bases:
object
A class representing a trace of a certain trajectory segment back to its origin.
- classmethod from_data_manager(n_iter, seg_id, data_manager=None)
Construct and return a trajectory trace whose last segment is identified by
seg_id
in the iteration numbern_iter
.
- get_segment_data_slice(datafile, dsname, n_iter, seg_id, slice_=None, index_data=None, iter_prec=None)
Return the data from the dataset named
dsname
within the givendatafile
(an open h5py.File object) for the given iteration and segment. By default, it is assumed that the dataset is stored in the iteration group for iterationn_iter
, but ifindex_data
is provided, it must be an iterable (preferably a simple array) of (n_iter,seg_id) pairs, and the index in theindex_data
iterable of the matching n_iter/seg_id pair is used as the index of the data to retrieve.If an optional
slice_
is provided, then the given slicing tuple is appended to that used to retrieve the segment-specific data (i.e. it can be used to pluck a subset of the data that would otherwise be returned).
- trace_timepoint_dataset(dsname, slice_=None, auxfile=None, index_ds=None)
Return a trace along this trajectory over a dataset which is layed out as [seg_id][timepoint][…]. Overlapping values at segment boundaries are accounted for. Returns (data_trace, weight), where data_trace is a time series of the dataset along this trajectory, and weight is the corresponding trajectory weight at each time point.
If
auxfile
is given, then load the dataset from the given HDF5 file, which must be layed out the same way as the main HDF5 file (e.g. iterations arranged as iterations/iter_*).If index_ds is given, instead of reading data per-iteration from iter_* groups, then the given index_ds is used as an index of n_iter,seg_id pairs into
dsname
. In this case, the target data set need not exist on a per-iteration basis inside iter_* groups.If
slice_
is given, then further slice the data returned from the HDF5 dataset. This can minimize I/O if it is known (and specified) that only a subset of the data along the trajectory is needed.
- class westpa.cli.tools.w_trace.WTraceTool
Bases:
WESTTool
- prog = 'w_trace'
- description = 'Trace individual WEST trajectories and emit (or calculate) quantities along the\ntrajectory.\n\nTrajectories are specified as N_ITER:SEG_ID pairs. Each segment is traced back\nto its initial point, and then various quantities (notably n_iter and seg_id)\nare printed in order from initial point up until the given segment in the given\niteration.\n\nOutput is stored in several files, all named according to the pattern given by\nthe -o/--output-pattern parameter. The default output pattern is "traj_%d_%d",\nwhere the printf-style format codes are replaced by the iteration number and\nsegment ID of the terminal segment of the trajectory being traced.\n\nIndividual datasets can be selected for writing using the -d/--dataset option\n(which may be specified more than once). The simplest form is ``-d dsname``,\nwhich causes data from dataset ``dsname`` along the trace to be stored to\nHDF5. The dataset is assumed to be stored on a per-iteration basis, with\nthe first dimension corresponding to seg_id and the second dimension\ncorresponding to time within the segment. Further options are specified\nas comma-separated key=value pairs after the data set name, as in\n\n -d dsname,alias=newname,index=idsname,file=otherfile.h5,slice=[100,...]\n\nThe following options for datasets are supported:\n\n alias=newname\n When writing this data to HDF5 or text files, use ``newname``\n instead of ``dsname`` to identify the dataset. This is mostly of\n use in conjunction with the ``slice`` option in order, e.g., to\n retrieve two different slices of a dataset and store then with\n different names for future use.\n\n index=idsname\n The dataset is not stored on a per-iteration basis for all\n segments, but instead is stored as a single dataset whose\n first dimension indexes n_iter/seg_id pairs. The index to\n these n_iter/seg_id pairs is ``idsname``.\n\n file=otherfile.h5\n Instead of reading data from the main WEST HDF5 file (usually\n ``west.h5``), read data from ``otherfile.h5``.\n\n slice=[100,...]\n Retrieve only the given slice from the dataset. This can be\n used to pick a subset of interest to minimize I/O.\n\n-------------------------------------------------------------------------------\n'
- pcoord_formats = {'f4': '%14.7g', 'f8': '%023.15g', 'i2': '%6d', 'i4': '%11d', 'i8': '%20d', 'u2': '%5d', 'u4': '%10d', 'u8': '%20d'}
- 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)
- parse_dataset_string(dsstr)
- go()
Perform the analysis associated with this tool.
- emit_trace_h5(trace, output_group)
- emit_trace_text(trace, output_file)
Dump summary information about each segment in the given trace to the given output_file, which must be opened for writing in text mode. Output columns are separated by at least one space.
- westpa.cli.tools.w_trace.entry_point()