Develop Plugins

You are here: Home > Develop Plugins

This section will show you how to write your own plugins for PIConGPU. However, you should be familiar with how to use plugins in PIConGPU, first. Last but not least, make sure the plugin you want to create does not already exist.

Plugins in PIConGPU are based on the plugin management system of the underlying libPMacc. Hence, all plugins are ultimately derived from PMacc::IPlugin. libPMacc defines a registration/notification interface. Registered plugins can specify the frequency with which the want to get notified on simulation progress (iterations). Additionally, the IPlugin interface defines methods that enable program-wide checkpoints required for restarting the simulation.

Developing a lightweight plugin

All user-plugins should be created as new classes in the $PICSRC/src/picongpu/plugins/ directory. Assuming that your new plugin will be named MyPlugin create the following file MyPlugin.hpp:

#pragma once

#include "plugins/ILightweightPlugin"

namespace picongpu
{
using namespace PMacc;

class MyPlugin : public ILightweightPlugin
{
public:
  MyPlugin()
  {
    // register our plugin during creation
    Environment<>::get().PluginConnector().registerPlugin(this);
  }

  std::string pluginGetName() const
  {
    return "MyPlugin";
  }

  void notify(uint32_t currentStep)
  {
    // notification callback for simulation step currentStep
    // called every notifyFrequency steps
  }

  void pluginRegisterHelp(po::options_description& desc)
  {
    // register command line parameters for your plugin
    desc.add_options()
      ("myplugin.period", po::value<uint32_t > (&notifyFrequency)->default_value(0),
       "Enable MyPlugin [for each n-th step]");
  }

  void setMappingDescription(MappingDesc *cellDescription)
  {
  }

private:
  uint32_t notifyFrequency;

  void pluginLoad()
  {
    // called when plugin is loaded, command line flags are available here
    // set notification frequency for our plugin at the PluginConnector
    Environment<>::get().PluginConnector().setNotificationFrequency(this, notifyFrequency);
  }

  void pluginUnload()
  {
    // called when plugin is unloaded, cleanup here
  }
};
}

Then, we just need to add an instance of the plugin to $PICSRC/plugins/PluginController.hpp:

#include "plugins/MyPlugin.hpp"
...
/**
* Initialises the controller by adding all user plugins to its internal list.
*/
virtual void init()
{
  ...
  /**
    * Add your plugin here, ...
    */
  plugins.push_back(new MyPlugin());
}
...

Developing a checkpoint/restart-capable plugin

More information

• See Benjamin Schneiders Diploma Thesis page 16ff. (2013)