Gromacs

Library Structure

    Version as of 00:24, 25 Aug 2019

    to this version.

    Return to Version archive.

    View current version

    Here is a discussion of how the Gromacs libraries 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.

    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/gromacs/.
    • Under src/gromacs/, 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 file that declares the external API in that file. There can also be a file-impl.h file that declares classes or functions that are not accessible outside the file/module. If a file does not contain any symbols that are accessible outside the module, the -impl suffix can be omitted, but comments in the header file should indicate that it should not be used outside the module.
    • Each module has a header file src/gromacs/module.h that includes the public API headers from the module. This header is installed into include/gromacs/, and all headers it includes are installed under include/gromacs/module/. Other headers are not installed. Comments at the top of the header files should contain a note what's their visibility: public (installed), intra-library (can be used from inside the library), or intra-module/intra-file.
    • Unit tests, and data required for them, go into a tests/ subdirectory under the module directory.
    • When compiling, the include search path is set to src/. Source files should include headers as #include "gromacs/module/file.h". #include "file.h" is allowed for intra-module/intra-file headers. Include files should include headers like #include "../othermodule/file.h".
    • Every installed header should compile by itself, without any reference to variables defined in config.h. This is best guaranteed by including every header in some source file as the first header, even before config.h. This will require moving GMX_DOUBLE and similar out of config.h into defines given to the compiler on the command-line.
    • 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. Within the library source files, include only headers from other modules that are necessary for that file. You can use the public API header if you really require everything declared in it.
    • Each executable is compiled from source files under src/programs/exename/. The main function should reside in exename.c/.cpp, and other code specific to that executable should be in files organized as in the module directories. Executables should only use the public API headers, and not include anything from the module directories directly.

    Points for discussion:

    • Where do we put larger-scale tests like regression tests for whole programs? Into a separate repository as it is now, or somewhere within the source tree?

    Migrating to New Layout

    To migrate from existing code to the new layout, the following steps are planned:

    • Create a src/gromacs/ directory and move the src/gmxlib/ and src/mdlib/ into src/gromacs/gmxlib/ and src/gromacs/mdlib/. Keep the old include/ directory. Set up the build such that a single library is built from these files.
    • Move the source code from src/kernel/ into src/programs/mdrun/, src/programs/grompp/ etc. as appropriate and set up the build actions. Move stuff that is needed in more than one binary into src/gromacs/gmxpreprocess/, and include that in the library.
    • Gradually move and/or rewrite in C++ items from the directories under src/gromacs/ into separate module directories, moving the corresponding include files from include/ at the same time. At the same time, the code should be cleaned up (but do that in separate commit(s) from the rename, otherwise git will lose history), according to the new coding standards, as much as is reasonable. Code that is migrated should not reference any of the old files!
    • Gradually move tools from src/tools/ into subdirectories under src/programs/. At the same time, move common functionality into modules under src/gromacs/. A major rework of the tools that analyze trajectory frames is planned; moving them to the new layout does not have a high priority as they will need to change significantly when this new analysis framework will be in place, and that is the natural time to migrate them.

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

    Page last modified 09:55, 19 Sep 2010 by tmurtola