westpa.core.propagators package

westpa.core.propagators module

westpa.core.propagators.blocked_iter(blocksize, iterable, fillvalue=None)

class westpa.core.propagators.WESTPropagator(rc=None)

Bases: object

prepare_iteration(n_iter, segments)

Perform any necessary per-iteration preparation. This is run by the work manager.

finalize_iteration(n_iter, segments)

Perform any necessary post-iteration cleanup. This is run by the work manager.

get_pcoord(state)

Get the progress coordinate of the given basis or initial state.

gen_istate(basis_state, initial_state)

Generate a new initial state from the given basis state.

propagate(segments)

Propagate one or more segments, including any necessary per-iteration setup and teardown for this propagator.

clear_basis_initial_states()

update_basis_initial_states(basis_states, initial_states)

westpa.core.propagators.executable module

class westpa.core.propagators.executable.BytesIO(initial_bytes=b'')

Bases: _BufferedIOBase

Buffered I/O implementation using an in-memory bytes buffer.

close()

Disable all I/O operations.

closed

True if the file is closed.

flush()

Does nothing.

getbuffer()

Get a read-write view over the contents of the BytesIO object.

getvalue()

Retrieve the entire contents of the BytesIO object.

isatty()

Always returns False.

BytesIO objects are not connected to a TTY-like device.

read(size=-1, /)

Read at most size bytes, returned as a bytes object.

If the size argument is negative, read until EOF is reached. Return an empty bytes object at EOF.

read1(size=-1, /)

Read at most size bytes, returned as a bytes object.

If the size argument is negative or omitted, read until EOF is reached. Return an empty bytes object at EOF.

readable()

Returns True if the IO object can be read.

readinto(buffer, /)

Read bytes into buffer.

Returns number of bytes read (0 for EOF), or None if the object is set not to block and has no data to read.

readline(size=-1, /)

Next line from the file, as a bytes object.

Retain newline. A non-negative size argument limits the maximum number of bytes to return (an incomplete line may be returned then). Return an empty bytes object at EOF.

readlines(size=None, /)

List of bytes objects, each a line from the file.

Call readline() repeatedly and return a list of the lines so read. The optional size argument, if given, is an approximate bound on the total number of bytes in the lines returned.

seek(pos, whence=0, /)

Change stream position.

Seek to byte offset pos relative to position indicated by whence:

0 Start of stream (the default). pos should be >= 0; 1 Current position - pos may be negative; 2 End of stream - pos usually negative.

Returns the new absolute position.

seekable()

Returns True if the IO object can be seeked.

tell()

Current file position, an integer.

truncate(size=None, /)

Truncate the file to at most size bytes.

Size defaults to the current file position, as returned by tell(). The current file position is unchanged. Returns the new size.

writable()

Returns True if the IO object can be written.

write(b, /)

Write bytes to file.

Return the number of bytes written.

writelines(lines, /)

Write lines to the file.

Note that newlines are not added. lines can be any iterable object producing bytes-like objects. This is equivalent to calling write() for each element.

westpa.core.propagators.executable.get_object(object_name, path=None)

Attempt to load the given object, using additional path information if given.

class westpa.core.propagators.executable.WESTPropagator(rc=None)

Bases: object

prepare_iteration(n_iter, segments)

Perform any necessary per-iteration preparation. This is run by the work manager.

finalize_iteration(n_iter, segments)

Perform any necessary post-iteration cleanup. This is run by the work manager.

get_pcoord(state)

Get the progress coordinate of the given basis or initial state.

gen_istate(basis_state, initial_state)

Generate a new initial state from the given basis state.

propagate(segments)

Propagate one or more segments, including any necessary per-iteration setup and teardown for this propagator.

clear_basis_initial_states()

update_basis_initial_states(basis_states, initial_states)

class westpa.core.propagators.executable.BasisState(label, probability, pcoord=None, auxref=None, state_id=None)

Bases: object

Describes an basis (micro)state. These basis states are used to generate initial states for new trajectories, either at the beginning of the simulation (i.e. at w_init) or due to recycling.

Variables:

• state_id – Integer identifier of this state, usually set by the data manager.

• label – A descriptive label for this microstate (may be empty)

• probability – Probability of this state to be selected when creating a new trajectory.

• pcoord – The representative progress coordinate of this state.

• auxref – A user-provided (string) reference for locating data associated with this state (usually a filesystem path).

classmethod states_to_file(states, fileobj)

Write a file defining basis states, which may then be read by states_from_file().

classmethod states_from_file(statefile)

Read a file defining basis states. Each line defines a state, and contains a label, the probability, and optionally a data reference, separated by whitespace, as in:

unbound    1.0

or:

unbound_0    0.6        state0.pdb
unbound_1    0.4        state1.pdb

as_numpy_record()

Return the data for this state as a numpy record array.

class westpa.core.propagators.executable.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.core.propagators.executable.return_state_type(state_obj)

Convinience function for returning the state ID and type of the state_obj pointer

class westpa.core.propagators.executable.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

westpa.core.propagators.executable.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').

westpa.core.propagators.executable.load_trajectory(folder)

Load trajectory from folder using mdtraj and return a mdtraj.Trajectory object. The folder should contain a trajectory and a topology file (with a recognizable extension) that is supported by mdtraj. The topology file is optional if the trajectory file contains topology data (e.g., HDF5 format).

westpa.core.propagators.executable.safe_extract(tar, path='.', members=None, *, numeric_owner=False)

westpa.core.propagators.executable.pcoord_loader(fieldname, pcoord_return_filename, destobj, single_point)

Read progress coordinate data into the pcoord field on destobj. An exception will be raised if the data is malformed. If single_point is true, then only one (N-dimensional) point will be read, otherwise system.pcoord_len points will be read.

westpa.core.propagators.executable.aux_data_loader(fieldname, data_filename, segment, single_point)

westpa.core.propagators.executable.npy_data_loader(fieldname, coord_file, segment, single_point)

westpa.core.propagators.executable.pickle_data_loader(fieldname, coord_file, segment, single_point)

westpa.core.propagators.executable.trajectory_loader(fieldname, coord_folder, segment, single_point)

Load data from the trajectory return. coord_folder should be the path to a folder containing trajectory files. segment is the Segment object that the data is associated with. Please see load_trajectory for more details. single_point is not used by this loader.

westpa.core.propagators.executable.restart_loader(fieldname, restart_folder, segment, single_point)

Load data from the restart return. The loader will tar all files in restart_folder and store it in the per-iteration HDF5 file. segment is the Segment object that the data is associated with. single_point is not used by this loader.

westpa.core.propagators.executable.restart_writer(path, segment)

Prepare the necessary files from the per-iteration HDF5 file to run segment.

westpa.core.propagators.executable.seglog_loader(fieldname, log_file, segment, single_point)

Load data from the log return. The loader will tar all files in log_file and store it in the per-iteration HDF5 file. segment is the Segment object that the data is associated with. single_point is not used by this loader.

class westpa.core.propagators.executable.ExecutablePropagator(rc=None)

Bases: WESTPropagator

ENV_CURRENT_ITER = 'WEST_CURRENT_ITER'

ENV_CURRENT_SEG_ID = 'WEST_CURRENT_SEG_ID'

ENV_CURRENT_SEG_DATA_REF = 'WEST_CURRENT_SEG_DATA_REF'

ENV_CURRENT_SEG_INITPOINT = 'WEST_CURRENT_SEG_INITPOINT_TYPE'

ENV_PARENT_SEG_ID = 'WEST_PARENT_ID'

ENV_PARENT_DATA_REF = 'WEST_PARENT_DATA_REF'

ENV_BSTATE_ID = 'WEST_BSTATE_ID'

ENV_BSTATE_DATA_REF = 'WEST_BSTATE_DATA_REF'

ENV_ISTATE_ID = 'WEST_ISTATE_ID'

ENV_ISTATE_DATA_REF = 'WEST_ISTATE_DATA_REF'

ENV_STRUCT_DATA_REF = 'WEST_STRUCT_DATA_REF'

ENV_RAND16 = 'WEST_RAND16'

ENV_RAND32 = 'WEST_RAND32'

ENV_RAND64 = 'WEST_RAND64'

ENV_RAND128 = 'WEST_RAND128'

ENV_RANDFLOAT = 'WEST_RANDFLOAT'

static makepath(template, template_args=None, expanduser=True, expandvars=True, abspath=False, realpath=False)

random_val_env_vars()

Return a set of environment variables containing random seeds. These are returned as a dictionary, suitable for use in os.environ.update() or as the env argument to subprocess.Popen(). Every child process executed by exec_child() gets these.

exec_child(executable, environ=None, stdin=None, stdout=None, stderr=None, cwd=None)

Execute a child process with the environment set from the current environment, the values of self.addtl_child_environ, the random numbers returned by self.random_val_env_vars, and the given environ (applied in that order). stdin/stdout/stderr are optionally redirected.

This function waits on the child process to finish, then returns (rc, rusage), where rc is the child’s return code and rusage is the resource usage tuple from os.wait4()

exec_child_from_child_info(child_info, template_args, environ)

update_args_env_basis_state(template_args, environ, basis_state)

update_args_env_initial_state(template_args, environ, initial_state)

update_args_env_iter(template_args, environ, n_iter)

update_args_env_segment(template_args, environ, segment)

template_args_for_segment(segment)

exec_for_segment(child_info, segment, addtl_env=None)

Execute a child process with environment and template expansion from the given segment.

exec_for_iteration(child_info, n_iter, addtl_env=None)

Execute a child process with environment and template expansion from the given iteration number.

exec_for_basis_state(child_info, basis_state, addtl_env=None)

Execute a child process with environment and template expansion from the given basis state

exec_for_initial_state(child_info, initial_state, addtl_env=None)

Execute a child process with environment and template expansion from the given initial state.

prepare_file_system(segment, environ)

setup_dataset_return(segment=None, subset_keys=None)

Set up temporary files and environment variables that point to them for segment runners to return data. segment is the Segment object that the return data is associated with. subset_keys specifies the names of a subset of data to be returned.

retrieve_dataset_return(state, return_files, del_return_files, single_point)

Retrieve returned data from the temporary locations directed by the environment variables. state is a Segment, BasisState , or InitialState``object that the return data is associated with. ``return_files is a dict where the keys are the dataset names and the values are the paths to the temporarily files that contain the returned data. del_return_files is a dict where the keys are the names of datasets to be deleted (if the corresponding value is set to True) once the data is retrieved.

get_pcoord(state)

Get the progress coordinate of the given basis or initial state.

gen_istate(basis_state, initial_state)

Generate a new initial state from the given basis state.

prepare_iteration(n_iter, segments)

Perform any necessary per-iteration preparation. This is run by the work manager.

finalize_iteration(n_iter, segments)

Perform any necessary post-iteration cleanup. This is run by the work manager.

propagate(segments)

Propagate one or more segments, including any necessary per-iteration setup and teardown for this propagator.