Joint Research Group Macromolecular Crystallography

Installation instructions

Installation of XDSAPP3

After downloading the file xdsapp3v1-yyyy-mm-dd.tar.gz in the directory of your choice, run the command
tar -zxf xdsapp3v1-yyyy-mm-dd.tar.gz
or
tar -xf xdsapp3v1-yyyy-mm-dd.tar

depending of the archive you received.

A new directory will be created, containing 19 files:

beamlines.py
eiger2cbf.py
generate_XDS.INP
logo_hzb.gif
messages.py
mp_xdsconv_job.py
myutils.py
plotting3.py
README
ReleaseNotes.txt
signals.py
XDS_from_H5.py
xdsapp3_gui.py
xdsapp3_help.html
xdsapp3_help.txt
xdsapp3.1.py
xdsenv.py
xdsit.py

Create an alias "xdsapp3" or "xdsapp" pointing to the file xdsapp3.1.py for easy use of the program.

Installation of the GUI components

Read carefully the README file for installation instructions.

The instructions are provided for x86_64 architecture and have been tested by us with the specified operating systems. They may not work with different or older systems. Please note that we can not provide solutions for all operating systems.
Before starting the installation, ensure that your OS and package management software are up to date.
You can check the installation of packages by using the search command of your package manager (e.g. yum search pyqt5). The packages for your architecture will be listed.

Isolated environment with Anaconda

If you like not to touch your Linux or MacOS installation, it is possible to run XDSAPP3 in an isolated Python environment with Anaconda. To do so, install the "Individual Edition" from the anaconda.com home page. During the installation, chose not to modify your shell startup script. Instead, create a file named xdsapp3.sh or similar with content:

example tcsh:

#!/bin/tcsh
# setup PATH to python3
set path_stored="$PATH"
setenv PATH /path/to/anaconda3/bin:$PATH
# to avoid OMP crash of XDS (Linux only)
setenv KMP_INIT_AT_FORK FALSE
# start xdsapp3
python /path/to/xdsapp3/xdsapp3.1.py $argv:q
#restore PATH
setenv PATH $path_stored

example bash:

#!/bin/bash
# setup PATH to python3
path_stored="$PATH"
export PATH=/path/to/anaconda3/bin:$PATH
# to avoid OMP crash of XDS (Linux only)
export KMP_INIT_AT_FORK=FALSE
# start xdsapp3
python /path/to/xdsapp3/xdsapp3.1.py $@
#restore PATH
export PATH $path_stored

Linux specific

There seems to be a bug in a multiprocessing library, which causes to crash xds_par (the parallel processing version of xds). A workaround is to set the environment variable KMP_INIT_AT_FORK to FALSE, e.g:
bash: export KMP_INIT_AT_FORK=FALSE
tcsh: setenv KMP_INIT_AT_FORK FALSE

macOS

macOS 10.13 (High Sierra)

Install Xcode including the Command Line Tools
install Qt5, PyQt5, and Python3, and Matplotlib:
with Anaconda3 (everything is included)
or
homebrew:
(this requires the previous installation of Xcode)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Then the rest of the packages can be easily installed:
brew install qt (will install Qt5)
brew install pyqt
Copy the line
export PYTHONPATH=/usr/local/lib/python3.7/site-packages:$PYTHONPATH
into your ~/.bashrc or ~/.bash_profile file (for the bash shell) for
future uses of XDSAPP3.

install hdf5 with e.g.
brew install hdf5

MacOS 10.15 (Catalina) , 11.1 (Big Sur)

See MacOS 10.13. In addition:

On macOS Catalina many of the programs used by XDSAPP3 will not run
immediately because they were not written by an "identified developer".
Try this:
* delete a possible quarantine attribute: >xattr -d com.apple.quarantine program
* start a program from the command line, there will be a message
* open System Preferences
* go to Security & Privacy and select the General tab
* click the button "Open Anyway"
* run the program again and acknowledge the pop-up message

(For the adventurous:
in terminal, activate a hidden option in Security & Privacy:
sudo spctl --master-disable
This will show a "Anywhere" button in the General tab. To revert it
sudo spctl --master-enable
Be aware of the risk to install malware, if you leave this option active.

On macOS Catalina make sure you have PyQt 5.12.3 installed, PyQt 5.9.2 will crash when opening a file selection dialog.

On macOS Catalina sometimes the XDSAPP3 GUI will not respond, click in the desktop and then back to the GUI.

MacOS Big Sur on Apple Silicon M1 Macs

There are M1 native versions of XDS, the neggia plugin and the durin-plugin available on the XDS wiki page.

Setting up the environment

The environment for XDSAPP3 is defined in the file xdsenv.py. There are 3 sections:

- Section 1: path settings
- Section 2: performance parameter (optional)
- Section 3: miscellaneous (optional)

Section 1 Here the path to various programs are defined if these are not found via the PATH environment variable. For the image viewer, select only one: xds-viewer or albula, not both.

Please take special care if you will evaluate data from Dectris Eiger detectors. It is strongly recommended to define only the path to the dectris-neggia or durin plugin (only one!) in the file xdsenv.py. This setting will use the script generate_XDS.INP to generate the necessary file XDS.INP. If you define the path to the albula-api in addition to one of the plugins, XDS.INP will be generated with XDS_from_H5.py. This is not recommended, as the script XDS_from_H5.py is not well tested. A third method to read Eiger data files is to use eiger2cbf. This should only be necessary, if you cannot use one of the plugins, and may have the drawback, that not all header informations are supplied to XDS.INP. This is the least recommended possibility.

Section 2 With the performance parameters you may define the number of CPUs to use, the number of jobs XDS is running and the nice level. You can define these parameters on a per computer basis, if necessary.

Section 3 Miscellaneous , see comments in xdsenv.py