lcls2
Classes
Section titled “Classes”| Name | Description |
|---|---|
CalibDocMetadata |
Retains information on calibration constants retrieved from metadata queries. |
CalibrationConstants |
A descriptor for a single kind of calibration constants. |
Functions
Section titled “Functions”| Return | Name | Description |
|---|---|---|
std::string |
get_detector_short_name |
Retrieve the short name for a detector of given type using its serial number. |
void |
load_values_from_byte_stream |
Extract the data from the raw byte stream given the provided metadata. |
void |
deserialize_json_dict |
Recursively traverse a CalibDB JSON dict, deserializing as it goes. |
CalibDocMetadata |
parse_metadata_doc |
Parse a metadata document retrieved from the calibdb. |
std::optional< std::pair< unsigned, unsigned > > |
is_doc_valid_for_run |
Check whether a retrieved metadata document has an appropriate validity range. |
std::map< std::string, CalibrationConstants > |
retrieve_calib_constants_of_type |
For the provided short name get most recent valid constants for the experiment/run. |
std::vector< T > |
split_string |
Split a string and peform an operation on it. |
get_detector_short_name
Section titled “get_detector_short_name”std::string get_detector_short_name(std::string & base_url, std::string & det_type, std::string & det_serial_no)Retrieve the short name for a detector of given type using its serial number.
The short name is used for all CalibDB API requests, so its retrieval is the first step in retrieving constants of any type.
Returns
Section titled “Returns”The short name of the indicated detector.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
base_url |
std::string & |
The main host/URL to use for CalibDB access. |
det_type |
std::string & |
The detector type. E.g. epixuhr3x2, jungfrau. |
det_serial_no |
std::string & |
The full serial number of the specific detector. |
load_values_from_byte_stream
Section titled “load_values_from_byte_stream”void load_values_from_byte_stream(const std::uint8_t * byte_stream, const std::string & data_dtype, std::size_t data_nelem, std::vector< std::uint8_t > & out_buf)Extract the data from the raw byte stream given the provided metadata.
This function is intended to traverse the bulk data from a gridfs request. It must be provided with certain metadata that is retrieved from a separate API call than the bulk data call.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
byte_stream |
const std::uint8_t * |
The raw bytes from the CalibDB HTTP request. |
data_dtype |
const std::string & |
The element datatype from the metadata doc. |
data_nelem |
std::size_t |
The total number of elements from the metadata doc. |
out_buf |
std::vector< std::uint8_t > & |
The buffer to copy the bytes to. |
deserialize_json_dict
Section titled “deserialize_json_dict”void deserialize_json_dict(rapidjson::Value & json_dict, std::map< std::string, CalibrationConstants > & constants)Recursively traverse a CalibDB JSON dict, deserializing as it goes.
Some calibration constants are serialized (even multiple times) as nested dictionaries, encoded as JSON strings. This is done, for example, with the XTCAV constants (at least at some points in history). This function will recurse the dictionary adding all parts to the output constants map.
The caller should check whether this is an appropraite function to call based on the constants type. Alternatively, a simpler, single call to the load function may be appropriate.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
json_dict |
rapidjson::Value & |
The JSON dictionary retrieved from the CalibDB API request. |
constants |
std::map< std::string, [CalibrationConstants](api-xalgospp-lcls2-CalibrationConstants.md#calibrationconstants) > & |
The map to store the deserialized constants. |
parse_metadata_doc
Section titled “parse_metadata_doc”CalibDocMetadata parse_metadata_doc(const rapidjson::Value & meta_doc)Parse a metadata document retrieved from the calibdb.
The metadata documents have the following schema (among others):
-
id_data (string): gridfs identifier for bulk data
-
data_type (string): Whether the constants are an array, string, or so on.
-
data_dtype (string): The datatype of the constants elements.
-
data_ndim (integer): The dimensionality of the constants data.
-
data_size (integer): The total number of elements in the constants.
-
data_shape (string): A serialized string of the constants shape. E.g. ‘(1, 2, 3)’
The metadata documents have additional fields such as various timestamps, the commands used for creating the constants and so on. Not all of these are relevant for our current use.
Returns
Section titled “Returns”The parsed struct with relevant metadata.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
meta_doc |
const rapidjson::Value & |
The document with metadata retrieved from CalibDB. |
is_doc_valid_for_run
Section titled “is_doc_valid_for_run”std::optional< std::pair< unsigned, unsigned > > is_doc_valid_for_run(const rapidjson::Value & metadata_doc, unsigned target_run, bool is_det_db_doc)Check whether a retrieved metadata document has an appropriate validity range.
Returns
Section titled “Returns”Returns the begin and end run if valid (for later sorting); otherwise nullopt.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
metadata_doc |
const rapidjson::Value & |
The retrieved constants metadata document. |
target_run |
unsigned |
The target run number for which the document should be valid. |
is_det_db_doc |
bool |
Whether the document was a detector database document. |
retrieve_calib_constants_of_type
Section titled “retrieve_calib_constants_of_type”std::map< std::string, CalibrationConstants > retrieve_calib_constants_of_type(std::string & base_url, std::string & det_short_name, std::string & experiment, unsigned run, std::set< std::string > constants_type)For the provided short name get most recent valid constants for the experiment/run.
This function will try to find the most recent constants of the provided type(s) for the experiment. It returns a map, as multiple constants can be requested, or in some cases, a single specified type will lead to a nested series of JSON dicts. In that case, the keys will be populated into the map. An empty map will be returned if no constants are found for any requested types.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
base_url |
std::string & |
The main host/URL to use for CalibDB access. |
det_short_name |
std::string & |
The short name of the indicated detector. |
experiment |
std::string & |
The experiment. If no constants are in the experiment DB, the more general detector database will also be searched. |
run |
unsigned |
The run number. |
split_string
Section titled “split_string”template<typename T, class Fn> std::vector< T > split_string(const std::string & s, const std::string & delim, Fn && cast)Split a string and peform an operation on it.
Returns
Section titled “Returns”The vector of split string components.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
s |
const std::string & |
The string to split. |
delim |
const std::string & |
The delimiter to use to split s. |
cast |
Fn && |
The operation to use on each part of the split string. |
Variables
Section titled “Variables”| Return | Name | Description |
|---|---|---|
constexpr unsigned |
LCLS_MAX_EXP_RUN_NUM static constexpr |
This is currently the maximum run number for an LCLS experiment. The calibration database uses this as the cutoff when checking run validity ranges for retrieved constants. |
LCLS_MAX_EXP_RUN_NUM
Section titled “LCLS_MAX_EXP_RUN_NUM”static constexpr
constexpr unsigned LCLS_MAX_EXP_RUN_NUM { 9999 }This is currently the maximum run number for an LCLS experiment. The calibration database uses this as the cutoff when checking run validity ranges for retrieved constants.