amber_manual.txt

==============================================================
Running phenix.refine using Amber gradients
==============================================================

.. contents::

Authors
=======

Principal authors: Pawel Janowski, Nigel W. Moriarty and David A. Case

Contributions from: Jason Swails (Python Sander API), Romain Wolf (pdb4amber which is used in AmberPrep)

Theory and Background
=====================

Amber refinement in Phenix combines the power and functionality of
Phenix crystallographic refinement with the Amber molecular mechanics
force field for geometry restraints. Amber restraints replace the
conventional set of Engh&Huber restraints. In addition to bond, angle
and dihedral terms, electrostatics and van der Waals
attractive/dispersive interactions are computed. Calls to Amber's
energy and gradient calculation engines are seamlessly integrated
through internal libraries shared with Phenix. Refinement with Amber
molecular mechanics has been shown to improve model quality and reduce
overfitting as compared to conventional restraints.

Running refinement with Phenix and Amber
========================================

To create to bridge between Phenix and Amber, run:

::

	[~:]$ phenix.build_amber_interface

This will 
reconfigure Phenix to include Amber and build the code required to
prepare Amber files and run them seamlessly with Phenix.

To run Amber in Phenix, in addition to a PDB file, a topology and a
coordinate file must be provided for Amber. You can easily create
these files by using the provided AmberPrep utility:

::

  phenix.AmberPrep 9xyz.pdb

which will generate three files.

::

  4amber_9xyz.prmtop
  4amber_9xyz.rst7
  4phenix_9xyz.pdb
	
The first two are the Amber files and the last one is the PDB file that matches
the two Amber files for atom order and must be used in phenix.refine replacing
9xyz.pdb. Having created the input files, refinement can be run as follows:

::

  phenix.refine 4phenix_9xyz.pdb 9xyz.mtz use_amber=True topology_file_name=4amber_9xyz.prmtop coordinate_file_name=4amber_9xyz.rst7 wxc_scale=0.025

Here is list of keywords:

  REQUIRED KEYWORDS
    use_amber - turn on refinement with Amber geometry
      restraints. ("True" or "False"; default = False)
    topology_file_name - relative path to the Amber topology file. This is 
      the *prmtop* file created by AmberPrep.
    coordinate_file_name - relative path to the Amber coordinate file. 
      This is the *rst7* file created by AmberPrep.
  OPTIONAL KEYWORDS
    wxc_factor - relative weight factor between the x-ray and 
      the Amber geometry restraint terms in refinement. 
      By default this is set to 0.1 which multiplies the standard wxc_scale
      which has a default of 0.5 for the x-ray and E&H restraints. 
      (Float; default=0.1)

ADDITIONAL INFORMATION:

1. We also provide the possibility to energetically optimize model coordinates 
using Amber's force field rather than the set of Engh & Huber restraints. 
This leads to models of improved quality. This minimization can be run 
as follows:

::

	phenix.geometry_minimization 4amber_xyz.pdb amber.use=True topology_file_name=4amber_9xyz.prmtop coordinate_file_name=4amber_9xyz.rst7

2. AmberPrep contains additional options that the user may wish to use.
Run:

::

  phenix.AmberPrep --show-defaults

to view all of the options. Here is a list of the optional keywords:

  minimise - type of energy minimization to perform. Possible options:

    amber_all - optimize coordinates of all atoms using Amber's minimizer

    amber_h - optimize only hydrogen positions using Amber's minimizer (default)

    phenix_all - optimize coordinates of all atoms using phenix minimizer

    off - do not optimize atoms

  clean - remove temporary files (on/off, default=on)

  redq - use Amber's redq force field instead of the default (currently 
      ff14SB). redq is a version of ff14SB that mitigates 
      the partial charges on charged amino acid side chains. In theory 
      this should account for the electrostatic screening effects of 
      the unmodelled solvent molecules. In practice our tests have not 
      shown any improvement in refinement when using the reduced charge 
      (redq) force field, but users are free to experiment (True/False,
      default=False)

3. Refinement with Amber currently has several limitations. All atoms
must be explicitely modelled and there can be no gaps in the peptide
or nucleic acid backbone. If hydrogen atoms are missing, they will be
added automatically by AmberPrep but missing heavy atoms should first
be manually modelled in by the user. Amber does not currently model
alternate conformations and AmberPrep will only retain the first
alternate conformer of each atom. Solutions to these two limitations
are currently in development.

4. Metal-containing ligands are not supported by 
Amber.

5. Atoms at special positions will most often produce high energy
clashes with Amber and usually will not work. If the atom is a solvent
molecule, the user may try to refine without it. If the structure
contains atoms at special positions, a warning will be issued when
running AmberPrep.

FOR ADVANCED USERS:

phenix.AmberPrep performs several important actions to prepare
files for refinement with Phenix and Amber. This includes:

  a. checks for existence of ligands and non-standard small molecules. Derives Amber parameters using eLBOW and Antechamber

  b. cleans and modifies PDB file for conformity with Amber
  
  c. runs TLEaP to prepare Amber topology and coordinate files

  d. runs Amber's XtalUtilities to preapre Amber inputs that conform to the given crystallographic space group

  e. adds missing hydrogen atoms and possibly missing side chain heavy atoms

  f. creates a PDB input file for Phenix that corresponds in atom order and content to the Amber input files