Cppxfel Installation

This details the installation instructions for cppxfel on Linux and Mac OS X. cppxfel relies on three components:

• Boost libraries (thread and system) - these allow C++ to access threading over multiple cores.
• DIALS distribution - provides the cctbx libraries for L-BFGS refinement and some crystallographic functions, and the indexing algorithms from DIALS itself.
• cppxfel distribution - primarily written in C++, but some Python scripts to automate DIALS indexing and prepare the results for input into cppxfel.

These installation instructions are not finished and will not currently result in a working version of cppxfel.

DIALS distribution

Download the DIALS distribution for your flavour of OS from [the DIALS website]. Ensure the distribution downloaded was compiled on 29th November or later (see [list of latest builds]). Extract the dials-installer-dev to a new location. Navigate into this directory.

cd dials-installer-dev

Start the install command to a new directory to which you have write access.

./install --prefix=/absolute/path/to/dials

cppxfel distribution

The cppxfel source code must be downloaded into the modules directory.

cd /absolute/path/to/dials/modules

The repository can be cloned from the GitHub link for cppxfel.

git clone https://github.com/cppxfel/cppxfel.git

The build directory must be removed and recreated.

cd ..
rm -r build
mkdir build
cd build

The DIALS distribution must be configured to compile the xfel extension, and then the distribution must be compiled.

../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 xfel
make

The same must be done for the cppxfel code.

../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 cppxfel
make

Set the paths to the DIALS and cppxfel command line tools (bash):

. /absolute/path/to/dials/build/setpaths.sh

Bash shell	Csh shell
. /absolute/path/to/dials/build/setpaths.sh	source /absolute/path/to/dials/build/setpaths.csh

This needs to be repeated every time a new shell is started. Alternatively, place this in your appropriate file (bash)

Bash shell	Csh shell
test -r /absolute/path/to/dials/build/setpaths.sh && \ . /absolute/path/to/dials/build/setpaths.sh	test -r /absolute/path/to/dials/build/setpaths.csh && \ source /absolute/path/to/dials/build/setpaths.csh
to ~/.bashrc	to ~/.cshrc

CCP4 Symmetry libraries

The cppxfel distribution requires the CCP4 symmetry libraries. This needs to be pointed to by the SYMINFO environment variable. To set this:

Bash shell	Csh shell
export SYMINFO="/absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib"	setenv SYMINFO /absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib

This will prevent run-time errors from the CCP4 library functions not being able to find its symmetry information library. Consider adding these links to your ~/.bashrc or ~/.cshrc files to be executed on the generation of every new shell.

Check the installation

Confirm that cppxfel runs:

cppxfel.run

The output should look something like this:

Welcome to cppxfel version 1.0!
Please refer to & cite paper in Journal of Applied Crystallography (unpublished)

Command order for regular structure solution:
	cppxfel.run_dials shot*.pickle
	cppxfel.input_gen
	cppxfel.run -i integrate.txt
	cppxfel.run -i refine.txt
	cppxfel.run -i merge.txt

Other functions for assessing data quality:

Correlation between two MTZ files:

	cppxfel.run -cc firstFile.mtz secondFile.mtz [ambiguity] [lowRes] [highRes] [bins]

ambiguity: 0, 1, 2 or 3 - will compare different indexing solutions where the Bravais lattice symmetry is higher than that of the point group for certain space groups. Default 0
lowRes and highRes: set to resolution in Angstroms to bound the results, or set to 0 to take lowest/highest resolution data. Default 0, 0
bins: number of bins to report correlation statistics. Default 20.

Partiality CSV files:

	cppxfel.run -partiality reference.mtz ref-img-shot-number.mtz [highRes]

highRes: 0, 1, 2 or 3 - highest resolution reflection to report results on. Default 1.4
This outputs partiality_[m].csv where m is bin number, which can be imported into other graphing softwares such as R.

Merging statistics:

	cppxfel.run -rpim unmerged_file.mtz [lowRes] [highRes] [bins]
	cppxfel.run -rmeas unmerged_file.mtz [lowRes] [highRes] [bins]
	cppxfel.run -rmerge unmerged_file.mtz [lowRes] [highRes] [bins]

lowRes and highRes: set to resolution in Angstroms to bound the results, or set to 0 to take lowest/highest resolution data. Default 0, 0
bins: number of bins to report correlation statistics. Default 20.

If you see this, cppxfel has been installed.

Next steps

Try running the tutorial on a set of 1000 images from CPV, starting with indexing.