Content
Purpose
- short-term goal - support in a single place detectors moving across LCLS experiments.
- perspective goal - calibration store for LCLS-II
It is assumed that hardware configuration of modern detectors will be associated with configuration index coming from DAQ. This index will be used to extract hardly retrievable calibration data such as geometry, gain factors etc. in case of transition of the detector from one experiment to another.
Architecture
Requirements
- instrument independent - detector can be moved between instruments and hatches
- experiment independent - detector can be moved between experiments
- portability - calibration data for particular detector should be portable as a self consistent file
- combination of FS & DB files (hdf5 for uniformity)
- management model - calibration data should be managed through API only in order to prevent adding/removing unknown files without history
- API + GUI for central management
- deployment -
Location of calibration directory and files
Default calibration directory in LCLS FS
instrument and experiment-independent path
- /reg/g/psdm/detector/calib
in contrast to the current instrument and experiment-dependent path
- /reg/d/psdm/<INS>/<experiment>/calib
In local space
define calib path
- <path>/calib/
assuming further structure of the calibration directory <dettype>/<dettype>-<detid>.h5
or use detector calibration file directly
- <path>/<dettype>-<detid>.h5
Structure of calibration directory
Everything in lower case:
<path>/calib/ <dettype>/ cspad2x2/ pnccd/ epix100a/ cspad/ <calib-files> <dettype>-<detid>.h5 <dettype>-<detid>.h5
Detector type <dettype> is used as a folder to organize files under the calib directory. In case of direct access to the hdf5 file the detector type is duplicated in the name of the file. Unique part of the detector name <detid> is used to assign calibration file to the particular detector version. If the detector is changing the new calibration file is created with new <detid>. Information about predecessor and successor (if available) can be saved under the root level of the calibration file.
Calibration data hierarchical scheme
Access to calibration data is based on time stamp. Time stamp internally is presented in Unix time sec which can be easily converted forth and back to human readable format YYYY-MM-DDTHH:MM:SS+HH:MM
The scheme of the calibration data, which presumably will be implemented in <dettype>-<detid>.h5
/ # top-root-level contains info for the unique detector version dettype (str) # detector type name, ex: cspad, pnccd, etc detid (str) # unique detector id, ex: 01234 tstamp_created (uint) # time stamp of creation of this structure predecessor (str) # name of the previous detector if available or None successor (str) # name of the next detector if available or None tags (dict) # dictionary of tags associated with this version of detector <ctype>/ # folder for calibration type <tstamp-range>/ # folder for time stamp validity range <tstamp>[-<tstamp-end>]/ # folder for validity range. If <tstamp-end> is not specified - then valid to the end tstamp_begin (uint) # time stamp for the beginning of the validity range tstamp_end (uint) # time stamp for the end of the validity range default_version # reference to the default calibration, ex: <vers-tstamp2> tags (dict) # dictionary of tags associated with validity range <vers-tstamp1>/ # folder for version created on tstamp1 tstamp_prod (uint) # tstamp1 of this version production calib (ndarray) # calibration data tags (dict) # dictionary of tags, # ex: array size, number of dimensions, shape, data type, experiment, run, comments, author <vers-tstamp2>/ # folder for version created on tstamp2 tstamp_prod (uint) calib (ndarray) tags (dict) <tstamp2>[-<tstamp2-end>]/ # folder for the next validity range. pedestals/ # folder for the next calibration type, pedestals rms/ # folder for the next calibration type, rms
Scheme features
- Detector name consists of a common part <dettype> and unique part <detid>.
- Alias to the detector name should be kept in separate dictionary outside the scheme.
- Each detector may have optional predecessor, successor, and other tags in the dictionary.
- Calibration type folders contain info about calibrations of particular type, ex: pedestals, rms, status, mask, background, etc.
- Each calibration type contains a set of time stamp ranges defining calibration validity range. If the second time stamp of the range is missing it is considered as infinity (by the end).
- The time stamp range folder contains tstamp_begin, tstamp_end (int) values, dictionary of tags associated with this folder, reference to the default calibration, and folders with calibration versions, distinguished by there production time stamp.
- The number of calibration versions for each time stamp range is not limited. Default calibration is defined by the reference default_version.
Data and metadata in tags
Below are the lists of fields which potentially can be used to define detector and access calibrations
Detector metadata
Field name | Description | More details, example |
---|---|---|
dettype | detector type | CSPAD, CSPAD2X2, EPIX100A, etc. |
detname | detector unique name | (if any) ex.: Camera1 |
detalias | alias name | if it is hard to memorize the entire name, ex.: 'cspad1' |
detidx | detector index | integer number which codes the hardware version |
detidxalias | symbolic alias of the index | can be used if it is hard to memorize the index integer number |
detcompidx:001 | list of component indexes | just in case if we are going to retrieve calibration parameters for separate components |
detidxprev | detector index for previous version | detector index for previous version (if available) for the purpose of old calibration search |
detidxnext | detector index for next version | detector index for next version (if available) for the purpose of new calibration search |
dettsec | time-stamp | time stamp associated with beginning of the validity range for new configuration |
detcom:001 | comments for this hardware version | as it says {key:comment} |
dettag:001 | other tags | just in case if something is forgotten in this table |
Calibration parameters' metadata
Field name | Description | More details, example |
---|---|---|
calibtype | calibration type | ex.: geometry, pixel_status, pixel_gain, pedestals, common_mode, etc. |
tsec | time stamp | beginning of the validity range |
exp | original experiment | (if available) where calibration constants were obtained |
runnum | original run number | (if available) where calibration constants were obtained |
runbegin | begin run number | (if available) for validity range |
runend | end run number | (if available) for validity range |
source | original DAQ data source | data source from DAQ, ex.: 'CxiDs2.0:Cspad.0' |
srcalias | data source alias | ex.: 'cspad' |
calibvers | version tag | in order to access using symbolic name or some alias |
calibversalias | version alias | if it is hard to memorize version tag |
com:001 | comments for this version | as it says {key:comment} |
tag:001 | other tags | just in case if something is forgotten in this table |
In case of numpy array their metadata are stored with an object.
Text file needs in n-d array metadata
n-d array metadata
Field name | Description | More details, example |
---|---|---|
dtype | data type | int, float, double, etc |
ndims | number of dimensions (N) | as it says |
dim:1 | size of dim.1 | ... |
dim:2 | size of dim.2 | ... |
... | ... | ... |
dim:N | size of dim.N | ... |
API
Parameters
dettype
(str) - detector type: cspad, cspad2x2, pnccd, fccd, opal, epix100a
, etc.
ctype
(str) - calibration type: pedestals, status, rms, mask, gain, bkgd, common_mode, geometry
detid
(str) - detector unique id number, ex: 123456
detname
(str) - detector unique name, combination of <dettype>-<detid>
detalias
(str) - detector alias name assigned to the detname
cpath
(str) - path to the calibration directory (ex: cpath='<path>/calib'
) or direct hdf5 file name (ex: cpath='<path>/<detname>-<detid>.h5'
). Default calibration directory CPATH_DEF='/reg/g/psdm/detector/calib'
.
Initialization
# Import from PSCalib.CalibStore import CalibStore # Initialization CPATH_DEF = '/reg/g/psdm/detector/calib' # default calib directory cpath = '<path>/calib' # local calib directory cpath = '<path>/<detname>-<detid>.h5' # direct to file cpath = env.calibDir() # '/reg/d/psdm/<INS>/<experiment>/calib' - accept current directory detname = 'pnccd-12345678' # standard name includes detector type, dash, and n-digit id number detname = 'Camera1' # alias detname = 'Camp.0:pnCCD.1' # accept source runnum = 10 # or evt.run() cs = CalibStore(cpath, detname) """ get calibration store object Input parameters: cpath [str] - path to the hdf5 file or calibration directory. If cpath is a path to hdf5 file - next parameter is ignored. If cpath=None - default path is used. detname [str] - name/alias of the detector """
UI - acess methods
p = evt.run() # run number, evt, tstamp - parameter to identify constants nda = cs.pedestals(p) nda = cs.pixel_status(p) nda = cs.pixel_rms(p) nda = cs.pixel_mask(p) nda = cs.pixel_gain(p) nda = cs.pixel_bkgd(p) nda = cs.common_mode(p) geo = cs.geometry(p)
Management methods
cs.addcalib(ctype, nda, p) cs.delete(ctype, p) cdic = cs.getdict(ctype)
TBD
Open questions
- What is included in the detector Id version? FEE version, controller version, etc?
- when constants are updated (file open to write) they are not available... Lock to resolve.
Data flow
- who produces and supply constants
- who is allowed to submit constants
- who is allowed to access constants
- ACL inside API or using OS
- ACL for all or particular detector/type/ etc.
References