westpa 2022.12__cp312-cp312-macosx_10_13_x86_64.whl

westpa/work_managers/zeromq/worker.py

@@ -0,0 +1,320 @@
+'''
+Created on May 29, 2015
+
+@author: mzwier
+'''
+
+import logging
+import multiprocessing
+import os
+import signal
+import threading
+
+from .core import ZMQCore, Message, ZMQWMTimeout, PassiveMultiTimer, Task, Result, TIMEOUT_MASTER_BEACON
+
+import zmq
+
+
+log = logging.getLogger(__name__)
+
+
+class ZMQWorker(ZMQCore):
+    '''This is the outward facing worker component of the ZMQ work manager. This
+    forms the interface to the master. This process cannot hang or crash due to an
+    error in tasks it executes, so tasks are isolated in ZMQExecutor, which
+    communicates with ZMQWorker via (what else?) ZeroMQ.'''
+
+    def __init__(self, rr_endpoint, ann_endpoint):
+        super().__init__()
+
+        # Upstream endpoints
+        self.rr_endpoint = rr_endpoint
+        self.ann_endpoint = ann_endpoint
+
+        # Downstream endpoints
+        self.task_endpoint = self.make_internal_endpoint()
+        self.result_endpoint = self.make_internal_endpoint()
+
+        self.master_id = None
+        self.identified = False
+
+        # The task currently being processed
+        self.pending_task = None
+
+        # Executor process
+
+        self.shutdown_timeout = 5.0  # Five second wait between shutdown message and SIGINT and SIGINT and SIGKILL
+        self.executor_process = None
+
+    @property
+    def is_master(self):
+        return False
+
+    def update_master_info(self, msg):
+        if self.master_id is None:
+            self.master_id = msg.master_id
+        self.timers.reset(TIMEOUT_MASTER_BEACON)
+
+    def identify(self, rr_socket):
+        if self.master_id is None or self.identified or self.timers.expired(TIMEOUT_MASTER_BEACON):
+            return
+        self.send_message(rr_socket, Message.IDENTIFY, payload=self.get_identification())
+        self.recv_ack(rr_socket, timeout=self.master_beacon_period * self.timeout_factor * 1000)
+        self.identified = True
+
+    def request_task(self, rr_socket, task_socket):
+        if self.master_id is None:
+            return
+        elif self.pending_task is not None:
+            return
+        elif self.timers.expired(TIMEOUT_MASTER_BEACON):
+            return
+        else:
+            self.send_message(rr_socket, Message.TASK_REQUEST)
+            reply = self.recv_message(rr_socket, timeout=self.master_beacon_period * self.timeout_factor * 1000)
+            self.update_master_info(reply)
+            if reply.message == Message.NAK:
+                # No task available
+                return
+            else:
+                with self.message_validation(reply):
+                    assert isinstance(reply.payload, Task)
+                    task = reply.payload
+                self.pending_task = task
+                self.send_message(task_socket, Message.TASK, task)
+
+    def handle_reconfigure_timeout(self, msg, timers):
+        with self.message_validation(msg):
+            assert msg.payload is not None
+            timer, new_period = msg.payload
+        timers.change_duration(timer, new_period)
+        timers.reset(timer)
+
+    def handle_result(self, result_socket, rr_socket):
+        msg = self.recv_message(result_socket)
+        with self.message_validation(msg):
+            assert msg.message == Message.RESULT
+            assert isinstance(msg.payload, Result)
+            assert msg.payload.task_id == self.pending_task.task_id
+
+        msg.src_id = self.node_id
+        self.pending_task = None
+        self.send_message(rr_socket, msg)
+        reply = self.recv_ack(rr_socket, timeout=self.master_beacon_period * self.timeout_factor * 1000)
+        self.update_master_info(reply)
+
+    def comm_loop(self):
+        '''Master communication loop for the worker process.'''
+
+        rr_socket = self.context.socket(zmq.REQ)
+
+        ann_socket = self.context.socket(zmq.SUB)
+        ann_socket.setsockopt(zmq.SUBSCRIBE, b'')
+        inproc_socket = self.context.socket(zmq.SUB)
+        inproc_socket.setsockopt(zmq.SUBSCRIBE, b'')
+
+        task_socket = self.context.socket(zmq.PUSH)
+        result_socket = self.context.socket(zmq.PULL)
+
+        self.log.info('This is {}'.format(self.node_description))
+
+        timers = self.timers = PassiveMultiTimer()
+        timers.add_timer(TIMEOUT_MASTER_BEACON, 86400)
+        timers.add_timer('worker_beacon', self.worker_beacon_period)
+        timers.add_timer('startup_timeout', self.startup_timeout)
+        peer_found = False
+
+        try:
+            rr_socket.connect(self.rr_endpoint)
+            ann_socket.connect(self.ann_endpoint)
+            inproc_socket.bind(self.inproc_endpoint)
+            task_socket.connect(self.task_endpoint)
+            result_socket.bind(self.result_endpoint)
+
+            poller = zmq.Poller()
+            poller.register(ann_socket, zmq.POLLIN)
+            poller.register(inproc_socket, zmq.POLLIN)
+            poller.register(result_socket, zmq.POLLIN)
+
+            timers.reset()
+            while True:
+                # If a timer is already expired, next_expiration_in() will return 0, which
+                # zeromq interprets as infinite wait; so instead we select a 1 ms wait in this
+                # case.
+                poll_results = dict(poller.poll((timers.next_expiration_in() or 0.001) * 1000))
+
+                if poll_results and not peer_found:
+                    timers.remove_timer('startup_timeout')
+                    peer_found = True
+                    timers.change_duration(TIMEOUT_MASTER_BEACON, self.master_beacon_period * self.timeout_factor)
+                    timers.reset(TIMEOUT_MASTER_BEACON)
+
+                announcements = []
+
+                # Check for internal messages first
+                if inproc_socket in poll_results:
+                    announcements.extend(self.recv_all(inproc_socket))
+
+                # Process announcements
+                if ann_socket in poll_results:
+                    announcements.extend(self.recv_all(ann_socket))
+
+                # announcements = Message.coalesce_announcements(announcements)
+                # self.log.debug('received {:d} announcements'.format(len(announcements)))
+
+                messages_by_tag = {}
+                for msg in announcements:
+                    messages_by_tag.setdefault(msg.message, list()).append(msg)
+
+                # Check for shutdown messages
+                if Message.SHUTDOWN in messages_by_tag:
+                    self.log.debug('received shutdown message')
+                    return
+                elif Message.TASKS_AVAILABLE in messages_by_tag:
+                    self.update_master_info(messages_by_tag[Message.TASKS_AVAILABLE][0])
+                elif Message.MASTER_BEACON in messages_by_tag:
+                    self.update_master_info(messages_by_tag[Message.MASTER_BEACON][0])
+
+                if self.master_id is not None and timers.expired('worker_beacon'):
+                    self.identify(rr_socket)
+                    timers.reset('worker_beacon')
+
+                # Handle results, so that we clear ourselves of completed tasks
+                # before asking for more
+                if result_socket in poll_results:
+                    self.handle_result(result_socket, rr_socket)
+                    # immediately request another task if available
+                    if not timers.expired(TIMEOUT_MASTER_BEACON):
+                        self.request_task(rr_socket, task_socket)
+
+                # Handle any remaining messages
+                for tag, msgs in messages_by_tag.items():
+                    if tag == Message.MASTER_BEACON:
+                        self.identify(rr_socket)
+                    elif tag == Message.RECONFIGURE_TIMEOUT:
+                        for msg in msgs:
+                            self.handle_reconfigure_timeout(msg, timers)
+                    elif tag == Message.TASKS_AVAILABLE:
+                        self.request_task(rr_socket, task_socket)
+
+                del announcements, messages_by_tag
+
+                if timers.expired(TIMEOUT_MASTER_BEACON):
+                    self.log.error('no contact from master; shutting down')
+                    return
+
+                if not peer_found and timers.expired('startup_timeout'):
+                    self.log.error('startup phase elapsed with no contact from master; shutting down')
+                    break
+
+        except ZMQWMTimeout:
+            # both handle_result() and request_task() have receive timeouts set to
+            # self.master_beacon_period*self.timeout_factor, and timeout exceptions
+            # propagate to this point.
+            self.log.error('timeout communicating with peer; shutting down')
+        finally:
+            self.shutdown_executor()
+            self.executor_process.join()
+            self.context.destroy(linger=1)
+            self.context = None
+            self.remove_ipc_endpoints()
+
+    def shutdown_executor(self):
+        if self.context is not None:
+            try:
+                self.log.debug('sending shutdown task to executor')
+                task_socket = self.context.socket(zmq.PUSH)
+                task_socket.connect(self.task_endpoint)
+                self.send_message(task_socket, Message.SHUTDOWN)
+                task_socket.close(linger=1)
+            except Exception:
+                pass
+
+        pid = self.executor_process.pid
+        self.executor_process.join(self.shutdown_timeout)
+        # is_alive() is prone to a race condition so catch the case that the PID is already dead
+        if self.executor_process.is_alive():
+            self.log.debug('sending SIGTERM to worker process {:d}'.format(pid))
+            self.executor_process.terminate()
+            # try:
+            #     os.kill(self.executor_process.pid, signal.SIGINT)
+            # except ProcessLookupError:
+            #     self.log.debug('worker process {:d} already dead'.format(pid))
+            self.executor_process.join(self.shutdown_timeout)
+            if self.executor_process.is_alive():
+                self.executor_process.kill()
+                self.log.warning('sending SIGKILL to worker process {:d}'.format(pid))
+                # try:
+                #     os.kill(self.executor_process.pid, signal.SIGKILL)
+                # except ProcessLookupError:
+                #     self.log.debug('worker process {:d} already dead'.format(pid))
+            self.executor_process.join()
+            self.log.debug('worker process {:d} terminated'.format(pid))
+        else:
+            self.log.debug('worker process {:d} terminated gracefully with code {:d}'.format(pid, self.executor_process.exitcode))
+
+    def install_signal_handlers(self, signals=None):
+        if not signals:
+            signals = {signal.SIGINT, signal.SIGQUIT, signal.SIGTERM}
+
+        for sig in signals:
+            signal.signal(sig, signal.SIG_IGN)
+
+    def startup(self, process_index=None):
+        self.install_signal_handlers()
+        executor = ZMQExecutor(self.task_endpoint, self.result_endpoint)
+        self.executor_process = multiprocessing.Process(target=executor.startup, args=(process_index,))
+        self.executor_process.start()
+        self.context = zmq.Context()
+        self.comm_thread = threading.Thread(target=self.comm_loop)
+        self.comm_thread.start()
+
+
+class ZMQExecutor(ZMQCore):
+    '''The is the component of the ZMQ WM worker that actually executes tasks.
+    This is isolated in a separate process and controlled via ZMQ from
+    the ZMQWorker.'''
+
+    def __init__(self, task_endpoint, result_endpoint):
+        super().__init__()
+
+        self.task_endpoint = task_endpoint
+        self.result_endpoint = result_endpoint
+
+    def comm_loop(self):
+        task_socket = self.context.socket(zmq.PULL)
+        result_socket = self.context.socket(zmq.PUSH)
+
+        task_socket.bind(self.task_endpoint)
+        result_socket.connect(self.result_endpoint)
+
+        self.log.info('This is {}'.format(self.node_description))
+
+        try:
+            while True:
+                try:
+                    msg = self.recv_message(task_socket, timeout=100)
+                except KeyboardInterrupt:
+                    break
+                except ZMQWMTimeout:
+                    continue
+                else:
+                    if msg.message == Message.TASK:
+                        task = msg.payload
+                        result = task.execute()
+                        self.send_message(result_socket, Message.RESULT, result)
+                    elif msg.message == Message.SHUTDOWN:
+                        break
+        finally:
+            self.context.destroy(linger=0)
+            self.context = None
+
+    def startup(self, process_index=None):
+        if process_index is not None:
+            from westpa.work_managers import environment
+
+            pi_name = '{}_PROCESS_INDEX'.format(environment.WMEnvironment.env_prefix)
+            self.log.debug('Setting {}={}'.format(pi_name, process_index))
+            os.environ[pi_name] = str(process_index)
+        self.context = zmq.Context()
+        self.comm_loop()

westpa-2022.12.dist-info/AUTHORS

@@ -0,0 +1,22 @@
+WESTPA development is led by Lillian Chong (ltchong@pitt.edu)
+in collaboration with Daniel Zuckerman (zuckermd@ohsu.edu)
+
+The original version of WESTPA was written by Matthew Zwier (matthew.zwier@drake.edu) 
+as part of his Ph.D. dissertation with Lillian Chong.
+
+Other core contributors are the following (in alphabetical order)
+
+Joshua Adelman
+Anthony Bogetti
+Jeremy Leung
+AJ Pratt
+John Russo
+Ali Saglam
+Jeff Thompson
+Kim Wong
+Darian Yang
+She Zhang
+
+The work manager interface is derived from the ``concurrent.futures`` module
+of Python 3.2 by Brian Quinlan, (C) 2011 the Python Software Foundation.
+See http://docs.python.org/3/license.html for more information.

westpa-2022.12.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013 WESTPA Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

westpa-2022.12.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.2
+Name: westpa
+Version: 2022.12
+Summary: WESTPA is a package for constructing and running stochastic simulations using the "weighted ensemble" approach of Huber and Kim (1996).
+Home-page: http://github.com/westpa/westpa
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Cython
+Requires-Python: >=3.9
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: numpy<3,>=1.25.0; python_version >= "3.10"
+Requires-Dist: numpy<2,>=1.25.0; python_version < "3.10"
+Requires-Dist: scipy>=0.19.1
+Requires-Dist: h5py>=2.10
+Requires-Dist: mdtraj>=1.9.5
+Requires-Dist: pyyaml
+Requires-Dist: pyzmq
+Requires-Dist: matplotlib
+Requires-Dist: blessings
+Requires-Dist: ipykernel
+Requires-Dist: tqdm
+Requires-Dist: pandas
+Requires-Dist: tables
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-rerunfailures; extra == "tests"
+Requires-Dist: pytest-timeout; extra == "tests"
+Provides-Extra: mpi
+Requires-Dist: mpi4py; extra == "mpi"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-rerunfailures; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+===============
+WESTPA 2.0 
+===============
+
+|ghactions| |anaconda| |tutorial| 
+
+|docs| |usersgroup| |develgroup| 
+
+.. |ghactions| image:: https://github.com/westpa/westpa/actions/workflows/test.yaml/badge.svg?branch=westpa2
+              :target: https://github.com/westpa/westpa/actions/workflows/test.yaml
+              :alt: GitHub Actions
+
+.. |docs| image:: https://readthedocs.org/projects/westpa/badge/?version=latest
+         :target: https://westpa.readthedocs.io/en/latest/?badge=latest
+         :alt: Documentation Status
+
+.. |tutorial| image:: https://img.shields.io/badge/WESTPA-tutorials-blueviolet.svg
+        :target: https://github.com/westpa/tutorials
+        :alt: WESTPA Tutorials GitHub
+
+.. |usersgroup| image:: https://img.shields.io/badge/Google%20Group-Users-lightgrey.svg
+        :target: http://groups.google.com/group/westpa-users 
+        :alt: Users Google Group
+
+.. |develgroup| image:: https://img.shields.io/badge/Google%20Group-Developers-lightgrey.svg
+        :target: https://groups.google.com/g/westpa-devel 
+        :alt: Developers Google Group
+
+.. |anaconda| image:: https://anaconda.org/conda-forge/westpa/badges/version.svg
+   :alt: Anaconda
+   :target: https://anaconda.org/conda-forge/westpa
+
+
+--------
+Overview
+--------
+
+WESTPA is a package for constructing and running stochastic simulations using the "weighted ensemble" approach 
+of Huber and Kim (1996). For use of WESTPA please cite the following:
+
+Zwier, M.C., Adelman, J.L., Kaus, J.W., Pratt, A.J., Wong, K.F., Rego, N.B., Suarez, E., Lettieri, S.,
+Wang, D.W., Grabe, M., Zuckerman, D.M., and Chong, L.T. "WESTPA: An Interoperable, Highly 
+Scalable Software Package For Weighted Ensemble Simulation and Analysis," J. Chem. Theory Comput., 11: 800−809 (2015). 
+
+Russo, J. D., Zhang, S., Leung, J.M.G., Bogetti, A.T., Thompson, J.P., DeGrave, A.J., Torrillo, P.A., Pratt, A.J., 
+Wong, K.F., Xia, J., Copperman, J., Adelman, J.L., Zwier, M.C., LeBard, D.N., Zuckerman, D.M., Chong, L.T. 
+WESTPA 2.0: High-Performance Upgrades for Weighted Ensemble Simulations and Analysis of Longer-Timescale Applications. 
+J. Chem. Theory Comput., 18 (2): 638–649 (2022).
+
+See this page_ and this powerpoint_ for an overview of weighted ensemble simulation.
+
+To help us fund development and improve WESTPA please fill out a one-minute survey_ and consider 
+contributing documentation or code to the WESTPA community.
+
+WESTPA is free software, licensed under the terms of the MIT License. See the file ``LICENSE`` for more information.
+
+.. _survey: https://docs.google.com/forms/d/e/1FAIpQLSfWaB2aryInU06cXrCyAFmhD_gPibgOfFk-dspLEsXuS9-RGQ/viewform
+.. _page: https://westpa.github.io/westpa/overview.html
+.. _powerpoint: https://docs.google.com/presentation/d/1PKsklN5aYLlLSTDOLdNGti6pcGs4Rgxm/edit?usp=sharing&ouid=117278498028744119802&rtpof=true&sd=true
+
+------------
+Requirements
+------------
+
+WESTPA is written in Python and requires version 3.9 or later. WESTPA also requires a number of Python scientific software packages.
+The simplest way to meet these requirements is to download the
+Anaconda Python distribution from www.anaconda.com (free for all users).
+
+WESTPA currently runs on Unix-like operating systems, including Linux and
+Mac OS X. It is developed and tested on x86_64 machines running Linux.
+
+--------------------------------
+Obtaining and Installing WESTPA
+--------------------------------
+
+WESTPA is developed and tested on Unix-like operating systems, including Linux and Mac OS X.
+
+
+Regardless of the chosen method of installation, before installing WESTPA, we recommend you to first install the Python 3 version provided by the latest free `Anaconda Python distribution`_. After installing Anaconda, create a new python environment for the WESTPA install with the following::
+
+    conda create -n westpa python=3.11
+    conda activate westpa
+
+Then, we recommend installing WESTPA through conda or pip. Execute either of the following::
+
+    conda install -c conda-forge westpa
+
+or::
+
+    python -m pip install westpa
+    
+See the install instructions on our `wiki`_ for more detailed information. 
+    
+
+To install from source (**not recommended**), start by downloading the corresponding tar.gz file from the `releases page`_. After downloading the file, unpack the file and install WESTPA by executing the following::
+
+    tar xvzf westpa-2022.11.tar.gz
+    cd westpa
+    python -m pip install -e .
+
+.. _`releases page`: https://github.com/westpa/westpa/releases
+.. _`Anaconda Python distribution`: https://www.anaconda.com/download
+.. _`wiki`: https://github.com/westpa/westpa/wiki/Installing-WESTPA
+
+---------------
+Getting started
+---------------
+
+High-level tutorials of how to use the WESTPA software can be found here_.
+Further, all WESTPA command-line tools provide detailed help when
+given the -h/--help option.
+
+Finally, while WESTPA is a powerful tool that enables expert simulators to access much longer 
+timescales than is practical with standard simulations, there can be a steep learning curve to 
+figuring out how to effectively run the simulations on your computing resource of choice. 
+For serious users who have completed the online tutorials and are ready for production simulations 
+of their system, we invite you to contact Lillian Chong (ltchong AT pitt DOT edu) about spending 
+a few days with her lab and/or setting up video conferencing sessions to help you get your 
+simulations off the ground.
+
+.. _here: https://github.com/westpa/westpa/wiki/Tutorials
+
+------------
+Getting help
+------------
+
+WESTPA FAQ_
+
+A mailing list for WESTPA is available, at which one can ask questions (or see
+if a question one has was previously addressed). This is the preferred means
+for obtaining help and support. See http://groups.google.com/group/westpa-users
+to sign up or search archived messages.
+
+.. _FAQ: https://github.com/westpa/westpa/wiki/Frequently-Asked-Questions
+ 
+----------
+Developers
+----------
+
+Search archived messages or post to the westpa-devel Google group: https://groups.google.com/group/westpa-devel.