.. highlight:: none ************ 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) ============================================================================= * For the changes made in the release see :ref:`Changelog release 1.4.1 ` * See also the BUSTER issues page https://www.globalphasing.com/buster/wiki/index.cgi?IssuesPage202307 Antecedent option terminates with an "atom index out of range" error -------------------------------------------------------------------- .. collapse:: Click to expand Using the :ref:`--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) ============================================================================= .. _csd-update-2023.2-breaks-old-grade2s: Grade2 will not work with the latest CSD update 2023.2 until you update to Grade2 ``1.4.1`` ------------------------------------------------------------------------------------------- .. collapse:: Click to expand The CSD update 2023.2 (July 2023) introduces a change that means that old Grade2 versions prior to release :ref:`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.* .. _bond-angle-sigma-zero: Bug: bond angle sigma set to zero in Grade2 restraints causes BUSTER to terminate --------------------------------------------------------------------------------- .. collapse:: 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* :ref:`#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 ------------------------------------------------------------------ .. collapse:: 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* :ref:`#580 ` *in Grade2 release* ``1.4.0``. Grade2 terminates with a "CSDNotFoundException" ----------------------------------------------- .. collapse:: 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) ------------------------------------------------------------------ .. collapse:: 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 ---------------------------------------------------------------------------- .. collapse:: Click to expand Please see :ref:`bug fix #570 ` in Changelog for details. *Bug fixed* :ref:`#570 ` *in Grade2 release* ``1.3.2``. Issues found with Grade2 version ``1.3.0`` (Distributed with BUSTER 20221121) ============================================================================= .. _issue-some-ambiguous: Grade2 does not properly handle SMILES with some ambiguous chirals ------------------------------------------------------------------ .. collapse:: 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* :ref:`#559 ` *in Grade2 release* ``1.3.1``. .. _issue_index_error: Grade2 termination ``IndexError: string index out of range`` for a very large ligand ------------------------------------------------------------------------------------- .. collapse:: 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* :ref:`#532 ` *in Grade2 release* ``1.3.1``. .. _issue_ssl_verify_failed: Grade2 ``--lookup`` and ``--pubchem_names`` terminates with ``SSL: CERTIFICATE_VERIFY_FAILED`` ----------------------------------------------------------------------------------------------- .. collapse:: Click to expand When BUSTER is installed on some Ubuntu Linux OS the :ref:`--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: ' A similar error can occur when the :ref:`--pubchem_names ` option is used. The bug has been fixed (#540) by introducing a mechanism to disable SSL verification. *Bug fixed* :ref:`#540 ` *in Grade2 release* ``1.3.1``. ---- Issues for Grade2 version ``1.2.0`` (Grade2 Update Release 31 March 2022) ========================================================================= .. _issue_smiles_charging: Charging from SMILES reorders atoms and can cause chiral inversion problems --------------------------------------------------------------------------- .. collapse:: Click to expand If Grade2 is supplied with a SMILES input that is then :ref:`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 :ref:`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 :ref:`--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* :ref:`#470 ` *in Grade2 release* ``1.3.0``. ---- Issues for Grade2 version ``1.1.0`` (Distributed with BUSTER 20220203) ====================================================================== .. _issue_mol2_charged: Grade2 cannot read a MOL2 file of a charged molecule when it has atomic partial charges --------------------------------------------------------------------------------------- .. collapse:: 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 :ref:`FAQ Editing MOL2 file of a charged molecule with atomic partial charges `. Thanks to Steven Sheriff for reporting the problem. (#444) *Bug fixed* :ref:`#444 ` *in Grade2 release* ``1.2.0``. .. _issue_coot_long_inchi: Grade2 restraint dictionaries cannot be read by Coot because of long InChI records ---------------------------------------------------------------------------------- .. collapse:: 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* :ref:`#438 ` *in Grade2 release* ``1.2.0``. On MacOS 10.15 using NFS - there may be problems running Grade2 ---------------------------------------------------------------- .. collapse:: 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* :ref:`section above ` - *Bug fixed* :ref:`#444 ` *in Grade2 release* ``1.2.0``. Grade2 restraint dictionaries cannot be read by Coot because of long InChI records ---------------------------------------------------------------------------------- *Please see* :ref:`section above ` - *Bug fixed* :ref:`#438 ` *in Grade2 release* ``1.2.0``. On MacOS, Grade2 does not work with latest CSD Release 2021.2 (September 2021) ------------------------------------------------------------------------------ .. collapse:: 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* :ref:`#390 ` *in Grade2 release* ``1.1.0``. On MacOS installation of (or update to) 2021.1 CSD Release (July 2021) causes Grade2 to crash --------------------------------------------------------------------------------------------- .. collapse:: Click to expand There is a patch for this problem. *Bug fixed* :ref:`#390 ` *in Grade2 release* ``1.1.0``. .. _old_big_planes_bug: The ``--big_planes`` option produces messed-up restraints --------------------------------------------------------- .. collapse:: Click to expand The :ref:`--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 :math:`{\sigma}` 's (standard deviation of the out-of-plane distance) for individual 4-atom plane restraints when merging, instead setting the :math:`{\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 :math:`{\sigma}` 's obtained from Mogul + custom CSD analysis: .. image:: images/DZ3_grade2_planes.png :width: 600 :alt: 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: .. image:: images/DZ3_grade2_bigplanes_bug.png :width: 600 :alt: DZ3 big planes bug diagram The subtleties of the individual 4-atom plane :math:`{\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 :math:`{\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* :ref:`#342 ` *in Grade2 release* ``1.1.0``. Bug: input from MOL2 file that has atom names containing lower case letters --------------------------------------------------------------------------- .. collapse:: 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* :ref:`#324 ` *in Grade2 release* ``1.1.0``. Bug: grade2 will fail if the environment variable ``PYTHONPATH`` is set ----------------------------------------------------------------------- .. collapse:: 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* :ref:`#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 ---------------------------------------------------------------------------------------------------------------- .. collapse:: 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 :ref:`--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* :ref:`#333 ` *in Grade2 release* ``1.1.0``. .. code-block:: none . (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.