Warning!

This is a personal unofficial repository of Cheetah. The official Website is http://www.desy.de/~barty/cheetah/, and the repository is https://github.com/antonbarty/cheetah/.

Here, features specific for SACLA are being developed. When matured, they will hopefully be merged to the official distribution.

New features

• saveSACLA option

  This is a multi-event HDF5 similar to CXIDB format but more primitive. The biggest difference is that we do not use 3D or 4D arrays to store multiple images. Instead, we make a group tag-XXXXX for each frame.

• SACLA API integration (cheetah-sacla-api2)

  This is similar to cheetah-sacla, but reads images from SACLA Data Access User API (Joti et al., 2015, J. Synchrotron Radiat.) instead of a HDF5 file created by DataConvert3/4. It also supports filtering by low-level filter (LLF) and photodiode values (for time-resolved experiments).

  cheetah-sacla-api is obsolete, only for backward-compatibility (to access old datasets).

• SACLA online API integration (cheetah-sacla-online)

  This is intended for online realtime image filtering. Under development.

---

The original README follows.

Cheetah Installation Instructions

Preparing for the build

To build cheetah you need cmake (and optionally ccmake).

If you're on psexport you can just do:

$ export PATH=~filipe/cmake/bin:${PATH}

Otherwise just ask your sysadmin to install it.

If your HDF5 is not installed in a standard location set the HDF5_ROOT environment variable to point to it, e.g.:

$ export HDF5_ROOT=${HOME}/local

You also need to have LCLS's ana available somewhere. If you're building at CFEL, LCLS or Uppsala this should already be available.

If not you can try to use the scripts/download_psana.py to download it but you will likely have to do modifications. The best is probably to ask LCLS about getting a portable version of ana.

Building and Installing

Now that you have cmake we can start the build:

• Create and go into a build directory:

    $ mkdir build
    $ cd build
  

• Run ccmake and point it to the base directory

    $ ccmake ..
  

• You will see something like:

 ANA_ARCH                         x86_64-rhel6-gcc44-opt                       
 ANA_RELEASE                      /opt/psana/g/psdm/portable/sw/releases/ana-current
 ANA_SIT_DATA                     /opt/psana/g/psdm/portable/sw/releases/ana-current/../../../data
 BUILD_CHEETAH_ANA_MOD            ON                                           
 BUILD_CHEETAH_MYANA              OFF                                          
 BUILD_PSANA                      ON                                           
 CMAKE_BUILD_TYPE                                                              
 CMAKE_CXX_COMPILER               /usr/bin/c++                                 
 CMAKE_C_COMPILER                 /usr/bin/cc                                  
 CMAKE_INSTALL_PREFIX             /usr/local                                   
 HDF5_C_INCLUDE_DIR               /opt/include                                 
 HDF5_hdf5_LIBRARY_RELEASE        /opt/lib64/libhdf5.so                        
 RPATH_ON_INSTALLED_BINS          ON                                           

ANA_ARCH: ana architecture to be used                                           
Press [enter] to edit option                              CMake Version 2.8.10.2
Press [c] to configure
Press [h] for help           Press [q] to quit without generating
Press [t] to toggle advanced mode (Currently Off)

• It's possible that you have to specify ANA_RELEASE manually. It should point to the ana-current directory, for example on psexport it is /reg/g/psdm/sw/releases/ana-current/

• You can also specify the CMAKE_INSTALL_PREFIX. I set mine to ~/usr

• Press "c" to configure.

 ANA_ARCH                         x86_64-rhel6-gcc44-opt                       
 ANA_RELEASE                      /opt/psana/g/psdm/portable/sw/releases/ana-current
 ANA_SIT_DATA                     /opt/psana/g/psdm/portable/sw/releases/ana-current/../../../data
 BUILD_CHEETAH_ANA_MOD            ON                                           
 BUILD_CHEETAH_MYANA              OFF                                          
 BUILD_PSANA                      ON                                           
 CMAKE_BUILD_TYPE                                                              
 CMAKE_CXX_COMPILER               /usr/bin/c++                                 
 CMAKE_C_COMPILER                 /usr/bin/cc                                  
 CMAKE_INSTALL_PREFIX             /home/filipe/usr                             
 HDF5_C_INCLUDE_DIR               /opt/include                                 
 HDF5_hdf5_LIBRARY_RELEASE        /opt/lib64/libhdf5.so                        
 RPATH_ON_INSTALLED_BINS          ON                                           

ANA_ARCH: ana architecture to be used                                           
Press [enter] to edit option                              CMake Version 2.8.10.2
Press [c] to configure       Press [g] to generate and exit
Press [h] for help           Press [q] to quit without generating
Press [t] to toggle advanced mode (Currently Off)

• If everything went well you should see a screen just like the one above and be able to press "g" to generate the Makefiles.

• When you press "g" ccmake will generate the necessary Makefiles and exit.

• Now just run make. This will build things and place the result in the build directory.

    $ make
  

• If you want to install just do.

    $ make install
  

Notes on psana and shared libraries

• If you do not care for LD_LIBRARY_PATHs and RPATHs you can safely skip this section and everything should work as expected. Otherwise read on!

Cheetah uses as the main backend psana. psana looks up and loads shared libraries at runtime according to the psana.cfg configuration files. If it cannot find the library specified it will exit with an error. The loaded dynamic libraries will themselves load other libraries, for example libcheetah_ana_mod loads libcheetah such that you end up with the following chain:

psana->libcheetah_ana_mod->libcheetah->libhdf5(among others)

This can often cause headaches for the user if the libraries are not in standard locations (which they usually are not). One solution is to set the LD_LIBRARY_PATH variable to include the directory of all the necessary libraries. Another option is to set the RPATH on the programs and libraries which tells them where to look for libraries. The RPATH takes precedence over the LD_LIBRARY_PATH and because it's hardwired is less flexible.

When building cheetah all binaries inside the build directory will have the RPATH set to the location using during the linking stage. This means that you should be able to run them directly from the build directory without the need to set any LD_LIBRARY_PATH. When you do make install the binaries are moved to their install directory and the RPATH is can be removed from the binaries. This means that on the one hand you now can control where they load the libraries from using the LD_LIBRARY_PATH, but on the other hand they will likely not find the required libraries if you do not specify any LD_LIBRARY_PATH.

If you wish to remove the RPATH from the installed binaries and you know what you're doing set RPATH_ON_INSTALLED_BINS to FALSE in ccmake.