4. Configuration

This section documents how to configure the GromacsWrapper package. There are options to configure where log files and templates directories are located and options to tell exactly which commands to load into this package. Any configuration is optional and all options have sane defaults. Further documentation can be found at gromacs.config.

4.1. Default configuration

Note

Do not configure anything. This is the best approach.

If you are used to loading your Gromacs environment by sourcing the GMXRC file yourself or via module then do not configure anything and let GromacsWrapper find your Gromacs installation. Only read on if there are specific things that you want to configure or if you always want to use exactly the same version of Gromacs with GromacsWrapper.

4.2. Basic options

Place an INI file named ~/.gromacswrapper.cfg in your home directory, it may look like the following document. The GMXRC parameter is the path your GMXRC start-up script:

[Gromacs]
GMXRC = /usr/local/gromacs/bin/GMXRC

The Gromacs software suite needs some environment variables that are set up sourcing the GMXRC file. You may source it yourself (then do not include it in the config file) or set the option like the above one. If this option isn’t provided, GromacsWrapper will guess that Gromacs was globally installed as if it was installed somewhere on your PATH or if you externally set the Gromacs environment.

As there isn’t yet any way to know which Gromacs version to use, GromacsWrapper will first try to use “modern” Gromacs (i.e., version 5, 2016, 2018, 2019, 2020, 2021, …) if available, then to use Gromacs 4.x. If you have modern versions (collectively referred to as “version 5”) and want to use version 4 or just want to document it, you may specify which version will be used with the release parameter:

[Gromacs]
GMXRC = /usr/local/gromacs/bin/GMXRC
release = 4.6.7

For now GromacsWrapper will guess which tools are available to put it into gromacs.tools, but you can always configure it manually with the tools parameter. Gromacs 5/2016/…/2021 has a driver command (typically called gmx) but depending on how you compile Gromacs, you can have different drivers installed. For example, you might have 4 “gmx” commands

[Gromacs]
tools = gmx gmx_d gmx_mpi gmx_mpi_d

for single and double precision work and compiled with MPI support.

For Gromacs 4, tools are separate executables and you can specify them explicitly:

[Gromacs]
GMXRC = /usr/local/gromacs/bin/GMXRC
release = 4
tools =
                 g_cluster     g_dyndom       g_mdmat      g_principal  g_select    g_wham    mdrun
      do_dssp    g_clustsize   g_enemat       g_membed     g_protonate  g_sgangle   g_wheel   mdrun_d
      editconf   g_confrms     g_energy       g_mindist    g_rama       g_sham      g_x2top   mk_angndx
      eneconv    g_covar       g_filter       g_morph      g_rdf        g_sigeps    genbox    pdb2gmx
      g_anadock  g_current     g_gyrate       g_msd                     g_sorient   genconf
      g_anaeig   g_density     g_h2order      g_nmeig      g_rms        g_spatial   genion    tpbconv
      g_analyze  g_densmap     g_hbond        g_nmens      g_rmsdist    g_spol      genrestr  trjcat
      g_angle    g_dielectric  g_helix        g_nmtraj     g_rmsf       g_tcaf      gmxcheck  trjconv
      g_bar      g_dih         g_helixorient  g_order      g_rotacf     g_traj      gmxdump   trjorder
      g_bond     g_dipoles     g_kinetics     g_pme_error  g_rotmat     g_tune_pme  grompp
      g_bundle   g_disre       g_lie          g_polystat   g_saltbr     g_vanhove   make_edi  xpm2ps
      g_chi      g_dist        g_luck         g_potential  g_sas        g_velacc    make_ndx

Commands will be available directly from the gromacs module:

import gromacs
gromacs.mdrun_d # either v5 `gmx_d mdrun` or v4 `mdrun_d`
gromacs.mdrun   # either v5 `gmx mdrun`   or v4 `mdrun`

Gromacs 4 tools will also be aliased to Gromacs 5 names (i.e., Gromacs 5/2016/2018/2019/2020/2021 names) so that it is, at least in principle, possible to run GromacsWrapper scripts under any version of Gromacs (between 4.x and at least 2021.x, except for incompatible changes in input files and command behavior).

Changed in version 0.6.0: The format of the tools variable in the [Gromacs] section of the config file was changed for Gromacs 5 commands.

4.3. More options

Other parameters can be set to customize where templates for job submission systems and mdp files are located:

[DEFAULT]
# Directory to store user templates and rc files.
configdir = ~/.gromacswrapper

# Directory to store user supplied queuing system scripts.
qscriptdir = %(configdir)s/qscripts

# Directory to store user supplied template files such as mdp files.
templatesdir = %(configdir)s/templates

And there are options for how to handle logging:

[Logging]
# name of the logfile that is written to the current directory
logfilename = gromacs.log

# loglevels (see Python's logging module for details)
#   ERROR   only fatal errors
#   WARN    only warnings
#   INFO    interesting messages
#   DEBUG   everything

# console messages written to screen
loglevel_console = INFO

# file messages written to logfilename
loglevel_file = DEBUG

4.4. Creating default configuration files and directories

If needed you may set up basic configuration files and directories using gromacs.config.setup():

import gromacs
gromacs.config.setup()