Protein-specific coordinates based on index groups

colvartools/write_index_group.tcl

@@ -1,10 +1,11 @@
 # Write a VMD selection into a GROMACS index file.
 
-# 1st argument is either a Tcl file channel or a file name: in the latter
-# case, content will be appended to that file.
-# 2nd argument is an atom selection proc, as returned by the atomselect
+# Parameters:
+# 1- either a Tcl file channel or a file name: in the latter
+#   case, content will be appended to that file.
+# 2- an atom selection proc, as returned by the atomselect
 # command.
-# 3rd argument is the name of the group.
+# 3- the name of the group.
 
 proc write_index_group { ndxfile sel name } {
     # Check that the name does not contain spaces or tabs
@@ -43,3 +44,41 @@ proc write_index_group { ndxfile sel name } {
         close ${output}
     }
 }
+
+# Write a GROMACS index file suitable for computing the alpha-helix
+# content of a helical segment
+
+# Parameters:
+# 1- either a Tcl file channel or a file name: in the latter
+#   case, content will be appended to that file.
+# 2- a selection text returning contiguous amino-acid residues
+# 3- optional: molecule id (default: top)
+# 4- optional: prefix for the group names (default: alpha_)
+
+proc write_alpha_groups { ndxfile seltext { mol top } { prefix alpha_ } } {
+
+    foreach atomname { N CA O } {
+        set sel [atomselect $mol "($seltext) and name $atomname"]
+        write_index_group $ndxfile $sel "${prefix}${atomname}"
+        $sel delete
+    }
+}
+
+# Write a GROMACS index file suitable for computing the dihedralPC
+# projection of a peptide chain
+
+# Parameters:
+# 1- either a Tcl file channel or a file name: in the latter
+#   case, content will be appended to that file.
+# 2- a selection text returning contiguous amino-acid residues
+# 3- optional: molecule id (default: top)
+# 4- optional: prefix for the group names (default: alpha_)
+
+proc write_dihedralPC_groups { ndxfile seltext { mol top } { prefix dihed_ } } {
+
+    foreach atomname { CA N C } {
+        set sel [atomselect $mol "($seltext) and name $atomname"]
+        write_index_group $ndxfile $sel "${prefix}${atomname}"
+        $sel delete
+    }
+}

doc/colvars-refman-main.tex

@@ -2768,17 +2768,21 @@
 \end{cvcoptions}
 
 
-\cvnamebasedonly{
+
 
 \cvsubsec{Protein structure descriptors}{sec:cvc_protein}
 
 \cvsubsubsec{\texttt{alpha}: $\alpha$-helix content of a protein segment.}{sec:cvc_alpha}
 \labelkey{colvar|alpha}
 
-The block \texttt{alpha~\{...\}} defines the
-parameters to calculate the helical content of a segment of protein
-residues.  The $\alpha$-helical content across the $N+1$ residues
-$N_{0}$ to $N_{0}+N$ is calculated by the formula:
+The block \texttt{alpha~\{...\}} defines a measure of the helical content of a segment of
+protein residues, as a tunable combination of an angle term between alpha carbon atoms, and a
+1-4 hydrogen-bond term.
+To create a colvar that computes the helical content of a protein with several,
+non-contiguous helical segments, just define several \texttt{alpha} blocks inside a single \text{colvar} block,
+and give them linear combination coefficients that sum to 1 (see \texttt{componentCoeff} in section \ref{sec:cvc_superp}).
+
+The $\alpha$-helical content across the $N+1$ residues $N_{0}$ to $N_{0}+N$ is calculated by the formula:
 \begin{eqnarray}
   \label{eq:colvars_alpha}
   {
@@ -2840,15 +2844,35 @@
 \mathrm{N}^{(n+4)}$ hydrogen bond is defined through a \texttt{hBond}
 colvar component on the same atoms.
 
+
 \begin{cvcoptions}
+  \item %
+  \labelkey{colvar|alpha|prefix}
+  \keydef
+    {prefix}{%
+      \texttt{alpha}}{%
+      Prefix of atom groups to be used for computing the $\alpha$-helix content}{%
+      string}{%
+      \texttt{alpha\_}}{%
+    Atoms involved in an alpha-helix component are based on groups defined within a
+    GROMACS-style index file specified with \refkey{indexFile}{Colvars-global|indexFile} in the global
+    Colvars configuration, i.e. outside of a \texttt{colvar} block.
+    The group names must use a common prefix followed by atom names, e.g. \texttt{alpha\_N}, \texttt{alpha\_CA},
+    and \texttt{alpha\_O} when using the default prefix \texttt{alpha\_}.
+    The CA group is only required when the angle term is enabled, that is when \texttt{hBondCoeff} is less than 1.
+    This option lets users set a different prefix, for example, when several $\alpha$-helical segments
+    must be tracked.}
 
+\cvnamebasedonly{
 \item %
   \labelkey{colvar|alpha|residueRange}
   \key
     {residueRange}{%
       \texttt{alpha}}{%
       Potential $\alpha$-helical residues}{%
     ``$<$Initial residue number$>$-$<$Final residue number$>$''}{%
+    Alternately, in some back-ends like NAMD and VMD, the atoms may be defined using their PSF segment name (segname)
+    and a range of residue numbers.
     This option specifies the range of residues on which this
     component should be defined.  The Colvars module looks for the
     atoms within these residues named ``\texttt{CA}'', ``\texttt{N}''
@@ -2865,7 +2889,7 @@
     This option sets the PSF segment identifier for the residues
     specified in \texttt{residueRange}.  This option is only required
     when PSF topologies are used.}
-
+} % end of \cvnamebasedonly
 
 \item %
   \labelkey{colvar|alpha|hBondCoeff}
@@ -2947,7 +2971,7 @@
 \labelkey{colvar|dihedralPC}
 
 The block \texttt{dihedralPC~\{...\}} defines the
-parameters to calculate the projection of backbone dihedral angles within
+parameters of the projection of backbone dihedral angles within
 a protein segment onto a \emph{dihedral principal component}, following
 the formalism of dihedral principal component analysis (dPCA) proposed by
 Mu et al.\cite{Mu2005} and documented in detail by Altis et
@@ -2967,17 +2991,31 @@
 + k_{4n-1} \cos (\phi_{n+1}) + k_{4n} \sin(\phi_{n+1})
 \end{equation}
 
-\texttt{dihedralPC} expects the same parameters as the \texttt{alpha}
-component for defining the relevant residues (\texttt{residueRange}
-and \texttt{psfSegID}) in addition to the following:
+The atoms involved in \texttt{dihedralPC} are defined by the same parameters as the \texttt{alpha}
+component.
 
 \begin{cvcoptions}
-
+  \item %
+  \labelkey{colvar|dihedralPC|prefix}
+  \keydef
+    {prefix}{%
+      \texttt{dihedralPC}}{%
+      Prefix of atom groups to be used for computing a dihedralPC projection}{%
+      string}{%
+      \texttt{dihed\_}}{%
+    Backbone atoms involved in a \texttt{dihedralPC} component are based on groups defined within a
+    GROMACS-style index file specified with \refkey{indexFile}{Colvars-global|indexFile} in the global
+    Colvars configuration, i.e. outside of a \texttt{colvar} block.
+    The group names must use a common prefix followed by atom names CA, N, and C, e.g. \texttt{dihed\_CA},
+    \texttt{dihed\_N}, and \texttt{dihed\_C} when using the default prefix \texttt{dihed\_}.}
+
+  \cvnamebasedonly{
 \item %
   \dupkey{residueRange}{\texttt{dihedralPC}}{colvar|alpha|residueRange}{\texttt{alpha} component}
 
 \item %
   \dupkey{psfSegID}{\texttt{dihedralPC}}{colvar|alpha|psfSegID}{\texttt{alpha} component}
+} % end of \cvnamebasedonly
 
 \item %
   \key
@@ -2998,7 +3036,6 @@
     Number of the eigenvector to be used for this component.}
 \end{cvcoptions}
 
-} % end of \cvnamebasedonly
 
 \cvalchlambdaonly{