doxygen/usinglibrary.md

   1 Using \Gromacs as a library {#page_usinglibrary}
   2 ===========================
   3
   4 Getting started
   5 ===============
   6
   7 \todo
   8 Describe how to link against \Gromacs (pkg-config, FindGromacs.cmake, etc.)
   9
  10 The \Gromacs library (`libgromacs`) provides a few different alternatives for
  11 using it.  These are listed here from the highest level of abstraction to the
  12 low-level functions.
  13  - If you are writing a trajectory analysis tool, please see
  14    \ref page_analysisframework.  \ref page_analysistemplate should contain
  15    all the ingredients to get started.
  16    If you have an existing tool written using the analysis template from 4.5 or
  17    4.6 (using the selection engine added in 4.5), you need to do some
  18    conversion work to get this work with the new template.  This is mostly
  19    straightforward, but requires some studying to understand the new framework.
  20  - If you are writing a command line tool for some other purpose, you can use
  21    the facilities provided by \ref module_commandline.  There are a few
  22    different alternatives, depending on how much control you want to give
  23    \Gromacs:
  24     - For C++ code, you can implement gmx::CommandLineModuleInterface, and
  25       use gmx::runCommandLineModule() to execute it.  This requires using some
  26       additional \Gromacs classes (in particular, for implementing
  27       gmx::CommandLineModuleInterface::writeHelp(), if you want to support the
  28       `-h` option).
  29     - For C code, you can use gmx_run_cmain() to wrap an existing C main
  30       method.  The only constraint on the provided main method is that it
  31       should use parse_common_args() for argument processing.
  32       This approach should allow you to convert existing C tools written
  33       against pre-5.0 \Gromacs (e.g., using the analysis template from 4.0 or
  34       earlier) to the new version.
  35     - If you want more control (for example, you do not want the default
  36       command line options added by \Gromacs), you can directly initialize
  37       \Gromacs using gmx::initForCommandLine() before calling other \Gromacs
  38       routines.  This allows you to write your own handling for command line
  39       options from scratch.  This is also discussed in \ref module_commandline.
  40  - For most control, you can use gmx::init() to do basic initialization, create
  41    your own implementation for gmx::ProgramContextInterface, and set that using
  42    gmx::setProgramContext().  This allows you to customize how the \Gromacs
  43    library shows the name of the program in messages, as well as how it locates
  44    its own data files.
  45
  46 If these do not fit your needs, you may need to modify the \Gromacs source code
  47 yourself.  In particular, it is currently relatively difficult to extend the
  48 functionality of `mdrun` without modifying the source code directly.
  49 If you think that some particular API would be necessary for your work, and
  50 think that it would be easy to expose, please drop a line on the
  51 `gmx-developers` mailing list, or contribute the necessary changes on
  52 http://gerrit.gromacs.org/.
  53
  54 Notes on \Gromacs API
  55 =====================
  56
  57 The headers for the public \Gromacs API are installed in `include/gromacs/`
  58 under the installation directory.  The layout reflects the source code layout
  59 under the `src/gromacs/` directory (see \ref page_codelayout).  The headers
  60 directly under `include/gromacs/` do not contain any declarations, but instead
  61 include a collection of headers from subdirectories.
  62 You should prefer to include these convenience headers instead of individual
  63 headers from the subdirectories, since they are much more stable.  The
  64 individual headers in the subdirectories can be renamed or moved, but the goal
  65 is to only rarely change the name of these top-level headers.
  66
  67 Pre-5.0 versions of \Gromacs installed (nearly) all headers directly under
  68 `include/gromacs/`.  Most of these headers still exist, but now under
  69 `include/gromacs/legacyheaders/`.  The long-term goal is to move these to
  70 proper module hierarchy or get rid of them, but unfortunately this can take a
  71 long time.  Thus, you should not expect much stability from the API in these
  72 headers.  Some have already been moved, so if you do not find your favorite
  73 header there, try searching for a declaration from the other subdirectories.
  74
  75 For headers under other subdirectories, some effort has been put to design the
  76 API for stability.  However, with limited development resources, and the focus
  77 of \Gromacs being in high performance simulations, all the APIs are subject to
  78 change without notice.  With each new release (with possible exception of patch
  79 releases), you should expect incompatible API changes.  This is in particular
  80 true until the planned reorganization of the `legacyheaders/` subdirectory is
  81 complete.
  82
  83 The header version.h (installed as `gromacs/version.h`) provides defines that
  84 calling code can use to check the exact (released) version of \Gromacs that
  85 installed the headers.
  86
  87 This Doxygen documentation only covers part of the API.  In particular, nearly
  88 all of `include/gromacs/legacyheaders/` is undocumented, as well as code
  89 recently moved from there.