API Changes (for C++ users)

Two incompatible API changes have been made that will affect some C++ users (but not Python users). These involve

  1. C++ Histograms
  2. Automatic header includes 

The reason for these changes is to allow installation of psana without requiring an installation of root. (We have replaced psana's build dependency on root with a run time dependency). Details of these changes are found below in the section API Changes Details.

Psana

  • IData: Allow user to override /reg/d/psdm as default location for data using environment variable SIT_PSDM_DATA
  • pypsalg: Added many new python wrappers to C methods in psalg.
  • pdscalibdata: 
    • AndorBaseV1.h - set Rows=0, Cols=0 in order to support variable shape for 514x512 and 2048x2048 data (PSAS-6, PSAS-121)
    •  in NDArrIOV1.cpp - in constructor 2 set m_size = nda_def.size(), other things are cosmetic.
  • ImgAlgos: add module EventCodeFilter (PSAS-122) 
  • CalibManager:
    • add option to select dark events in any run using event code filter (PSAS-122)
    • add GUIAlignment, and widget wrapper GUIROIMask (PSAS-6, PSAS-11). In many modules use class Frame in stead of QFrame + many cosmetic changes.
  • psana_test: minor update
  • psana_python: add boost converters for Event,Env,Source.
  • PSQt: Add modules WdgColorBar, WdgRadHist, WdgSpecHist, add multiple protections - the 1st stable version with all basic features (PSAS-11). Improve doxygen documentation, cleenup code.
  • PSCalib: add support for calibration types pixel_mask, pixel_bkgd; fix problem with different ndarray size/shape for common_mode.
  • pytopsana: add C++ class Detector with python wrapper for direct access to calibration data. 
  • Translator, ImgPixSpectra: minor changes due to root header files previously including some standard C++ declarations (PSAS-131)
  • RootHist: add factory function to return instance of PSHist::HManager to allow dynamic loading of RootHist (PSAS-131)
  • PSEnv: API changes as discussed above (remove rhmgr, change hmgr to return pointer, remove root header files) (PSAS-131)
  • psana: remove using statement for RootHistoManager::AxisDef (since package deprecated and has been removed) (PSAS-131)
  • psana_examples: update one example for new hmgr API (PSAS-131)
  • TimeTool: update Analyze, Check and Setup to use new hmgr API. Report non-fatal errors if histogram service is not available, but otherwise continue (PSAS-131)

New Packages

  • PSQt: C++ GUI-based application for detector alignment using Qt4.
  • pytopsana:  python to psana interface classes/methods.

Removed Package

  • RootHistoManager: use of this, through PSEnv::Env::rhmgr() has been deprecated in favor of PSEnv::Env::hmgr() for some time now. With this release it has now been removed so users will need to use hmgr() (see the section API Changes Details). (PSAS-131) 

Bugs fixed 

  • PSCalib: GeometryObject - delete and make new array pointers only if array size is changing (PSAS-11)
  • ImgAlgos:   PixCoordsProducer - move calls of savePixCoordsInCalibStore(env) in checkCalibPars(...) (PSAS-11)

Known Issues

  • When reading small data files (.smd.xtc) and extracting data that resides in the large file, psana will crash after about 1000 retrievals (PSAS-130). This will be fixed in the next release. In the mean time, one can make a test release and do
    addpkg psddl_pds2psana V00-09-20
    to get the bug fix.

  • TimeTool.Analyze and Setup
    •  do not work on newer data with EvrDataV4 (as opposed to EvrDataV3). Usage of TimeTool will generated warnings about no evr data. This will be fixed in the next release. In the mean time, one can make a test release and do
      addpkg TimeTool V00-02-02
      to get the fix.
    • Crash in MPI jobs. Setting dump=0 should turn off the .root file creation, but the bug is that an empty root file is created. This is fixed in the next release. In the mean time, one can make a test release and do
      addpkg TimeTool V00-02-02
      to get the fix

API Changes Details

Below we document details of the two API changes affecting C++ users.

C++ Histograms

Psana provides a histogram mechanism that is available to C++ modules. (This mechanism is not part of the Python interface where one can use numpy or scipy). The API to use this mechanism has changed. The old API implemented the following two methods of PSEnv::Env:

RootHistoManager::RootHMgr& rhmgr();
PSHist::HManager& hmgr();

rhmgr has been a deprecated function for some time that has now been removed. The interface is now

boost::shared_ptr<PSHist::HManager> hmgr();

Clients of hmgr() need to check that they have a valid pointer before using histogram services, and be cognizant of the change from a reference to a pointer in the return argument of hmgr. Otherwise, there is no change to user code. The histogram service should work as expected. However in the future, we may install psana in computing centers where hmgr() returns null and no histogram service is available for C++ modules.

Automatic Header Includes

Psana used to include certain header files from the root C++ library. These headers in turn included numerous items from the standard C++ library, and used using std statements. For example, a psana C++ module did not need to include <fstream>, it could just use ofstream without qualifying it as std::ofstream. We have since removed these root headers. Consequently users may need to include the appropriate headers from the C++ library in their own code, and make use of the std:: namespace qualifier.

  • No labels