.. highlight:: none

*****************
CSD compatibility
*****************

**Please check the online version of this page:**
https://gphl.gitlab.io/grade2_docs/csd_compatibility.html
**before updating your CSD installation.**
The online page is updated when new CSD releases are made.

Grade2 obtains data from the Cambridge Structural Database
(`CSD <https://www.ccdc.cam.ac.uk/solutions/csd-core/components/csd/>`_)
using the
`CSD Python API <https://downloads.ccdc.cam.ac.uk/documentation/API/>`_
and you must have an CSD installation to use Grade2. Because the
CSD and BUSTER installations are separate, incompatibilities can arise.
This page shows which recent releases of the two packages work together.
Releases made in the past year are listed.

Please note that the CSD update procedure is, to our knowledge
irreversible and you can only download the latest version.
So if you update the code to an incompatible version and there
is a problem you may well be stuck.

Linux
=====

.. flat-table:: Linux Grade2/CSD Compatibility
   :widths: 1 1 1
   :header-rows: 1

   * - Grade2 version (build date)
     - CSD Version (release date)
     - Work together?
   * - :rspan:`4` 1.5.0 (12 January 2024)
     - CSD 2024.1 (March 2024)
     - **Yes**
   * - CSD 2023.3 (November 2023)
     - Yes
   * - CSD 2023.2 (July 2023)
     - Yes
   * - CSD 2023.1 (April 2023)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - CSD 2022.3 (November 2022)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - :rspan:`4` 1.4.1 (18 July 2023)
     - CSD 2024.1 (March 2024)
     - **Yes**
   * - CSD 2023.3 (November 2023)
     - Yes
   * - CSD 2023.2 (July 2023)
     - Yes
   * - CSD 2023.1 (April 2023)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - CSD 2022.3 (November 2022)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - :rspan:`2` 1.4.0 (22 May 2023)
     - CSD 2023.2 (July 2023) *and following*
     - **No**
   * - CSD 2023.1 (April 2023)
     - Yes
   * - CSD 2022.3 (November 2022)
     - Yes
   * - :rspan:`1` 1.3.2 (06 March 2023)
     - CSD 2023.1 (April 2023) *and following*
     - **No**
   * - CSD 2022.3 (November 2022)
     - Yes


MacOS
=====

.. flat-table:: MacOS Grade2/CSD Compatibility
   :widths: 1 1 1
   :header-rows: 1

   * - Grade2 version (build date)
     - CSD Version (release date)
     - Work together?
   * - :rspan:`4` 1.5.0 (12 January 2024)
     - CSD 2024.1 (March 2024)
     - **Yes**
   * - CSD 2023.3 (November 2023)
     - Yes
   * - CSD 2023.2 (July 2023)
     - Yes
   * - CSD 2023.1 (April 2023)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - CSD 2022.3 (November 2022)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - :rspan:`4` 1.4.1 (18 July 2023)
     - CSD 2024.1 (March 2024)
     - **Yes**
   * - CSD 2023.3 (November 2023)
     - Yes
   * - CSD 2023.2 (July 2023)
     - Yes
   * - CSD 2023.1 (April 2023)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - CSD 2022.3 (November 2022)
     - Yes with :ref:`BDG_GRADE2_PYTHON_VERSION="3.7" <using_old_csd_releases>`
   * - :rspan:`2` 1.4.0 (22 May 2023)
     - CSD 2023.2 (July 2023) *and following*
     - **No**
   * - CSD 2023.1 (April 2023)
     - Yes
   * - CSD 2022.3 (November 2022)
     - Yes
   * - :rspan:`1` 1.3.2 (06 March 2023)
     - CSD 2023.1 (April 2023) *and following*
     - **No**
   * - CSD 2022.3 (November 2022)
     - Yes

.. _using_old_csd_releases:

Using Grade2 release 1.4.1 (and following) with old CSD releases
================================================================

CSD release ``2023.2`` (July 2023) contained an update to the miniconda
environment included with CSD from Python 3.7 to Python 3.9.
Grade2 is distributed with BUSTER within in a separate miniconda environment.
In order to work together the two
Python versions of these two miniconda environments must be the same.
Grade2 in all versions up to
:ref:`1.4.0 <changelog-1.4.0>` used a Python 3.7 miniconda
environment and so will not work with the new CSD release ``2023.2`` (July 2023).

From Grade2 release :ref:`1.4.1 <changelog-1.4.1>`
includes both a Python 3.9 miniconda environment to work with
the new CSD release  ``2023.2`` (July 2023) and a
Python 3.7 miniconda environment to work with older CSD releases.
We will continue to include a Python 3.7 miniconda environment
until July 2024 to support older CSD releases.

The easiest way to ensure compatibility is to update both BUSTER
(and hence Grade2) and CSD.

If you wish to use an older installation of CSD with Grade2 following
release :ref:`1.4.1 <changelog-1.4.1>` or following
set the environment variable ``BDG_GRADE2_PYTHON_VERSION`` to ``3.7``.
Users of bash/ksh/zsh shells can do this by:

.. code-block:: text

   export BDG_GRADE2_PYTHON_VERSION="3.7"

Users of csh can set the environment variable by

.. code-block:: text

   setenv BDG_GRADE2_PYTHON_VERSION "3.7"

It is best practice that Grade2 environment variables are are added to
the BUSTER ``setup_local.sh`` or ``setup_local.csh`` file
as explained in
:ref:`Grade2 environment variables <environment-variables>` section.

Once you update CSD you will need to make sure that
``BDG_GRADE2_PYTHON_VERSION`` is not set for Grade2 to work.

*(Page updated 28 March 2024)*