Skip to content

Deprecate "enableFitGradients no" #869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HanatoK wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Deprecate "enableFitGradients no" #869

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cd0dd63
test: add new tests with "enableFitGradients yes"
HanatoK Oct 17, 2025
f2af1d8
fix: add a warning when fit gradients are disabled when it should not
HanatoK Oct 17, 2025
f5bd1e7
doc: Update fit gradient documentation
jhenin Apr 2, 2026
fb7c29e
test: remove enablefitgradients no from unit tests
jhenin Apr 2, 2026
69f9036
fix: cvmodule pointer
jhenin Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cmake/buildColvarsTests.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ if(BUILD_TESTS)
endforeach()

# Copy input files (coordinates, index files, etc)
add_custom_command(TARGET copy_test_files
add_custom_command(TARGET copy_test_files POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_directory
${COLVARS_SOURCE_DIR}/tests/input_files
${CMAKE_BINARY_DIR}/tests/functional
Expand Down
33 changes: 10 additions & 23 deletions doc/colvars-refman-main.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5219,7 +5219,6 @@
This atom group itself}{%
If either \texttt{centerToReference} or \texttt{rotateToReference} is defined, this keyword defines an alternate atom group to calculate the optimal roto-translation.
Use this option to define a continuous rotation if the structure of the group involved changes significantly (a typical symptom would be the message ``Warning: discontinuous rotation!'').
\textbf{Performance considerations:} note that enabling this option will result in projecting each of the atomic gradients of the colvar (e.g.{} the RMSD) onto each the gradients of the roto-translation, which may be a computationally expensive operation: see the closely related \refkey{enableFitGradients}{atom-group|enableFitGradients} for details.%
}

\end{itemize}
Expand Down Expand Up @@ -5253,34 +5252,22 @@
\end{cvexampleinput}
}

The following options have default values appropriate for the vast majority of applications, and are only provided to support rare, special cases.
\begin{itemize}

\item %
\labelkey{atom-group|enableFitGradients} %
\keydef%
{enableFitGradients}{%
atom group}{%
Include the roto-translational contribution to colvar gradients}{%
boolean}{%
\texttt{on}}{%
When either \texttt{centerToReference} or \texttt{rotateToReference} is on,
the gradients of some colvars include terms proportional to
$\partial{}R/\partial\mathbf{x}_{i}$ (rotational gradients) and
$\partial\mathbf{x}^{\mathrm{C}}/\partial\mathbf{x}_{i}$ (translational gradients).
In practice, these terms are calculated as follows,\newline
$\begin{aligned}
\cvsubsubsec{Note on fit gradients}{sec:fit_gradients}

When either \texttt{centerToReference} or \texttt{rotateToReference} is on,
the gradients of some colvars include terms proportional to
$\partial{}R/\partial\mathbf{x}_{i}$ (rotational gradients) and
$\partial\mathbf{x}^{\mathrm{C}}/\partial\mathbf{x}_{i}$ (translational gradients).
In practice, these terms are calculated as follows,\newline
$\begin{aligned}
\nabla_k \zeta(\mathbf{X})&=\sum_{l,\rm main}\left[\nabla_l f \cdot \nabla_k R\left(\mathbf{x}_l-\mathbf{\bar{x}}^{\rm (fit)}\right) - \frac{1}{n^{\rm (fit)}} \nabla_l f \cdot R \mathbbm{1}\right] \\
&=\left(\sum_{l,\rm main}\nabla_l f \cdot\frac{\partial R}{\partial q_0}\left(\mathbf{x}_l-\mathbf{\bar{x}}^{\rm (fit)}\right), \sum_{l,\rm main}\nabla_l f \cdot\frac{\partial R}{\partial q_1}\left(\mathbf{x}_l-\mathbf{\bar{x}}^{\rm (fit)}\right), \sum_{l,\rm main}\nabla_l f \cdot\frac{\partial R}{\partial q_2}\left(\mathbf{x}_l-\mathbf{\bar{x}}^{\rm (fit)}\right), \right.\\
&\left.\sum_{l,\rm main}\nabla_l f \cdot\frac{\partial R}{\partial q_3}\left(\mathbf{x}_l-\mathbf{\bar{x}}^{\rm (fit)}\right)\right) \cdot \left(\nabla_k q_0, \nabla_k q_1, \nabla_k q_2, \nabla_k q_3\right)-\frac{1}{n^{\rm (fit)}} R^{\intercal}\sum_{l,\rm main}{\nabla_l f}
\end{aligned}$\newline
By default, these terms are calculated and included in the total gradients;
if this option is set to \texttt{off}, they are neglected.
In the case of a minimum RMSD component, this flag is automatically disabled because the contributions of those derivatives to the gradients cancel out; other types of variable will require projecting each of the gradients of the variable onto each of the gradients of the roto-translation.
When \refkey{fittingGroup}{atom-group|fittingGroup} is enabled, the computation is a $O(n^{(\rm fit)}+n^{(\rm main)})$ loop for all variables, including RMSDs.
}

\end{itemize}
In the case of a minimum RMSD component, the contributions of those derivatives to the gradients cancel out, so this term is not computed. Other types of variable require projecting each of the gradients of the variable onto each of the gradients of the roto-translation.
When \refkey{fittingGroup}{atom-group|fittingGroup} is enabled, the computation is a $O(n^{(\rm fit)}+n^{(\rm main)})$ loop -- that is, linear in both atom group sizes, for all variables including RMSDs.


\cvsubsec{Treatment of periodic boundary conditions.}{sec:colvar_atom_groups_wrapping}
Expand Down
6 changes: 6 additions & 0 deletions src/colvaratoms.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -928,6 +928,12 @@ int cvm::atom_group::parse_fitting_options(std::string const &group_conf) {
if (b_fit_gradients && (is_enabled(f_ag_center) || is_enabled(f_ag_rotate))) {
enable(f_ag_fit_gradients);
}

if (!b_fit_gradients && (is_enabled(f_ag_center) || is_enabled(f_ag_rotate))) {
cvmodule->log(
"Warning: the fit gradients are manually disabled, which shouldn't be, "
"unless you are sure that the forces on the fitting group are exactly zero.\n");
}
}

return COLVARS_OK;
Expand Down
2 changes: 0 additions & 2 deletions tests/distancedir-fitgroup.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ colvar {
indexGroup group1
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
fittingGroup {
indexGroup heavy_atoms
}
Expand All @@ -21,7 +20,6 @@ colvar {
indexGroup group2
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
fittingGroup {
indexGroup heavy_atoms
}
Expand Down
4 changes: 0 additions & 4 deletions tests/distancevec-PDBflags.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ colvar {

centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsFile ../Common/da-flags.pdb
refPositionsCol B
refPositionsColValue 1
Expand All @@ -29,7 +28,6 @@ colvar {

centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsFile ../Common/da-flags.pdb
refPositionsCol B
refPositionsColValue 2
Expand All @@ -53,7 +51,6 @@ colvar {

centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsFile ../Common/da-partial.pdb
}
group2 {
Expand All @@ -63,7 +60,6 @@ colvar {

centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsFile ../Common/da-flags.pdb
refPositionsCol B
refPositionsColValue 2
Expand Down
2 changes: 0 additions & 2 deletions tests/distancevec-fitgroup.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ colvar {
indexGroup group1
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
fittingGroup {
indexGroup heavy_atoms
}
Expand All @@ -21,7 +20,6 @@ colvar {
indexGroup group2
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
fittingGroup {
indexGroup heavy_atoms
}
Expand Down
2 changes: 0 additions & 2 deletions tests/distancevec-refposgroup.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ colvar {
indexGroup group1
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsGroup {
indexGroup heavy_atoms
}
Expand All @@ -21,7 +20,6 @@ colvar {
indexGroup group2
centerToReference yes
rotateToReference yes
enableFitGradients no # Not available because gradients are implicit
refPositionsGroup {
indexGroup heavy_atoms
}
Expand Down
2 changes: 1 addition & 1 deletion tests/input_files/distancedir-fitgroup_harmonic-ddir-fixed/AutoDiff/test_out.colvars.state
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
configuration {
step 5
dt 1.000000e+00
version 2025-08-30
version 2026-01-22
units real
}

Expand Down
102 changes: 51 additions & 51 deletions tests/input_files/distancedir-fitgroup_harmonic-ddir-fixed/AutoDiff/test_out_forces_0.dat
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,54 @@
-8.405943914527e-04 7.704099463114e-05 4.177459781188e-05
-8.405943914527e-04 7.704099463114e-05 4.177459781188e-05
-8.405943914527e-04 7.704099463114e-05 4.177459781188e-05
-8.405943914527e-04 7.704099463114e-05 4.177459781188e-05
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
8.405943914527e-04 -7.704099463114e-05 -4.177459781188e-05
8.405943914527e-04 -7.704099463114e-05 -4.177459781188e-05
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
8.405943914527e-04 -7.704099463114e-05 -4.177459781188e-05
8.405943914527e-04 -7.704099463114e-05 -4.177459781188e-05
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
-8.725373121708e-04 1.396157628656e-04 1.468999733023e-05
-8.515139910464e-04 1.630794191063e-04 3.664383005090e-05
-8.353259671796e-04 1.476114574159e-04 5.140698673066e-05
-8.451909649194e-04 1.308891674947e-04 4.074060617816e-05
-2.405252056948e-05 1.229346811442e-04 -1.555303345629e-05
8.714839147281e-04 -4.472638229862e-07 -6.828411628595e-06
8.905407287112e-04 -1.580219806965e-05 1.073327892612e-05
7.697005389404e-05 7.506107571621e-05 7.968441501584e-05
8.845361881888e-04 -8.715463527802e-06 5.343414864208e-06
8.859101443095e-04 -3.331847968577e-05 5.109253011696e-06
3.620615924179e-05 1.022338625025e-04 4.175648080748e-05
2.856977936244e-05 1.123703706188e-04 3.497358805577e-05
2.397555024283e-05 1.538564489964e-04 3.315250204856e-05
4.410811638229e-06 9.378889723142e-05 1.028053828552e-05
2.990170888306e-06 8.240282581954e-05 8.171210927034e-06
-1.498972638724e-05 8.923582355713e-05 -8.886809787458e-06
-3.846503349375e-05 7.062291020898e-05 -3.291666922504e-05
-5.861072686187e-05 7.798189535571e-05 -5.204841062765e-05
-3.311330103840e-05 2.994593543767e-05 -3.030687184558e-05
-4.232949856573e-05 1.350325784972e-05 -4.032411895270e-05
-1.708802475624e-05 1.310732830013e-05 -1.578958953060e-05
-7.900674188910e-06 -2.447245812187e-05 -9.249987988521e-06
8.462951653648e-06 -3.435631463971e-05 6.040598685984e-06
7.867862963973e-06 -3.268402765284e-05 5.568363811267e-06
3.622504530921e-06 -5.917179828029e-05 -2.537093932768e-07
2.588728899993e-05 -9.123764634476e-06 2.460559237208e-05
4.051837841003e-05 -1.105660660634e-05 3.871813898211e-05
6.033172884349e-05 1.908951911314e-05 5.992138283444e-05
2.352997783218e-05 -8.158109082755e-06 2.237360338971e-05
2.660866606901e-05 -2.981182236203e-05 2.398646252000e-05
4.642672300044e-06 1.830187510778e-05 5.685951053836e-06
-1.392458239711e-05 2.277043825320e-05 -1.209454490887e-05
-3.044551378676e-05 5.808096991105e-05 -2.591458126572e-05
-3.165359427002e-05 -9.081377843787e-06 -3.137865513894e-05
-3.680086353342e-05 -2.088355979333e-05 -3.714054150345e-05
-4.101014391493e-05 -2.436494800327e-05 -4.145844983319e-05
-5.621925018595e-05 -5.645559662355e-05 -5.830595669188e-05
-6.728134776332e-05 -6.219279400389e-05 -6.943566098428e-05
-4.092678148101e-05 -9.067551284692e-05 -4.561156687434e-05
-5.090806305876e-05 -1.128730215189e-04 -5.674070832052e-05
-1.610439252731e-05 -9.546279066494e-05 -2.176521201243e-05
1.106885835337e-06 -1.255181083110e-04 -6.937902870563e-06
2.512892285900e-05 -1.270584252685e-04 1.633704716320e-05
9.896023117484e-06 -1.236511814894e-04 1.733089699088e-06
1.107662767591e-05 -1.508348275852e-04 1.146013025305e-06
2.663981868757e-06 -8.155269121368e-05 -2.615467338252e-06
7.407054977886e-06 -8.338578072544e-05 1.882464959383e-06
-2.190472365469e-05 -7.453443739549e-05 -2.607253179121e-05
1.662231238331e-05 -9.134986774836e-05 1.034031548842e-05
2.502545305542e-05 -8.626108738243e-05 1.884146539839e-05
4.230420316947e-05 -5.322960710143e-05 3.776280035395e-05
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
0.000000000000e+00 0.000000000000e+00 0.000000000000e+00
Expand Down
Loading