Colvars scripting

This interface is particularly useful to implement custom biases as scripted colvar forces. See the scriptedColvarForces option in . Note that scripting commands may not be used directly in the NAMD configuration file before the first run or minimize statement. They may be used either within the callback procedures (e.g. calc_colvar_forces) or in the NAMD config file after a run or minimize statement.

Collective variables and biases can be added, queried and deleted through the scripting command cv, with the following syntax: cv $<$ subcommand$>$ [args...]. For example, to query the value of a collective variable named myVar, use the following syntax: set value [cv colvar myVar value]. All subcommands of cv are documented below.

2]

#1

Managing the Colvars module

• configfile $<$ file name$>$ : read configuration from a file;
• config $<$ string$>$ : read configuration from the given string; both config and configfile subcommands may be invoked multiple times;
• reset: delete all internal configuration of the Colvars module;
• version: return the version of the colvars code.

Input and output

• list: return a list of all currently defined variables;
• list biases: return a list of all currently defined biases (i.e. sampling and analysis algorithms);
• load $<$ file name$>$ : load a collective variables state file, typically produced during a previous simulation;
• load $<$ prefix$>$ : same as above, but without the .colvars.state suffix;
• save $<$ prefix$>$ : save the current state in a file whose name begins with the given argument; if any of the biases have additional output files defined, those are saved as well using the same prefix;
• update: recalculate all colvars and biases based on the current atomic coordinates;
• addenergy $<$ E$>$ : add value E to the total bias energy; this must be used within calc_colvar_forces;
• printframe: return a summary of the current frame, in a format equivalent to a line of the collective variables trajectory file;
• printframelabels: return text labels for the columns of printframe's output;

Accessing collective variables

• colvar $<$ name$>$ value: return the current value of colvar $<$ name$>$ ;
• colvar $<$ name$>$ update: recalculate colvar $<$ name$>$ ;
• colvar $<$ name$>$ type: return the type of colvar $<$ name$>$ ;
• colvar $<$ name$>$ addforce $<$ F$>$ : apply given force on colvar $<$ name$>$ ;
• colvar $<$ name$>$ getappliedforce: get the force currently being applied on colvar $<$ name$>$ ;
• colvar $<$ name$>$ gettotalforce: get the total force acting on colvar $<$ name$>$ at the previous step (see );
• colvar $<$ name$>$ getconfig: return config string of colvar $<$ name$>$ .
• colvar $<$ name$>$ cvcflags $<$ flags$>$ : for a colvar with several CVCs (numbered according to their name string order), set which CVCs are enabled or disabled in subsequent evaluations according to a list of 0/1 flags (one per CVC).
• colvar $<$ name$>$ modifycvcs $<$ strings$>$ : for a colvar with one or more CVCs (numbered according to their name string order), pass a list of new configuration strings to modify each CVC without needing to delete the colvar. This option is currently limited to changing the values of componentCoeff and componentExp (e.g. to update the polynomial superposition parameters on the fly), of period and wrapAround (e.g. to update the period of variables such as distanceZ), and of the forceNoPBC option for those CVCs that support it. Changes in configuration done by this command are not saved to state files, and are lost when restarting a simulation, deleting the parent colvar, or resetting the module with cv reset.

Accessing biases

• bias $<$ name$>$ energy: return the current energy of the bias $<$ name$>$ ;
• bias $<$ name$>$ update: recalculate the bias $<$ name$>$ ;
• bias $<$ name$>$ delete: delete the bias $<$ name$>$ ;
• bias $<$ name$>$ getconfig: return config string of bias $<$ name$>$ .

<35348>>Collective variables and biases can be added, queried and deleted through the scripting command cv, with the following syntax: cv $<$ subcommand$>$ [args...]. For example, to query the value of a collective variable named myVar, use the following syntax: set value [cv colvar myVar value]. All subcommands of cv are documented below.

#1

<35649>>

Managing the colvars module

• configfile $<$ file name$>$ : read configuration from a file;
• config $<$ string$>$ : read configuration from the given string; both config and configfile subcommands may be invoked multiple times;
• reset: delete all internal configuration of the colvars module;
• version: return the version of the colvars code.

Input and output

• list: return a list of all currently defined variables;
• list biases: return a list of all currently defined biases (i.e. sampling and analysis algorithms);
• load $<$ file name$>$ : load a collective variables state file, typically produced during a simulation;
• save $<$ prefix$>$ : save the current state in a file whose name begins with the given argument; if any of the biases have additional output files defined, those are saved as well;
• update: recalculate all colvars and biases based on the current atomic coordinates;
• printframe: return a summary of the current frame, in a format equivalent to a line of the collective variables trajectory file;
• printframelabels: return text labels for the columns of printframe's output;

Accessing collective variables

• colvar $<$ name$>$ value: return the current value of colvar $<$ name$>$ ;
• colvar $<$ name$>$ update: recalculate colvar $<$ name$>$ ;
• colvar $<$ name$>$ type: return the type of colvar $<$ name$>$ ;
• colvar $<$ name$>$ delete: delete colvar $<$ name$>$ ;
• colvar $<$ name$>$ addforce $<$ F$>$ : apply given force on colvar $<$ name$>$ ;
• colvar $<$ name$>$ getconfig: return config string of colvar $<$ name$>$ .
• colvar $<$ name$>$ cvcflags $<$ flags$>$ : for a colvar with several cvcs (numbered according to their name string order), set which cvcs are enabled or disabled in subsequent evaluations according to a list of 0/1 flags (one per cvc).

Accessing biases

• bias $<$ name$>$ energy: return the current energy of the bias $<$ name$>$ ;
• bias $<$ name$>$ update: recalculate the bias $<$ name$>$ ;
• bias $<$ name$>$ delete: delete the bias $<$ name$>$ ;
• bias $<$ name$>$ getconfig: return config string of bias $<$ name$>$ .

The following configuration options can modify the behavior of the scripting interface for optimization purposes:

• scriptingAfterBiases $<$ Scripted colvar forces need updated biases $>$
  Context: global
  Acceptable Values: boolean
  Default Value: on
  Description: This flag specifies that the calc_colvar_forces procedure, when defined, is executed only after all biases have been updated. For example, this allows using the energy of a restraint bias, or the force applied on a colvar, to calculate additional scripted forces, such as boundary constraints. When this flag is set to off, it is assumed that only the values of their colvars (but not their energy or forces) will be used by calc_colvar_forces: this can be used to schedule the calculation of scripted forces and biases concurrently to increase performance.