Several improvements to colvar component classes

doc/colvars-code-refs.bib

@@ -102,9 +102,9 @@ @article {Ebrahimi2022
 % Moving frame of reference
 % Optimal rotation via flexible fitting
 % orientationAngle colvar component (derived from orientation)
-% orientationProj colvar component (derived from orientation)
-% spinAngle colvar component (derived from orientation)
-% tilt colvar component (derived from orientation)
+% orientationProj colvar component (derived from orientationAngle)
+% spinAngle colvar component (derived from tilt)
+% tilt colvar component (derived from orientationProj)
 % alpha colvar component
 % dihedralPC colvar component
 % cartesian colvar component
@@ -161,9 +161,9 @@ @article{Fu2016
 
 % polarTheta colvar component
 % polarPhi colvar component
-% eulerPhi colvar component (derived from orientation)
-% eulerTheta colvar component (derived from orientation)
-% eulerPsi colvar component (derived from orientation)
+% eulerPhi colvar component (derived from orientation_angle)
+% eulerTheta colvar component (derived from orientation_angle)
+% eulerPsi colvar component (derived from orientation_angle)
 @article{Fu2017,
   author = {Fu, Haohao and Cai, Wensheng and H\'enin, J\'er\^ome and Roux, Beno\^it and Chipot, Christophe},
   title = {New Coarse Variables for the Accurate Determination of Standard Binding Free Energies},

doc/colvars-refman-main.tex

@@ -851,7 +851,7 @@
 \noindent{}where each argument is a string passed to the function or functions that are used to compute the variable, and are called colvar components, or CVCs (\ref{sec:cvc_list}).
 For example, a variable ``\texttt{DeltaZ}'' made of a single ``\texttt{distanceZ}'' component can be made periodic with a period equal to the unit cell dimension along the $Z$-axis:
 \cvscriptexampleinputcolvar{modifycvcs}{"period \$\{Lz\}"}{"DeltaZ"}
-\noindent{}Please note that this option is currently limited to changing the values of the polynomial superposition parameters \refkey{componentCoeff}{sec:cvc_superp}, or of the \refkey{componentExp}{sec:cvc_superp} to update on the fly, of \refkey{period}{sec:cvc_periodic}, \refkey{wrapAround}{sec:cvc_periodic} or \refkey{forceNoPBC}{colvar|distance|forceNoPBC} options for components that support them.
+\noindent{}Please note that this option is currently limited to changing the values of the polynomial superposition parameters \refkey{componentCoeff}{sec:cvc_superp}, or of the \refkey{componentExp}{sec:cvc_superp} to update on the fly, of \refkey{period}{sec:cvc_periodic}, \refkey{wrapAround}{sec:cvc_periodic} or \refkey{forceNoPBC}{colvar|cvc|forceNoPBC} options for components where it is relevant.
 \cvlammpsonly{Furthermore, because the call above uses an \emph{immediate} expansion of the variable ``\texttt{\$\{Lz\}}'', its value will not be updated during a constant-pressure simulation.}
 
 If the variable is computed using many components, it is possible to selectively turn some of them on or off:
@@ -1476,6 +1476,37 @@
 The very few keywords that are available for all types of components are listed in a separate section \ref{sec:cvc_common}.
 
 
+\cvsubsec{Treatment of periodic boundary conditions}{sec:cvc_pbcs}
+
+In all colvar components described below, the following rules apply concerning periodic boundary
+conditions (PBCs):
+\begin{enumerate}
+\item Distance vectors between two coordinates
+  $\mathbf{d}_{i,j} = \left(\mathbf{x}_1 - \mathbf{x}_2\right)$, are calculated following the
+  minimum-image convention by default, unless \refkey{forceNoPBC}{colvar|cvc|forceNoPBC} is enabled.
+  ($\mathbf{x}_1$ and $\mathbf{x}_2$ may be either individual atomic coordinates, or centers of mass
+  of two groups.)
+\item For all other functions of individual atomic coordinates,
+  $f\left(\mathbf{x}_1, \mathbf{x}_2, \ldots\right)$, it is assumed that all atoms that are part of
+  the same group are in the same periodic unit cell (see \ref{sec:colvar_atom_groups_wrapping}).
+\end{enumerate}
+
+\begin{itemize}
+\item %
+  \labelkey{colvar|cvc|forceNoPBC}%
+  \keydef{forceNoPBC}{%
+    any component}{%
+    Use absolute rather than minimum-image distances?}{%
+    boolean}{%
+    \texttt{no}}{%
+    If this keyword is set to \texttt{yes}, PBCs will be ignored when calculating this component.
+    This is only useful in a limited number of special cases, e.g.\ to describe the distance between
+    remote points of a single macromolecule, which cannot be split across periodic cell boundaries,
+    and for which the minimum-image distance might give the wrong result because of a relatively
+    small periodic cell.}
+\end{itemize}
+
+
 \cvsubsec{Distances}{sec:cvc_distances}
 
 
@@ -1498,24 +1529,6 @@
   \labelkey{colvar|distance|group2}
   \simkey{group2}{\texttt{distance}}{group1}
 
-\item %
-  \labelkey{colvar|distance|forceNoPBC}
-  \keydef
-    {forceNoPBC}{%
-    \texttt{distance}}{%
-    Calculate absolute rather than minimum-image distance?}{%
-    boolean}{%
-    \texttt{no}}{%
-    By default, in calculations with periodic boundary conditions, the
-    \texttt{distance} component returns the distance according to the
-    minimum-image convention. If this parameter is set to \texttt{yes},
-    PBC will be ignored and the distance between the coordinates as maintained
-    internally will be used. This is only useful in a limited number of
-    special cases, e.g. to describe the distance between remote points
-    of a single macromolecule, which cannot be split across periodic cell
-    boundaries, and for which the minimum-image distance might give the
-    wrong result because of a relatively small periodic cell.}
-
 \item %
   \labelkey{colvar|distance|oneSiteTotalForce}
   \keydef
@@ -1600,9 +1613,6 @@
     (\bm{r}-\bm{r}_1)$.  The vector should be written as three
     components separated by commas and enclosed in parentheses.}
 
-\item %
-  \dupkey{forceNoPBC}{\texttt{distanceZ}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
-
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{distanceZ}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1634,8 +1644,6 @@
   \dupkey{ref2}{\texttt{distanceXY}}{colvar|distanceZ|ref2}{\texttt{distanceZ} component}
 \item %
   \dupkey{axis}{\texttt{distanceXY}}{colvar|distanceZ|axis}{\texttt{distanceZ} component}
-\item %
-  \dupkey{forceNoPBC}{\texttt{distanceXY}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{distanceZ}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1645,19 +1653,17 @@
 \cvsubsubsec{\texttt{distanceVec}: distance vector  between two groups.}{sec:cvc_distanceVec}
 \labelkey{colvar|distanceVec}
 
-The \texttt{distanceVec~\{...\}} block defines
-a distance vector component, which accepts the same keywords as
-the component \texttt{distance}: \texttt{group1}, \texttt{group2}, and
-\texttt{forceNoPBC}. Its value is the 3-vector joining the centers
-of mass of \texttt{group1} and \texttt{group2}.
+The \texttt{distanceVec} component computes the 3-dimensional vector joining the centers of mass of
+\texttt{group1} and \texttt{group2}.  Its values are therefore multi-dimensional and are subject to
+the restrictions listed in \ref{sec:cvc_non_scalar}.  Moreover, when computing differences between
+two different values of a \texttt{distanceVec} variable the minimum-image convention is assumed
+(unless \refkey{forceNoPBC}{colvar|cvc|forceNoPBC} is enabled).
 
 \begin{cvcoptions}
 \item %
   \dupkey{group1}{\texttt{distanceVec}}{colvar|distance|group1}{\texttt{distance} component}
 \item %
   \simkey{group2}{\texttt{distanceVec}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{distanceVec}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{distanceVec}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1679,8 +1685,6 @@
   \dupkey{group1}{\texttt{distanceDir}}{colvar|distance|group1}{\texttt{distance} component}
 \item %
   \simkey{group2}{\texttt{distanceDir}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{distanceDir}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{distanceDir}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1733,8 +1737,6 @@
   \simkey{group2}{\texttt{angle}}{group1}
 \item %
   \simkey{group3}{\texttt{angle}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{angle}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{angle}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1756,8 +1758,6 @@
   \simkey{group2}{\texttt{dipoleAngle}}{group1}
 \item %
   \simkey{group3}{\texttt{dipoleAngle}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{dipoleAngle}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{dipoleAngle}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -1783,8 +1783,6 @@
   \simkey{group3}{\texttt{dihedral}}{group1}
 \item %
   \simkey{group4}{\texttt{dihedral}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{dihedral}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \item %
   \dupkey{oneSiteTotalForce}{\texttt{dihedral}}{colvar|distance|oneSiteTotalForce}{\texttt{distance} component}
 \end{cvcoptions}
@@ -3039,8 +3037,6 @@
   \dupkey{group1}{\texttt{distancePairs}}{colvar|distance|group1}{\texttt{distance} component}
 \item %
   \simkey{group2}{\texttt{distancePairs}}{group1}
-\item %
-  \dupkey{forceNoPBC}{\texttt{distancePairs}}{colvar|distance|forceNoPBC}{\texttt{distance} component}
 \end{cvcoptions}
 This component returns a $N_{\mathrm{1}}\times{}N_{\mathrm{2}}$-dimensional vector of numbers, each ranging from $0$ to the largest possible distance within the chosen boundary conditions.
 
@@ -3873,42 +3869,40 @@
 
 
 \cvsubsec{Periodic components}{sec:cvc_periodic}
-The following components returns
-real numbers that lie in a periodic interval:
-\begin{itemize}
-\item \texttt{dihedral}: torsional angle between four groups;
-\item \texttt{spinAngle}: angle of rotation around a predefined axis
-  in the best-fit from a set of reference coordinates.
-\end{itemize}
-In certain conditions, \texttt{distanceZ} can also be periodic, namely
-when periodic boundary conditions (PBCs) are defined in the simulation
-and \texttt{distanceZ}'s axis is parallel to a unit cell vector.
 
-In addition, a custom \cvscriptonly{or scripted} scalar colvar may be periodic
-depending on its user-defined expression. It will only be treated as such by
-the Colvars module if the period is specified using the \texttt{period} keyword,
-while \texttt{wrapAround} is optional.
+Certain components, such as \refkey{dihedral}{colvar|dihedral} or
+\refkey{dihedral}{colvar|spinAngle}, compute angles that lie in a periodic interval between
+$-180^\circ$ and $180^\circ$.  When computing pairwise distances between values of those angles
+(e.g.\ for the sake of computing restraint potentials, or sampling PMFs), periodicity is taken into
+account by following the minimum-image convention.
+
+Additionally, several other components, such as \refkey{distanceZ}{colvar|distanceZ}, support
+optional periodicity if this is provided in the configuration.
 
-The following keywords can be used within periodic components\cvleptononly{, or within custom variables (\ref{sec:colvar_custom_function})}\cvscriptonly{, or wthin scripted variables \ref{sec:colvar_scripted}}).
+The following keywords can be used within periodic components\cvleptononly{, or within custom
+  variables (\ref{sec:colvar_custom_function})}\cvscriptonly{, or wthin scripted variables
+  \ref{sec:colvar_scripted}}).
 
 \begin{itemize}
 \item %
+  \labelkey{colvar|cvc|period}
   \keydef
     {period}{%
-    \texttt{distanceZ}, custom colvars}{%
+    components with optional periodicity}{%
     Period of the component}{%
     positive decimal}{%
-    0.0}{%
-    Setting this number enables the treatment of \texttt{distanceZ} as
+    0.0, unless otherwise stated}{%
+    Setting this number enables the treatment of as
     a periodic component: by default, \texttt{distanceZ} is not
     considered periodic.  The keyword is supported, but irrelevant
     within \texttt{dihedral} or \texttt{spinAngle}, because their
     period is always 360~degrees.}
 
 \item %
+  \labelkey{colvar|cvc|wrapAround}
   \keydef
     {wrapAround}{%
-    \texttt{distanceZ}, \texttt{dihedral}, \texttt{spinAngle}, custom colvars}{%
+    periodic components}{%
     Center of the wrapping interval for periodic variables}{%
     decimal}{%
     0.0}{%
@@ -3917,11 +3911,7 @@
     This can be useful for convenience of output, or to set the walls for a \texttt{harmonicWalls} in an order that would not otherwise be allowed.}
 \end{itemize}
 
-Internally, all differences between two values of a periodic colvar
-follow the minimum image convention: they are calculated based on
-the two periodic images that are closest to each other.
-
-\emph{Note: linear or polynomial combinations of periodic components (see \ref{sec:cvc_superp}) may become meaningless when components cross the periodic boundary.  Use such combinations carefully: estimate the range of possible values of each component in a given simulation, and make use of \texttt{wrapAround} to limit this problem whenever possible.}
+\emph{Note: using linear/polynomial combinations of periodic components (see \ref{sec:cvc_superp}), or other custom or scripted function may invalidate the periodicity.  Use such combinations carefully: estimate the range of possible values of each component in a given simulation, and make use of \texttt{wrapAround} to limit this problem whenever possible.}
 
 
 \cvsubsec{Non-scalar components}{sec:cvc_non_scalar}
@@ -7482,3 +7472,7 @@
   \url{https://colvars.github.io/README-c++11.html}
 \end{itemize}
 
+% Emacs
+% Local Variables:
+% fill-column: 100
+% End:

doc/colvars-refman.tex

@@ -232,13 +232,14 @@
 \newcommand{\bm}[1]{{\mbox{\boldmath{$#1$}}}}
 
 \newenvironment{cvcoptions}{%
-  %% TODO Uncomment when all itemizations environment are redefined
-  %% \begin{mdframed}[linecolor=cvexample-border-color,linewidth=2pt]
-  \noindent\textbf{List of keywords} (see also \ref{sec:cvc_superp} for additional options):
-  \begin{itemize}}{%
+  \noindent\textbf{List of keywords} (see also \ref{sec:cvc_pbcs}, \ref{sec:cvc_common}, \ref{sec:cvc_periodic} and \ref{sec:cvc_superp} for additional options):
+  \begin{itemize}
+  }{%
+  \item %
+    \colorbox{cvkeyword-background-color}{\texttt{forceNoPBC}} --- \emph{Use absolute rather than minimum-image distances?} (see \hyperlink{colvar|cvc|forceNoPBC}{description})\\
+    Default: \texttt{no}
   \end{itemize}
-  %% \end{mdframed}
-  }
+}
 
 \newcommand{\pagetoplink}{\ifdefined\HCode
   \begin{flushright}

doc/extract_code_refs.py

@@ -8,7 +8,7 @@
 
 
 def gen_cplusplus_entry(entry, key, url):
-    key_year_sep = re.search('\d', key).start()
+    key_year_sep = re.search('\\d', key).start()
     key_author = key[0:key_year_sep]
     key_year = key[key_year_sep:]
     result = """