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 number n_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 given datafile (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 iteration n_iter, but if index_data is provided, it must be an iterable (preferably a simple array) of (n_iter,seg_id) pairs, and the index in the index_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()