hoomd-component-template
provides a framework to develop components that extend
HOOMD-blue. It includes template C++ and
Python modules, an example unit test, CMake scripts to build the component, and GitHub Actions
workflows.
To build this component:
- Build and install HOOMD-blue from source.
- Obtain the component's source.
$ git clone https://github.com/glotzerlab/hoomd-component-template
- Configure.
$ cmake -B build/hoomd-component-template -S hoomd-component-template
- Build the component.
$ cmake --build build/hoomd-component-template
- Install the component.
$ cmake --install build/hoomd-component-template
Once installed, the template is available for import via:
import hoomd.template
(replace template
with the COMPONENT_NAME
you set in src/CMakeLists.txt
).
To create a new component:
- Fork hoomd-component-template.
- Address all TODO comments (including those in
.github/
) - Add C++ and Python files to
src/
. - Add unit tests in
src/pytest
. - Format and check code style with pre-commit.
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.
The HOOMD-blue developers will periodically update hoomd-component-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.
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.