BUSTER frequently-asked questions

I get an error message 'OMP abort...

Answer from Claus Flensburg

  • The core refinement part of BUSTER is a fairly complicated multi-threaded program, and as such needs rather a lot of stack space; if you get error messages of the form
OMP abort: Unable to set worker thread stack size to 4194304 bytes
  • solutions:
    • Try reducing KMP_STACKSIZE or increasing the shell stack limit.
    • Then try ulimit -s unlimited to permit applications to use a larger stack.
    • If neither of these work, unset KMP_STACKSIZE; unsetenv KMP_STACKSIZE (or its equivalent in your favourite shell) has worked in some cases.

A MakeTNT application does not run.

Answer from Peter Keller.

  • If any MakeTNT application (MakeTNT, PDB2TNT, MDL2TNT, MOL22TNT, EditTNT, EditREFMAC or MakeLINK) fails to run please see MakeTNT applications do not run page for advice.

grade_PDB_ligand gives a message 'Tool babel not found on path'

Answer from Tom Womack

  • grade_PDB_ligand uses the 'babel' tool from the OpenBabel software suite to convert the PDB files, which are what LigandExpo makes available to describe ligands, to MOL2 format and assign atom types for use by grade. This tool has to be on your path.

I get an error message 'rms gradient is NaN'

This rather unhelpful message will be improved in the next release. For the August 2009 academic release, it normally means that your PDB file has two atoms in exactly the same place, generally because you went through a list of peaks in coot and inserted a water atom in one of them twice.

To find these, you could do

egrep -e "^(ATOM  |HETATM)" model.pdb | awk '{print substr($_,30,24)}' | sort | uniq -d

which will tell you the coordinates, and then grep model.pdb for the coordinates and delete one of the coincident atoms.

I get a 'error code 11' from grade when using mol2 input generated by CORINA

This is a known issue in grade in the February release; adding

-o t=mol2,fcharges

to your CORINA command line should produce mol2 output that grade can parse. This will be fixed in the next release.

I get a 'server: bind: Operation not supported' message from refine

BUSTER requires that the file system it's running on supports the creation of UNIX sockets - the Linux and Darwin local filesystems and NFS do this, but AFS does not. If you see this message, try running BUSTER in a directory on a local filesystem.

How can I check my BUSTER is correctly installed? How fast is it supposed to run?

Answer from Tom Womack

We distribute a test script refine_test.sh which runs a small refinement, using the options that we would recommend for regularising a structure and generating a new map after you've done a bit of rebuilding in coot; information on how to run it and on how long it takes to run on several machines we have tested it on is at the BusterShortRefineTest page.

What BUSTER output should I look at?

Please see dedicated page on interpreting BUSTER output

When should I start using TLS?

Answer from Tom Womack:

For relatively high-resolution X-ray data, I've found that TLS is useful for making difference density clearer at the end of a refinement; once modelling to take account of difference density is starting to become frustrating, running BUSTER with -M TLSbasic sometimes makes the density enough more clear that you can do another couple of model-and-run-BUSTER cycles. Once you've started using TLS, it's probably best to keep using it for the rest of the refinement.

For low-resolution data and models where there is a well-understood domain structure, TLS may well be useful from the very beginning, and we'd be very interested in hearing any success stories, particularly ones non-proprietary enough that they could at some point be converted into tutorial material.

Why does BUSTER use one B-factor per atom even at 3Å resolution?

Answer by Tom Womack

The BUSTER geometry function incorporates a very strong BCORREL term which couples the B-factors of bonded atoms; so neighbouring atoms are restrained to having similar B-factors. In tests, this 'soft grouping' works well from high resolution at least as far as 3Å.

At very high resolutions (say 1.2Å and below) you may want to use GeometryWeight_bcorrel=0 to allow the B-factor to be refined separately and in an unrestrained fashion for every atom.

In visualise-geometry-coot, what is an "Unhappy atom"?

Answer by Oliver Smart

The "unhappy atom" category uses the information from the geometry screen output (you can find this by follow link from LIST.html):

Atoms that make the largest contribution to overall function value.
    Report the (function contribution)/(median contribution). Median= 8.093
        5.5     A|175:CA(LEU)
        4.8     D|175:CA(LEU)

So it is a measure of the atom's total geometry function contribution including BOND, ANGLE, STORS, PLANE, BCORREL, IDEAL, BAD terms. LSSR is excluded from the measure. So if an atom is "unhappy" this can be because a combination of things add to make it so. Generally if the number is large the area will need rebuilding.

Why does BUSTER refinement result in a molprobity score with a large number of C-beta deviations? Is there anything that I can do about this?

Answer by Oliver Smart

  • The geometry function used by BUSTER was greatly improved in the July 2009 releases compared to the old function which produced very poor molprobity scores. There was a great improvement in all categories other than C-beta deviations.
  • We are still looking into this. The restraints in the Engh & Huber dictionary are enough to define the chiral volume around a C-alpha; we augment them with a chiral restraint that is only active when the conformation is badly distorted, whilst other programs put an additional always-active restraint on the chiral volume. We suspect that this over-restrains the terms around the C-alpha, and so molprobity's statistics might be based on over-restrained structures.
  • If you want to ensure fewer C-beta deviations, then the following additional restraint dictionary file defines harmonic restraints on the chirality of C-alpha atoms:
-Gelly protgeo_option_chiralrestraint_from_equilib.dat
    • for a practical example of what effect this has see page: AutoBusterCBetaDeviations
    • we have not yet finished examining whether this should be used by default.

Why do the Rfree and Rfact values change abruptly at the start of the final cycle of a BUSTER refinement?

Answer by Andrew Sharff

If the parameter AnalyseVoids is set to 'yes', as it is by default, then the solvent-correction process in the final cycle attempts to account for hydrophobic voids. We have found that this is often useful in removing patches of negative difference density from, for example, the interior of helix bundles; if you find that the change is for the worse on one of your structures, try running with refine AnalyseVoids=no.

How should I run a BUSTER refinement after some model rebuilding with coot?

Answer by Andrew Sharff

The February 2011 release includes macros specially for BUSTER refinement after some model rebuilding with coot: see AutoBusterShortRunMacros page.

What is an easy way to get started with occupancy refinement?

We provide a simple tool to generate appropriate commands (in Gelly-syntax) describing the most common classes of occupancy refinement:

  • alternate conformations
    • this includes consecutive alternate conformations describing e.g. two loop conformations (the important point here is that conformations belong to one loop conformation should all have the same alternate conformation identifier)
  • partially occupied atoms
    • this includes waters, ions, ligands or cofactors

Analysis is based on some basic assumptions, like

  • the occupancy in the PDB file is below 1
  • occupancy of atoms belonging to the same residue (and same alternate conformation identifier) have identical occupancy


% pdb2occ -p your.pdb -o occref.gelly
% refine -p your.pdb -Gelly occref.gelly ...

will first analyse the existing PDB file (creating the text file occref.gelly), which is subsequently used in refinement. The text file can also be used as a starting template for defining more complicated situations. For further information and a full example please see AutoBusterLigandAndOccRef.

How do I specify the value used to select the set of reflections used for computing R-free?

Answer by Claus Flensburg

The October 2010 release introduced the parameter BusterFreeFlagValue:

% refine ... BusterFreeFlagValue=0

It defaults to '0' to follow the usual CCP4 selection. For releases prior to that one has to use the indirect specification:

% refine ... BusterExtraKwds="FREFLG=0"

You can also see AutoBusterFreeRFlag

What exactly do the 24 columns in the output MTZ file mean?

Answer by Tom Womack

There are a few circumstances (PDB deposition in particular) in which you have to pick columns from the MTZ file; the MTZcolumns page aims to explain what each column means and under what circumstances you should pick it.

Handling LINKs and covalent ligands in BUSTER

Answer by Oliver Smart

  • To get BUSTER to recognize a covalent link as bonded then make sure that the input PDB file has a LINK card in it (see). The current BUSTER (from 2011) version will handle the LINK as follows, however far apart the atoms are in the model:
    • if the atoms and the residues involved in the link are of kinds known to make a particular sort of bond (eg C1 of a pyranose sugar to O4 of another pyranose), enforce the standard geometry for that kind of linkage
    • if they are not, impose a bond length between the two atoms depending on the element type, leaving the angles unrestrained
  • For a better treatment of the geometry of the LINK see GradeCovalentTutorial
  • If your input model contains accidental contacts between protein regions from different parts of the sequence (this is something we have seen for output from Buccaneer or from mediocre molecular-replacement output) then the 2011 handling of peptide linkage within the protein using MakeLINK may introduce incorrect cross-links, which will tend to be reported as sanity-check failures from BUSTER. In these cases you should run with the option SequenceFileGeneration=pdb2seq.

How do I set up a disulfide bond to a symmetry-related CYS?

Answer by Oliver Smart

This can be done by adding a SSBOND card before the CRYST1 line in the input PDB file. The card must have correct column spacing.

SSBOND   1 CYS A  429    CYS A  476                          1555   4445  2.04
key:           c nnnn        d mmmm                               oooooo
change 'c' and 'nnnn' to the chain id residue number of the identity copy CYS
       'd' and 'mmmm' to the chain id residue number of the symmetry related CYS
leave  'oooooo' alone, provide it is not 1555 BUSTER will work out the correct symmetry operator.

PDB entry http://www.rcsb.org/pdb/files/4J0U.pdb provides an example with correct column spacing and a pretty disulfide across a symmetry contact:

    • 4j0u_SSBOND_coot.png

Currently BUSTER refine will suggest adding a SSBOND lacking a symmetry operator that will not work! This bug will be fixed in the next release this note dated April 2013

Is there anything I can do with grade if all I have as input is a PDB file with no hydrogens?

If that's all you have, then the general answer is no; it's entirely possible for a PDB file arising from a sufficiently badly driven refinement process to lack critical information about the chemistry of the ligand. But if you also have a good idea as to what the chemistry is, have a look at HydrogenatePDBwithOpenBabel

What is the order and the priorities for setting specific options?

The order in which settings can be changed from the defaults when running BUSTER:

1. installation-wide

This means a .autoBUSTER file in the same directory as the command (e.g. 'refine'). Or in more practical terms, these files should be located in

  • for sh/bash/ksh/zsh:
    % dir=`which refine`
    % ls -l `dirname $dir`/.autoBUSTER
  • for tcsh/csh
    % set dir=`which refine`
    % ls -l `dirname $dir`/.autoBUSTER

2. user-wide

A file in the users home directory, i.e.


3. directory-wide

A file in the current directory (where the command, eg. 'refine' is being issued):


4. environment

Setting environemental variables in the usual shell-dependent way, eg.

  • for sh/bash/ksh/zsh
    % MyParameter="XYZ"
    % export MyParameter
    % refine ...
  • for tcsh/csh
    % setenv MyParameter "XYZ"
    % refine ...              

5. command-line

% refine MyParameter="XYZ" ...


% refine -M MyMacro ...

where a file MyMacro.macro contains something like

# my fancy stuff

and the directory containing that MyMacro.macro file being specified in the autoBUSTER_MacroDirs environmental variable.

Remember, the command-line is read in order, so

% refine MyParameter="ABC" -M MyMacro ...

will have a different effect to

% refine -M MyMacro MyParameter="ABC" ...

There is a big advantage of just using command-line arguments of the form par="value": the complete command-line is written into the header of the final refine.pdb file - so you always know exactly how it was run.

What is the optimal number of processors to use with BUSTER?

Please see the dedicated page Optimal number of processors for BUSTER.

How can I specify a specific Perl version/binary for use with BUSTER?

You should be able to set a specific Perl binary at installation time via

% env BDG_perl=/where/ever/bin/perl ./GPhL_BUSTER_snapshot_20190607_install.sh

to have this binary set within the BUSTER installation (instead of taking the location of "perl" from the PATH at installation time).

If you need to use another Perl version than the one found when BUSTER was installed, you can do the following:

  • Lets assume the new Perl binary is located at /opt/myperl/bin/perl.
  • You can then test this e.g. with hydrogenate by using :
      % env BDG_perl=/opt/myperl/bin/perl KeepFromEnv_BDG_perl=yes hydrogenate ...

If this works, you could add the following lines to your $BDG_home/setup_local.(c)sh files:

# setup_local.csh
setenv BDG_perl /opt/myperl/bin/perl
setenv KeepFromEnv_BDG_perl yes


# setup_local.sh
export BDG_perl=/opt/myperl/bin/perl
export KeepFromEnv_BDG_perl=yes

Remember to re-source the setup file again via

% source $BDG_home/setup_local.csh    # tcsh/csh
  - or -
% . $BDG_home/setup_local.sh          # sh/bash/zsh/ksh/dash

BusterFAQ page. Please address problems, corrections and clarifications to buster-develop@globalphasing.com