Authors

Principal authors: Pawel Janowski and Nigel W. Moriarty

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

The Phenix user should install the latest AmberTools. AmberTools is avaialable free of charge at www.ambermd.org. Follow the installation instructions in the Amber manual. One important note, you must set the environmental variable $AMBERHOME. This is required for the installation and can be added to the appropriate login script (bashrc or cshrc).

To create to bridge between Phenix and Amber, run:

[~:]$ phenix.build_amber_interface

This will create a link to $AMBERHOME in the Phenix installation, reconfigure Phenix to include Amber and build the code required to prepare Amber files and run them seamlessly with Phenix. Amber will remain linked and therefore $AMBERHOME should remain set to the Amber installation.

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_factor=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.

wxc_factor - relative weight between the x-ray and the Amber

geometry restraint terms in refinement. By default this is set to 0.5 which is the value that works best with conventional (Engh&Huber) restraints. When using Amber we recommend wxc_factor=0.025, but tests indicate that values from 0.025 to 0.075 work well. Lower values improve model quality while higher values tend to improve R-factors. The user is encouraged to experiment. (Float; default=0.5)

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:

1. Phenix automatically recognizes the user's environment at runtime. Therefore, if you have multiple versions of Amber installed and would like to switch between them, it is sufficient to change the AMBERHOME variable and source the corresponding $AMBERHOME/amber.sh script before running Phenix. However, if you are using MDGX for your gradient calculation (the default is to use Sander and MDGX use should only be reserved for advanced users) you will also need to change the soft link to Amber in your Phenix modules directory.

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

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

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

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