Running phenix.refine using Amber gradients



Principal authors: Nigel W. Moriarty, Pawel Janowski, Hai Nguyen & 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 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

From Phenix 1.16, Amber is distributed with the standard installer for unix and OSX. To run Amber in Phenix, in addition to a PDB file, a topology and a coordinate file must be provided for Amber. From Phenix 1.18, you can allow the phenix.refine GUI to run AmberPrep, automatically creating the files needed. You can also easily create these files by using the provided AmberPrep utility via the AmberPrep GUI or via the commandline:

phenix.fetch_pdb 4Lzt --mtz
phenix.AmberPrep 4Lzt.pdb

which will generate four files.


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 4Lzt.pdb. Having created the input files, refinement can be run as follows:

phenix.refine 4phenix_4Lzt.pdb 4Lzt.mtz use_amber=True topology_file_name=4amber_4Lzt.prmtop coordinate_file_name=4amber_4Lzt.rst7

Here is list of 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.
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)


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_4Lzt.prmtop coordinate_file_name=4amber_4Lzt.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 (True/False, default=True)

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.


1. To use MDGX instead of Sander for gradient calculation, use md_engine=mdgx keyword for phenix.refine. The default md_engine is Sander.

2. phenix.refine with Amber also has a hidden wxc_factor parameter. In ordinary refinement the x-ray term is scaled by the ratio of the gradient norms between the x-ray and geometry terms times the wxc_factor (default 0.5 when using E&H; recommended 0.025 when using Amber). If wxc_factor is set, the ratio of the gradient norms will be ignored and the x-ray term will be scaled by wxc_factor directly. This is an experimental feature and has not been shown to improve refinement in any way.

3. The advanced user may wish to change the Amber force field used to impose geometry restraints. Be default the force field used is ff14SB. This can easily be changed by modifing AmberPrep script, run_tleap() method, to source a different force field from Amber.

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

  1. checks for existence of ligands and non-standard small molecules. Derives Amber parameters using eLBOW and Antechamber
  2. cleans and modifies PDB file for conformity with Amber
  3. runs TLEaP to prepare Amber topology and coordinate files
  4. runs Amber's XtalUtilities to preapre Amber inputs that conform to the given crystallographic space group
  5. adds missing hydrogen atoms and possibly missing side chain heavy atoms
  6. creates a PDB input file for Phenix that corresponds in atom order and content to the Amber input files