[gmx-developers] parallelization

[Justin MacCallum]

Hi,

K.A.Feenstra wrote:

> 
> Justin MacCallum wrote:
>  >
> > I looked into some automatic documentation tools.  The most promising one
> > is called doxygen (www.doxygen.org).  It extracts all functions, global
> > variables, enums, and structs from the source code and makes nice
> > cross-linked web pages.  It will also extract specially formatted comments
> > from the source and incorperate them into the web page.  The comment
> > format is relatively unobtrusive.  I would be willing to convert the
> > existing comments to doxygen format, as well as host the documentation as
> > long as that isn't a problem with any other developers, and as long as
> > they would be willing to use the new format when updating or adding
> > comments.
> 
> That sounds like a splendid idea. Could you give a short example of how
> comments would have to be formatted? Just so we can get an idea of how
> much work that would be. If it is too involved (I've seen some examples
> of similar systems, which are in practice absolutely unworkable), it
> would probably not be worth wile, since nobody will make the effort...

Doxygen actually seems to be pretty simple.  If you have a comment that
comes before a function/data type/enum/etc, you just need to change it
from /* to /*! and the comments will be included.  If you want the
documentation/comment to come after say a member of a structure, you just
put in /*!< instead of /*!.  Here's a quick example of a structure that I
converted from pulls.h.



//! Information for each reference and pulled groups
/*! This structure holds information about each reference or pulled group.
    This structure, combined with the t_pull structure, contains all
    of the information necessary to perform a pull run.  Not all of the
    members are used for all types of pulling.
*/
typedef struct {
  int        n;         //!< number of groups
  atom_id    **idx;     //!< indices of pull atoms in full coordinate array
  real       **weights; //!< position depended weight (switch function)
  int        *ngx;      //!< pull group sizes
  char       **grps;    //!< pull group names
  real       *tmass;    //!< total mass of the groups
  rvec       **x0;      //!< pull group coordinates at t=0
  rvec       **xp;      //!< pull group coordinates at previous step
  rvec       *x_ref;    //!< reference positions
  rvec       *x_unc;    //!< center of mass before constraining
  rvec       *x_con;    //!< center of mass, obeying constraints
  rvec       *xprev;    //!< position of coms in last written structure
  rvec       *f;        //!< forces due to the pulling/constraining
  rvec       *spring;   //!< coordinates of the springs (eAfm)
  rvec       *dir;      //!< direction of constraint
  real       *d_ref;    //!< reference distance
  rvec       *xtarget;  //!< target coordinates for structure generation
  rvec       **comhist; //!< com over the last nhist steps (for running aver)
} t_pullgrps; 


The c++ style comments (//!) will show up in a brief summary, while the
/*! style comments, along with the brief comments will show up in the more
detailed view.  The software also extracts all functions and data types
even if they don't have properly formatted comments.  Additionally it has
a source code browser with clickable links, and a search engine.  You can
check out my progress so far at:

moose.bio.ucalgary.ca/~justin/devel/devel-doc/index.html

I haven't converted any of the existing comments yet, but I will keep the
website updated as I do.  It might be a bit of a pain to convert the
existing comments, but I'm willing to site down with emacs search and
replace for a couple of days.  Adding new comments with the correct
formatting isn't any more work than adding normal C style comments, so
hopefully if someone is writing or documenting a function they will be
willing to format them correctly.

I'll put up a page with a couple of examples at
moose.bio.ucalgary.ca/devel/index.html.
 
> > I also plan to produce some how-to/tutorial pages for developers.  For the
> > first one, I want to put some answers to questions I had when I was just
> > starting out.  Things like how to add a new program to the makefile, how
> > to compile for debugging, how to debug MPI, etc.  This could probably even
> > go into the developer FAQ.  I'd also like to produce a document to help
> > people getting starting writing analysis programs.  We need this for our
> > group anyway.
> 
> I know someone in our group (MD group in Groningen), who has been doing
> some things in this direction while implementing a QM/MM hybrid interface
> into gromacs. I'll BCC this to him (though I think he is on the list), so
> you could join forces...