The BMFF Protocol

BMFF (BatchMin Force Field) is an interprocess communication protocol which allows MacroModel to obtain force-field interactions from an external process. In this context, MacroModel is the client and the external process is the server.

The purpose of this topic is to provide a functional description of the protocol, rather than to define the underlying implementation details. The current implementation is based on pipes. There is no requirement at present that the server be re-entrant; that is, at present, each client process starts up and terminates its own server process.

In the current implementation, the named pipes for communication between MacroModel and the server process are set up in:

  • The directory named in the environment variable FIFO_LOCATION, if this variable exists;

  • Otherwise, /tmp, if this directory exists;

  • Otherwise, the local directory.

A BMFF server normally looks for its startup files (such as its standard parameter file) in the directory $SCHRODINGER/mmshare-vversion/data/fnn, where nn is the value used in arg1 of the FFLD command to invoke the server. However, if the environment variable MMFF_PATH exists, mmff_setup expects to find a valid directory name stored in that variable, and looks for its run-time files there instead.

The MacroModel force field continues to be specified by means of the FFLD command in the command file. In the past (i.e., prior to the implementation of BMFF), the first argument of this command was limited to the values 1 through 5; for example, the value 3 specifies the AMBER force field.

BMFF extends this mechanism as follows. If the first argument to the FFLD command is 10, an external process is started to generate force-field interactions. MacroModel obtains information it needs to initiate, control, and utilize the results of this process from an extended force-field file called fnn.fld, where nn is the value of this argument.

Values between 10 and 99, inclusive, are reserved for assignment by the MacroModel development team; for example, the value 10 is assigned to the MMFF force-field. Then the MMFF force-field file would be called f10.fld. Customers developing their own in-house applications are free to use values of 100 or greater for nn.

The extended force-field file contains, on the first non-blank line, the word Process:, followed by a command line: typically, a process name plus (perhaps) command-line arguments. If the process name contains the character /, the named executable image is used; otherwise, the process with the given name is searched for first in the local directory and, if not found, in the $SCHRODINGER/mmshare-vversion/data directory.

Following the Process: line, there may be one or more Option: lines. These specify command-line options for the server process that the user can invoke by means of arg4 of the FFLD command. Each Option: line should include an integer followed by one or more strings. If an integer given on an Option: line is specified in arg4 of FFLD, then the strings will be appended to the command-line when the process is started. Right now, only a single option specified in this manner can be used at run-time. Both the Process: and the Option: lines use free format; their contents consist of strings separated by spaces, but no tabs are allowed.

Beyond the first few lines, the extended force-field file follows the plan of a normal MacroModel force-field file. The STR, BND, etc. keywords define the equations which MacroModel is to use internally to describe stretches, bends, etc. MacroModel will call on the server, eventually, to obtain the atoms constituting the interactions and the corresponding parameters. For van der Waals and hydrogen-bonding interactions, the constituent atoms are passed to the server as needed, and the corresponding parameters are passed back whenever the pair-list is updated. Universal constants associated with the various interaction equations are specified on the equation lines for BMFF force-fields; see f10.fld for examples. In a BMFF force-field file,

The Main Interaction Section of the file may specify general interactions. If present, these will override the corresponding parameters obtained by the server. Similarly, the Substructure Section may contain overriding parameters for molecular substructures. The substructure section may also specify additional interactions (e.g., remote torsions) not created by the server process. If overriding parameters or added interactions are actually used, a warning message will be printed to the MacroModel log file. The server process may also write to the command file simply by writing to the UNIX standard output.

When the nonbonded pair list is updated, MacroModel (the client) passes each interacting atom-pair to the server and receives back the parameters for that pair; if overriding parameters exist for this pair, the server is not called. (If fast VDW processing is in effect, the client-side library stores a table of nonbonded parameters by pair type. In this situation, the server is never contacted for a nonbonded update. Here, this table is not consulted if overriding parameters exist for the pair in question.)

Before exiting, MacroModel commands the server to terminate.