Installation, Configuration & Testing

Installation

Grade2 is installed as part of the BUSTER distribution. For a full description of how to install BUSTER please see the installation documentation included with the package:

$BDG_home/docs/installation/index.html

Grade2 uses the Mogul and the CSD Python API tools from the CCDC. Because of this Grade2 requires an installation of the CSD-Core package to work. For details on how to obtain CSD-Core please see https://www.ccdc.cam.ac.uk/solutions/csd-core/

If no local installation of CSD-Core is available, we would recommend using the Grade Webserver at http://grade.globalphasing.org (for non-confidential ligands). The Grade Webserver will soon be upgraded to use Grade2.

Configuration

To work Grade2 needs to be able to locate the CSD and CSD Python API installations. The locations are found by setting environment variable(s). If you have followed the BUSTER Snapshot Installation Guide

$BDG_home/docs/installation/index.html

BUSTER configuration instructions and can run Grade it is likely that Grade2 will already work.

To check whether Grade2 can find the CSD installations use the grade2 command-line option -checkdeps:

grade2 -checkdeps

If this results in a final line starting with SUCCESS then Grade2 has been successfully setup, for example:

$ grade2 -checkdeps
 set CSDHOME=/Applications/CCDC/CSD_2021 from $BDG_TOOL_MOGUL=/Applications/CCDC/CSD_2021/mogul.app/Contents/MacOS/mogul
 ############################################################################
 ##   [grade2] ligand restraint dictionary generation
 ############################################################################

 ... (output abbreviated) ...

 -checkdeps option: verbose dependencies check for required external tools
                   with tests all tools work properly.
 CSD installation found
 Test using carbon dioxide from SMILES O=C=O bond angle:
 RDKit generated molecule and coordinates from input SMILES: O=C=O
 CHECK: Check the molecule's InChiKey against known PDB components:
 CHECK: Exact match to PDB chemical component(s):
 CHECK:   CO2 https://www.rcsb.org/ligand/CO2 "carbon dioxide"
 Minimization with MMFF94s reduces energy from 30.80 to 0.00 kcal/mol
 Using CCDC Mogul-like geometry analysis.
 Mogul version 2020.3.0, CSD version 542, csd-python-api 3.0.4
 Geometry Optimization is turned off.
 Result: O=C=O ideal bond angle 179.1 degs from Mogul_mean_28_hits
 SUCCESS: grade2 -checkdeps indicates that everything needed to run grade2 works fine

If instead grade2 -checkdeps has lines starting with ERROR then you will need to set the shell variable CSDHOME to the location the CSD_2021 directory on your system. If are a sh, bash or dash user this can be achieved by a command like:

export CSDHOME=/Applications/CCDC/CSD_2021

whereas if you are a tcsh or csh you should use a command like:

setenv CSDHOME /Applications/CCDC/CSD_2021

You will need to modify the command used to the correct location on your system. For more information on setting CSDHOME please see the CSD Release and Installation Notes

As well as setting the environment variable CSDHOME, if there has been creative use of symbolic links, it might be necessary to set the environment variable BDG_TOOL_CSD_PYTHON_API to the location of the Python_API_2021 directory included in the CSD distribution.

Once you have found the environment variables necessary to get grade2 -checkdeps reporting SUCCESS these should be added to the BUSTER setup_local.sh or setup_local.csh file as explained in the BUSTER Snapshot Installation Guide

$BDG_home/docs/installation/index.html

Testing Grade2

To test whether Grade2 has been configured correctly then use the grade2 command-line option -checkdeps:

grade2 -checkdeps

If this does not result in a final line that starts with SUCCESS then please follow instructions in the Configuration section above.

To test that all the components used by Grade2 work as expected on your system then run the command grade2_tests. For example:

$ grade2_tests
 using CSD from $CSDHOME=/Applications/CCDC/CSD_2021
============================ test session starts =============================
platform darwin -- Python 3.7.4, pytest-6.2.2, py-1.10.0, pluggy-0.13.1
rootdir: /Users/osmart/GPhL/BUSTER_snapshot_20210420/.mc/darwin/lib/python3.7/site-packages/grade2/tests
plugins: forked-1.2.0, cov-2.11.1, xdist-2.2.0, mock-3.5.1
collected 350 items

test_big_planes.py .......                                             [  2%]
test_charge_neutral_groups.py .................                        [  6%]
test_csd_mol2_file_parser.py .............................             [ 15%]
test_dictionary_comparison.py ....                                     [ 16%]
test_dictionary_creation.py .......................................... [ 28%]
............................                                           [ 36%]
test_dictionary_reader.py .......................                      [ 42%]
test_geometry_optimization.py ....                                     [ 44%]
test_grade2_cli.py ................................................... [ 58%]
............................................                           [ 71%]
test_grade2_utils_cli.py ..........                                    [ 74%]
test_ideal_pdb_contents.py .....                                       [ 75%]
test_metal_handling.py ..                                              [ 76%]
test_mogul_dictionary_creation.py ....s.............                   [ 81%]
test_pdb_ccd_cif_reader.py ..                                          [ 81%]
test_producing_shelx_restraints.py ...........                         [ 84%]
test_recognise_pdb_ccd.py .............                                [ 88%]
test_restraint_cif.py .............                                    [ 92%]
test_svg_diagram.py .ss                                                [ 93%]
test_type_energys_for_rdkit.py ...................                     [ 98%]
test_utilities.py .....                                                [100%]

================= 347 passed, 3 skipped in 209.53s (0:03:29) =================

grade2_tests will run over 300 unit, functional and integration tests written as part of the test-driven development used for coding Grade2. Any failure is serious, please report it to buster-develop@globalphasing.com.

Please also see the Examples section for how to run/test the grade2 command-line tool.