control file

The Iphigenie control file ctl.xml generated by xpl2lis contains all settings for the simulation and the default parameters. This may be confusing at a first glace, but it spares you to memorize keywords, which may also change from version to version. Don't worry, you will probably only need a small subset of them. Since the control file is written in the xml format it is advisable to modify it at first with an editor that supports syntax highlighting and code folding.

1. General Remarks

All sections of the control file can be turned off by setting the active property to false. For example the externalDynamics integrator is turned off in freshly created ctl files

  <externalDynamics active="false">
    <!--read trajectory from a previous calculation-->
    <dcdInputFile/>
    <every>1</every>
  </externalDynamics>

This allows you to comment out sections without getting in conflict with the xml-comments that are already present in the file providing a brief explanation of all keywords. To activate a section one correspondingly sets the active property to true or omits it (the default is active="true"). In our example

  <externalDynamics active="true">
    <!--read trajectory from a previous calculation-->
    <dcdInputFile>trajectory.dcd</dcdInputFile>
    <every>1</every>
  </externalDynamics>

the externalDynamics integrator is now turned on, reading coordinates from trajectory.dcd and recomputing the energy/forces for every frame.

The Iphigenie parser generates at startup an xml template file with all defaults settings. These defaults are overwritten by the individual settings provided by the input file. Thus, it is sufficient to provide only the difference to the default as an input. At startup, iffi writes out a full version of the input including all default settings and a stripped version containing only the differences of your input to the default to the backup directory. The stripped control file provides an easy to read summary of the settings of a simulation and can be used equivalently to the full version.
To generate these stripped files one can also use the ctlstrip tool (be sure that the svn version of ctlstrip matches that of tyour iffi executable, to get the correct default values).

2. Organizing your control file

There are some features that help you to organize your simulations without having to rewrite each input file from the beginning. The iffi control file parser supports simple C-like preprocessing directives for file inclusion and variable substitution by checking lines that start with #include, #define, or #external:

  #include "filename"

includes sections of the control file filename

  #define variable value

substitutes all subsequent occurrences of $variable$ by value, e.g.

  #define MYVAR 3

substitutes all subsequent occurrences of $MYVAR$ by 3. The #external directive

  #external variable envvar

works similarly, but uses the value of the environment variable envvar to substitute $variable$, e.g.

  #define ME  USER

replaces all instances of $ME$ by the value of $USER.

Important for replica exchange runs:
the predefined variable $REPLICA$ is substituted by the id of the replica, e.g. 0,1,2,.. . The format of the $REPLICA$ expansion can be controlled by

  #define REPFMT "[format]"

(the default format is "%03d")

File inclusion an variable substitution occur during on the fly while the input is parsed and are annotated in the log file. The full and stripped copies of the control file generated by iffi contain all inclusions and substitutions.

3. Major sections of the control file

The <iphigenie></iphigenie> section of the control file provides the Iphigenie version number along with the subversion revision number if applicable. In the <settings></settings> subsection the parameters for the simulation are given. Here the major subsections are

• <system></system>
  set the path variables, force field, constraints...
• <integrators></integrators>
  set the time step, number of integration steps, Hessian calculation, Langevin dynamics, external dynamics,....
• <restarting></restarting>
  specify a restart file, choose properties not to read from restart file
• <ensemble></ensemble>
  set thermostats and barostat, define periodic boundary conditions, translation/rotation correction
• <outputoptions></outputoptions>
  steer the writing of various observables like energies, forces, trajectory, restart files, ...
• <longrange></longrange>
  set up clustering, pair list generation, SAMM electrostatics and VDW treatment, HADES reactionfield, polarizable force fields, fluctuating charges
• <freeenergy></freeenergy>
  set up replica exchange/simulated tempering, solute tempering, Hamiltonian replica exchange, PLUMED interface, continuous tempering
• <qmmm></qmmm>
  configure DFT/PMM interface to CPMD

For most keywords (xml tags) a brief comment explains what they are good for.