share/hoomd/plugin_template_cpp/README

   1 Files that come in this template:
   2  - CMakeLists.txt   : main CMake configuration file for the plugin
   3  - FindHOOMD.cmake  : script to find a HOOMD-Blue installation to link against
   4  - README           : This file
   5  - cppmodule        : Directory containing C++ and CUDA source code that interacts with HOOMD
   6  - pymodule         : Directory containing python UI level source code that drives the C++ module
   7
   8 To compile this example plugin, follow steps similar to those in compiling HOOMD-Blue. The process of finding a HOOMD
   9 installation to link to will be fully automatic IF you have hoomd_install_dir/bin in your PATH when running ccmake.
  10
  11 Note that plugins can only be built against a hoomd build that has been installed via a package or compiled and then
  12 installed via 'make install'. Plugins can only be built against hoomd when it is built as a shared library.
  13
  14 $ mkdir plugin_build
  15 $ cd plugin_build
  16 $ ccmake /path/to/plugin_template_cpp
  17 (follow normal cmake steps)
  18 $ make -j6
  19 $ make install
  20
  21 If hoomd is not in your PATH, you can specify the root using
  22 $ ccmake /path/to/plugin_template -DHOOMD_ROOT=/path/to/hoomd
  23 where ${HOOMD_ROOT}/bin/hoomd is where the hoomd executable is installed
  24
  25 By default, make install will install the plugin into
  26 ${HOOMD_ROOT}/lib/hoomd/python_module/hoomd_plugins/plugin_template
  27 This works if you have 'make install'ed hoomd into your home directory.
  28
  29 If hoomd is installed in a system directory (such as via an rpm or deb package), then you can still use plugins.
  30 Delete the plugin_build directory and start over. Set the environment variable HOOMD_PLUGINS_DIR in your .bash_profile
  31  - export HOOMD_PLUGINS_DIR=${HOME}/hoomd_plugins  # as an example
  32 When running ccmake, add -DHOOMD_PLUGINS_DIR=${HOOMD_PLUGINS_DIR} to the options
  33  - ccmake /path/to/plugin_template_cpp -DHOOMD_PLUGINS_DIR=${HOOMD_PLUGINS_DIR}
  34 Now, 'make install' will install the plugins into ${HOOMD_PLUGINS_DIR} and hoomd, when launched, will look there
  35 for the plugins.
  36
  37 The plugin can now be used in any hoomd script.
  38 Example of how to use an installed plugin:
  39
  40 from hoomd_script import *
  41 from hoomd_plugins import plugin_template
  42 init.create_random(N=1000, phi_p=0.20)
  43 plugin_template.update.example(period=10)
  44
  45 To create a plugin that actually does something useful
  46  - copy plugin_template_cpp to a new location
  47  - change the PROJECT() line in CMakeLists.txt to the name of your new plugin. This is the name that it will install to
  48  - Modify the source in cppmodule and pymodule. The existing files in those directories serve as examples and include
  49    many of the details in comments.