Added new multicolour features from hack the tree (plumed#1020)

* Started adding vector/matrix/grid stuff into Value from hack-the-tree

In hack-the-tree you can pass vectors/matrices and grids through Values.
This necessitates some changes to the Value class.  In particular inputForce
becomes a vector and similarly the double value becomes a vector called data.  I avoid
having a confusing vector called derivatives (which is not always the derivatives).
If I have a scalar I store the value and the derivatives in the data vector.  data
thus has a length of 1 + number of derivatives.  The first element is the value of the scalar.

Notice that I also have functionality to set the value to be a constant that is calculated once and
only once during the calculation

* Using basic/rt-make-extracv to test passing values from plumed to code

I added a few lines into the script here to test the code that allows you
to get values from PLUMED and pass them back to the calling program. This
means you can test this functionality even when you don't have python installed

* Added functionality for passing data to and from PLUMED from hack-the-tree

This functionality introduces two new actions into plumed:

PUT = an ActionWithValue that transfers some data from a pointer that is passed from the MD code to a PLMD::Value.
GET = an ActionWithArgument that transfers data from a PLMD::Value to a pointer than is passed from the MD code

Notice that you can also pass a pointer to the forces on a object that is passed to PUT.  The forces from value
are then added to the MD code's force pointer when you call the apply method.

To demonstrate how this functionality works I have replaced all the stuff for passing extraCVs to PLUMED with PUT
commands

I have amm also using GET in place of the old DataFetchingObject class, which has now been deleted

* Passing cell vectors through PUT action

This commit modifies the code so that cell vectors are passed through a
PUT action.  The virial is then passed as the forces that any forces on the
input value are added on.  To deal with the fact that the virial and cell should only
be passed from one of the MD codes processes there is a special new class PbcAction
that deals with passing the cell vectors.  Methods from this class are also invoked
when the box parameters are sought elswhere in the code.

Notice that I have also added the DomainDecomposition class from hack-the-tree here.
Much of the functionality in this class is not yet used.  It also needs to be modified
before it can be used here.  I felt as we merge hack-the-tree it is easier to start out
with a code that resembles the one in hack-the-tree.

* Changes to pass timestep from MD code to PLUMED through a PUT action

The timestep is now passed to PLUMED using a PUT action.  The timestep is
thus stored in a value called timestep that can be accessed using the label
timestep.  Notice that changes to the object that collects the data from the MD
code were required here because the timestep is passed directly (and not via a
pointer).  To resolve this there is a variable in DataPassingObject that can hold
a double that is passed from the MD code.

* Passing kBT through a PUT action

kBT is now passed from the MD code into a PLMD::Value by passing the value
to a PUT action.  Whenever an action needs kBT you can call a method in action
called getkBT.  This reads in the keyword TEMP (if it is registered).  If TEMP
is present the value read for this flag is multiplied by Boltzmann's constant.  If
TEMP is not present then the kBT value that was passed from the MD code to PLUMED is
returned.

* Ran astyle and fixed some codecheck issues

* Fixed ccpcheck issues and issues with DEBUG mode

* Fixed bug in last commit

This should resolve the problem that is cauased when you call
setNatoms multiple times and it tries to create multiple
DOMAIN_DECOMPOSITION objects

* Functionality for passing atoms moved from Atoms to DOMAIN_DECOMPOSITION

The atomic positions, masses and charges are now passed from the MD code into PLMD::Values.
Five PLMD::Value objects are created to hold these quantities.  These PLMD::Value objects are
all vectors with natoms elements.  The ActionWithValue that owns each of thse PLMD::Values is
a PUT object.  These PUT objects are created by a new action called DOMAIN_DECOMPOSITION.  This
action is created when you call cmd("setNatoms").  However, this action could be created from the
MD code directly by doing cmd("readInputLine mdcode: DOMAIN_DECOMPOSITION").  This would then
give the flexibility to pass quantities other than the the positions, masses and charges to PLUMED.

N.B. The passing of energy between the MD code and PLUMED is broken by this commit.  I will fix this
on the next commit.

* Fixed mechanism for passing energy between MD code and PLUMED

The energy is now passed through a specialised PUT action.  When apply is called
for this PUT action the rescaleForces method of the position and forces PUT actions
are called.  This allows one to adjust the forces on the atoms in the correct way due
to a force that acts on the value of the energy

* Fixed dates for copyright in header in these files

* Getting group from Group class rather than storing groups in Atoms

If, when interpretting an atom list, ActionAtomistic encounters a group it now calls a method
of the Group action with that label to get the relevant list of atoms.  This means you no longer
need to store all the groups in a map in the Atoms class.

* Added getKBoltzmann, getUnits and usingNaturalUnits methods to Action

To get Boltzmann's constant, the units or a bool telling you if PLUMED is using
natural units inside an action you used to have to include a call something like the following

plumed.getAtoms().getUnits()

As this is used in a lot of places I put a method in Action so you can now get the units using:

getUnits()

instead.  I have made similar changes from:

plumed.getAtoms().getKBoltzman()

to

getKBoltzmann()

and

plumed.getAtos().usingNaturalUnits()

to

usingNaturalUnits()

* Moved duplicated functionality for getting forces from Values in Function and Colvar to ActionWithValue

The way that you get the forces from the Values is the same in Function and in Colvar.  I thus created a
method called getForcesFromValues in ActionWithValue and used this method in Function and Colvar.  I also
rewrote the interface for the methods setForcesOnAtoms and addForcesToArguments.  You now passed a reference
to an unsigned which keeps track of where you are in the forcesForApply array that is passed to this functions.

* Virtual atom positions are now passed in three PLMD::Value

ActionWithVirtualAtom now creates 5 values: the x, y and z position of the atom
and the mass and charge of the atom.  This replaces the mechanism whereby additional
atoms were created in the Atoms class.  ActionAtomistic creates vectors containing
pointers to the PLMD::Values that are created by the PUT actions that pass positions from
the MD code and the Virtual Atom actions.  If virtual atoms are needed a dependency on the
virtual atoms action is created in requestAtoms.

* Moved code for storing real precision to DataPassingTools and out of Atoms

* Moved passing of units from MD code into PlumedMain and out of Atoms

* Removed Atoms and MDAtoms classes as they are no longer used and ran astyle to fix formatting

* Fixed bug for ccpcheck with extra docs adding in header file for DomainDecomposition

* Fixed bug due to unintialised variable "resetable" in constructor for ActionToPutData

* This test doesn't really use mpi so removed need for it

* Fixed a couple of unitialised variables

* Changed a couple of unsigned variables to size_t variables to stop some complaints

* Ran asyle and fixed some warnings that the compiler gave

* Added virtual destructors in DataPassingObject and DataPassingTools

* Fixed code quality issues that were flagged by github

* Wrote code to ensure Values that should be calclated during update are calculated during update

In hack the tree all averages are stored in PLMD::Value objects.  Furthermore, you can
calculate a function of an average that is stored in a PLMD::Value.  This function should
not be calculated when you call calculate, however.  It should be called during the update
step.  This little bit of code allows plumed to deal with functions of averages

* Rewrote functions so that we can use them with vector, grid and matrix as input eventually.

It is useful to be able to use the CUSTOM, SORT and Piecewise functions with inputs other than scalars.
If a multiple vectors are passed to CUSTOM, for example, you can compute the defined function element wise.
This mechanism is used extensively when implementing complicated CVs in the hack-the-tree branch.  In order
for this to appear simple to users a shortcut action is called when you create one of the functions above.
This shortcut action decides whether the input is a scalar, vector, matrix or grid and calls the version of the
action that is appropriate to the input arguments.  FunctionOfScalar, FunctionOfVector, FunctionOfMatrix and
FunctionOfGrid template classes are used to create CUSTOM_SCALAR, CUSTOM_VECTOR, CUSTOM_MATRIX and CUSTOM_GRID
actions.  The type of function being used is the template parameter and must inherit from the class FunctionTemplateBase.

In this commit I adjusted the code so that this new mechanism is used for scalar function.  We cannot compute vectors yet
with PLUMED so there is no point in adding the FunctionOfVector code from hack-the-tree yet.  However, I will add this in a
future commit that will take place shortly.

Changes to regtests are simply because there is an additional action in the input.  Action with labels such as @3 thus change
to having labels like @4

* Added shortcut action to create basic Colvars as I will use them in MultiColvar to create vectors of these basic quantities

ANGLE, DIPOLE, DISTANCE, POSITION and TORSION currently calculate 1 or more scalar quantities.
It would be easy to imagine another version of these colvars that takes multiple groups of atoms
and that calculates multiple angles or multiple distances.  This is what MultiColvar does.  In hack-the-tree,
however, it is implemented as a wrapper round the underlying Colvars.  Eventually you will be able to implement
a Multicolvar and a Colvar just by implementing a Colvar

* Started reimplimenting MultiColvar in a much simpler way

A MultiColvar in hack-the-tree is a vector of colvars of a particular type.  You specify
what is to be calculated for a distance multicolvar by doing:

DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6

A vector containing three distances is then computed.  I have implemented this by writing a
general templace class called MultiColvarTemplate.  The template parameter of this class is one
of the regular Colvars that we have implementations.  You can thus reuse the code for Distance
to calculate the vector with three distances above.

To make this work I have to move some of the functionality in the underlying colvars to three
static functions. To be clear, you can still implement Colvars in the old way.  Hopefully
the way to implement a Colvar so that it is automatically a MultiColvar is relatively self explanatory.

* Added code to calculate functions of Vectors

Now that we can calculate a vector of CVs using MultiColvarTemplate we should also
be able to calculate a function of the vectors that the MultiColvarTemplate function
outputs.  The same set of functions (and more) that are available for scalars can be used
to calculate functions of vectors.  We thus defined a FunctionOfVector class here.

I also modified the rt-basic-print regtest to test the FunctionOfVector class

* Started ensuring ActionWithVector works as it should

* Derivatives for new multicolvar implementation are now working

* Changed a few loop variable types in MultiColvarTemplate to prevent warnings

* Added command land tool that provides a mermaid graph that illustrates how data passes through the code

With PLUMED passing Vector, matrices, grids and scalars between actions it is useful to have some
illustration of how data is being passed about inside the code.  This commit provides a tool that
can be used to visualise inputs.  Show_graph draws a graph.  Each node in the graph is an action
and the connections between nodes illustrate the PLMD::Value objects that are passed between Actions.
If a connection is coloured black then a scalar is passed.  If it is blue, red or green then a vector,
matrix and grid respectively is being passed.  Lastly violet connections are used to show how atoms are
passed between actions.

* Further developments on show_graph functionality

You can now do plumed show_graph --force and it will output a graph
that shows you how forces are applied in the input.

* Added functionality to show_graph for ActionWithVector as well

* Added the code required to apply forces on vectors

* Added code to show graph to indicate how forces are applied in ActionWithVector

* Created two new modules called volumes and symfunc

This is a tidy-up of the multicolvar module.  The contents of the multicolvar
module are different in hack-the-tree so I have thus made the contents of the
multicolvar module the same as the contents for hack-the-tree to make transferring
the code from the hack-the-tree branch to hear more straightforward

* All multicolvars now implemented using new hack-the-tree functionality

Multicolvar like syntax is now implemented by using shortcut actions to create
a chain of Plumed actions that calculate the final scalar quantities that you could
calculate from the single line commands before. ActionWithArguments has been adjusted so
that it can identify the "components" of shortcut actions.  The output syntax is thus unchanged.

I no longer have numerical derivatives for multicolvars as I think it is not particularly useful.
This is why some regtests have been changed.  For these tests I now check analytic forces against
numerical forces.

This commit also breaks some regtests ( volumes/rt23, pamm/rt-pamm-periodic, analytis/rt-weights-integral and analysis/rt-uweights-integral).
I know how to fix the code to repair these problems.  Substantial changes are required, however, which I will move to a later commit

* Added functionality from hack-the-tree for constact matrices (and coordination numbers)

A useful first step in calculating many CVs in condensed matter is to compute a matrix
in which element ij tells you if there is a "bond" between atoms/molecule i and atom/molecule
j.  If this matrix is multiplied by a vector of ones you get the coordination numbers of the
molecules.  You can calculate SPRINT coordinates from the eigendecmposition of this matrix.
You can also find clusters of atoms by doing a clustering on the adjacency graph that this matrix
describes.

I have written a base class here to calculate these adjacency matrices.  This base class can also
be used to do products of matrices and vectors (to get coordination numbers).

* Fixed perovskite nucleation CV with product of transformed coordination numbers

* Added test to ensure graph for perovskite derivatives is created correctly

* Fixes to output of graphs so that it works on GitHub

Also clarified forward graphs for actions that use matrices

* And put new matrix subgraphs in backward graph as well

* Modified SecondaryStructureVariables so they work like new MultiColvar

* Added function to diagonalise a matrix

Matrix eigenvalues and eigenvectors can be used as a collective variable and
are in the SPRINT methodology.

* Added action to select components of a vector/matrix

* Full implementation of SPRINT collective variables as shortcut action

* Added action to compute matrix inverse

* Reworked clustering functionality to bring it in line with what is done in hack-the-tree

Also realised that there were some mistakes in the way that matrices were stored.  I have fixed
these now.

Will write more notes on clustering and how it works now.

* Added more functionality from hack-the-tree branch for matrices

* Implementation of Behler symmetry functions

* Added first attempt at hexatic order parameter

* Coordination number action now implemented as product of contact matrix and vector of ones

* Rewritten cubic harnomic symmetry functions as they are written in hack-the-tree branch

* Added implementations of new measures of tetrahedraility from hack-the-tree branch

* Added warning in neighbors about non-continuus symmetry functions that can be created using this action

* Implemented hack-the-tree version of CENTER_OF_MULTICOLVAR.

When you use caclulate a center of mass the weights can come from any vector.
This change allows you to use any arbitrary vector calculated by PLUMED as the weights
in a center of mass calculation

* Added shortcut to create actions that add a restraint on the components of a vector

* Added VSTACK command to join vectors in a matrix

* Added shortcut actions to calculate gyration tensor variables with weights from any vector

* Implemented Steinhardt parameters in the way they are implemented in hack-the-tree

* Added shortcut action for doing local average of CV and copied regtests from htt

* Important commit that should be added with Q6 stuff.

I moved the 64.xyz trajectory that is used in many tests on Q6 to the trajectories directory
so we only have one copy.  I then forgot to add the moved file.

* Moved new implementation of SMAC from htt here

* Added COORD_ANGLES shortcut action to calculate properties of the distribution of angles in the first coordination sphere

* New implmenetation of local_average of Q6 vectors

This is implmeneted as a shortcut

* Reimplemented functionality for calculating the number of particles in a particular volume and the average value of a quantity in a volume

We can introduce a new type of ActionVolume object that takes in a series of atom positions and returns a vector that is one if each of those
atoms are within a particular part of the box and that is zero otherwise.  If you take the sum of these vectors you get the number of atoms
that is in the particular part of the box of interest.  However, you can also multiply these ones and zeros by vectors of symmetry functions
and hence determine the average value of a particular symmetry function in a particular part of the box.  This functionality was implemented
in previous versions of PLUMED but now it is done in a much more transparent way.

* Can now do multiple matrix vector products with MATRIX_TIMES_VECTOR

The ability to multiply multiple matrices by a single vector or a single matrix by multiple
vectors is useful when you calculate Steinhardt parameters.  Previously I used multiple
MATRIX_VECTOR_PRODUCT actions to do all these operations.  When implemented this way, however,
there is some additional computational overhead.  By allowing all the matrix vector multiplications
to take place in a single action you reduce the computational expense.

* First commit of module for molecular crystalline order from Jake McKibbin, Erik Santiso and me

This module will provide tools for comparing the relative orientations of molecules in a medium with the
orientations that they have in the ideal crystal structure of the solid.  Some of the functionality for
this sort of CV is already available in PLUMED.  Tests to ensure that you can use these features in the way
that Jake and Erik use them have thus been included in this commit.  This commit also includes the beginnings
of a class for calculating quaternions.  This class will be used when determining the orientations of the molecules.

* Added derivatives of quaternion CVs

* Added shortcut to calculate DOPS order parameter

* Fixed typo in documention for DOPS

* Added quaternion product matrix action

This is used to calculate relative orientations of molecules in the ROPS order parameter from Trout and Santiso.
In Trout and Santiso's work they use a different method for calculating the quaternion than we used in our original implementation
of the quaternion.  We thus changed the way the quaternion is calculated so that what we do is consistent with what is done in those works.
In practise this means the signs of the imaginary components of the quaternions change.  This is why there are changes in the regression tests

* Fixed derivatives for Quaternion

* Added flag to turn off task reduction in cases when user is printing out all values in a vector while computing the average of the vector in a part of the box

* Added shortcut to compute rops order parameter that is used by E. Santiso group

* Reworked implementation of KDE, grids and histograms

* Fixed gradient CV

* Using new version of grid for contour finding stuff

* Moved all distance from contour stuff to contour directory and added test for distance from spherical contour

* Fixed fourier transform to work with new style grids and deleted most of old style grid stuff

* Added shortcut to compute the RDF

* Added shortcut action to compute entropy CV by Pablo Piaggi.

* Added function that allows you to calculate a function that stored on a grid

* Added a couple of regtests to check whether functions that like HIGHEST, MOMENTS and LOWEST can accept scalar input

* Transferred a couple of regtests from hack-the-tree to this new branch.

These regtests check things in the topology matrix

* Created a new module to caluclate the distance/s from a reference point

To calculate the distance from a reference point we do the product of a row vector with a column vector.
This can easily be extended to the mahalanobis distance by adding in a covariance.  Furthermore, we can calcualte
multiple distances at once by multiplying a matrix by its transpose.

* Fixed the implementation of PAMM so that it uses the new methods for calculating distances from reference points

* Added additional regtests for crystdistrib stuff and base for bops

* Added Bops Shortcut from Jake and regtests

* Fixed test forces for tests on bops and rops

* Reworked ENVIRONMENTSIMILARITY so it no longer uses old implementation of MultiColvar

ENVIRONMENTSIMILARITY is now implemented as a shortcut that calls DISTANCE_MATRIX and CUSTOM

* Removed old code in vesselbase and multicolvar that is no longer used

* Fixed liscence agreement

* Fixed issues with compiling that were introduced by merge

* Fixed this regtest which needed changing after merge

* Ran astyle

* Fixed json outputting for files in crystdistrib

* Added documentation to many actions to fix problems higlighted by ccpcheck

* Fixed more issues highlighted by cppcheck

* Fixed regtests rt-simplecubic and rt-averaged-q6-spAspB and ran astyle

* Fixed some reference values in regression tests for crystdistrib

* Added test on passing vectors from plumed to python

* Fixed issues in regtests basic/rt-make-exception and gridtools/rt-integral

* Decreased precision in rt-bops regtest so we can pass tests on github

* Fixed tests and building so new optional modules (adjmat,symfunc,etc) are treated correctly when plumed is built and tested without them active

* Ensuring that tests that are reliant on particular modules are not run when those modules are not available

* Fixed bug in InterpolateGrid that only causes problem when you compile with debug flags

* Python test for passing grids from plumed to python

* Ensured you can get number of bins with debug even when bounds is not set

* Moved duplicated large file to trajectories directory in regtests and lowered precision of some tests so that they work on intel

* Decreased precision and adjusted tests in crystdistrib so they are passed with clang and intel compilers

* Removed some trajectories that were duplicated

* Fixed a bug that was introduced by merge

* Small fixes for cppcheck things

* Some small changes to tests of crystdistrib to get rid of things that cannot be reproduced exactly on intel configuration on github actions

* Removed unecessary printing of forces in some regtests

* Removed new switching function types as they can be done with CUSTOM

* Fixed test of transferring vectors from plumed to python

* Fixed unitialised variable that was flagged by valgrind in FunctionTemplateBase

* Fixed uninintialized variable in way suggested by @GiovanniBussi

* Fixed typo in for loop

* Removed RETURN_DERIV option from SwitchingFunction as requested by @GiovanniBussi

The feature was only used in one place and it was easy to have the code working without it

* Added explicit destructors in ActionWithVector and ActionWithMatrix so that there are no pointers to actions that are not there in the code

* Added description of changes made to change log

* Removed REPLICA keyword from print actions.  This functionality can be put into UPDATE_IF

* Ran astyle

* Added functionality in FindGridOptimum to prevent this from hanging on intel machines

When you use the intel compiler isinf returns 0 if you pass it infinity (brilliant!).  I have thus
incorporated a workaround here to ensure that FindGridOptimum detects cases where all the points on the
grid are infinite that doesn't rely on isinf.

* Ran astyle

* Changed the way -nan is converted to nan in fixzeros script so it works for tests involving grids as well as tests involving lepton

If your output contains nans you should use a format specifier like %8.4f and the fixzeros script will then work if you have a compiler that
outputs -nan.  If you use %f or %.7f then I think that nan is put at the start of the space.  If you use %8.4f then the nan will be put in the final
three characters of the format specifier

---------

Co-authored-by: Gareth Aneurin Tribello <[email protected]>
Co-authored-by: Gareth Aneurin Tribello <[email protected]>

Release v2.9.0

Release v2.8.3

Release v2.9b

Release v2.8.2

Release v2.7.6

Release v2.8.1

Release v2.7.5

Release v2.8.0

Release v2.7.4