Table of Contents 1. Introduction 2. Organization of WESTPA 3. Contributing to WESTPA Guidelines: Development process: 1. Post your coding plans 2. Develop your contribution 3. Submit your contribution 4. Review process 5. Document changes 6. Cross referencing issues Stylistic Guidelines Writing pytests for WESTPA Test Coverage Writing Plugins Publishing a WESTPA release

Thank you for your interest in contributing to WESTPA! This guide is intended to facilitate your coding efforts by outlining the organization of WESTPA and the development process that should be followed.

Code contributions may involve either directly adding features to the WESTPA software (e.g. replacing an existing WESTPA module with a modified module) or Writing Plugins:

• Replacing an existing module. For example, if you would like to modify the WE resampler (split/merge) scheme, we suggest replacing the resampler module with a modified resampler module.
• Writing a plugin. If you would like to make use of data already outputted by WESTPA or apply any functions either before or after the resampler step, we suggest developing a WESTPA plugin (e.g., implementing a particular progress coordinate, as in the plugin for a WE-based string method).

As a start, the following video discussions involving WESTPA development may be helpful to you:

• Overview of WESTPA 1.0
• WESTPA 1.0 code Q&A
• Plans for a WESTPA-Orion Interface
• Overview of WESTPA 2.0 (Slides from the video)

For more information about the installation process, see our Setting Up a Development Environment Page.

Other resources include our GitHub Issue Tracker, archives of the WESTPA developer's mailing list, and Sphinx API documentation of the WESTPA code from autogenerated docstrings. Please note our Code of Conduct.

WESTPA is designed to be highly scalable, interoperable with any dynamics engine (e.g. Amber, OpenMM, NAMD, etc.), and modular, where each component of WESTPA can be swapped out or customized as needed (Figure 1). Figure 2 shows key steps of running a weighted ensemble simulation within the WESTPA framework.

Figure 1 | Logical structure of WESTPA. Components in blue are implemented in WESTPA and may be replaced, if desired, by custom code. Components in yellow are managed by WESTPA and can generally be customized using configuration options. Components in red are defined by the user, typically as Python modules, shell scripts, or compiled executables. This diagram is taken from the original WESTPA software paper (Zwier et al., 2015).

HDF5 File Organization of Simulation Data

Index of Command-Line Tools

• All contributions are submitted by making Pull Requests (PRs), even from developers who have write permission on the WESTPA repository.
• All code should pass the GitHub Actions continuous integration (CI) tests.
• All code should be documented (Section 5).
• No changes are ever committed without review and approval by a core WESTPA developer. Every effort will be made to respond to a Pull Request (PR) within a week.

To post your coding plans, please open an issue or comment on a relevant issue on GitHub, using the appropriate labels. To avoid any duplication of efforts, @ltchong may contact you to set up a videoconferencing call with other developers to discuss your plans.

If @ltchong or @mczwier confirms that your coding plans are not duplicating existing efforts, create your own copy of the WESTPA repository by clicking on the Fork button on GitHub and develop your contribution in this separate fork. To adhere to the Stylistic Guidelines, make sure you have pre-commit configured and test your contribution locally using pytest.

All GitHub Actions continuous integration (CI) tests, including unit/functional tests and checks on coding style must pass before submitting your contribution. If any CI tests fail, you can find out why by clicking on the “failed” icon (red cross) and inspecting the build and test log. To avoid overuse and waste of this resource, please test your work locally before committing.

All documentation must build properly with Read the Docs. Please check code documentation before committing.

Submit your contribution by making a PR using the PR template. If your contribution introduces a new feature or changes functionality, please explain in a PR comment. Make sure the PR is set to merge to the develop branch.

Reviewers (other developers and interested community members) will comment inline on your PR to help you improve its implementation, documentation, and style. Every single developer working on the project has their code reviewed with the intention of a friendly conversation from which we all learn to improve the quality of the project.

To update your PR, make your changes on your fork, commit, run tests, and only if they succeed, push to your fork. As soon as those changes are pushed up (to the same branch as before) the PR will update automatically. The GitHub Actions CI services are triggered after each PR update. If you do not know how to fix the test failures, you may still push your changes and ask for help in a PR comment.

A PR must be approved by at least one core WESTPA developer before merging. Approval means the core developer has carefully reviewed the changes, and the PR is ready for merging.

Beyond changes to a functions docstring and possible description in the general documentation, if your change introduces any user-facing modifications they may need to be mentioned in the release notes. To add your change to the release notes, you need to create a short file with a summary and place it in CHANGELOG. The file README.rst details the format and filename conventions. If your change introduces a deprecation, make sure to discuss this first on GitHub.

If the PR relates to any issues, you can add the text xref gh-xxxx where xxxx is the number of the issue to GitHub comments. Likewise, if the PR solves an issue, replace the xref with closes, fixes or any of the other flavors GitHub accepts. In the source code, be sure to preface any issue or PR reference with gh-xxxx.