Colvars as scripted functions of components

When scripting is supported (default in VMD), a colvar may be defined as a custom function of its components, rather than a linear or polynomial combination. When implementing generic functions of Cartesian coordinates rather than functions of existing components, the cartesian component may be particularly useful.

An example of elaborate scripted colvar is given in example 10, in the form of path-based collective variables as defined by Branduardi et al[50]. The required Tcl procedures are provided in the colvartools directory.

• scriptedFunction $\langle\,$ Compute colvar as a scripted function of its components$\,\rangle$
  Context: colvar
  Acceptable values: string
  Description: If this option is specified, the colvar will be computed as a scripted function of the values of its components. To that effect, the user should define two Tcl procedures: calc_$<$ scriptedFunction$>$ and calc_$<$ scriptedFunction$>$ _gradient, both accepting as many parameters as the colvar has components. Values of the components will be passed to those procedures in the order defined by their sorted name strings. Note that if all components are of the same type, their default names are sorted in the order in which they are defined, so that names need only be specified for combinations of components of different types. calc_$<$ scriptedFunction$>$ should return one value of type $<$ scriptedFunctionType$>$ , corresponding to the colvar value. calc_$<$ scriptedFunction$>$ _gradient should return a Tcl list containing the derivatives of the function with respect to each component. If both the function and some of the components are vectors, the gradient is really a Jacobian matrix that should be passed as a linear vector in row-major order, i.e. for a function $f_i(x_j)$ : $\nabla_x f_1 \nabla_x f_2 \cdots$ .

• scriptedFunctionType $\langle\,$ Type of value returned by the scripted colvar$\,\rangle$
  Context: colvar
  Acceptable values: string
  Default value: scalar
  Description: If a colvar is defined as a scripted function, its type is not constrained by the types of its components. With this flag, the user may specify whether the colvar is a scalar or one of the following vector types: vector3 (a 3D vector), unit_vector3 (a normalized 3D vector), or unit_quaternion (a normalized quaternion), or vector (a vector whose size is specified by scriptedFunctionVectorSize). Non-scalar values should be passed as space-separated lists, e.g. ``1. 2. 3.''.

• scriptedFunctionVectorSize $\langle\,$ Dimension of the vector value of a scripted colvar$\,\rangle$
  Context: colvar
  Acceptable values: positive integer
  Description: This parameter is only valid when scriptedFunctionType is set to vector. It defines the vector length of the colvar value returned by the function.