==============
 Configuration
==============

.. highlight:: ini

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 :mod:`gromacs.config`.


Default configuration
---------------------

.. Note:: *Do not configure anything.* This is the best approach.

If you are used to loading your Gromacs environment by sourcing the
:file:`GMXRC` file yourself or via :program:`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**.


   
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
:file:`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 :file:`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 :envvar:`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
:mod:`gromacs.tools`, but you can always configure it manually with the
**tools** parameter. Gromacs 5/2016/.../2021 has a *driver* command (typically
called :program:`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 :mod:`gromacs` module:

.. code-block:: python

    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).

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



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


Creating default configuration files and directories
----------------------------------------------------

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

.. code-block:: python

  import gromacs
  gromacs.config.setup()
