Getting Started

Running Beamlime

Run the beamlime command, and specify which workflow to use. Usually this would be done from a terminal. The current setup plots the results of the workflow and saves them to a file, which can we specify using the --image-path flag:

!beamlime \
    --workflow dummy \
    --nexus-template-path ../../tests/applications/ymir_detectors.json \
    --image-path-prefix reduction-result

[05/24/24 12:32:45] INFO     Application     | Start running         ]8;id=95946;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=877988;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#265\265]8;;\
                             Application...
                    INFO     Application     | Running daemon        ]8;id=826181;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=672661;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#220\220]8;;\
                             MessageRouter
                    INFO     Application     | Running daemon        ]8;id=574223;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=823072;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#220\220]8;;\
                             FakeListener
                    INFO     FakeListener    | Fake data          ]8;id=549855;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=255439;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#168\168]8;;\
                             streaming started...
                    INFO     FakeListener    | Frame #0: sending  ]8;id=475959;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=623251;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_0.
                    INFO     FakeListener    | Frame #0: sending  ]8;id=170252;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=356651;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_1.
                    INFO     FakeListener    | Neutron events of  ]8;id=469360;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=824029;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#177\177]8;;\
                             frame #0 were sent.
                    INFO     DataReductionHandler | Running data ]8;id=850405;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=121271;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
                    INFO     DataReductionHandler | Running data ]8;id=741107;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=736745;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
[05/24/24 12:32:46] INFO     PlotSaver       | Received          ]8;id=643825;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=203114;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
                    INFO     PlotSaver       | Received          ]8;id=601884;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=983964;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
[05/24/24 12:32:47] INFO     FakeListener    | Frame #1: sending  ]8;id=214524;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=854523;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_0.
                    INFO     FakeListener    | Frame #1: sending  ]8;id=914701;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=79372;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_1.
                    INFO     DataReductionHandler | Running data ]8;id=917536;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=888629;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
                    INFO     FakeListener    | Neutron events of  ]8;id=464567;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=132376;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#177\177]8;;\
                             frame #1 were sent.
                    INFO     PlotSaver       | Received          ]8;id=885983;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=589505;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
[05/24/24 12:32:48] INFO     DataReductionHandler | Running data ]8;id=886370;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=358450;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
                    INFO     PlotSaver       | Received          ]8;id=650622;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=277118;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
                    INFO     FakeListener    | Frame #2: sending  ]8;id=212532;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=296843;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_0.
                    INFO     FakeListener    | Frame #2: sending  ]8;id=772908;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=433434;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#174\174]8;;\
                             neutron events for 
                             entry/instrument/hypothetical_detect
                             or_1.
                    INFO     FakeListener    | Neutron events of  ]8;id=202173;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=749942;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#177\177]8;;\
                             frame #2 were sent.
                    INFO     DataReductionHandler | Running data ]8;id=663452;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=878069;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
                    INFO     DataReductionHandler | Running data ]8;id=444609;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=20922;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#157\157]8;;\
                             reduction
                    INFO     PlotSaver       | Received          ]8;id=733736;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=592777;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
[05/24/24 12:32:49] INFO     PlotSaver       | Received          ]8;id=827124;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py\handlers.py]8;;\:]8;id=372878;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/handlers.py#240\240]8;;\
                             histogram(s), saving into 
                             reduction-result.png...
                    INFO     Application     | Stop running          ]8;id=651286;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=526738;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#188\188]8;;\
                             application Application...
                    INFO     Application     | Daemon MessageRouter  ]8;id=778398;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=111471;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#236\236]8;;\
                             completed.
                    INFO     FakeListener    | Fake data          ]8;id=982983;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py\daemons.py]8;;\:]8;id=875910;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/daemons.py#181\181]8;;\
                             streaming finished...
                    INFO     Application     | Daemon FakeListener   ]8;id=449433;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py\base.py]8;;\:]8;id=375076;file:///home/runner/work/beamlime/beamlime/.tox/docs/lib/python3.10/site-packages/beamlime/applications/base.py#236\236]8;;\
                             completed.

The dummy workflow returns a single result named “reduction-result.png”, which is added as a suffix to the output file name:

Adding workflows

Python packages can add workflows as plugins to Beamlime. To do this, create a Python package with a beamlime.stateless 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.stateless"]
dummy = "beamlime.stateless_workflow:dummy_workflow"

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

# In esssans' pyproject.toml
[project.entry-points."beamlime.stateless"]
ess-loki = "ess.sans.loki:live_workflow"

where live_workflow must adhere to the beamlime.StatelessWorkflow protocol:

import inspect

from beamlime import StatelessWorkflow

print(inspect.getsource(StatelessWorkflow))

class StatelessWorkflow(Protocol):
    """
    Protocol for stateless workflows.

    Can be implemented by a class or a function in plugins, in the
    `beamlime.stateless` entry point group.
    """

    def __call__(self, group: JSONGroup) -> WorkflowResult:
        pass

This can be fulfilled by a class or a function, as long as it takes a JSONGroup and returns a beamlime.WorkflowResult.