************************************* 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 available at https://www.globalphasing.com/buster/manual/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/ .. _Mogul: https://www.ccdc.cam.ac.uk/solutions/csd-core/components/mogul/ .. _CCDC: https://www.ccdc.cam.ac.uk/ .. _CSD Python API: https://www.ccdc.cam.ac.uk/solutions/csd-core/components/csd-python-api/ 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: Initial 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 available at https://www.globalphasing.com/buster/manual/installation/index.html 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 ############################################################################ ## [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" For help on checks against known PDB components, , see: .... ---- https://gphl.gitlab.io/grade2_docs/faqs.html#checkpdbmatch Minimization with MMFF94s reduces energy from 30.80 to 0.00 kcal/mol Using CCDC Mogul-like geometry analysis. Mogul version 2022.2.0, CSD version 543, csd-python-api 3.0.13 Mogul Data Libraries: as543be_ASER, Mar22_ASER, Jun22_ASER Geometry Optimization is turned off. Result: O=C=O ideal bond angle 179.1 degs from Mogul_mean_30_hits SUCCESS: grade2 -checkdeps indicates that everything needed to run grade2 works fine If instead ``grade2 -checkdeps`` has lines starting with ``ERROR`` then you should set the shell variable ``BDG_TOOL_MOGUL`` to the location the mogul executable on your system. If are a ``sh``, ``bash`` or ``dash`` user this can be achieved by a command like: :: export BDG_TOOL_MOGUL=/Applications/CCDC/CSD_2022/mogul.app/Contents/MacOS/mogul whereas if you are a ``tcsh`` or ``csh`` you should use a command like: :: setenv BDG_TOOL_MOGUL /Applications/CCDC/CSD_2022/mogul.app/Contents/MacOS/mogul You will need to modify the command used to the correct location on your system. Please note that there was a major change in the CSD file locations and configuration in the release CSD 2023.1 made in April 2023. This can lead to problems where Grade2 terminates with a "CSDNotFoundException" error, if this occurs please see: `FAQ Grade2 terminates with a "CSDNotFoundException", what should I do? `_. As well as setting the environment variable ``BDG_TOOL_MOGUL``, 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_2022`` directory or ``csd-python-api`` directory included in your CSD distribution. Once you have found the environment variables necessary to get ``grade2 -checkdeps`` reporting ``SUCCESS`` it is best if these are added to the BUSTER ``setup_local.sh`` or ``setup_local.csh`` file, as explained in the BUSTER Snapshot Installation Guide `BUSTER configure`_ section. This means that the Grade2 configuration will done together with BUSTER by the setup script ``setup.sh`` or ``setup.csh``. .. _BUSTER configure: https://www.globalphasing.com/buster/manual/installation/UbuntuXXXX_64bit/index.html#configure .. _testing: 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_2022 ============================ 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_20220420/.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 :doc:`Examples ` section for how to run/test the ``grade2`` command-line tool. .. _environment-variables: .. _advanced-configuration: Advanced Configuration ====================== If is possible to configure site-specific features for Grade2 by using the environment variables as set out below. Do not worry about these if are a new user of Grade2. Grade2 environment variables ---------------------------- In general, environment variables are used to configure an installation of Grade2 by specifying site-specific choices that have can be set once and will not vary from run to run. In contrast, :ref:`command-line arguments ` are used to specify things that will vary for individual ``grade2`` runs. It is best Grade2 environment variables are are added to the BUSTER ``setup_local.sh`` or ``setup_local.csh`` file, as explained in the BUSTER Snapshot Installation Guide `BUSTER configure`_ section, so that there are setup together with BUSTER. Users can of course set or alter any of the environment variables if they wish by using ``export`` or ``setenv`` (depending on the shell they use). BDG_TOOL_MOGUL ^^^^^^^^^^^^^^ ``BDG_TOOL_MOGUL`` is the environment variable that gives the location of the Mogul executable. Grade2 does not use this executable but instead uses it to find the location of CSD data and the CSD Python API direction. Please see the :ref:`Initial Configuration ` section above for more detail. BDG_GRADE2_PYTHON_VERSION ^^^^^^^^^^^^^^^^^^^^^^^^^ Grade2 is distributed with BUSTER within in a miniconda environment. In order to work with the CSD Python API that is loaded at run time from the CSD Python API distributed with the CSD the two Python versions must be compatible. To use Grade2 following release :ref:`1.4.1 ` or above with a CSD installation that predates ``2023.2.0``, released in July 2023 set the environment variable ``BDG_GRADE2_PYTHON_VERSION`` to ``3.7``. If not set, then ``BDG_GRADE2_PYTHON_VERSION`` currently defaults to ``3.9``. BDG_TOOL_CSD_PYTHON_API ^^^^^^^^^^^^^^^^^^^^^^^ ``BDG_TOOL_CSD_PYTHON_API`` is provided in case it is necessary to provide the of the CSD Python API directory included in the CSD distribution. If you have a standard CSD installation then the location of CSD Python API will be found from ``BDG_TOOL_MOGUL``, so it is seldom necessary to set ``BDG_TOOL_CSD_PYTHON_API``. Please see the :ref:`Initial Configuration ` section above for more detail. BDG_GRADE2_PUBCHEM_NAMES_ON_ACCEPT_SMILES_TO_WEB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The grade2 command line option :ref:`--pubchem_names ` does an online lookup the systematic (IUPAC) name for ligands that occur in PubChem. This online search involves uploading the SMILES string of the molecule to the PubChem server. For this reason, **the** ``--pubchem_names`` **option should not be used for confidential ligands.** To be extra careful, by default the ``--pubchem_names`` option is deactivated until the environment variable is set. To enable the ``--pubchem_names`` option set ``BDG_GRADE2_PUBCHEM_NAMES_ON_ACCEPT_SMILES_TO_WEB`` to ``"yes"``. Apologies for the long name but it is chosen to explicitly show you have accepted that the ligand's SMILES string is uploaded to a public web server. BDG_GRADE2_LIGAND_LOOKUP ^^^^^^^^^^^^^^^^^^^^^^^^ The :ref:`--lookup option ` provides a mechanism whereby an external script is invoked to look up details of a ligand from a database. To use your own script, set environment variable ``BDG_GRADE2_LIGAND_LOOKUP`` to the location of the script. Please see the :ref:`--lookup option ` for more details. BDG_GRADE2_SSL_DISABLE_VERIFICATION ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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``. A similar error when the :ref:`--pubchem_names ` option is used. If the problem occurs set environment variable ``BDG_GRADE2_SSL_DISABLE_VERIFICATION`` to ``"yes"``. This will disable SSL verification for PubChem lookups and should mean the options work. As you should not using the options for any confidential ligands turning off verification should be fine. BDG_GRADE2_CIF_LOOP_ALL ^^^^^^^^^^^^^^^^^^^^^^^ Set ``BDG_GRADE2_CIF_LOOP_ALL`` to ``"yes"`` to write all CIF categories as loops, even if they only contain a single item. Currently this only affects category ``gphl_chem_comp_info`` which by default is written using key-value pairs as this makes inspection easier. All other CIF categories are written as loops anyway. BDG_GRADE2_TEST_WEB ^^^^^^^^^^^^^^^^^^^ By default, the ``grade2_tests`` tool does not run tests that use external online services, as these can be unavailable because of maintenance or network issues. Set ``BDG_GRADE2_CIF_LOOP_ALL`` to ``"yes"`` to turn on the tests involving external online services. This will enable testing of the :ref:`--pubchem_names ` and the :ref:`--lookup ID ` options.