How to add a new command-line tool

To implement a command line tool you need to create a single cpp file call CLToolNAME.cpp.

You can, in a command line tool, use functionality from plumed to perform simple post-processing tasks. For example, sum_hills uses the functionality inside from inside the biasing PLMD::Action, PLMD::BiasMetaD to calculate free energy surfaces. Regardless, of what you are endeavoring to do your CLToolNAME.cpp file should be formatted in accordance with the following template:

#include "CLTool.h"
#include "CLToolRegister.h"
#include "PlumedConfig.h"
#include "ActionRegister.h"

using namespace std;

namespace PLMD {
/**
//+PLUMEDOC TOOLS name

Insert the documentation for your new tool here

\par Examples

Insert some examples of how to use your tool here

*/
//+ENDPLUMEDOC

/******* This is how you should declare the class for your command line tool.  main() does
         all the analsysis you require. The constructor and the registerKeywords routine 
         only do anything if you are using one of the template forms of input described below.
         However, reigsterKeywords() must always be declared.

class CLToolNAME:
public CLTool
{
public:
  static void registerKeywords( Keywords& keys );
  CLToolNAME(const CLToolOptions& co );
  int main(FILE* in, FILE*out,Communicator& pc);
  string description()const{
    return "a description of the particular kind of task CLToolNAME performs";
  }
};

PLUMED_REGISTER_CLTOOL(CLToolNAME,"name")

Insert the code for main, registerKeywords and the constructor here.

}  /--- don't forget to close the namespace PLMD { at the end of the file

Input

The input stream is passed to main so you can create tools that have an input in any form. However, there are certain standardized forms of input that can be used for command line tools. If your tool takes its input in one of these forms we strongly encourage you to use the code that is already present. If you do so a great deal of manual generation will be looked after automatically.

There are two command line input types that are implemented in the base class. The first is for tools such as driver where the input is specified using a series of command line flags e.g.

plumed driver --plumed plumed.dat --ixyz trajectory.xyz --dump-forces

The other are tools like simplmd that take an input file that contains one directive per line and a corresponding value for that directive. For both these forms of input it is possible to read in everything that is required to run the calculation prior to the actual running of the calculation. In other words these the user is not prompted to provide input data once the main calculation has started running (N.B. you can do tools with input of this sort though as the input stream is passed to main).

If you wish to use driver-like or simple-md like input then you have to specify this in the constructor. For driver-like input you would write the following for the constructor:

CLToolNAME::CLToolNAME(const CLToolOptions& co ):
CLTool(co)
{
 inputdata=commandline;
}

For simplemd-like input you write the following for the constructor:

CLToolNAME( const CLToolOptions& co ) :
CLTool(co)
{
  inputdata=ifile;
}

If you are not using one of these input forms then you don't need to write a constructor although you may choose to for reasons not connected to the input of data.

Once you have created the constructor the actual readin and manual creation is done in much the same manner as it is done for Actions in the main plumed code (Creating plumed documentation). You write a registerKeywords routine as follows:

void CLToolNAME::registerKeywords( Keywords& keys ){
  CLTool::registerKeywords( keys );
}  

Inside this routine you add descriptions of all your various command-line flags (driver-like) or input directives (simple-md-like) and these descriptions are used to create the manual. The code will automatically check if a particular flag is present and read any input directive connected with a particular flag (i.e. the data after the space). Within main you can recover the read in data using CLTool::parse and CLTool:parseFlag.

Re-using plumed

To re-use the functionality that is present in plumed you use the same tools that are used to patch the various MD codes (How to add plumed to an MD code). Alternatively, if you want to create an instance of a particular Action you can do so by issuing the following commands:

PlumedMain* plumed=new PlumedMain(); std::vector<std::string> words;
Action* action=actionRegister().create(ActionOptions(plumed,words));
delete plumed; delete action;

Please be aware that words should contain everything that would be required in an input line to make a valid instance of the Action you require.