Cppxfel Installation: Difference between revisions

From cctbx_xfel
Jump to navigation Jump to search
No edit summary
mNo edit summary
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This details the installation instructions for [[Cppxfel|''cppxfel'']] on Linux and Mac OS X. '''These installation instructions are not finished and will not currently result in a working version of ''cppxfel''.'''
This details the installation instructions for [[Cppxfel|''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 have been tested on CentOS 7.


== Installing the boost libraries ==
== DIALS distribution ==


The boost library is a dependency of ''cppxfel'' allowing it to run on multiple threads from within C++. Either download source and compile from boost website, or if you have user privileges, you can use a package manager.
Download the DIALS distribution for your flavour of OS (see [[http://cci.lbl.gov/dials/installers/ list of latest builds]]) from [[http://dials.github.io/installation.html the DIALS website]]. Ensure the distribution downloaded was compiled on 29th November 2015 or later for Boost thread support. Extract the dials-installer-dev to a new location. Navigate into this directory, e.g.:


=== With user privileges ===
<pre>cd dials-installer-dev</pre>


On CentOS:
Start the install command to a new directory to which you have write access.
 
<pre>./install --prefix=/absolute/path/to/dials</pre>


<pre>yum install boost boost-devel</pre>
== ''cppxfel'' distribution ==


On Ubuntu:
The ''cppxfel'' source code must be downloaded into the <code>modules</code> directory. Navigate to this directory, e.g.


<pre>apt-get install libboost-all-dev</pre>
<pre>cd /absolute/path/to/dials/dials-dev-508/modules</pre>


On Mac OS X, install brew, and then:
The repository can be cloned from the GitHub link for cppxfel.


<pre>brew install boost</pre>
<pre>git clone https://github.com/cppxfel/cppxfel.git</pre>


{| class="wikitable"
The build directory must be removed and recreated.
|-
! CentOS
! Ubuntu
! Mac OS X
|-
| <code>yum install boost boost-devel</code>
| <code>apt-get install libboost-all-dev</code>
| Install brew, then: <code>brew install boost</code>
|}


We need to make sure the boost library is visible to the DIALS/cppxfel installation. To see where the boost library was installed:
<pre>
cd ..
rm -r build
mkdir build
cd build
</pre>


<pre>locate libboost_thread-mt.so</pre>
The DIALS distribution must be configured to compile the xfel extension, and then the distribution must be compiled.


This will show a directory e.g.
<pre>
../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 xfel
make
</pre>


<pre>/usr/lib64/libboost_thread-mt.so</pre>
The same must be done for the cppxfel code.
<pre>
../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 cppxfel
make
</pre>


This should be set to the environment variable <code>BOOST_LOCATION</code>.
Set the paths to the DIALS and cppxfel command line tools (bash):


{| class="wikitable"
{| class="wikitable"
Line 45: Line 54:
! Csh shell
! Csh shell
|-
|-
| <code>export BOOST_LOCATION="/usr/lib64/"</code>
| <code>. /absolute/path/to/dials/dials-dev-508/build/setpaths.sh</code>
| <code>setenv BOOST_LOCATION /usr/lib64</code>
| <code>source /absolute/path/to/dials/dials-dev-508/build/setpaths.csh</code>
|}
|}


<pre></pre>
This needs to be repeated every time a new shell is started. Alternatively, place this in your appropriate file (bash)
 
=== Without user privileges ===
 
Download the Boost source code from the Boost website. For example, [[http://www.boost.org/users/history/version_1_59_0.html Version 1.59.0]]. Follow the instructions in Section 5 in Boost's [[http://www.boost.org/doc/libs/1_59_0/more/getting_started/unix-variants.html Getting Started - Unix Variants]] page to compile the boost libraries required by ''cppxfel''. Install these files to a suitable location by specifying an appropriate prefix that you have write privileges to.
 
Because you do not have user privileges and cannot install the libraries to a standard place, you will have to set the environment variable LD_LIBRARY_PATH to the path of the library, and you will also have to set the environment variable BOOST_LOCATION in order that ''cppxfel'' can find your boost libraries. You may want to append these to your .bashrc or .cshrc files.


{| class="wikitable"
{| class="wikitable"
Line 62: Line 65:
! Csh shell
! Csh shell
|-
|-
| <code>export BOOST_LOCATION="/path/to/boost/lib/"</code>
| <code>test -r /absolute/path/to/dials/dials-dev-508/build/setpaths.sh && \
| <code>setenv BOOST_LOCATION /path/to/boost/lib/</code>
. /absolute/path/to/dials/dials-dev-508/build/setpaths.sh</code>
| <code>test -r /absolute/path/to/dials/dials-dev-508/build/setpaths.csh && \
source /absolute/path/to/dials/dials-dev-508/build/setpaths.csh</code>
|
|-
|-
|<code>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH":/path/to/boost/lib/"</code>
| to <code>~/.bashrc</code>
|<code>setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/path/to/boost/lib/</code>
| to <code>~/.cshrc</code>
|-
| Enter last line into ~/.bashrc
| Enter last line into ~/.cshrc
|}
|}


== DIALS distribution ==
== Alternate ''cppxfel''-''DIALS'' distribution for non-graphical High Performance Computing ==


Download the DIALS distribution for your flavour of OS from [[http://dials.github.io/installation.html the DIALS website]]. Extract the dials-installer-dev to a new location. Navigate into this directory.
<span style="color:red">  Skip this section for typical use cases.  On request from an HPC center, we give special instructions for building the Python library without importing graphics library code (instructions were tested on Centos 6.5). For a non-graphical installation do NOT start above with the DIALS distribution, instead start HERE:


<pre>cd dials-installer-dev</pre>
<pre>


Start the install command to a new directory to which you have write access.
wget --no-check-certificate https://raw.githubusercontent.com/cctbx/cctbx_project/master/libtbx/auto_build/bootstrap.py
 
python bootstrap.py hot update --builder=dials
<pre>./install --prefix=/absolute/path/to/dials</pre>
python modules/cctbx_project/libtbx/auto_build/install_base_packages.py
 
cd modules
== ''cppxfel'' distribution ==
git clone https://github.com/cppxfel/cppxfel.git
 
cd ..
The ''cppxfel'' source code must be downloaded into the <code>modules</code> directory.
mkdir build
 
cd build
<pre>cd /absolute/path/to/dials/modules</pre>
../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 xfel
 
make
The repository can be cloned from the GitHub link for cppxfel.
../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 cppxfel
 
make
<pre>git clone https://github.com/cppxfel/cppxfel.git</pre>
</pre>
 
The DIALS distribution must be configured to compile the cppxfel code, and then the distribution must be compiled.
 
<pre>libtbx.configure cppxfel
cd ../build
make</pre>


Set the paths to the DIALS and cppxfel command line tools (bash):
<span style="color:red">Set the paths to the DIALS and cppxfel command line tools:
 
. /absolute/path/to/dials/build/setpaths.sh


{| class="wikitable"
{| class="wikitable"
Line 107: Line 102:
! Csh shell
! Csh shell
|-
|-
| <code>. /absolute/path/to/dials/build/setpaths.sh</code>
| <code>. /absolute/path/to/build/setpaths.sh</code>
| <code>source /absolute/path/to/dials/build/setpaths.csh</code>
| <code>source /absolute/path/to/build/setpaths.csh</code>
|}
|}


This needs to be repeated every time a new shell is started. Alternatively, place this in your appropriate file (bash)
<span style="color:red">This needs to be repeated every time a new shell is started. Alternatively, place this in your appropriate file:


{| class="wikitable"
{| class="wikitable"
Line 118: Line 113:
! Csh shell
! Csh shell
|-
|-
| <code>test -r /absolute/path/to/dials/build/setpaths.sh && \
| <code>test -r /absolute/path/to/build/setpaths.sh && \
. /absolute/path/to/dials/build/setpaths.sh</code>
. /absolute/path/to/build/setpaths.sh</code>
| <code>test -r /absolute/path/to/dials/build/setpaths.csh && \
| <code>test -r /absolute/path/to/build/setpaths.csh && \
source /absolute/path/to/dials/build/setpaths.csh</code>
source /absolute/path/to/build/setpaths.csh</code>
|
|
|-
|-
Line 127: Line 122:
| to <code>~/.cshrc</code>
| to <code>~/.cshrc</code>
|}
|}
== 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:
{| class="wikitable"
|-
! Bash shell
! Csh shell
|-
| <code>export SYMINFO="/absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib"</code>
| <code>setenv SYMINFO /absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib</code>
|}
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 <code>~/.bashrc</code> or <code>~/.cshrc</code> files to be executed on the generation of every new shell.
== Check the installation ==


Confirm that ''cppxfel'' runs:
Confirm that ''cppxfel'' runs:
Line 172: Line 184:
</pre>
</pre>


If you see this, ''cppxfel'' has been installed. A pointer to the CCP4 symmetry libraries is required.
If you see this, ''cppxfel'' has been installed.
 
== 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:
 
{| class="wikitable"
|-
! Bash shell
! Csh shell
|-
| <code>export SYMINFO="/absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib"</code>
| <code>setenv SYMINFO /absolute/path/to/cctbx/modules/ccp4io/libccp4/data/syminfo.lib</code>
|}
 
This will prevent run-time errors from the CCP4 library functions not being able to find its symmetry information library.


== Next steps ==
== Next steps ==


Try running the tutorial on a set of 1000 images from CPV, starting with [[Cppxfel Indexing|indexing]].
Try running the tutorial on a set of 1000 images from CPV, starting with [[Cppxfel Indexing|indexing]].

Latest revision as of 17:55, 16 December 2016

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 have been tested on CentOS 7.

DIALS distribution

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

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. Navigate to this directory, e.g. 

cd /absolute/path/to/dials/dials-dev-508/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):

Bash shell Csh shell
. /absolute/path/to/dials/dials-dev-508/build/setpaths.sh source /absolute/path/to/dials/dials-dev-508/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/dials-dev-508/build/setpaths.sh && \

. /absolute/path/to/dials/dials-dev-508/build/setpaths.sh

test -r /absolute/path/to/dials/dials-dev-508/build/setpaths.csh && \

source /absolute/path/to/dials/dials-dev-508/build/setpaths.csh

to ~/.bashrc to ~/.cshrc

Alternate cppxfel-DIALS distribution for non-graphical High Performance Computing

Skip this section for typical use cases. On request from an HPC center, we give special instructions for building the Python library without importing graphics library code (instructions were tested on Centos 6.5). For a non-graphical installation do NOT start above with the DIALS distribution, instead start HERE: 


wget --no-check-certificate https://raw.githubusercontent.com/cctbx/cctbx_project/master/libtbx/auto_build/bootstrap.py
python bootstrap.py hot update --builder=dials
python modules/cctbx_project/libtbx/auto_build/install_base_packages.py
cd modules
git clone https://github.com/cppxfel/cppxfel.git
cd ..
mkdir build
cd build
../base/bin/python ../modules/cctbx_project/libtbx/configure.py --enable_boost_threads=1 xfel
make
../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 shell Csh shell
. /absolute/path/to/build/setpaths.sh source /absolute/path/to/build/setpaths.csh

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

Bash shell Csh shell
test -r /absolute/path/to/build/setpaths.sh && \

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

test -r /absolute/path/to/build/setpaths.csh && \

source /absolute/path/to/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.

Retrieved from "http://viper.lbl.gov:8080/cctbx.xfel/index.php?title=Cppxfel_Installation&oldid=1309"