gelly Documentation : Introduction

Contents

• What is gelly?
• This manual
• Contact the authors
• Using gelly within BUSTER
• Doing geometry-only regularisation with gelly_refine tool
• Setting gelly run options

What is gelly?

• gelly is the name of the refinement and geometry module included as part of the BUSTER program.
• It is also supplied with BUSTER as a separate executable that can be used to refine with the GEOMETRY function only (no X-ray term). This is useful for fixing geometry restraint violations caused by manual rebuilding. The regularisation will cause bond lengths, angles, short contacts to be adjusted to the "ideal" values. It is easiest to use this separate executable by using the gelly_refine wrapper as this will do all the restraint file setup, coordinate conversion, weight assignment in an identical manner to BUSTER.
• gelly is based on the geometry program supplied with TNT, written by Lynn Ten Eyck and Dale Tronrud. It replaces the geometry, shift and ncs programs in BUSTER operation.
• gelly enables a much more powerful optimisation method to be used for X-ray crystallographic refinement.
• If you are refining too many degrees of freedom then you will also notice that the gelly optimiser quickly widens the Rfactor Rfree gap. This is not a problem with the optimiser: instead it indicates that you are trying to adjust more parameters than your data/current model justify. We are currently working hard on procedures to help for this case.
• gelly takes novel approaches for various parametrisations (e.g. rigid body parameters, NCS restraints).

This manual

• The gelly optimisation module can normally be used without worrying about what is presented here.
• Often BUSTER will be using new features that gelly enables in an automated fashion.
• However, you may wish to get access to features that are not yet provided in an automatic manner or to do things in a distinct way.
• This manual provides the full details of the additional control cards that gelly introduces. If you find anything confusing or need help in other way please let us know.

Contact the authors

• Gelly was initially primarily written by Oliver S. Smart( with many contributions from Tom Womack, Claus Flensburg, Wlodek Paciorek, Clemens Vonrhein, Maria Brandl and Gerard Bricogne). Since 2015 the main contributors are Claus Flensburg and Clemens Vonrhein.
• It is under active development.
• We welcome comments and user feedback both good and bad.
• Please send feedback to buster-develop@globalphasing.com

Using gelly within BUSTER

Doing geometry-only regularisation with gelly_refine tool

If you want to control the geometry function and/or parameter selection in gelly_refine use the -l <filename> option. This can be used to introduce a file of Gelly cards. For example if you want to geometry regularise only part of a molecule that has been rebuilt before full refinement. then produce a file with appropriate NOTE BUSTER_CONSTANT XYZ ... cards and use this with the -l option.

gelly command line options

• gelly command line options are used primarily to control detailed features of a run. The controls can include things like the convergence gradient limit and how frequently pdb files are written.
• For the gelly_refine geometry regularization tool, command line arguments not recognised by the tool itself will be passed directly to gelly.

  For example, a useful combination of options is

  gelly_refine -type one -screen_sigma 3.0 -p foo.pdb -d screenit -o /dev/null

  which writes a summary of all the restraint violations worse than 3 sigma for foo.pdb to screenit/gelly_refine.log

• The most useful gelly command line options are are

  -autoncs	automatically detect NCS and impose LSSR restraints for these.
  -autoncs2	automatically detect NCS and impose LSSR v2 restraints for these.
  -autoncs_weight <w>	use weight w for -autoncs LSSR restraints (should not be required when using LSSR v2).
  -target <file.pdb>	impose target LSSR restraints to file.pdb.
  -target_weight <w>	use weight w for -target LSSR restraints.
  -sim_swap_equiv	Swap equivalent atoms to improve NCS and/or target restraints
  -special_dist <d>	Distance cutoff d for special position handling
  -glim <n>	Set the gradient convergence limit to terminate a small cycle. Terminate the optimisation when the RMS gradient drops below n units
  -dlim <n>	Stop the optimisation when the RMSd movement of the molecule is more than n Å
  -keeppdb <n>	Write out a pdb file every n small cycles
  -verbose <n>	Set the level of reporting produced by gelly. The default level is -verbose 2; verbose level 4 produces enormous lists, for example every inter-atom bond and the full list of atoms in each COMBINE and CONSTANT set, but is useful for bug reports.
  -screen <NS>	Adjust screen output so that it report the worst NS violations of each kind of restraint (default 100)
  -screen_sigma <s>	Report up to NS restraint violations worse than s sigmas (default 3.0)
  -type one	gelly_refine only - Just calculate the initial function values and display a report, rather than optimize
  -max <n>	gelly_refine only - Allow up to n optimisation steps (within BUSTER/refine use the -nsmall argument instead).