glotzerlab / hpmc-energy-template

Template repository for HPMC pair and/or external energy evaluators.

HOOMD-blue component template for HPMC interaction energies

hpmc-energy-template provides a framework to develop components that extend HOOMD-blue with new pairwise and external potentials for HPMC. It includes template C++ and Python modules, an example unit test, CMake scripts to build the component, and GitHub Actions workflows.

Building the component

To build this component:

1. Build and install HOOMD-blue from source.
2. Obtain the component's source.

   $ git clone https://github.com/glotzerlab/hoomd-component-template
   

3. Configure.

   $ cmake -B build/hoomd-component-template -S hoomd-component-template
   

4. Build the component.

   $ cmake --build build/hoomd-component-template
   

5. Install the component.

   $ cmake --install build/hoomd-component-template
   

Once installed, the template is available for import via:

import hoomd.hpmc_energy

(replace template with the COMPONENT_NAME you set in src/CMakeLists.txt).

Creating a new component

To create a new component:

1. Fork hpmc-energy-template.
2. Address all TODO comments (including those in .github/)
3. Add C++ and Python files to src/.
4. Add unit tests in src/pytest.
5. Format and check code style with pre-commit.

Using the provided GitHub Actions configuration

When you push your changes to GitHub, the unit test workflow compile your code on the CPU (with and without MPI) and on the GPU (with and without MPI). The workflow also executes the unit tests on the CPU. You should run GPU unit tests locally, as GitHub does not provide free GPU runners for GitHub Actions. As a one time step, you need to navigate to the "Actions" tab of your repository and confirm that GitHub should execute actions for your fork.

When you push a new tag, the release workflow will create a new GitHub release with automatically generated release notes.

Maintaining your component

The HOOMD-blue developers will periodically update hpmc-energy-template, including updates to the GitHub Actions workflow, pre-commit configuration, and CMake scripts. Merge these changes into your fork to support the latest version of HOOMD-blue.

Documenting and releasing your component

TODO: Document your component in README.md (this file) and remove documentation relevant to the template.

When appropriate:

• Add Sphinx documentation and publish it on readthedocs.
• Add a conda-forge package.
• Announce your component on the HOOMD-blue discussion board.