Extend user docs on affine transformations for densities

Add more extensive information to the reference manual and .mdp option description
in the user-guide.

Fix one documentation typo.

diff --git a/docs/reference-manual/special/density-guided-simulation.rst b/docs/reference-manual/special/density-guided-simulation.rst
index 6c921e36ae8806da4abdcc9bdb59cfd045186dfd..ac58be33a0a0386b69c32318379ca308f86d25a8 100644 (file)
--- a/docs/reference-manual/special/density-guided-simulation.rst
+++ b/docs/reference-manual/special/density-guided-simulation.rst
@@ -202,18 +202,25 @@ the force constant is increased by multiplying by :math:`1+2\delta t_{\mathrm{de
 Note that adaptive force scaling does not conserve energy and will ultimately lead to very high
 forces when similarity cannot be increased further.
 
-Aligning input structure and density
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Mapping input structure to density data with affine transformations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To align input structure and density data, a transformation matrix
 :math:`\mathbf{A}` and shift vector :math:`\mathbf{v_{\mathrm{shift}}}` may be
 defined that transform the input structure atom coordinates before evaluating
 density-guided-simulation energies and forces, so that 
 
-.. math:: U = U_{\mathrm{forcefield}}(\mathbf{r}) - k S[\rho^{\mathrm{ref}},\rho^{\mathrm{sim}}\!(\mathbf{A r+v_{\mathrm{shift}}})]\,\mathrm{.}
-          :label:eqndensnine
+.. math:: U = U_{\mathrm{forcefield}}(\mathbf{r}) - k S[\rho^{\mathrm{ref}},\rho^{\mathrm{sim}}\!(\mathbf{A} \mathbf{r}+\mathbf{v}_{\mathrm{shift}})]\,\mathrm{.}
+          :label: eqndensnine
 
-.. math:: \mathbf{F}_{\mathrm{density}} = k \nabla_{\mathbf{r}} S[\rho^{\mathrm{ref}},\rho^{\mathrm{sim}}\!(\mathbf{A r+v_{\mathrm{shift}}})]\,\mathrm{.}
-          :label:eqndensten
+.. math:: \mathbf{F}_{\mathrm{density}} = k \nabla_{\mathbf{r}} S[\rho^{\mathrm{ref}},\rho^{\mathrm{sim}}\!(\mathbf{A} \mathbf{r}+\mathbf{v}_{\mathrm{shift}})]\,\mathrm{.}
+          :label: eqndensten
+
+Affine transformations may be used, amongst other things, to perform
+
+ * rotations, e.g., around the z-axis by an angle :math:`\theta` by using :math:`A=\begin{pmatrix} \cos \theta & -\sin \theta & 0 \\ \sin \theta & \cos \theta & 0 \\ 0 & 0 & 1 \end{pmatrix}`.
+ * projection, e.g., onto the z-axis by using :math:`A=\begin{pmatrix} 0 & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 0 & 1 \end{pmatrix}`. This allows density-guided simulations to be steered by a density-profile along this axis.
+ * scaling the structure against the density by a factor :math:`s` by using :math:`A=\begin{pmatrix} s & 0 & 0 \\ 0 & s & 0 \\ 0 & 0 & s \end{pmatrix}`. This proves useful when, e.g., voxel-sizes in cryo-EM densities have to be adjusted.
+ * and arbitrary combinations of these by matrix multiplications (note that matrix multiplications are not commutative).
 
 Future developments
 ^^^^^^^^^^^^^^^^^^^

diff --git a/docs/user-guide/mdp-options.rst b/docs/user-guide/mdp-options.rst
index 4fa3b4a4cda831ef9d7a7bfac44cc72c1a4fc35c..c3085b034c4c8e701aef009732f190304523797f 100644 (file)
--- a/docs/user-guide/mdp-options.rst
+++ b/docs/user-guide/mdp-options.rst
@@ -3245,8 +3245,11 @@ electron-microscopy experiments. (See the `reference manual`_ for details)
    (1,0,0,0,1,0,0,0,1) Multiply all atoms with this matrix in the 
    density-guided-simulation-group before calculating forces and energies for
    density-guided-simulations. Affects only the density-guided-simulation forces
-   and energies. Corresponds to a transformation of the input density in the
-   opposite by the inverse of this matrix. The matrix is given in row-major order.
+   and energies. Corresponds to a transformation of the input density by the
+   inverse of this matrix. The matrix is given in row-major order.
+   This option allows, e.g., rotation of the density-guided atom group around the
+   z-axis by :math:`\theta` degress by using following input:
+   :math:`(\cos \theta , -\sin \theta , 0 , \sin \theta , \cos \theta , 0 , 0 , 0 , 1)` .
 
 User defined thingies
 ^^^^^^^^^^^^^^^^^^^^^

diff --git a/src/gromacs/applied_forces/densityfitting/densityfittingparameters.h b/src/gromacs/applied_forces/densityfitting/densityfittingparameters.h
index cfafc1f6f5de9f13343a5d9ae9b9c15e80e43a5d..0e123ef5bc4efc1a4b5df76871b1e2f886c83016 100644 (file)
--- a/src/gromacs/applied_forces/densityfitting/densityfittingparameters.h
+++ b/src/gromacs/applied_forces/densityfitting/densityfittingparameters.h
@@ -84,7 +84,7 @@ struct DensityFittingParameters
     real adaptiveForceScalingTimeConstant_ = 4;
     //! Translation of the structure, so that the coordinates that are fitted are x+translation
     std::string translationString_ = "";
-    //! Linear transformat of the structure, so that the coordinates that are fitted are Matrix * x
+    //! Linear transformation of the structure, so that the coordinates that are fitted are Matrix * x
     std::string transformationMatrixString_ = "";
 };