Readme

This is intended to be a quick guide to getting started with Cheetah 
Thanks to:
	Chuck Yoon
	Rick Kirian
	Nadia Zatsepin
	Oleksandr Yefanov
	Anton Barty
	


There are a couple of steps to follow when starting from scratch:

1. Compile libcheetah (the analysis part of the code)
2. Link libcheetah to the file reading front-end (currently psana at LCLS)
3. Run the analysis
4. Optimise parameters for your experiment

Some knowledge of your computing architecture is assumed.

------------------------------------------------------------------------
For people in a hurry: Compiling pdslib, libcheetah and psana
------------------------------------------------------------------------
In your startup script .profile or .bashrc add the following line: 
. /reg/g/psdm/bin/sit_setup.sh

Then
Look at examples/build-all

Which builds everything from steps 0 to 2. For more information, read on.
For running cheetah, go to step 3.


------------------------------------------------------------------------
0. Compiling the SLAC data analysis libraries
------------------------------------------------------------------------

Look at:  examples/build-pdslib

Which does the following: 
>------------------------------------------------------------------------<
cd source/lcls/myana/release/pdsdata
make x86_64-linux
>------------------------------------------------------------------------<

Technically this is only required if compiling cheetah within the myana framework.
libcheetah and psana SHOULD be able to compile without this. 

However, it seems to help if this is present (make does not tank).
Some modification may be required for compilation on your home system
(mainly missing #includes and some type definitions. SLAC does not 
guarantee ease portability outside of their own system, nor do we.)



------------------------------------------------------------------------
1. Compiling libcheetah
------------------------------------------------------------------------

Look at:  examples/build-libcheetah

This script executes the makefile in source/, but it first sets a few environment variables.
Here's what is in the script:

>------------------------------------------------------------------------<
export HDF5DIR=/reg/neh/home/rkirian/local
export CHEETAHDIR=/reg/neh/home/rkirian/software/cheetah
export LD_LIBRARY_PATH="/reg/neh/home/rkirian/local/lib:/reg/neh/home/rkirian/software/cheetah/source/lcls/myana/release/build/pdsdata/lib/x86_64-linux"
export LD_RUN_PATH="/reg/neh/home/rkirian/local/lib:/reg/neh/home/rkirian/software/cheetah/source/lcls/myana/release/build/pdsdata/lib/x86_64-linux"

make cheetah
make libcheetah

cp cheetah /reg/d/psdm/cxi/cxi54312/scratch/programs/bin/cheetah-rick
cp cheetah /reg/neh/home/rkirian/local/bin
cp libcheetah.so.* /reg/neh/home/rkirian/local/lib
>------------------------------------------------------------------------<

Copy this script, edit these fields to point to where things are for you, and run it.
Re-run this after making any changes to libcheetah.

Make sure to point to a thread-safe version of the HDF5 library.   
If you don't cheetah will start to run, but randomly crash with segmentation faults whenever two threads try to write an HDF5 file at the same time.
Simply add "--enable-threadsafe" to the hdf5 ./configure command.
hdf5-directory > ./configure --enable-threadsafe


------------------------------------------------------------------------
2. Compiling psana with libcheetah
------------------------------------------------------------------------

Look at: examples/build-psana

Which does the following: 
>------------------------------------------------------------------------<
cd ~/cheetah/source/lcls-psana
. /reg/g/psdm/bin/sit_setup.sh
export LIBPATH=/reg/neh/home/rkirian/local/lib
scons
>------------------------------------------------------------------------<

In case of errors, look at ~/cheetah/source/lcls-psana/README

Common errors are:
- Path to libcheetah not set
- Mismatched HDF5 versions
- Out-of-date psana references

Look at: examples/update-psana for fixing the last problem.

It is possibly a good idea to re-compile psana after making any changes to libcheetah.
Note that SLAC does not guarantee psana to be easily portable outside of their own systems.


------------------------------------------------------------------------
3. Running analysis scripts
------------------------------------------------------------------------

Cheetah can now be run directly; however it is more useful to have a script do a lot of the housekeeping for you.
This is what scripts/hitfinder does.

Look at: 
scripts/hitfinder
examples/run-cheetah-psana

First you have to set a few environment variables telling Cheetah where to look for things:

>------------------------------------------------------------------------<
XTCDIR:    Path to where the xtc data is (default: ./)
H5DIR:     Path to where the results of cheetah will be written (default: ./)
CONFIGDIR: Search path for ini files (default: ./)
TMPDIR:    A place to put temporary files (default: /tmp)
CHEETAH:   The path to cheetah (default: cheetah)
>------------------------------------------------------------------------<

Then hitfinding for data can be done with a simple one-line command, such as: 

> hitfinder -r 57 -i /some/path/foobar.ini

Running "hitfinder -h" tells you all the options.


------------------------------------------------------------------------
4. Optimising Cheetah for your experiment
------------------------------------------------------------------------

Operation of cheetah is controlled by the parameters specified in cheetah.ini 

As with most analysis programs, not all default parameters can cover every situation, and it is most likely that you can benefit from tweaking parameters.
Monitoring output and optimising, in particular Bragg peak identification, is normal procedure.

Common things to change are:
Crystals:
- Local background subtraction radius (tradeoff for speed vs peak size)
- Size and number of Bragg peaks to qualify as a hit
- Minimum signal:noise ratio
- Static ADC threshold (if used)
Single particles:
- ADC value and number of pixels above threshold to qualify as a hit
- Number of past non-hit frames to use as background

See the full cheetah documentation for all options, or talk to your local guru.

Most parameters take sensible default values if not specified. 
There are many 'hidden parameters' which are not critical, but can be tweaked if you need to.

------------------------------------------------------------------------
5. Source code for cheetah
------------------------------------------------------------------------

Cheetah's shared library is under:
~/cheetha/source/cheetah.lib

Myana source code is under:
~/cheetah/source/lcls/myana

Psana source code is under:
~/cheetah/source/lcls-psana