Setup: Difference between revisions

From cctbx_xfel
Jump to navigation Jump to search
(Link to separate page for PSDM setup.)
(Reorganized for consistency with PSDM setup)
Line 1: Line 1:
''cctbx.xfel'' is installed at SLAC for general use.  Before it can be used, the following setup commands need to be run to configure the environment.
<!-- XXX Should probably rename this page to "Set up ''cctbx.xfel''" or some such -->


== One-time setup ==


These steps need only be performed once before using ''cctbx.xfel''.
== Prerequisities ==


=== LCLS quick start ===
''cctbx.xfel'' must be installed, which in turn requires the PSDM software distribution to be set up.  See [[Set up PSDM software]] for the latter and [[Installation]] for the former.  ''cctbx.xfel'' can be installed anywhere on the filesystem where write access is granted.


See [[Set up PSDM software]].  Linking the ''cctbx.xfel'' analysis modules to the analysis package is described in [[#Linking cctbx.xfel to pyana|Linking cctbx.xfel to pyana]].
The installation root directory affects the absolute paths used in these instructions and differs from site to site.  Some common installation root directories are listed below.
{| class="wikitable sortable"
|-
! Site
!class="unsortable"| Installation root directory
!class="unsortable"| Notes
|-
| BNL
| <code>/usr/local/crys_test/cctbx</code>
|
|-
| CCI, LBNL
|
| No central installation available
|-
| SLAC
| <code>/reg/g/cctbx/sources</code>
|
|}
Developers will generally have ''cctbx.xfel'' installed in their home directory.


=== ''cctbx.xfel'' setup ===
To start using an installation of ''cctbx.xfel'', the environment has to be configured.  The details depend on the user's shell.


<ul>
== ''cctbx.xfel'' setup ==
<li>
For a bash(1) shell, <code>setpaths.sh</code> should be sourced from the shell configuration files.  To do that, add
<pre>test -r "/reg/g/cctbx/build/setpaths.sh" && \
  . "/reg/g/cctbx/build/setpaths.sh"</pre>
to <code>~/.bashrc</code>.  This ensures the environment is properly prepared for non-interactive shells, ''e.g.'' the shells that are used to run jobs on the cluster.  To also be able to use ''cctbx.xfel'' from interactive shells, ''e.g.'' the shell started after logging in to a host, it is recommended to put
<pre>test -r "${HOME}/.bashrc" && . "${HOME}/.bashrc"</pre>
near the top of <code>~/.bash_profile</code>.  These changes will not take effect until a new shell is started.  To start using the ''cctbx.xfel'' environment from the running shell, source <code>setpaths.sh</code> on the command line,
<pre>. /reg/g/cctbx/build/setpaths.sh</pre>
</li>


<li>
To start using ''cctbx.xfel'', the environment has to be configured.  The details depend on the ''cctbx.xfel'' installation root directory and the user's shell.
csh(1)-users should instead source <code>setpaths.csh</code>.  Add
In what follows it is assumed that ''cctbx.xfel'' is installed at <code>/reg/g/cctbx/build</code>. Substitute <code>/reg/g/cctbx/build</code> with the appropriate path in the instructions below.  These steps need only be performed once.
<pre>test -r "/reg/g/cctbx/build/setpaths.csh" && \
source "/reg/g/cctbx/build/setpaths.csh"</pre>
to <code>~/.cshrc</code>. There is no need to edit any additional files for interactive shells.  To set up the environment for the running shell, execute
<pre>source /reg/g/cctbx/build/setpaths.csh</pre>
on the command line.
</li>
</ul>


=== Linking ''cctbx.xfel'' to ''pyana'' ===
In a bash shell, the environment is prepared for ''cctbx.xfel'' using
$ . /reg/g/cctbx/build/setpaths.sh
For csh, the corresponding command is
% source /reg/g/cctbx/build/setpaths.csh
Sourcing <code>setpaths.sh</code> or <code>ana_env.csh</code> only modifies the environment of the current shell, and would have to be repeated every time a new shell is started.  To make the changes persistent, add
test -r "/reg/g/cctbx/build/setpaths.sh" && \
  . "/reg/g/cctbx/build/setpaths.sh"
to <code>~/.bashrc</code>, or
test -r "/reg/g/cctbx/build/setpaths.csh" && \
  source "/reg/g/cctbx/build/setpaths.csh"
to <code>~/.cshrc as appropriate</code>.
 
 
== Linking ''cctbx.xfel'' to ''pyana'' ==


Run these commands to associate ''pyana'' and ''cctbx.xfel'':
Run these commands to associate ''pyana'' and ''cctbx.xfel'':
Line 39: Line 52:
  $ sit_setup
  $ sit_setup
  $ cd ~/myrelease/my_ana_pkg
  $ cd ~/myrelease/my_ana_pkg
  $ ln -s /reg/g/cctbx/sources/cctbx_project/xfel/cxi/cspad_ana src
  $ ln -fns /reg/g/cctbx/sources/cctbx_project/xfel/cxi/cspad_ana src
  $ cd ..
  $ cd ..
  $ ln -s /reg/g/cctbx/sources/cctbx_project/xfel/cxi/lsf.sh .
  $ ln -s /reg/g/cctbx/sources/cctbx_project/xfel/cxi/lsf.sh .
Line 45: Line 58:
The last step compiles the analysis modules just linked in.
The last step compiles the analysis modules just linked in.


=== Setup your scratch area ===
<!-- XXX Should check this with Andy or so; this can probably be done better.  Perhaps note that using -fns will zap any old src link in place. -->


== Setup your scratch area ==
<!-- XXX This should probably be moved out of the general installation instructions -->
Create a scratch folder and populate it with some directories that will be used during this tutorial, changing <username> to your SLAC account name:
Create a scratch folder and populate it with some directories that will be used during this tutorial, changing <username> to your SLAC account name:


Line 55: Line 72:
  $ mkdir averages
  $ mkdir averages
  $ mkdir results
  $ mkdir results


== Run each time on logging on to SLAC ==
== Run each time on logging on to SLAC ==


Whenever you log on to a fresh shell at SLAC, before you can use any portion of ''cctbx.xfel'' that uses pyana, you must run these commands:
Whenever you log on to a fresh shell at SLAC, before you can use any portion of ''cctbx.xfel'' that uses ''pyana'', you must run these commands:
  $ cd ~/myrelease
  $ cd ~/myrelease
  $ sit_setup
  $ sit_setup


== Test the installation ==
== Test the installation ==
At SLAC, test that it is working by e.g.
At SLAC, test that it is working by <i>e.g.</i>
  $ cd ~/myrelease
  $ cd ~/myrelease
  $ cxi.pyana -c /reg/g/cctbx/tutorials/setup/test.cfg /reg/d/ana11/cxi/data/Mar2013calib/xtc/e236-r0004-s00-c00.xtc
  $ cxi.pyana -c /reg/g/cctbx/tutorials/setup/test.cfg /reg/d/ana11/cxi/data/Mar2013calib/xtc/e236-r0004-s00-c00.xtc
This should start a viewer, displaying dark-subtracted averages from an XTC stream. Press the green run button to see the images.  This particular stream has a series of misses at its beginning; hits will appear presently.
This should start a viewer, displaying dark-subtracted averages from an XTC stream. Press the green run button to see the images.  This particular stream has a series of misses at its beginning; hits will appear presently.


More specifically, this command starts pyana with a configuration file (-c) and an XTC file.  For more information, see the [[Overview]] and other tutorial pages.
More specifically, this command starts ''pyana'' with a configuration file (<code>-c</code>) and an XTC file.  For more information, see the [[Overview]] and other tutorial pages.

Revision as of 18:42, 5 February 2014


Prerequisities

cctbx.xfel must be installed, which in turn requires the PSDM software distribution to be set up. See Set up PSDM software for the latter and Installation for the former. cctbx.xfel can be installed anywhere on the filesystem where write access is granted.

The installation root directory affects the absolute paths used in these instructions and differs from site to site. Some common installation root directories are listed below.

Site Installation root directory Notes
BNL /usr/local/crys_test/cctbx
CCI, LBNL No central installation available
SLAC /reg/g/cctbx/sources

Developers will generally have cctbx.xfel installed in their home directory.


cctbx.xfel setup

To start using cctbx.xfel, the environment has to be configured. The details depend on the cctbx.xfel installation root directory and the user's shell. In what follows it is assumed that cctbx.xfel is installed at /reg/g/cctbx/build. Substitute /reg/g/cctbx/build with the appropriate path in the instructions below. These steps need only be performed once.

In a bash shell, the environment is prepared for cctbx.xfel using 

$ . /reg/g/cctbx/build/setpaths.sh

For csh, the corresponding command is 

% source /reg/g/cctbx/build/setpaths.csh

Sourcing setpaths.sh or ana_env.csh only modifies the environment of the current shell, and would have to be repeated every time a new shell is started. To make the changes persistent, add 

test -r "/reg/g/cctbx/build/setpaths.sh" && \
  . "/reg/g/cctbx/build/setpaths.sh"

to ~/.bashrc, or 

test -r "/reg/g/cctbx/build/setpaths.csh" && \
  source "/reg/g/cctbx/build/setpaths.csh"

to ~/.cshrc as appropriate.


Linking cctbx.xfel to pyana

Run these commands to associate pyana and cctbx.xfel: 

$ cd ~/myrelease
$ sit_setup
$ cd ~/myrelease/my_ana_pkg
$ ln -fns /reg/g/cctbx/sources/cctbx_project/xfel/cxi/cspad_ana src
$ cd ..
$ ln -s /reg/g/cctbx/sources/cctbx_project/xfel/cxi/lsf.sh .
$ scons

The last step compiles the analysis modules just linked in.


Setup your scratch area

Create a scratch folder and populate it with some directories that will be used during this tutorial, changing <username> to your SLAC account name: 

$ cd /reg/g/cctbx/tutorials/scratch/
$ mkdir <username>
$ cd <username>
$ mkdir darks
$ mkdir averages
$ mkdir results


Run each time on logging on to SLAC

Whenever you log on to a fresh shell at SLAC, before you can use any portion of cctbx.xfel that uses pyana, you must run these commands: 

$ cd ~/myrelease
$ sit_setup

Test the installation

At SLAC, test that it is working by e.g. 

$ cd ~/myrelease
$ cxi.pyana -c /reg/g/cctbx/tutorials/setup/test.cfg /reg/d/ana11/cxi/data/Mar2013calib/xtc/e236-r0004-s00-c00.xtc

This should start a viewer, displaying dark-subtracted averages from an XTC stream. Press the green run button to see the images. This particular stream has a series of misses at its beginning; hits will appear presently.

More specifically, this command starts pyana with a configuration file (-c) and an XTC file. For more information, see the Overview and other tutorial pages.

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