Squash-merge of master branch

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

@@ -1442,10 +1442,8 @@
 \item \refkey{gyration}{colvar|gyration}: radius of gyration of a group of atoms;
 \item \refkey{inertia}{colvar|inertia}: moment of inertia of a group of atoms;
 \item \refkey{inertiaZ}{colvar|inertiaZ}: moment of inertia of a group of atoms around a chosen axis;
-\cvnamebasedonly{
 \item \refkey{alpha}{colvar|alpha}: $\alpha$-helix content of a protein segment.
 \item \refkey{dihedralPC}{colvar|dihedralPC}: projection of protein backbone dihedrals onto a dihedral principal component.
-}
 \cvalchlambdaonly{
 \item \refkey{alchLambda}{colvar|alchLambda}: alchemical lambda parameter (for controlling the back-end).
 \item \refkey{alchFlambda}{colvar|alchFlambda}: force along alchLambda.
@@ -2768,17 +2766,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 +2842,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$>$''}{%
+    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 +2887,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 +2969,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 +2989,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 +3034,6 @@
     Number of the eigenvector to be used for this component.}
 \end{cvcoptions}
 
-} % end of \cvnamebasedonly
 
 \cvalchlambdaonly{
 
@@ -7151,11 +7186,12 @@
     dependence of the energy on $\lambda$ around $k_\lambda = 0$.}
 
 \item %
-  \key
+  \keydef
     {targetEquilSteps}{%
     \texttt{harmonic}}{%
     Number of steps discarded from TI estimate}{%
     positive integer}{%
+    0}{%
     Defines the number of steps within each stage that are considered
     equilibration and discarded from the restraint free energy derivative
     estimate reported reported in the output.}

doc/cv_version.tex

@@ -1 +1 @@
-\newcommand{\cvversion}{2024-10-16}
+\newcommand{\cvversion}{2024-11-08}

gromacs/src/applied_forces/colvars/colvarsMDModule.cpp

@@ -110,33 +110,28 @@ class ColvarsMDModule final : public IMDModule
         }
 
         // Writing internal parameters during pre-processing
-        const auto writeInternalParametersFunction = [this](KeyValueTreeObjectBuilder treeBuilder) {
-            colvarsOptions_.writeInternalParametersToKvt(treeBuilder);
-        };
+        const auto writeInternalParametersFunction = [this](KeyValueTreeObjectBuilder treeBuilder)
+        { colvarsOptions_.writeInternalParametersToKvt(treeBuilder); };
         notifier->preProcessingNotifier_.subscribe(writeInternalParametersFunction);
 
         // Access of the topology during pre-processing
-        const auto processTopologyFunction = [this](gmx_mtop_t* mtop) {
-            colvarsOptions_.processTopology(mtop);
-        };
+        const auto processTopologyFunction = [this](gmx_mtop_t* mtop)
+        { colvarsOptions_.processTopology(mtop); };
         notifier->preProcessingNotifier_.subscribe(processTopologyFunction);
 
         // Set Logger during pre-processing
-        const auto setLoggerFunction = [this](const MDLogger& logger) {
-            colvarsOptions_.setLogger(logger);
-        };
+        const auto setLoggerFunction = [this](const MDLogger& logger)
+        { colvarsOptions_.setLogger(logger); };
         notifier->preProcessingNotifier_.subscribe(setLoggerFunction);
 
         //  Notification of the Coordinates, box and pbc during pre-processing
-        const auto processCoordinatesFunction = [this](const CoordinatesAndBoxPreprocessed& coord) {
-            colvarsOptions_.processCoordinates(coord);
-        };
+        const auto processCoordinatesFunction = [this](const CoordinatesAndBoxPreprocessed& coord)
+        { colvarsOptions_.processCoordinates(coord); };
         notifier->preProcessingNotifier_.subscribe(processCoordinatesFunction);
 
         //  Notification for the temperature
-        const auto processTemperatureFunction = [this](const EnsembleTemperature& temp) {
-            colvarsOptions_.processTemperature(temp);
-        };
+        const auto processTemperatureFunction = [this](const EnsembleTemperature& temp)
+        { colvarsOptions_.processTemperature(temp); };
         notifier->preProcessingNotifier_.subscribe(processTemperatureFunction);
     }
 
@@ -165,73 +160,61 @@ class ColvarsMDModule final : public IMDModule
         }
 
         // Reading internal parameters during simulation setup
-        const auto readInternalParametersFunction = [this](const KeyValueTreeObject& tree) {
-            colvarsOptions_.readInternalParametersFromKvt(tree);
-        };
+        const auto readInternalParametersFunction = [this](const KeyValueTreeObject& tree)
+        { colvarsOptions_.readInternalParametersFromKvt(tree); };
         notifier->simulationSetupNotifier_.subscribe(readInternalParametersFunction);
         // Retrieve the LocalAtomSetManager during simulation setup
-        const auto setLocalAtomManagerFunction = [this](LocalAtomSetManager* localAtomSetManager) {
-            this->ColvarsSimulationsParameters_.setLocalAtomSetManager(localAtomSetManager);
-        };
+        const auto setLocalAtomManagerFunction = [this](LocalAtomSetManager* localAtomSetManager)
+        { this->ColvarsSimulationsParameters_.setLocalAtomSetManager(localAtomSetManager); };
         notifier->simulationSetupNotifier_.subscribe(setLocalAtomManagerFunction);
 
         // constructing PBC during simulation setup
-        const auto setPeriodicBoundaryContionsFunction = [this](const PbcType& pbc) {
-            this->ColvarsSimulationsParameters_.setPeriodicBoundaryConditionType(pbc);
-        };
+        const auto setPeriodicBoundaryContionsFunction = [this](const PbcType& pbc)
+        { this->ColvarsSimulationsParameters_.setPeriodicBoundaryConditionType(pbc); };
         notifier->simulationSetupNotifier_.subscribe(setPeriodicBoundaryContionsFunction);
 
         // Retrieve the topology during simulation setup
-        const auto setTopologyFunction = [this](const gmx_mtop_t& mtop) {
-            this->ColvarsSimulationsParameters_.setTopology(mtop);
-        };
+        const auto setTopologyFunction = [this](const gmx_mtop_t& mtop)
+        { this->ColvarsSimulationsParameters_.setTopology(mtop); };
         notifier->simulationSetupNotifier_.subscribe(setTopologyFunction);
 
         // Retrieve the Communication Record during simulations setup
-        const auto setCommFunction = [this](const t_commrec& cr) {
-            this->ColvarsSimulationsParameters_.setComm(cr);
-        };
+        const auto setCommFunction = [this](const t_commrec& cr)
+        { this->ColvarsSimulationsParameters_.setComm(cr); };
         notifier->simulationSetupNotifier_.subscribe(setCommFunction);
 
         // Retrieve the Multisim Record during simulations setup
-        const auto setMultisimFunction = [this](const gmx_multisim_t* ms) {
-            this->ColvarsSimulationsParameters_.setMultisim(ms);
-        };
+        const auto setMultisimFunction = [this](const gmx_multisim_t* ms)
+        { this->ColvarsSimulationsParameters_.setMultisim(ms); };
         notifier->simulationSetupNotifier_.subscribe(setMultisimFunction);
 
         // setting the simulation time step
-        const auto setSimulationTimeStepFunction = [this](const SimulationTimeStep& simulationTimeStep) {
-            this->ColvarsSimulationsParameters_.setSimulationTimeStep(simulationTimeStep.delta_t);
-        };
+        const auto setSimulationTimeStepFunction = [this](const SimulationTimeStep& simulationTimeStep)
+        { this->ColvarsSimulationsParameters_.setSimulationTimeStep(simulationTimeStep.delta_t); };
         notifier->simulationSetupNotifier_.subscribe(setSimulationTimeStepFunction);
         // Saving MDLogger during simulation setup
-        const auto setLoggerFunction = [this](const MDLogger& logger) {
-            this->ColvarsSimulationsParameters_.setLogger(logger);
-        };
+        const auto setLoggerFunction = [this](const MDLogger& logger)
+        { this->ColvarsSimulationsParameters_.setLogger(logger); };
         notifier->simulationSetupNotifier_.subscribe(setLoggerFunction);
 
-        const auto setEdrFileNameFunction = [this](const EdrOutputFilename& filename) {
-            colvarsOptions_.processEdrFilename(filename);
-        };
+        const auto setEdrFileNameFunction = [this](const EdrOutputFilename& filename)
+        { colvarsOptions_.processEdrFilename(filename); };
         notifier->simulationSetupNotifier_.subscribe(setEdrFileNameFunction);
 
         // writing checkpoint data
-        const auto checkpointDataWriting = [this](MDModulesWriteCheckpointData checkpointData) {
-            colvarsForceProvider_->writeCheckpointData(checkpointData, ColvarsModuleInfo::name_);
-        };
+        const auto checkpointDataWriting = [this](MDModulesWriteCheckpointData checkpointData)
+        { colvarsForceProvider_->writeCheckpointData(checkpointData, ColvarsModuleInfo::name_); };
         notifier->checkpointingNotifier_.subscribe(checkpointDataWriting);
 
         // reading checkpoint data
-        const auto checkpointDataReading = [this](MDModulesCheckpointReadingDataOnMain checkpointData) {
-            colvarsState_.readState(checkpointData.checkpointedData_, ColvarsModuleInfo::name_);
-        };
+        const auto checkpointDataReading = [this](MDModulesCheckpointReadingDataOnMain checkpointData)
+        { colvarsState_.readState(checkpointData.checkpointedData_, ColvarsModuleInfo::name_); };
         notifier->checkpointingNotifier_.subscribe(checkpointDataReading);
 
         // Handle the atoms redistributed signal
         const auto handleAtomsRedistributedSignal =
-                [this](const MDModulesAtomsRedistributedSignal& atomsRedistributedSignal) {
-                    colvarsForceProvider_->processAtomsRedistributedSignal(atomsRedistributedSignal);
-                };
+                [this](const MDModulesAtomsRedistributedSignal& atomsRedistributedSignal)
+        { colvarsForceProvider_->processAtomsRedistributedSignal(atomsRedistributedSignal); };
         notifier->simulationSetupNotifier_.subscribe(handleAtomsRedistributedSignal);
     }
 
@@ -263,7 +246,7 @@ class ColvarsMDModule final : public IMDModule
                     colvarsOptions_.colvarsAtomCoords(),
                     colvarsOptions_.colvarsOutputPrefix(),
                     colvarsState_);
-            forceProviders->addForceProvider(colvarsForceProvider_.get());
+            forceProviders->addForceProvider(colvarsForceProvider_.get(), "Colvars");
         }
     }