Gromacs

Library Structure

    Version as of 03:59, 21 Nov 2019

    to this version.

    Return to Version archive.

    View current version

    Here is a discussion of how the gmxlib will change in the near future. This page contains a status overview and guidelines for coding.

    Current status

    The current directory structure is as follows (in CVS head before 4.1):

    gmx/
    gmx/admin
    gmx/config
    gmx/include/
    gmx/include/types
    gmx/man
    gmx/man1
    gmx/man7
    gmx/scripts
    gmx/share
    gmx/share/html
    gmx/share/template
    gmx/share/top
    gmx/share/tutor
    gmx/share/tutor/gmxdemo
    gmx/share/tutor/methanol
    gmx/share/tutor/mixed
    gmx/share/tutor/nmr1
    gmx/share/tutor/nmr2
    gmx/share/tutor/speptide
    gmx/share/tutor/water
    gmx/src/contrib
    gmx/src/gmxlib
    gmx/src/gmxlib/gmx_blas
    gmx/src/gmxlib/gmx_lapack
    gmx/src/gmxlib/gmx_statistics
    gmx/src/gmxlib/nonbonded
    gmx/src/gmxlib/nonbonded/mknb_generator
    gmx/src/gmxlib/nonbonded/nb_kernel
    gmx/src/gmxlib/nonbonded/nb_kernel_bluegene
    gmx/src/gmxlib/nonbonded/nb_kernel_f77_double
    gmx/src/gmxlib/nonbonded/nb_kernel_f77_single
    gmx/src/gmxlib/nonbonded/nb_kernel_ia32_3dnow
    gmx/src/gmxlib/nonbonded/nb_kernel_ia32_sse
    gmx/src/gmxlib/nonbonded/nb_kernel_ia32_sse2
    gmx/src/gmxlib/nonbonded/nb_kernel_ia64_double
    gmx/src/gmxlib/nonbonded/nb_kernel_ia64_single
    gmx/src/gmxlib/nonbonded/nb_kernel_power6
    gmx/src/gmxlib/nonbonded/nb_kernel_ppc_altivec
    gmx/src/gmxlib/nonbonded/nb_kernel_x86_64_sse
    gmx/src/gmxlib/nonbonded/nb_kernel_x86_64_sse2
    gmx/src/kernel
    gmx/src/mdlib
    gmx/src/ngmx
    gmx/src/tools
    

    (in alphabetical order). Four libraries are created: libgmx.a, libmd.a, libgmxpreprocess.a, libgmxana.a. Programs are installed from kernel, tools and ngmx.

    Proposed new source tree layout

    This section discusses the source tree layout where we want to aim in the long term. Concrete steps of how this could be reached are discussed in the next section.

    • A single library, libgromacs, is built from code under src/libgromacs/.
    • Under src/libgromacs/, we have subdirectories for modules. Each module consists of a set of routines that do some well-defined task or a collection of tasks, such as basic math functions, topology handling, or trajectory I/O.
    • Each module directory contains one or more file.c/.cpp files, each of which have a corresponding file.h/.hpp file that declares the external API in that file. There can also be a file-impl.h/.hpp file that declares functions in the file that are only accessible within the library. Unit tests for these files go in file_test.c/.cpp. Only file.h/.hpp is installed.
    • In addition, there can be convenience headers that just include a collection of the external API headers and don't have a corresponding source file.
    • Code inside the library should not unnecessarily include headers. In particular, headers should not include other headers if a forward declaration of a type is enough for the header. This keeps build dependencies to a minimum. Currently, changes to nearly any data structure triggers recompilation of the whole tree.
    • Each executable is compiled from source files under src/programs/exename/. The main function should reside in main.c/.cpp, and other code specific to that executable should be in files organized as in the module directories.

    Points for discussion:

    • Where should convenience headers lie in the source tree? In the module subdirectories, in src/libgromacs, or in a separate directory like include?
    • What should the installed header tree look like? A flat tree, or with subdirectories? Where should headers included by convenience headers be installed? How do we handle cross-references between headers in different modules such that they work both during build time and after install?
      • One approach would be to install the headers in the same tree as in the source tree, but declare that only headers in the top level are part of the public API, i.e., user code should not include anything from the subdirectories directly.
      • One point to consider is that a good way to learn how to use a library is to look at existing code that uses it. So ideally, include directives in Gromacs code would use the same directory names etc. as user code would. If we install the headers in a tree that is different from how they lie in the source tree, this requires some additional magic, e.g., with symbolic links.
    • The naming scheme above does not address intra-file definitions. Where should they go? Into the .c/.cpp file? Or do we want to have all C++ class declarations in headers? If so, how should intra-file class declaration headers be named? We could also use file-impl.h/.hpp for this purpose, and another name for intra-library headers.
      • There can be at least four different types of headers: those belonging to the public API, those used internally within the library, those that contain intra-file definitions, and those that contain definitions of inline functions/templates. Ideally, we should have a common naming convention for all of them.
    • Do we want to have separate .h and .hpp headers for pure C and C++ code, respectively? Or just use .h for all?
    • Should there be any source (.c/.cpp) files in the top src/libgromacs directory?
    • Do we want to name the main file for executables main.c/.cpp, or perhaps pdb2gmx.c/.cpp etc.?

    Future plans

    In order to make the layout easier to comprehend and to maintain (and test!) the following actions are proposed:

    • Gradually move independent parts of gmxlib and mdlib into subdirectories of gmxlib with minimal inter-dependencies. As an example one could have src/gmxlib/neighborsearching, src/gmxlib/coordinatefiles, src/gmxlib/topology and so on. Each sublibrary should contain a specific test program to test the code in that directory.
    • Eventually we probably want to rename this directory to "libgromacs" so that the directory and library has the same name, and it would also be a point to change the library name when we allow C++ after 4.1 and the linking actions will have to change.
    • Clean up the code according to the Encapsulation principles, adhering to the rules for Indentation and Block structure
    • Remove confusing datatypes (in particular "bool" which should be replaced by specific enumerated types)
    • Library functions may never crash or fail. All library functions should return a well-defined status, such that it can be checked by the calling routine.
    • Make a new subdirectory src/programs, and move all programs to a separate subdirectory within that one, e.g. src/programs/mdrun, src/programs/trjconv etc.
    • For each module, we want the interface (.h header file), implementation (.c or .cxx), and test driver (.test.c or .test.cxx) in the same location, with the same base name, and just different extensions.

    See also the page about Compilation for other changes that are imminent following 4.1.

    New library structure

    Here is a proposal for a structure of the gromacs tree (only for the source code for now). Note that we do not use gmx_ prefixes on subdirectories, since it is rather obvious we are in the gromacs tree.

    gmx/src/gmxlib/basic
    gmx/src/gmxlib/geometry
    gmx/src/gmxlib/io
    gmx/src/gmxlib/math
    gmx/src/gmxlib/math/blas
    gmx/src/gmxlib/math/lapack
    gmx/src/gmxlib/statistics
    gmx/src/gmxlib/interactions
    gmx/src/gmxlib/interactions/listed
    gmx/src/gmxlib/interactions/nonbonded (+ subdirectories, not ideal for now)
    gmx/src/gmxlib/parallel
    gmx/src/gmxlib/neighborsearch
    gmx/src/gmxlib/ More libraries here
    
    

    gmx/src/include (wrappers for header files installed in subdirectories under gmxlib)

    gmx/src/programs/mdrun
    gmx/src/programs/grompp
    gmx/src/programs/trjconv
    gmx/src/programs/ More programs here
    

    Tests for modules are included in gmxlib, higher-level tests for programs in src/programs.

    Page last modified 09:41, 18 Aug 2010 by tmurtola