==============
 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 has sane defaults. Further
documentation can be found at :mod:`gromacs.config`.

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

Basic options
-------------

Place an INI file named ``~/.gromacswrapper.cfg`` in your home directory, it
may look like the following document::

  [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 or set an option like
the above one. If this option isn't provided, **GromacsWrapper** will guess
that Gromacs was globally installed like if it was installed by the ``apt-get``
program.

As there isn't yet any way to know which Gromacs version to use,
**GromacsWrapper** will first try to use Gromacs 5 if available, then to use
Gromacs 4. If you have both versions and want to use version 4 or just want
to document it, you may specify the which release version will be used::

  [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. Gromacs 5 has
up to 4 commands usually named::

  [Gromacs]
  tools = gmx gmx_d gmx_mpi gmx_mpi_d


This option will instruct which commands to load. For Gromacs 4 you'll need to
specify more tools::

  [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`:

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


More options
------------

Other options are to set where template 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 yet 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

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

.. code-block:: python

  import gromacs
  gromacs.config.setup()