Known Issues

Please check the online version of this issues page: https://gphl.gitlab.io/grade2_docs/issues.html as this is updated frequently as new issues arise.

Issues found with Grade2 version 1.4.1 (Distributed with BUSTER 20230726)

Antecedent option terminates with an "atom index out of range" error

Click to expand

Using the --antecedent RELATED_RESTRAINTS_CIF option with a restraint dictionary for a related molecule that matches only part of a large complex ligand can result in Grade2 terminating with error messages, like the following:

...
ANTECEDENT: 16 unmatched atoms from input molecule so set new atom IDs: C10 C11 C12 C13 C14 N15 N16 O17 O18 H10A H10B H12 H14A H14B H15 H16
ERROR: Exception "atom index out of range" found in creating dictionary.
ERROR: Please rerun with --debug and report error to buster-develop@globalphasing.com

The problem is caused by difficulties in creating 2D coordinates with the matching atoms being aligned.

The bug will be fixed in the next release of Grade2 (fix #632).

In the meantime, it is possible to workaround the problem by editing the restraint dictionary used for the --antecedent option and removing the CIF loop pdbe_chem_comp_atom_depiction that contains the 2D coordinates.

Issues found with Grade2 version 1.4.0 (Distributed with BUSTER 20230614)

Grade2 will not work with the latest CSD update 2023.2 until you update to Grade2 1.4.1

Click to expand

The CSD update 2023.2 (July 2023) introduces a change that means that old Grade2 versions prior to release 1.4.1 will not work with it.

The easiest way to ensure compatibility is to update both BUSTER (and hence Grade2) and CSD. Please see the CSD compatibility chapter https://gphl.gitlab.io/grade2_docs/csd_compatibility.html for further details.

Grade2 release 1.4.1 works with both the CSD update 2023.2 and with older versions of the CSD.

Bug: bond angle sigma set to zero in Grade2 restraints causes BUSTER to terminate

Click to expand

Occasionally, Mogul returns a bond angle sigma of 0.0º. When this occurs the TNT program used Grade2 via gelly reports an error message that is included in the gelly output:

WARNING: ERROR in running gelly. Details: gelly optimization run failed
...
gelly_log_output:  ************** Error encountered in program GEOMETRY            **************
gelly_log_output:
gelly_log_output:  Line   983 in file gelly.tnt
gelly_log_output:
gelly_log_output:  GEOMETRY XXX ANGLE 109.7 0.0 C69 C71 C72
gelly_log_output:                               !
gelly_log_output:
gelly_log_output:
gelly_log_output:                Sigma cannot be zero or negative!

Grade2 then proceeds and writes a .restraints.cif file including the bond angle with the problematic sigma of 0.0º. Using this restraint file in BUSTER will cause BUSTER to fail because of the TNT GEOMETRY protecting against Sigma cannot be zero or negative errors.

This issue affects all versions of Grade2 prior to release 1.4.1.

As a temporary workaround, the .restraints.cif can be edited to alter the CIF item _chem_comp_angle.value_angle_esd for the problem bond angle from 0.0 to 0.3. The editing can be done either with a text editor or with a restraint editor like EditREFMAC or within Coot. Once this is done then BUSTER should be able to use the .restraints.cif without any problems.

Thanks to Christian Schleberger for reporting this bug.

Problem fixed #622 in Grade2 release 1.4.1.

Issues found with Grade2 version 1.3.2

Getting Grade2 to work with CSD release 2023.1 released April 2023

Click to expand

The CSD release 2023.1 made late April 2023 involves a large alteration in its directory structure. The next Grade2 release (due in early June 2023) will work immediately with CSD 2023.1. Until then there is a workaround to get Grade2 to work with the new CSD release.

Problem fixed #580 in Grade2 release 1.4.0.

Grade2 terminates with a "CSDNotFoundException"

Click to expand

After update to CSD release 2023.1, it is possible for Grade2 to terminate with an error message ending with a line that contains CSDNotFoundException. If this occurs please see: FAQ Grade2 terminates with a "CSDNotFoundException", what should I do?.

Grade2 -P, --PDB_ligand failed for some PDB components (now fixed)

Click to expand

Between 31 March 2023 and 13 April 2023 grade2 --PDB_ligand or grade2 --P failed for many PDB components with an error that ended pdbecif.mmcif_tools.MMCIFWrapperSyntaxError. The problem was caused by a change to the ccdtools tool used at PDBe to the chemical components definitions (CCDs). This has now been fixed https://github.com/PDBeurope/ccdutils/issues/12 and grade2 --PDB_ligand will now work fine.

The problem affected all versions of Grade2 but has been fixed by PDBe. Big thanks to the PDBe team, particularly Ibrahim Roshan for the fix.

Issues found with Grade2 version 1.3.1 (Distributed with BUSTER 20230217)

Grade2 wrongly assigns ambiguous chiral restraints for some SDF input files

Click to expand

Please see bug fix #570 in Changelog for details.

Bug fixed #570 in Grade2 release 1.3.2.

Issues found with Grade2 version 1.3.0 (Distributed with BUSTER 20221121)

Grade2 does not properly handle SMILES with some ambiguous chirals

Click to expand

When Grade2 is given an input SMILES string having some chiral center configurations specified but some left ambiguous it arbitrarily assigns a configuration to the ambiguous centers.

The bug affects all Grade2 releases prior to 1.3.1.

Thanks to Meigang Gu for reporting this bug.

Bug fixed #559 in Grade2 release 1.3.1.

Grade2 termination IndexError: string index out of range for a very large ligand

Click to expand

When supplied with a ligand that has contains than 26 six-membered rings Grade2 crashes with an error message that ends:

File "grade2/restraint_dictionary_creator.py", line 1401, in grade2.restraint_dictionary_creator.RestraintDictionaryCreator._setup_rings
IndexError: string index out of range

The error occurs because rings are given identifiers in the sequence ring6A, ring6B, ring6C ... ring6Z. This broke down when there are more the 26 rings.

The bug has been fixed (#532) allowing any number of rings by continuing the sequence of identifiers ... ring6Z, ring6AA, ring6AB The bug affects all Grade2 releases prior to 1.3.1.

Thanks to Deepak Deepak for reporting this bug.

Bug fixed #532 in Grade2 release 1.3.1.

Grade2 --lookup and --pubchem_names terminates with SSL: CERTIFICATE_VERIFY_FAILED

Click to expand

When BUSTER is installed on some Ubuntu Linux OS the --lookup ID using the default pubchem_g2_lookup_script.py script distributed with BUSTER can fail terminating with an error message that includes SSL: CERTIFICATE_VERIFY_FAILED. For example:

$ grade2 -f --lookup 2244
ERROR in running --lookup: 2244
ERROR 'Problem running --lookup_script: pubchem_g2_lookup_script.py: connection error:
<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: self signed certificate in certificate chain (_ssl.c:1076)>'

A similar error can occur when the --pubchem_names option is used.

The bug has been fixed (#540) by introducing a mechanism to disable SSL verification.

Bug fixed #540 in Grade2 release 1.3.1.

Issues for Grade2 version 1.2.0 (Grade2 Update Release 31 March 2022)

Charging from SMILES reorders atoms and can cause chiral inversion problems

Click to expand

If Grade2 is supplied with a SMILES input that is then charged then atoms are often reordered during the charging process. This reordering can cause chiral inversions compared to the original input. The bug was first observed when testing the new amino acid atom labelling feature using modified amino acids from SMILES strings and can cause an erroneous chiral restraint forcing a D-amino acid conformation.

The problem can be avoided by using the --no_charging command-line option that will mean the original SMILES string will be used. If charging is wanted then the resulting Grade2 restraint dictionary can be used for a follow-on Grade2 run. For instance:

$ grade2 'C[C@@H]1CC=N[C@H]1C(=O)NCCCC[C@@H](C(=O)O)N' --no_charging -o pyl_smiles_no_charge --just_cif

$ grade2 --in pyl_smiles_no_charge.restraints.cif -o pyl_smiles_zwitterionic

the second Grade2 run will apply charging so a zwitterionic amino acid restraint dictionary is produced.

Please note that the bug is limited to SMILES inputs and does not occur with other kinds of input like SD files. This bug affects previous Grade2 releases.

Thanks to Andrew Sharff and Matthias Zebisch for reporting this bug.

Bug fixed #470 in Grade2 release 1.3.0.

Issues for Grade2 version 1.1.0 (Distributed with BUSTER 20220203)

Grade2 cannot read a MOL2 file of a charged molecule when it has atomic partial charges

Click to expand

Depending on their source, MOL2 files can contain a variety of atomic charge records. Grade2 uses CSD routines to read MOL2 files and can correctly process MOL2 files for neutral uncharged molecules. Currently, grade2 has a problem reading in molecules with formal charges when the MOL2 has partial charge records (that will result in unusual valence and RDKit sanitization errors). There is no problem reading MOL2 files that use the CSD convention where the atomic charges are used for formal charges, for instance those written by Conquest or Grade2 itself.

We are currently working on improving Grade2 so that it will better handle MOL2 files with partial charges. This will be included in the next release. In the meantime, it is possible to manually edit correct formal charges, please see the FAQ Editing MOL2 file of a charged molecule with atomic partial charges. Thanks to Steven Sheriff for reporting the problem. (#444)

Bug fixed #444 in Grade2 release 1.2.0.

Grade2 restraint dictionaries cannot be read by Coot because of long InChI records

Click to expand

For large molecules, attempting to read a Grade2 restraint dictionary results in an error message that begins Dirty mmCIF file?, for instance:

Dirty mmCIF file? T8W.restraints.cif
   Bad mmdb::mmcif::CIFRC_Ok on ReadMMCIFFile
   Unknown error.
CIF error rc=544 reason:unrecognized items found on 1691th line

The problem occurs because of long InChI records in the restraint dictionary and also occurs with CCP4-distributed restraint dictionaries. Currently the CCP4 MMDB library (against which Coot is linked) places a line length limit of 500 characters, despite the IUCR CIF specification allowing lines of up to 2048 characters. We have let CCP4 know and the limit will be raised in a future CCP4/Coot release. As an additional measure to avoid the problem, the next Grade2 release will not output long InChI records.

In the meantime, if the problem occurs then please adapt the following command-line fix:

grep "InChI=" -v T8W.restraints.cif | tr -s ' ' > T8W.restraints.fixed.cif

The resulting restraint dictionary will be stripped of the problematic lines and should work with Coot.

Thanks to Steven Sheriff for reporting this problem. (#438)

Bug fixed #438 in Grade2 release 1.2.0.

On MacOS 10.15 using NFS - there may be problems running Grade2

Click to expand

We have found a problem in running Grade2 on a MacOS 10.15 workstation where the software has been installed on a NFS-mounted filesystem. If you come across such issues please let us know.

Issues for Grade2 version 1.0.0 (Distributed with BUSTER 20210716 and 20211020)

Grade2 cannot read a MOL2 file of a charged molecule when it has atomic partial charges

Please see section above - Bug fixed #444 in Grade2 release 1.2.0.

Grade2 restraint dictionaries cannot be read by Coot because of long InChI records

Please see section above - Bug fixed #438 in Grade2 release 1.2.0.

On MacOS, Grade2 does not work with latest CSD Release 2021.2 (September 2021)

Click to expand

On MacOS there is a problem using Grade2 with the latest CSD update due to library duplication.

So please do not update CSD to release 2021.2

Bug fixed #390 in Grade2 release 1.1.0.

On MacOS installation of (or update to) 2021.1 CSD Release (July 2021) causes Grade2 to crash

Click to expand

There is a patch for this problem.

Bug fixed #390 in Grade2 release 1.1.0.

The --big_planes option produces messed-up restraints

Click to expand

The --big_planes option merges neighbouring individual four-atom planes into as large a single plane as possible. -big_planes was included in the Grade2 options as Grade had this feature. Unfortunately, the current Grade2 --big_planes option ignores the \({\sigma}\) 's (standard deviation of the out-of-plane distance) for individual 4-atom plane restraints when merging, instead setting the \({\sigma}\) of each big plane to 0.020 Angstroms.

For example, for PDB component DZ3 https://www.rcsb.org/ligand/DZ3 Grade2 produces four-atom planes with \({\sigma}\) 's obtained from Mogul + custom CSD analysis:

DZ3 plane sigmas diagram

In particular, notice the weak planes across the bonds joining the phenyl rings to the amide (marked in green). These weakly encourage planarity but can easily overcome if the electron density fit warrants it.

Running grade2 -P DZ3 --big_planes produces a single big plane:

DZ3 big planes bug diagram

The subtleties of the individual 4-atom plane \({\sigma}\) 's are ignored and the single plane is erroneous, imposing unrealistic conformational restriction.

We will be looking at whether it is sensible to merge plane definitions given that plane \({\sigma}\) 's are now derived from CSD analysis and how this best be done. This issue will be fixed in the next release. For now, it is strongly recommended that the Grade2 --big_planes option should not be used.

The BUSTER tool aB_fuseplanes that has a number of different modes for combining planes. Unfortunately, aB_fuseplanes from Jul 16 2021 BUSTER release does not work with Grade2 CIF restraint dictionaries. The issue has been fixed in the BUSTER release Oct 20 2021 and aB_fuseplanes now works with Grade2 CIF restraint dictionaries. Initial test show that aB_fuseplanes -checkTOR produces a reasonable set of fused planes.

Bug fixed #342 in Grade2 release 1.1.0.

Bug: input from MOL2 file that has atom names containing lower case letters

Click to expand

If supplied with a MOL2 file that has atom names with lower case letters such as Cl2 Grade2 will output a restraint dictionary CIF using these identifiers unchanged. This will cause a downstream problems as BUSTER cannot cope with lower case letters in atom names. Thanks to Dirk Reinert for reporting this.

Grade2 should emulate Grade when by giving a WARNING message and then making the atom name upper case. The bug will be fixed (#324) in the next release. In the meantime, then sed (or awk) could be used as a workaround, for instance:

sed -i -e "s/Cl/CL/g" L_1.*

Bug fixed #324 in Grade2 release 1.1.0.

Bug: grade2 will fail if the environment variable PYTHONPATH is set

Click to expand

The environment variable PYTHONPATH can be set to add additional directories where Python will look for modules and packages (see tutorialspoint PYTHONPATH for more detail). In general, it is best practice to avoid setting PYTHONPATH in your default run time environment in order to get a particular program to work as this can interfere with other programs.

Currently, Grade2 is vulnerable to PYTHONPATH being set and will fail with a message being ERROR: ImportError when grade2 is run. Thanks to Yong Wang for reporting the problem.

The easiest way to avoid the problem is to unset PYTHONPATH before Grade2 is run by:

unset PYTHONPATH

One way to do this is to use an alias for grade2, for bash/dash shell this can be done by:

alias grade2='unset PYTHONPATH; $BDG_home/scripts/grade2'

Alternatively the wrapper script $BDG_home/scripts/grade2 could be edited adding a line unset PYTHONPATH after the first line.

The bug will be fixed in the next release (#349).

Bug fixed #349 in Grade2 release 1.1.0.

Bug: "Suggestion: to view/edit the restraints, use one of the commands" gives wrong filenames when --out is used

Click to expand

Grade2 tries to be helpful by suggesting commands that can be used to view or edit the restraints. For instance, if restraints for the PDB chemical component ID VIA are produced by:

$ grade2 --PDB_ligand VIA

The terminal output produced will end with:

Have written CIF-format restraint dictionary to:   VIA.restraints.cif
Have written ideal coordinates to PDB-format file: VIA.xyz.pdb
Have written ideal coordinates to SDF-format file: VIA.xyz.sdf
Have written ideal coordinates in  MOL2-format to: VIA.xyz.mol2
Have written schematic 2D diagram SVG-format file: VIA.diagram.svg
Have written 2D diagram & atom_id labels to file:  VIA.diagram.atom_labels.svg
Suggestion: to view/edit the restraints, use one of the commands:
    coot -p VIA.xyz.pdb --dict VIA.restraints.cif
    EditREFMAC VIA.restraints.cif VIA.xyz.pdb VIA
Normal termination (16 secs)

The EditREFMAC and coot commands will work to be able to view/edit the restraints produced.

However, if the --out option is used then currently incorrect suggested commands are given. For example, running:

$ grade2 'Oc1ccccc1' --resname LIG --out compound_356

currently produces incorrect suggested commands:

Have written CIF-format restraint dictionary to:   compound_356.restraints.cif
Have written ideal coordinates to PDB-format file: compound_356.xyz.pdb
.... (edited)
Have written 2D diagram & atom_id labels to file:  compound_356.diagram.atom_labels.svg
Suggestion: to view/edit the restraints, use one of the commands:
    coot -p LIG.xyz.pdb --dict LIG.restraints.cif
    EditREFMAC LIG.restraints.cif LIG.xyz.pdb LIG

both commands will fail as the restraint dictionary and PDB filenames are incorrect. The suggested commands will be corrected in the next release of Grade2, in this case to:

Have written CIF-format restraint dictionary to:   compound_356.restraints.cif
Have written ideal coordinates to PDB-format file: compound_356.xyz.pdb
.... (edited)
Suggestion: to view/edit the restraints, use one of the commands:
    coot -p compound_356.xyz.pdb --dict compound_356.restraints.cif
    EditREFMAC compound_356.restraints.cif compound_356.xyz.pdb LIG

For now, please manually correct the command.

Thanks to Dirk Reinert and Jola Kopec for reporting this bug.

Bug fixed #333 in Grade2 release 1.1.0.

.


























(the blank lines above are included so that hyperlinks to issues above work better).

Please check the online version of this issues page: https://gphl.gitlab.io/grade2_docs/issues.html as this is updated frequently as new issues arise.