/**
\page julich-devel Julich tutorial: Developing CVs in plumed

\section aims-julich-devel Aims

The aim of this tutorial is to introduce users to the tutorials in the developer manual of 
PLUMED. We will learn a little bit about the structure of the code and how this structure
can be visualized using the tree diagrams in the developer manual.  You will then learn how
to implement a new collective variable in a way that uses as much of the functionality that
is already within the code and that thus avoids the duplication of code.  Finally, you will
learn how to write regression tests and how these can be used for continuous integration.

\section julich-devel-lo Learning Outcomes

By the end of this session you will know how to:

- access the developer manual for PLUMED. 
- find the tutorial information for implementing new collective variables, multicolvars, functions, biases and analysis routines.  
- find the tree diagrams showing the class structure in the PLUMED developer manual.
- exploit the functionality within <a href="../../developer-doc/html/class_p_l_m_d_1_1multicolvar_1_1_multi_colvar.html">PLMD::multicolvar</a> in order to write a reasonably complex collective variable quickly.
- write regression tests for PLUMED and understand how these are used for continuous integration.

To do this module you must understand the basics of object-oriented programming. Information on object oriented programming 
and how it is used within plumed can be found <a href="../../developer-doc/html/_a_brief_introduction.html"> here </a>.  

\section julich-devel-resrouces Resources

The <a href="tutorial-resources/julich-devel.tar.gz" download="julich-devel.tar.gz"> tarball </a> for this project contains 
the following directories:

- rt-coord : a directory containing input files for doing a regtest on an already existing collective variable.
- rt-second-shell : a directory containing input files for doing a regtest on the collective variable you will implement within 
this tutorial

At the start of the exercise you should move these two directories to the plumed2/regtest/multicolvar directory of your PLUMED source.
You should see many other directories called rt... within the same directory.  If you change into any of these directories and issue 
the following set of commands:

\verbatim
source ../../../sourceme.sh
make
\endverbatim

Then you will have run one of the regression tests of PLUMED.  If the test runs without a hitch you should get an output
something like this:

\verbatim
../../scripts/run
Thu Aug 20 14:33:00 IST 2015
Running regtest in /Users/gareth/Projects/CVception/plumed2/regtest/multicolvar/rt22
cp: ../tmp is a directory (not copied).
++ Test type: driver
++ Arguments: --plumed plumed.dat --trajectory-stride 10 --timestep 0.005 --ixyz trajectory.xyz --dump-forces forces --dump-forces-fmt=%8.4f
++ Processors: 0
/Users/gareth/Projects/CVception/plumed2/regtest/multicolvar/rt22/tmp
Run driver
Done. Here is the error file:
\endverbatim

\section julich-devel-intro Introduction

PLUMED has two manuals: a manual that is for users of the code and a manual that is for developers of the code.  
If you are interested in implementing new features in the code your first point of call should thus be the developer 
manual, which can be found <a href="../../developer-doc/html/index.html"> here </a>.  Alternatively,
you can get to the front page of the developer manual by clicking the USER/DEVELOPER logo in the top right hand 
corner of any page of the user manual. 

One of nicest features of PLUMED for the developer is that all the code and documentation for any new PLUMED command
all appears together in a single file.  When you come to implement a new feature it is thus relatively unlikely that 
you will have to modify any of the files you downloaded.  Adding a new feature is simply a matter of adding one further
cpp file containing the new method and the documentation for this method.  We are able to achieve this by exploiting 
abstract base classes and polymorphism.  All classes that calculate collective variables, print these variables or 
calculate biases thus inherit from a single base class called Action.  You can read about the Action class 
<a href="../../developer-doc/html/class_p_l_m_d_1_1_action.html"> here </a>.  Notice also that this page also 
shows how all the various classes within the code inherit from this single base class.  It is perhaps worth spending a 
little while browsing through the various branches of this tree and understanding how the classes
at each level become increasingly specialized and thus fit for particular purposes.

Lets say you want to implement a new collective variable in PLUMED.  One way to start this task would be to write a
new class that inherits from the <a href="../../developer-doc/html/class_p_l_m_d_1_1_colvar.html">PLMD::Colvar</a> base class.  
If you click on the box in the tree for <a href="../../developer-doc/html/class_p_l_m_d_1_1_colvar.html">PLMD::Colvar</a> 
and follow various links on the various subject pages you will eventually get to the following 
<a href="../../developer-doc/html/_adding_a_colvar.html"> page </a>, which will give you a step-by-step set of instructions
for implementing a new collective variable.  If you look through the manual you can find similar pages that provide you
with instructions for implementing new analysis methods, functions and so on.  Our suggestion when you implement 
something new would thus be to find some similar functionality in the code, look at how it is implemented and to look
in the developer manual at the descriptions of the classes that have been inherited.  This process is what we will 
try and take you through in this short tutorial.   

\section julich-devel-instruct Instructions

\subsection whats-there Calculating a reasonably complex collective variable

In this first exercise I would like you to look through the manual and work out how to use the functionality that
is already available in PLUMED to calculate the following collective variable:

\f[
s = \sum_{i=1}^{108} 1 - \frac{1 - \left(\frac{c_i}{4}\right)^6}{1 - \left(\frac{c_i}{4}\right)^{12}}
\f]

where \f$c_i\f$ is equal to the coordination number of atom \f$i\f$, i.e.:

\f[
c_i = \sum_{j \ne i} \frac{1 - \left(\frac{r_{ij}}{1}\right)^6}{1 - \left(\frac{r_{ij}}{1}\right)^{12}}
\f]

So \f$r_{ij}\f$ is the distance between atom \f$i\f$ and atom \f$j\f$.  This collective variable measures the number of 
coordination numbers that are more than 4 so the summations in the above expressions run over all 108 atoms in this particular system.

Write an input file that computes \f$s\f$ and outputs its value to a file called colvar and that computes both the analytical
and numerical derivatives of \f$s\f$ and outputs this information to a file called deriv.  You are going to run this calculation
in the rt-coord directory that you downloaded with the tarball for this exercise so you should create this input file within 
that directory.  You will need to output the quantities in the colvar and deriv files with only four decimal places.  
When you are content with your input run the calculation by typing make.  If you have done everything correctly
you should see the output that was discussed above. 

In setting up your input files you may find it useful to watch our 
<a href="http://www.youtube.com/watch?v=PxJP16qNCYs"> introductory </a> 
video and <a href="http://www.youtube.com/watch?v=iDvZmbWE5ps"> this video </a> on some of the 
features that are available in the code.  Obviously, the user manual will be indispensable as well.

\subsection new-cv Implementing a new collective variable

In this second exercise I would like you to implement the following collective variable:

\f[
s = \sum_{i=1}^{108} \int_{57}^{59} \exp\left( -\frac{(x_i - x)^2}{2} \right) \textrm{d}x
\f]

where \f$x_i\f$ is number of atoms in the second coordination sphere of the \f$i\f$th atom, i.e.:

\f[
s = \sum_{i \ne j} \int_{2}^{4} \exp\left( -\frac{(r_{ij} - r)^2}{2} \right) \textrm{d}r
\f] 

So \f$r_{ij}\f$ is the distance between atom \f$i\f$ and atom \f$j\f$.  This collective variable measure the number of
atoms that have between 57 and 59 atoms in their second coordination sphere.  There are a number of observations we can 
make here that will help you enormously:

- Notice that CV is similar to the coordination number CV you calculated in the first example. For both CVs there is a sum over
a quantity that is calculated for different sets of atoms.  You should thus look at what was done by the routines that calculate
the first CV and see what you can reuse.

- Notice that with the first CV we can calculate the number of coordination numbers that are within a certain range as well as the 
number of coordination numbers that are less than a certain threshold.  

- You can set the link cell cutoff equal to 

\verbatim
std::numeric_limits<double>::max() 
\endverbatim

- Lastly, <a href="../../developer-doc/html/class_p_l_m_d_1_1_histogram_bead.html"> this tool </a> will prove very useful.

Write an input file that computes \f$s\f$ and outputs its value to a file called colvar and that computes both the analytical
and numerical derivatives of \f$s\f$ and outputs this information to a file called deriv.  When outputting numbers to colvar and deriv
you should output numbers to four and three decimal places respectively.  You are going to run this calculation
in the rt-second-shell directory that you downloaded with the tarball for this exercise so you should create this input file within
that directory.  When you are content with your input run the calculation by typing make.  If you have done everything correctly
you should see the output that was discussed above.

If you have sufficient time try use <a href="../../developer-doc/html/using_doxygen.html"> doxygen within PLUMED </a> to write the 
documentation for your new collective variable.

\section julich-devel-extend Final thoughts

The aim of this tutorial is not so much to implement the CV.  I do not think it is a particularly interesting or useful CV.  Instead 
the hope is that by doing it you will get some idea of how to implement things within PLUMED.  Based on my experience there are three 
key things I wish I could go back and tell my younger self about programming, which I would urge you to learn now:

- <B> Write less code </B> The more code you write the more bugs you generate.  To be totally clear this is not me trying to say I am better at 
coding than you are - the same statement holds true if I replace each you in the above with an I - it holds true for everyone.  In addition, 
there are lots of smart people out in the world writing code (and again I am not talking about the developers of plumed).  Their code is properly 
tested and faster than anything that you will write so spend your time learning how it works so that you can re-use it.    

- <B> Test your code </B> Notice that I set up directories that you could use to test your code for this tutorial.  Testing should always be part of your
development workflow and coming up with ways to test your code is hard, which is why we often don't do it enough.  Also don't develop stuff in a 
vacuum get in touch with people who are using the code.  You need to test your code on systems that people actually want to simulate and not 
just on dummy problems.  In addition, you should learn to use profiling tools such as Valgrind and instruments on the mac so that you can find 
memory leaks and bottlenecks in your code.  When you start doing this properly you will realize that you cannot possibly properly maintain all the code 
that you have written and you will see clearly that you that you need to write less code.

- <B> Write documentation for your code </B> Undocumented software is useless.  You need to explain how to use your code and to fill your manual with
examples of how the code can be used to solve specific and interesting problems.  That is to say that you need to provide examples of calculations that
users actually want to perform.  To be clear here writing a manual that tells users how something like the shake algorithm works in general terms is 
actually pretty useless.  After all a user can go off and find out this information from a textbook, you could thus replace your description with a 
link to a textbook.  What users want from you is an example that is similar to the calculation they actually want to set up.  If I were providing 
documentation for an implementation of shake in an MD code I would thus explain in detail how to set up shake to constrain all the angles and bonds 
in all the water molecules in my system as it is a fair bet that this is how it will be being used by many users.

I hope you have seen from this tutorial that PLUMED tries to help you with all of these aims.  We have a developer manual where we try to explain how
to use the code that is already there.  In addition, you can quite quickly generate nicely formatted user documentation for new CVs and it is easy to 
add new regression tests that allow you to test new features.  Notice also that whenever commits are made on the origin git repository we use a website called 
<a href="https://travis-ci.org/plumed/plumed2/branches">travis-ci</a> to test that the code works across a range of platforms.  

*/

link: @subpage julich-devel

description: Implementing new collective variables in plumed

additional-files: julich-devel
