data_retrieval_layer

Data Extraction Layer's Protocol classes.

This module contains base Protocol classes for OM's Data Extraction Layer.

OmDataSourceProtocol

Bases: Protocol

See documentation of the __init__ function.

__init__(*, data_source_name, monitor_parameters)

Protocol for OM's Data Source classes.

Data Sources are classes that perform all the operations needed to retrieve data from a single specific sensor or detector. A Data Source class can refer to any type of detector, from a simple diode or wave digitizer, to a big x-ray or optical detector.

This class Protocol describes the interface that every Data Source class in OM must implement.

A Data Source class must be initialized with the full set of OM's configuration parameters, from which it extracts information about the sensor or detector. An identifying name for the sensor must also be provided.

Parameters:

Name	Type	Description	Default
data_source_name	str	A name that identifies the current data source. It is used, for example, in communications with the user or for the retrieval of a sensor's initialization	required
monitor_parameters	MonitorParameters	An object storing OM's configuration parameters.	required

initialize_data_source()

Data source initialization.

This method prepares OM to retrieve data from the sensor or detector, reading all the necessary configuration parameters and retrieving any additional required external data.

get_data(*, event)

Data Retrieval.

This function retrieves all the data generated by the sensor or detector for the provided data event.

Parameters:

Name	Type	Description	Default
event	Dict[str, Any]	A dictionary storing the event data.	required

Returns:

Type	Description
Any	Data from the sensor.

OmDataEventHandlerProtocol

Bases: Protocol

See documentation of the __init__ function.

__init__(*, source, data_sources, monitor_parameters)

Protocol class for OM's Data Event Handler classes.

Data Event Handlers are classes that deal with data events and their sources. They have methods to initialize data event sources, retrieve events from them, open and close events, and examine the events' content.

This Protocol class describes the interface that every Data Event Handler class in OM must implement.

A Data Event Handler class must be initialized with a string describing its data event source, and with a set of Data Source class instances that instruct the Data Event Handler on how to retrieve data from the events.

Parameters:

Name	Type	Description	Default
source	str	A string describing the data event source.	required
data_sources	Dict[str, OmDataSourceProtocol]	A dictionary containing a set of Data Source class instances. Each dictionary key must define the name of a data source. The corresponding dictionary value must store the instance of the Data Source class # noqa: E501 that describes the data source.	required
monitor_parameters	MonitorParameters	An object storing OM's configuration parameters.	required

initialize_event_handling_on_collecting_node(*, node_rank, node_pool_size)

Initializes event handling on the collecting node.

This function is called on the collecting node when OM starts, and initializes the event handling on the node.

Parameters:

Name	Type	Description	Default
node_rank	int	The rank, in the OM pool, of the processing node calling the function.	required
node_pool_size	int	The total number of nodes in the OM pool, including all the processing nodes and the collecting node.	required

initialize_event_handling_on_processing_node(*, node_rank, node_pool_size)

Initializes event handling on a processing node.

This function is called on a processing node when OM starts. It configures the node to start retrieving and processing data events, and initializes all the relevant Data Sources.

Parameters:

Name	Type	Description	Default
node_rank	int	The rank, in the OM pool, of the processing node calling the function.	required
node_pool_size	int	The total number of nodes in the OM pool, including all the processing nodes and the collecting node.	required

event_generator(*, node_rank, node_pool_size)

Retrieves events from the source.

This function retrieves a series of data events from a source. OM calls this function on each processing node to start retrieving events. The function, which is a generator, returns an iterator over the events that the calling node must process.

Parameters:

Name	Type	Description	Default
node_rank	int	The rank, in the OM pool, of the processing node calling the function.	required
node_pool_size	int	The total number of nodes in the OM pool, including all the processing nodes and the collecting node.	required

Yields:

Type	Description
Dict[str, Any]	A dictionary storing the data for the current event.

open_event(*, event)

Opens an event.

This function processes a data event and makes its content accessible for OM. OM calls this function on each processing node before the extract_data function.

Parameters:

Name	Type	Description	Default
event	Dict[str, Any]	A dictionary storing the event data.	required

close_event(*, event)

Closes an event.

This function processes a data event and prepares it to be discarded by OM. OM calls this function on each processing node after the extract_data function.

Parameters:

Name	Type	Description	Default
event	Dict[str, Any]	A dictionary storing the event data.	required

extract_data(*, event)

Extracts data from a frame stored in an event.

This function extracts data from a data event. It works by calling, one after the other, the get_data function of each Data Source associated with the event, passing the event itself as input each time. Each function call returns the data extracted from the Data Source. All the retrieved data items are finally aggregated and returned.

Parameters:

Name	Type	Description	Default
event	Dict[str, Any]	A dictionary storing the event data.	required

Returns:

Type	Description
Dict[str, Any]	A dictionary storing the extracted data. Each dictionary key identifies a Data Source in the event for which data has been retrieved. The corresponding dictionary value stores the data that could be extracted from the Data Source for the provided event.

initialize_event_data_retrieval()

Initializes frame data retrieval.

This function initializes the retrieval of data for a single standalone data event from a data event source, with all its related information. The way this function operates is in contrast with the way OM usually works. OM usually retrieves a series of events in sequence, one after the other. This function retrieves a single event, separated from all others.

This function can be called on any type of node in OM and even outside of an OnDA Monitor class instance. It prepares the system to retrieve the event data, it initializes the relevant Data Sources, etc.

After this function has been called, data for single events can be retrieved by invoking the retrieve_event_data function.

retrieve_event_data(event_id)

Retrieves all data attached to the requested data event.

This function retrieves all the information associated with the data event specified by the provided identifier. The data is returned in the form of a dictionary.

Before this function can be called, frame data retrieval must be initialized by calling the initialize_event_data_retrieval function.

Parameters:

Name	Type	Description	Default
event_id	str	A string that uniquely identifies a data event.	required

Returns:

Type	Description
Dict[str, Any]	All data related to the requested data event.

OmDataRetrievalProtocol

Bases: Protocol

See documentation of the __init__ function.

__init__(*, monitor_parameters, source)

Protocol for OM's Data Retrieval classes.

Data Retrieval classes implement OM's Data Retrieval Layer for a specific beamline, experiment or facility. They describe how data is retrieved and data events are managed.

This Protocol class describes the interface that every Data Retrieval class in OM must implement.

A Data Retrieval class must be initialized with a string describing a data event source, and the full set of OM's configuration parameters.

Parameters:

Name	Type	Description	Default
monitor_parameters	MonitorParameters	An object storing OM's configuration parameters.	required
source	str	A string describing the data event source.	required

get_data_event_handler()

Retrieves the Data Event Handler used by the class.

This function returns the Data Event Handler used by the Data Retrieval class to manipulate data events.

Returns:

Type	Description
OmDataEventHandlerProtocol	The Data Event Handler used by the Data Retrieval class.