Module setup

Build Gromacs topology files from pdb.

Make index file with the special groups.

This routine adds the group __main__ and the group __environment__
to the end of the index file. __main__ contains what the user
defines as the *central* and *most important* parts of the
system. __environment__ is everything else.

The template mdp file, for instance, uses these two groups for T-coupling.

These groups are mainly useful if the default groups "Protein" and "Non-Protein"
are not appropriate. By using symbolic names such as __main__ one
can keep scripts more general.
    
:Returns:
  *groups* is a list of dictionaries that describe the index groups. See
  :func:`gromacs.cbook.parse_ndxlist` for details.

:Arguments:    
  *struct* : filename
    structure (tpr, pdb, gro)    
  *selection* : string
    is a ``make_ndx`` command such as ``"Protein"`` or ``r DRG`` which
    determines what is considered the main group for centering etc. It is
    passed directly to ``make_ndx``.
  *ndx* : string
     name of the final index file
  *oldndx* : string
     name of index file that should be used as a basis; if None
     then the ``make_ndx`` default groups are used.
              
This routine is very dumb at the moment; maybe some heuristics will be
added later as could be other symbolic groups such as __membrane__.

Find vdwradii.dat and add special entries for lipids.

See :data:`gromacs.setup.vdw_lipid_resnames` for lipid
resnames. Add more if necessary.

Put protein into box, add water, add counter-ions.

Currently this really only supports solutes in water. If you need
to embedd a protein in a membrane then you will require more
sophisticated approaches.

However, you *can* supply a protein already inserted in a
bilayer. In this case you will probably want to set *distance* =
``None`` and also enable *with_membrane* = ``True`` (using extra
big vdw radii for typical lipids).


:Arguments:
  *struct* : filename
      pdb or gro input structure
  *top* : filename
      Gromacs topology
  *distance* : float
      When solvating with water, make the box big enough so that
      at least *distance* nm water are between the solute *struct*
      and the box boundary.
      Set this to ``None`` in order to use a box size in the input
      file (gro or pdb).
  *boxtype* : string
      Any of the box types supported by :class:`~gromacs.tools.Genbox`.
      If set to ``None`` it will also ignore *distance* and use the box
      inside the *struct* file.
  *concentration* : float
      Concentration of the free ions in mol/l. Note that counter
      ions are added in excess of this concentration.
  *cation* and *anion* : string
      Molecule names of the ions. This depends on the chosen force field.
  *water* : string
      Name of the water model; one of "spc", "spce", "tip3p",
      "tip4p". This should be appropriate for the chosen force
      field. If no water is requird, simply supply the path to a box with solvent
      molecules (used by :func:`gromacs.genbox`'s  *cs* argument).
  *with_membrane* : bool
       ``True``: use special ``vdwradii.dat`` with 0.1 nm-increased radii on 
       lipids. Default is ``False``.
  *ndx* : filename
      The name of the custom index file that is produced here.
  *mainselection* : string
      A string that is fed to :class:`~gromacs.tools.Make_ndx` and
      which should select the solute.
  *dirname* : directory name
      Name of the directory in which all files for the solvation stage are stored.
  *includes* : list of additional directories to add to the mdp include path

.. Note:: non-water solvents only work if the molecules are named SOL.

Energy minimize the system.

This sets up the system (creates run input files) and also runs
``mdrun_d``. Thus it can take a while.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values. 

:Keywords:
   *dirname*
      set up under directory dirname [em]
   *struct*
      input structure (gro, pdb, ...) [solvate/ionized.gro]
   *output*
      output structure (will be put under dirname) [em.pdb]
   *deffnm*
      default name for mdrun-related files [em]
   *top*
      topology file [top/system.top]
   *mdp*
      mdp file (or use the template) [templates/em.mdp]
   *includes*
      additional directories to search for itp files
   *mdrunner*
      :class:`gromacs.run.MDrunner` class; by defauly we
      just try :func:`gromacs.mdrun_d` and :func:`gromacs.mdrun` but a
      MDrunner class gives the user the ability to run mpi jobs
      etc. [None]
   *kwargs*
      remaining key/value pairs that should be changed in the 
      template mdp file, eg ``nstxtcout=250, nstfout=250``.

.. note:: If :func:`~gromacs.mdrun_d` is not found, the function
          falls back to :func:`~gromacs.mdrun` instead.

Run multiple energy minimizations one after each other.

:Keywords:
  *integrators*
       list of integrators (from 'l-bfgs', 'cg', 'steep')
       [['bfgs', 'steep']]
  *nsteps*
       list of maximum number of steps; one for each integrator in
       in the *integrators* list [[100,1000]]
  *kwargs*
       mostly passed to :func:`gromacs.setup.energy_minimize`

:Returns: dictionary with paths to final structure ('struct') and 
          other files        

:Example:
   Conduct three minimizations:
     1. low memory Broyden-Goldfarb-Fletcher-Shannon (BFGS) for 30 steps
     2. steepest descent for 200 steps
     3. finish with BFGS for another 30 steps
   We also do a multi-processor minimization when possible (i.e. for steep
   (and conjugate gradient) by using a :class:`gromacs.run.MDrunner` class
   for a :program:`mdrun` executable compiled for OpenMP in 64 bit (see
   :mod:`gromacs.run` for details)::

      import gromacs.run
      gromacs.setup.em_schedule(struct='solvate/ionized.gro',
                mdrunner=gromacs.run.MDrunnerOpenMP64,  
                integrators=['l-bfgs', 'steep', 'l-bfgs'], 
                nsteps=[50,200, 50])

.. Note:: You might have to prepare the mdp file carefully because at the
          moment one can only modify the *nsteps* parameter on a
          per-minimizer basis.

Set up MD with position restraints.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values. Note that
setting *mainselection* = ``None`` will disable many of the automated
choices and is often recommended when using your own mdp file.

:Keywords:
   *dirname*
      set up under directory dirname [MD_POSRES]
   *struct*
      input structure (gro, pdb, ...) [em/em.pdb]
   *top*
      topology file [top/system.top]
   *mdp*
      mdp file (or use the template) [templates/md.mdp]
   *ndx*
      index file (supply when using a custom mdp)
   *includes*
      additional directories to search for itp files          
   *mainselection*
      :program:`make_ndx` selection to select main group ["Protein"]
      (If ``None`` then no canonical index file is generated and
      it is the user's responsibility to set *tc_grps*,
      *tau_t*, and *ref_t* as keyword arguments, or provide the mdp template
      with all parameter pre-set in *mdp* and probably also your own *ndx* 
      index file.)
   *deffnm*
      default filename for Gromacs run [md]
   *runtime*
      total length of the simulation in ps [1000]
   *dt*
      integration time step in ps [0.002]
   *qscript*
      script to submit to the queuing system; by default
      uses the template :data:`gromacs.config.qscript_template`, which can 
      be manually set to another template from :data:`gromacs.config.templates`; 
      can also be a list of template names.
   *qname*
      name to be used for the job in the queuing system [PR_GMX]
   *mdrun_opts*
      option flags for the :program:`mdrun` command in the queuing system
      scripts such as "-stepout 100". [""]
   *kwargs*
      remaining key/value pairs that should be changed in the template mdp
      file, eg ``nstxtcout=250, nstfout=250`` or command line options for
      ``grompp` such as ``maxwarn=1``.

      In particular one can also set **define** and activate
      whichever position restraints have been coded into the itp
      and top file. For instance one could have

         *define* = "-DPOSRES_MainChain -DPOSRES_LIGAND"

      if these preprocessor constructs exist. Note that there
      **must not be any space between "-D" and the value.**

      By default *define* is set to "-DPOSRES".

:Returns: a dict that can be fed into :func:`gromacs.setup.MD`
          (but check, just in case, especially if you want to
          change the ``define`` parameter in the mdp file)

.. Note:: The output frequency is drastically reduced for position
          restraint runs by default. Set the corresponding ``nst*``
          variables if you require more output.

Set up equilibrium MD.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values. Note that
setting *mainselection* = ``None`` will disable many of the automated
choices and is often recommended when using your own mdp file.

:Keywords:
   *dirname*
      set up under directory dirname [MD]
   *struct*
      input structure (gro, pdb, ...) [MD_POSRES/md_posres.pdb]
   *top*
      topology file [top/system.top]
   *mdp*
      mdp file (or use the template) [templates/md.mdp]
   *ndx*
      index file (supply when using a custom mdp)
   *includes*
      additional directories to search for itp files          
   *mainselection*
      ``make_ndx`` selection to select main group ["Protein"]
      (If ``None`` then no canonical index file is generated and
      it is the user's responsibility to set *tc_grps*,
      *tau_t*, and *ref_t* as keyword arguments, or provide the mdp template
      with all parameter pre-set in *mdp* and probably also your own *ndx* 
      index file.)
   *deffnm*
      default filename for Gromacs run [md]
   *runtime*
      total length of the simulation in ps [1000]
   *dt*
      integration time step in ps [0.002]
   *qscript*
      script to submit to the queuing system; by default
      uses the template :data:`gromacs.config.qscript_template`, which can 
      be manually set to another template from :data:`gromacs.config.templates`; 
      can also be a list of template names.
   *qname*
      name to be used for the job in the queuing system [MD_GMX]
   *mdrun_opts*
      option flags for the :program:`mdrun` command in the queuing system
      scripts such as "-stepout 100 -dgdl". [""]
   *kwargs*
      remaining key/value pairs that should be changed in the template mdp
      file, e.g. ``nstxtcout=250, nstfout=250`` or command line options for
      :program`grompp` such as ``maxwarn=1``.

:Returns: a dict that can be fed into :func:`gromacs.setup.MD`
          (but check, just in case, especially if you want to
          change the *define* parameter in the mdp file)

CONC_WATER

Value:

55.345

recommended_mdp_table

Value:

'''Table: recommended mdp parameters for different FF ========== ========= ================ mdp GROMOS OPLS-AA ========== ========= ================ rvdw 1.4 1.0 rlist 1.4 ? 1.0 ========== ========= ================ '''

trj_compact_main

Value:

gromacs.tools.Trjconv(ur= 'compact', center= True, boxcenter= 'tric', pbc= 'mol', input= ('__main__', 'system'), doc= "Returns a compact rep resentation of the system centered on the __main__ group")

vdw_lipid_resnames

Hard-coded lipid residue names for a ``vdwradii.dat`` file. Use together with
:data:`~gromacs.setup.vdw_lipid_atom_radii` in :func:`~gromacs.setup.get_lipid_vdwradii`.

Value:

['POPC', 'POPE', 'POPG', 'DOPC', 'DPPC', 'DLPC', 'DMPC', 'DPPG']

vdw_lipid_atom_radii

Value:

{'C': 0.25, 'H': 0.09, 'N': 0.16, 'O': 0.155}