Contribute to SSAGES

The SSAGES project is built on an inclusive and welcoming group of physicists, chemists, and chemical engineers working on complex Molecular Dynamics simulations employing Metadynamic techniques. Metadynamics is an exciting and fast developing field and similarly this project is designed to facilitate the usage and implementation of a wide array of Metadynamics methods. And we welcome you heartily to join us and to embark with us on this great adventure.

There are many ways to contribute to SSAGES and you do not necessarily need programming skills to be part of this project (even though they surely help). But, if you decide to work on the code base, you will be happy to find that SSAGES is designed to be easy to use and is just as easy to extend. We put a high priority on maintaining a readable and clearly structured code base as well as an inclusive community welcoming new ideas and contributions.

Here is a short summary of ideas how you can become part of SSAGES:

Reporting, Triaging, and Fixing Bugs
No software is without errors, inconsistencies, and strange behaviors. Even with zero programming knowledge, you can help tremendously by reporting bugs or confirming issued bugs. Read more...
Improving the SSAGES documentation
SSAGES would like to have a detailed yet comprehensive documentation on what it does and how it does it. This should include concise introductions to the methods, quick to learn tutorials, complete coverage of the nooks and crannies of each method, and of course helpful pointers in case you run into errors. And while the documentation is already expansive, improvements on it never go unappreciated. Read more...
Including your Method and CV in SSAGES
You have developed a new Metadynamics scheme or a Collective Variable and want to make it available to the community via SSAGES? Great! Read more...
Working on the core SSAGES system
If you would like to climb into the heart of SSAGES and get your hands dirty, this task is for you. Read more...

Reporting bugs and wishes

Todo

Link to GitHub issue tracker

Improving the Documentation

Great documentation and great code produces great software. -SSAGE advice

Improvements on the documentation are always highly appreciated. The SSAGES documentation is split into two parts: The User Manual (which you are reading right now), and the API documentation. While the Manual uses the Sphinx documentation and contains all information necessary to use the program, the API docs are bulit on Doxygen and describe the usage of the underlying classes and functions for everyone willing to extend and improve SSAGES.

Here are a few ideas on how you can help:

  • Fix typos: Even though we have thoroughly checked, there are certainly still a few hidden somewhere.
  • Check if all internal and external links are working.
  • Make sure that the documentation is up to date, i.e. that it reflects the usage of the latest version.
  • Add examples: An examples on how to use a method, avoid a common problem, etc. are more helpful than a hundred pages of dry descriptions.
  • Write a tutorial.

Building the documentation

Before you can work on the documentation, you first have to build it. The documentation is part of the SSAGES source code. It is assumed that you have already downloaded and built the source code as described in the Getting Started section. You will find a collection of rst files comprising the User Manual under doc/source/ where the file ending rst stands for ReStructured Text. The API documentation on the other hand resides directly in the header files right next to the classes and functions they describe.

Assuming you have already built SSAGES, building the documentation is as easy as typing make doc in your build directory. In order to make correctly check that you have the following programs installed:

  • Sphinx (with PyPI via pip install Sphinx for example)
  • Doxygen
  • dot (in Ubuntu this is part of the graphViz package)
  • Sphinx “Read the docs” theme (via pip install sphinx_rtd_theme)

Once you have successfully built the documentation you will find the User Manual under doc/Manual/ and the API documentation under doc/API-doc/html/ (relative to your build directory - do not confuse it with the doc/ folder in the main directory of the project). To view it in your favorite web browser (using FireFox as an example) just type

firefox doc/Manual/index.html

for the User Manual or

firefox doc/API-doc/html/index.html

for the API documentation.

How to write documentation

Here are a few pointers on how to write helpful documentation, before we dive into the details of Sphinx and Doxygen for the User Manual and the API documentation:

  • Write documentation “along the way”. Do not code first and write the documentation later.

  • Use helpful error messages. These are considered part of the documentation and probably are the part that is read most frequently.

  • Do everything you can to structure the text. Let’s face it: Most people will just skim the documentation. Feel encouraged to use all techniques that help to spot the relevant information, for example:

    • Format your text bold, italic, code, etc.
    • Write in short paragraphs, use headers
    • Use lists, code blocks, tables, etc.

    Note

    These Note blocks are extremely helpful for example.

    Warning

    Warnings work great, too!

    See also

    Here you can find more examples for helpful Sphinx markup: http://www.sphinx-doc.org/en/stable/markup/para.html

  • Use examples, a lot of them

  • In the initial stages: Don’t be a perfectionist. Missing documentation is the worst kind of documentation. “It is better to have written and coded than to have never written at all.” -SSAGE advice

How to write Sphinx

The Sphinx documentation system uses ReStructured text which is loosely based on the markdown format. Examples for documentations written with Sphinx include:

The following tutorials are extremely helpful:

One of the great things of Sphinx is that most documentations have a “view page source” link where you can take a look at the Sphinx source code. Thus, the best way to learn Sphinx is to click on this link right now and look at the source code of this page. But here is a short summary of the most important commands:

  • Markup: You can use *italic*, **bold**, and ``code`` for italic, bold and code.
  • Headers. Underline your headers with at least three === for titles, --- for subtitles, ^^^ for subsubtitles and ~~~ for paragraphs.
  • Bullet lists are indicated by lines beginning with *.

Note

These highlighted blocks can be created with .. note::. The content of this block needs to be indented. You can also use warning and seealso. Even more can be found here.

How to write Doxygen

Doxygen follows a very different philosophy compared to Sphinx and is more steered towards API documentation, exactly what we use it for in SSAGES. Instead of maintaining the documentation separate from the source code, the classes and functions are documented in the same place where they are declared: The header files. Doxygen then reads the source code and automatically builds the documentation. Examples for documentation created with Doxygen:

The mainpage of the Doxygen documentation is written in a separate header file, in our case doc/mainpage.h. A good introduction to the Doxygen syntax can be found at

The basic rule is that Doxygen comments start with //! or /*! and document the class, namespace or function that directly follows it. Let’s start with a short example:

//! Function taking the square of a value
/*!
 * \param val Input value
 * \returns Square of the input value
 *
 * This function calculates the square of a given value.
 */
double square(double val)
{
    return val*val;
}

This example documents the function square() which simply calculates the square of a number. The first line, starting with //!, is the brief description and should not be longer than one line. The second comment block, starting with /*! is the full description. Here, two special commands are used:

\param
This command documents one parameter of the function
\returns
This command documents the return value of the function

There are many special Doxygen commands. They all start with a backslash and the most important, apart from the two mentioned above, are:

\tparam
Used to document a template parameter.
\ingroup
This class is part of a group, such as Methods or Core. The groups are defined in doc/mainpage.h.

Helpful are also boxes highlighting a given aspect of the function, such as:

\attention
Puts the following text in a raised box. A blank line ends the attention box.
\note
Starts a highlighted block. A blank line ends the note block.
\remark
Starts a paragraph where remarks may be entered.
\see
Paragraph for “See also”.
\deprecated
The documented class or function is deprecated and only kept for backwards compatibility.
\todo
Leave a ToDo note with this command.

You can also highlight your text:

\em
For italic word. To highlight more text use <em> Highlighted text </em>.
\b
For bold text. To highlight more text use <b> Bold text </b>.
\c
For typewriter font. To have more text in typewriter font, use <tt>Typewriter Font</tt>.
\code
Starts a code block. The block ends with \endcode.
\li
A line starting with \li is an entry in a bullet list.

Another big benefit of doxygen is that you can use a lot of LaTeX syntax. For example:

\f$
Starts and ends an inline math equation, similar to $ in Latex.
\f[ and \f]
Start and end a display-style LaTeX equation.
\cite <label>
Cite a reference. The references are listed in doc/references.bib and follow the BibTex syntax.

Doxygen is very clever in producing automatic links. For example, there exists a class Method in SSAGES. Thus, Doxygen automatically creates a link to the documentation of this class where the word “Method” appears. This does, however, not work for the plural, “Methods”. Instead, you can write \link Method Methods \endlink. On the other hand, if you want to prevent Doxygen from creating an autolink, put a % in front of the word.

What to document

We are aiming for a comprehensive documentation of all the methods available in SSAGES as well as the core features. Thus, for each method the documentation should include

  • An introduction into the method, what it does and how it does it.
  • A short tutorial based on one of the working examples. The reader should be able to complete the tutorial in ~30min and should leave with a sense of accomplishment, e.g. a nice energy profile or a picture of a folded protein.
  • A detailed description on how to use the method, the parameters, constraints, requirements, etc.

Adding your method to SSAGES

See also

See here for an introduction to how to develop your own method.

So, you have developed a new Metadynamics method or a new collective variable (CV)? Great! SSAGES is about collaboration and integrating your new CV or method is a priority. But before we do that, make sure you check the following boxes:

  • Your code needs to compile and run (obviously).
  • If you have implemented a new method, this method should have been published in a peer reviewed journal and the publication should be cited in the documentation of the method (see next point). If you have implemented a CV, please give a small example of usage. In which case(s) does the new CV come in handy?
  • Your method needs to come with the necessary documentation. For others to be able to use your method, you will have to explain how it works. You can take a look at the section “How to improve the documentation” for a starter on how to write good documentation.
  • Please provide an example system. This could be the folding of an Alanine Dipeptide molecule, a NaCl system or just a toy model with a simple energy landscape. As long as the system is small and the method can easily complete within a few hours, it will be fine.

Once these boxes have been checked, our team of friendly code-reviewers will take a look at your source code and help you meet the high standard of the SSAGES code.

Working on the core classes

Todo

Describe SSAGES development