Getting Started

Adding Workflow Constructors

Python packages can add workflow constructors as plugins to Beamlime. To do this, create a Python package with a beamlime.workflow_plugin entry point in the pyproject.toml file. This is how the “dummy” workflow is added to Beamlime:

# In beamlime's pyproject.toml
[project.entry-points."beamlime.workflow_plugin"]
dummy = "beamlime.workflow_protocols:DummyLiveWorkflow"

Above, ‘dummy’ is the name of the workflow (which can then be passed to beamlime --workflow), and ‘beamlime.workflow_protocols:’ is the name of the Python package and module containing the workflow constructor. As an example, for a Loki monitor workflow plugin provided by esssans, the entry point might look as follows:

# In esssans' pyproject.toml
[project.entry-points."beamlime.workflow_plugin"]
ess-loki-monitor = "ess.loki.live:LokiMonitorWorkflow"

where live_workflow must adhere to the beamlime.LiveWorkflow protocol:

import inspect

from beamlime import LiveWorkflow

print(inspect.getsource(LiveWorkflow))

@runtime_checkable
class LiveWorkflow(Protocol):
    def __init__(self, nexus_filename: Path) -> None:
        """Initialize the workflow with all static information.

        The only argument we need is the path to the nexus file or
        a file object that workflow can read from,
        since the file carrys all the static information.
        """
        ...

    def __call__(
        self, nxevent_data: dict[str, JSONGroup], nxlog: dict[str, JSONGroup]
    ) -> WorkflowResult:
        """Call the workflow and return the computed results that can be visualized.

        Parameters
        ----------
        nxevent_data:
            Dictionary of event data groups.
            It should contain empty events even if no events was received
            since the last call.

        nxlog:
            Dictionary of log data groups.
            It should only contain keys that we received since the last call.


        Returns
        -------
        :
            A dictionary of objects that can be visualized.

        """
        ...

This can be fulfilled by a class with

• a constructor that accepts a nexus file path

• __call__ method that accepts JSONGroups of each types, (nxlog, nxevent)

• __call__ method that returns a dictionary of a plottable results: beamlime.WorkflowResult.