Psana has a simple python-script interface, which can be run online (in realtime), offline, and parallelized over many cores/machines both online and offline. Once you have run the quick example below (we believe you should be able to run/understand it in <30 minutes) you can run a variety of "building block" examples here.
There are also some higher-level hutch-specific analysis packages here.
You can also find some links to useful computing topics on the LCLS Data Analysis main page.
To do analysis with a psana python script execute the following commands. This requires the ability to ssh to an LCLS unix account and the ability to open up a graphics window on your computer ("X-windows"). Two free options for graphics:We recommend the free NX Technology (for Mac or Windows) for improved performance, but XQuartz (Mac) or XWin32 (Windows) also works. Replace "YOURACCOUNTNAME" in the first line below with your unix account name.
Note that psana is a package in a larger python-ecosystem called conda. Conda only supports the "bash" unix shell. Once you login you can see what shell you have by typing "echo $SHELL". If it is not bash:
- you can type "bash" to start the correct shell
- we recommend that users send email to firstname.lastname@example.org to get your default shell changed to bash.
- we recommend to make an alias you can remember to set the analysis environment rather than always sourcing it in your .bashrc as we have seen issues e.g. with NoMachine when doing that.
The 17-line ipsana.py script loops over 2 events and plots a CSPAD camera image with many applied calibration corrections, and geometry corrections for each of the detector panels. Close each image window to see the next one. You can examine the script with the command "cat firstExample.py" or edit it with unix editors like emacs, vim, or vi.
NOTE: The commands above will activate the most recent python 3 version of psana. Psana used to work with python 2, but this version of python has not maintained by the Python Software Foundation since January 1, 2020, and psana support has been discontinued. You can use tools like the "2to3" command to migrate your code to python 3. New psana versions do not support python 2, but it still possible to activate the last available python 2 environment (ana-4.0.45) by adding the
py2 option to the
Some of the features of psana-python:
- many of the "building block" tools can be used at FELs around the world: e.g. python, MPI and scikit-beam algorithms
- part of the world-standard conda python ecosystem
- same code works for online/offline analysis analysis (with real-time plot display), allowing users to do their entire analysis chain with one tool
- ability to use both simple and complex languages (python/C++)
- users don't have to wait for xtc-to-hdf5 conversion time
- access to calibrated images both online/offline (pedestals, common-mode, geometry, bad-pixel mask) for complex detectors (CSPAD, pnCCD, EPIX)
- local support at SLAC from ~10 people (core offline group and instrument engineers)
- simple detector names using experiment-specific "aliases"
- ability to randomly access xtc data ("jump" to event in middle of file)
- support for fast parallel processing of xtc files with hundreds of cores using MPI
- ability to run entire psana code on Windows/Mac machines using virtual box (useful for off-site visualization or code development, for example)
Legacy versions of psana
The command above:
Activates the latest version of psana. However, it might still be useful, for compatibility with existing code, to run a legacy version of psana. After running the command above, the complete list of available psana versions can be displayed using the following command:
To run a legacy version of psana, the current psana environment needs to be deactivated. The required version of psana can then be launched. For example, if version 4.0.23 is required, it can be accessed with the following sequence of commands
Please be aware that legacy versions of psana, while keeping compatibility with existing software, cannot of course take advantage of features and improvement introduced in more recent versions of the environment.