Interactive molecular dynamics based model building into low-resolution crystallographic and cryo-EM maps
ISOLDE is a plugin to UCSF ChimeraX, designed to ease the task of macromolecular model building into low-to-medium resolution maps derived from crystallographic or electron cryo-microscopy (cryoEM) experiments. Historically, this has been an extremely challenging task, since at low resolutions the maps alone are insufficient to precisely place individual atoms. ISOLDE aims to reduce this challenge in a number of ways:
Like this:
For other examples and demonstration videos, see the ISOLDE webpage.
In most cases, you should not need to build ISOLDE from source for yourself. Regular (approximately fortnightly) development builds are released for Linux, Mac and Windows on the ChimeraX Tool Shed, and can be installed directly from within ChimeraX itself. In general, just download and install the latest daily build of ChimeraX from here, then go to Tools/More Tools... and follow the links to ISOLDE.
NOTE: Some large files in this repository are stored using Git-LFS. To clone these to your own system you'll need to have the Git-LFS client installed.
ISOLDE uses ChimeraX's bundle building pipeline, with the majority of the build information defined in bundle_info.xml. Dependencies outside of those already present in ChimeraX itself are kept to a minimum. You will need to have a compatible version of ISOLDE's sister package ChimeraX-Clipper installed (whether built from source or installed via the Tool Shed). Additionally, you will need to provide the OpenMM header files (these are not currently distributed with ChimeraX). The paths to these are hard-coded in bundle_info.xml, so you'll need to change the following lines to the correct path(s):
<IncludeDir platform="mac">/Users/tic20/anaconda3/envs/openmm74/include</IncludeDir>
<IncludeDir platform="linux">/home/tic20/anaconda3/envs/openmm74/include</IncludeDir>
<IncludeDir platform="windows">C:\Users\tic20\Anaconda3\envs\openmm74\include</IncludeDir>
IMPORTANT NOTE FOR LINUX USERS: the version of GCC you use for building needs to be binary-compatible with the version used to build both ChimeraX and OpenMM. The version of OpenMM distributed with ChimeraX is the official release, compiled with GCC 4.8. The RedHat and Generic Linux builds of ChimeraX are both built with GCC 4.9, so your easiest path is to also build ISOLDE using GCC 4.9 (if you're using a RedHat flavour, the most convenient way is to use devtoolset-3). The Ubuntu builds of ChimeraX are built with the GCC versions shipped with the OS - these are not backward-compatible. If you really wish to build with these, you will first need to build and install your own version of OpenMM into the ChimeraX environment following the instructions here.
For MacOS you will need to have XCode installed, while for Windows you will need Visual Studio 2015 or better.
Once the above conditions are met, you can go ahead and build in a Linux or MacOS environment as follows:
/path/to/ChimeraX/bin/ChimeraX -m PyQt5.pyrcc_main -o src/resources/resources_rc.py src/resources/resources.qrc
/path/to/ChimeraX/bin/ChimeraX --nogui --cmd "devel build . ; exit"
/path/to/ChimeraX/bin/ChimeraX --nogui --cmd "devel install . ; exit"
To clean the compilation and start from scratch, use:
/path/to/ChimeraX/bin/ChimeraX --nogui --cmd "devel clean . ; exit"
For convenience, these are also wrapped in a simple Makefile, allowing the above to be achieved with the equivalent commands:
make
, make install
and make clean
respectively.
In Windows, a special executable is needed for the command-line switches to be correctly handled. The following command will clean, build and install ISOLDE:
C:\Program Files\ChimeraX\bin\ChimeraX-console.exe" -m PyQt5.pyrcc_main -o src/resources/resources_rc.py src/resources/resources.qrc
C:\Program Files\ChimeraX\bin\ChimeraX-console.exe" --nogui --cmd "devel clean .; devel install .; exit"
For convenience, these commands are also wrapped in a batch file, make_win.bat.
make_win release clean app-install
... will achieve the same result as the above.
ISOLDE's documentation tree is defined using Sphinx. While Sphinx itself is bundled with ChimeraX, you will also need an installation of LaTeX on your system path.
Since Sphinx's source code documentation relies on introspection from within Python itself, you will need to have already built and installed ISOLDE into ChimeraX before the documentation can be built. Once you've done that, change to the directory containing bundle_info.xml, then do the following:
Linux/MacOS:
/path/to/ChimeraX/bin/ChimeraX -m sphinx docs/source src/docs/user
or
make docs
Windows:
C:\Program Files\ChimeraX\bin\ChimeraX-console.exe" -m sphinx docs/source src/docs/user
or
make_docs.bat release
... then reinstall ISOLDE.
Remember, you can always find the most recent version of the documentation here.