essreduce 24.11.3__py3-none-any.whl → 25.1.0__py3-none-any.whl

ess/reduce/time_of_flight/types.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+from dataclasses import dataclass
+from typing import NewType
+
+import scipp as sc
+
+Ltotal = NewType("Ltotal", sc.Variable)
+"""
+Total length of the flight path from the source to the detector.
+"""
+
+
+@dataclass
+class SimulationResults:
+    """
+    Results of a time-of-flight simulation used to create a lookup table.
+
+    The results (apart from ``distance``) should be flat lists (1d arrays) of length N
+    where N is the number of neutrons, containing the properties of the neutrons in the
+    simulation.
+
+    Parameters
+    ----------
+    time_of_arrival:
+        Time of arrival of the neutrons at the position where the events were recorded
+        (1d array of size N).
+    speed:
+        Speed of the neutrons, typically derived from the wavelength of the neutrons
+        (1d array of size N).
+    wavelength:
+        Wavelength of the neutrons (1d array of size N).
+    weight:
+        Weight/probability of the neutrons (1d array of size N).
+    distance:
+        Distance from the source to the position where the events were recorded
+        (single value; we assume all neutrons were recorded at the same position).
+        For a ``tof`` simulation, this is just the position of the detector where the
+        events are recorded. For a ``McStas`` simulation, this is the distance between
+        the source and the event monitor.
+    """
+
+    time_of_arrival: sc.Variable
+    speed: sc.Variable
+    wavelength: sc.Variable
+    weight: sc.Variable
+    distance: sc.Variable
+
+
+@dataclass
+class FastestNeutron:
+    """
+    Properties of the fastest neutron in the simulation results.
+    """
+
+    time_of_arrival: sc.Variable
+    speed: sc.Variable
+    distance: sc.Variable
+
+
+LtotalRange = NewType("LtotalRange", tuple[sc.Variable, sc.Variable])
+"""
+Range (min, max) of the total length of the flight path from the source to the detector.
+This is used to create the lookup table to compute the neutron time-of-flight.
+Note that the resulting table will extend slightly beyond this range, as the supplied
+range is not necessarily a multiple of the distance resolution.
+
+Note also that the range of total flight paths is supplied manually to the workflow
+instead of being read from the input data, as it allows us to compute the expensive part
+of the workflow in advance (the lookup table) and does not need to be repeated for each
+run, or for new data coming in in the case of live data collection.
+"""
+
+DistanceResolution = NewType("DistanceResolution", sc.Variable)
+"""
+Step size of the distance axis in the lookup table.
+Should be a single scalar value with a unit of length.
+This is typically of the order of 1-10 cm.
+"""
+
+TimeOfArrivalResolution = NewType("TimeOfArrivalResolution", int | sc.Variable)
+"""
+Resolution of the time of arrival axis in the lookup table.
+Can be an integer (number of bins) or a sc.Variable (bin width).
+"""
+
+TimeOfFlightLookupTable = NewType("TimeOfFlightLookupTable", sc.DataArray)
+"""
+Lookup table giving time-of-flight as a function of distance and time of arrival.
+"""
+
+MaskedTimeOfFlightLookupTable = NewType("MaskedTimeOfFlightLookupTable", sc.DataArray)
+"""
+Lookup table giving time-of-flight as a function of distance and time of arrival, with
+regions of large uncertainty masked out.
+"""
+
+LookupTableRelativeErrorThreshold = NewType("LookupTableRelativeErrorThreshold", float)
+
+FramePeriod = NewType("FramePeriod", sc.Variable)
+"""
+The period of a frame, a (small) integer multiple of the source period.
+"""
+
+UnwrappedTimeOfArrival = NewType("UnwrappedTimeOfArrival", sc.Variable)
+"""
+Time of arrival of the neutron at the detector, unwrapped at the pulse period.
+"""
+
+PivotTimeAtDetector = NewType("PivotTimeAtDetector", sc.Variable)
+"""
+Pivot time at the detector, i.e., the time of the start of the frame at the detector.
+"""
+
+UnwrappedTimeOfArrivalMinusPivotTime = NewType(
+    "UnwrappedTimeOfArrivalMinusPivotTime", sc.Variable
+)
+"""
+Time of arrival of the neutron at the detector, unwrapped at the pulse period, minus
+the start time of the frame.
+"""
+
+TimeOfArrivalMinusPivotTimeModuloPeriod = NewType(
+    "TimeOfArrivalMinusPivotTimeModuloPeriod", sc.Variable
+)
+"""
+Time of arrival of the neutron at the detector minus the start time of the frame,
+modulo the frame period.
+"""
+
+FrameFoldedTimeOfArrival = NewType("FrameFoldedTimeOfArrival", sc.Variable)
+
+
+PulsePeriod = NewType("PulsePeriod", sc.Variable)
+"""
+Period of the source pulses, i.e., time between consecutive pulse starts.
+"""
+
+PulseStride = NewType("PulseStride", int)
+"""
+Stride of used pulses. Usually 1, but may be a small integer when pulse-skipping.
+"""
+
+PulseStrideOffset = NewType("PulseStrideOffset", int)
+"""
+When pulse-skipping, the offset of the first pulse in the stride.
+"""
+
+RawData = NewType("RawData", sc.DataArray)
+"""
+Raw detector data loaded from a NeXus file, e.g., NXdetector containing NXevent_data.
+"""
+
+TofData = NewType("TofData", sc.DataArray)
+"""
+Detector data with time-of-flight coordinate.
+"""
+
+ResampledTofData = NewType("ResampledTofData", sc.DataArray)
+"""
+Histogrammed detector data with time-of-flight coordinate, that has been resampled.
+
+Histogrammed data that has been converted to `tof` will typically have
+unsorted bin edges (due to either wrapping of `time_of_flight` or wavelength
+overlap between subframes).
+We thus resample the data to ensure that the bin edges are sorted.
+It makes use of the ``to_events`` helper which generates a number of events in each
+bin with a uniform distribution. The new events are then histogrammed using a set of
+sorted bin edges to yield a new histogram with sorted bin edges.
+
+WARNING:
+This function is highly experimental, has limitations and should be used with
+caution. It is a workaround to the issue that rebinning data with unsorted bin
+edges is not supported in scipp.
+"""

ess/reduce/ui.py

@@ -9,7 +9,8 @@ from IPython import display
 from ipywidgets import Layout
 
 from .parameter import Parameter
-from .widgets import SwitchWidget, create_parameter_widget, default_layout
+from .widgets import Spinner, SwitchWidget, create_parameter_widget, default_layout
+from .widgets._base import get_fields, set_fields
 from .workflow import (
     Key,
     assign_parameter_values,
@@ -81,11 +82,13 @@ class ParameterBox(widgets.VBox):
             self._input_widgets.clear()
             self._input_widgets.update(
                 {
-                    node: widgets.HBox([create_parameter_widget(parameter)])
-                    for node, parameter in registry_getter().items()
+                    node: create_parameter_widget(parameter)
+                    for node, parameter in new_input_parameters.items()
                 }
             )
-            self._input_box.children = list(self._input_widgets.values())
+            self._input_box.children = [
+                widgets.HBox([widget]) for widget in self._input_widgets.values()
+            ]
 
         self.parameter_refresh_button.on_click(_refresh_input_box)
 
@@ -97,8 +100,7 @@ class ParameterBox(widgets.VBox):
         return {
             node: widget.value
             for node, widget_box in self._input_widgets.items()
-            if (not isinstance((widget := widget_box.children[0]), SwitchWidget))
-            or widget.enabled
+            if (not isinstance((widget := widget_box), SwitchWidget)) or widget.enabled
         }
 
 
@@ -125,12 +127,14 @@ class ResultBox(widgets.VBox):
         def run_workflow(_: widgets.Button) -> None:
             self.output.clear_output()
             with self.output:
+                display.display(Spinner())
                 compute_result = workflow_runner()
+                display.clear_output()
                 if result_registry is not None:
                     result_registry.clear()
                     result_registry.update(compute_result)
                 for i in compute_result.values():
-                    display.display(display.HTML(i._repr_html_()))
+                    display.display(i)
 
         def clear_output(_: widgets.Button) -> None:
             self.output.clear_output()
@@ -232,3 +236,82 @@ def workflow_widget(result_registry: dict | None = None) -> widgets.Widget:
     workflow_selection_box = widgets.HBox([workflow_select], layout=default_layout)
     workflow_box = widgets.Box(layout=default_layout)
     return widgets.VBox([workflow_selection_box, workflow_box])
+
+
+def _get_parameter_box(widget: WorkflowWidget | ParameterBox) -> ParameterBox:
+    if isinstance(widget, WorkflowWidget):
+        return widget.parameter_box
+    elif isinstance(widget, ParameterBox):
+        return widget
+    else:
+        raise TypeError(
+            f"Expected target_widget to be a WorkflowWidget or ParameterBox, "
+            f"got {type(widget)}."
+        )
+
+
+def set_parameter_widget_values(
+    widget: WorkflowWidget | ParameterBox, new_parameter_values: dict[type, Any]
+) -> None:
+    """Set the values of the input widgets in the target widget.
+
+    Nodes that don't exist in the input widgets will be ignored.
+
+    Example
+    -------
+    .. code-block::
+
+        set_parameter_widget_values(widget, {
+            'WavelengthBins': {'start': 1.0, 'stop': 14.0, 'nbins': 500}
+        })
+
+    Parameters
+    ----------
+    widget:
+        The widget containing the input widgets.
+    new_parameter_values:
+        A dictionary of values/state to set each fields/state or value of input widgets.
+
+    Raises
+    ------
+    TypeError:
+        If the widget is not a WorkflowWidget or a ParameterBox.
+
+    """
+    parameter_box = _get_parameter_box(widget)
+    # Walk through the existing input widgets and set the values
+    # ``node`s that don't exist in the input widgets will be ignored.
+    for node, widget in parameter_box._input_widgets.items():
+        if node in new_parameter_values:
+            # We shouldn't use `get` here because ``None`` is a valid value.
+            set_fields(widget, new_parameter_values[node])
+
+
+def get_parameter_widget_values(
+    widget: WorkflowWidget | ParameterBox,
+) -> dict[type, Any]:
+    """Return the current values of the input widgets in the target widget.
+
+    The result of this function can be used to set the values of the input widgets
+    using the :py:func:`~set_parameter_widget_values` function.
+
+    Parameters
+    ----------
+    widget:
+        The widget containing the input widgets.
+
+    Returns
+    -------
+    :
+        A dictionary of the current values/state of each input widget.
+
+    Raises
+    ------
+    TypeError:
+        If the widget is not a WorkflowWidget or a ParameterBox.
+
+    """
+    return {
+        node: get_fields(widget)
+        for node, widget in _get_parameter_box(widget)._input_widgets.items()
+    }

ess/reduce/uncertainty.py

@@ -13,7 +13,7 @@ The recommended use of this module is via the :py:func:`broadcast_uncertainties`
 helper function.
 """
 
-from enum import Enum
+from enum import Enum, auto
 from typing import TypeVar, overload
 
 import numpy as np
@@ -23,18 +23,18 @@ from scipp.core.concepts import irreducible_mask
 T = TypeVar("T", bound=sc.Variable | sc.DataArray)
 
 
-UncertaintyBroadcastMode = Enum(
-    'UncertaintyBroadcastMode', ['drop', 'upper_bound', 'fail']
-)
-"""
-Mode for broadcasting uncertainties.
+class UncertaintyBroadcastMode(Enum):
+    """Mode for broadcasting uncertainties.
 
-- `drop`: Drop variances if the data is broadcasted.
-- `upper_bound`: Compute an upper bound for the variances.
-- `fail`: Do not broadcast, simply return the input data.
+    See https://doi.org/10.3233/JNR-220049 for context.
+    """
 
-See https://doi.org/10.3233/JNR-220049 for context.
-"""
+    drop = auto()
+    """Drop variances if the data is broadcast."""
+    upper_bound = auto()
+    """Compute an upper bound for the variances."""
+    fail = auto()
+    """Do not broadcast, simply return the input data."""
 
 
 @overload

ess/reduce/widgets/__init__.py

@@ -29,6 +29,7 @@ from ._bounds_widget import BoundsWidget
 from ._string_widget import MultiStringWidget, StringWidget
 from ._switchable_widget import SwitchWidget
 from ._optional_widget import OptionalWidget
+from ._spinner import Spinner
 
 
 class EssWidget(Protocol):
@@ -191,4 +192,5 @@ __all__ = [
     'SwitchWidget',
     'VectorWidget',
     'create_parameter_widget',
+    'Spinner',
 ]

ess/reduce/widgets/_base.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+import warnings
+from collections.abc import Iterable
+from typing import Any, Protocol, runtime_checkable
+
+from ipywidgets import Widget
+
+
+@runtime_checkable
+class WidgetWithFieldsProtocol(Protocol):
+    def set_fields(self, new_values: dict[str, Any]) -> None: ...
+
+    def get_fields(self) -> dict[str, Any]: ...
+
+
+def _warn_invalid_field(invalid_fields: Iterable[str]) -> None:
+    for field_name in invalid_fields:
+        warning_msg = f"Cannot set field '{field_name}'."
+        " The field does not exist in the widget."
+        "The field value will be ignored."
+        warnings.warn(warning_msg, UserWarning, stacklevel=2)
+
+
+class WidgetWithFieldsMixin:
+    def set_fields(self, new_values: dict[str, Any]) -> None:
+        # Extract valid fields
+        new_field_names = set(new_values.keys())
+        valid_field_names = new_field_names & set(self.fields.keys())
+        # Warn for invalid fields
+        invalid_field_names = new_field_names - valid_field_names
+        _warn_invalid_field(invalid_field_names)
+        # Set valid fields
+        for field_name in valid_field_names:
+            self.fields[field_name].value = new_values[field_name]
+
+    def get_fields(self) -> dict[str, Any]:
+        return {
+            field_name: field_sub_widget.value
+            for field_name, field_sub_widget in self.fields.items()
+        }
+
+
+def set_fields(widget: Widget, new_values: dict[str, Any]) -> None:
+    """Set the fields of a widget with the given values.
+
+    Parameters
+    ----------
+    widget:
+        The widget to set the fields. It should either be an instance of
+        ``WidgetWithFieldsProtocol`` or have a value property setter.
+    new_values:
+        The new values to set for the fields.
+        i.e. ``{'field_name': field_value}``
+        If the widget does not have a ``set_fields/get_fields`` method,
+        (e.g. it is not an instance of ``WidgetWithFieldsProtocol``),
+        it will try to set the value of the widget directly.
+        The value of the widget should be available in the ``new_values`` dictionary
+        with the key 'value'.
+        i.e. ``{'value': widget_value}``
+
+    Raises
+    ------
+    TypeError:
+        If ``new_values`` is not a dictionary.
+
+    """
+    if not isinstance(new_values, dict):
+        raise TypeError(f"new_values must be a dictionary, got {type(new_values)}")
+
+    if isinstance(widget, WidgetWithFieldsProtocol) and isinstance(new_values, dict):
+        widget.set_fields(new_values)
+    else:
+        try:
+            # Use value property setter if ``new_values`` contains 'value'
+            if 'value' in new_values:
+                widget.value = new_values['value']
+            # Warn if there is any other fields in new_values
+            _warn_invalid_field(set(new_values.keys()) - {'value'})
+        except AttributeError as error:
+            # Checking if the widget value property has a setter in advance, i.e.
+            # ```python
+            # (widget_property := getattr(type(widget), 'value', None)) is not None
+            # and getattr(widget_property, 'fset', None) is not None
+            # ```
+            # does not work with a class that inherits Traitlets class.
+            # In those classes, even if a property has a setter,
+            # it may not have `fset` attribute.
+            # It is not really feasible to check all possible cases of value setters.
+            # Instead, we try setting the value and catch the AttributeError.
+            # to determine if the widget has a value setter.
+            warnings.warn(
+                f"Cannot set value for widget of type {type(widget)}."
+                " The new_value(s) will be ignored."
+                f" Setting value caused the following error: {error}",
+                UserWarning,
+                stacklevel=1,
+            )
+
+
+def get_fields(widget: Widget) -> dict[str, Any] | None:
+    """Get the fields of a widget.
+
+    If the widget is an instance of ``WidgetWithFieldsProtocol``,
+    it will return the fields of the widget.
+    i.e. ``{'field_name': field_value}``
+    Otherwise, it will try to get the value of the widget and return a dictionary
+    with the key 'value' and the value of the widget.
+    i.e. ``{'value': widget_value}``
+
+    Parameters
+    ----------
+    widget:
+        The widget to get the fields. It should either be an instance of
+        ``WidgetWithFieldsProtocol`` or have a value property.
+
+    """
+    if isinstance(widget, WidgetWithFieldsProtocol):
+        return widget.get_fields()
+    try:
+        return {'value': widget.value}
+    except AttributeError:
+        warnings.warn(
+            f"Cannot get value or fields for widget of type {type(widget)}.",
+            UserWarning,
+            stacklevel=1,
+        )

ess/reduce/widgets/_binedges_widget.py

@@ -3,6 +3,8 @@
 import ipywidgets as ipw
 import scipp as sc
 
+from ._base import WidgetWithFieldsMixin
+
 UNITS_LIBRARY = {
     "wavelength": {"options": ("angstrom", "nm")},
     "Q": {"options": ("1/angstrom", "1/nm")},
@@ -19,7 +21,7 @@ UNITS_LIBRARY = {
 }
 
 
-class BinEdgesWidget(ipw.HBox, ipw.ValueWidget):
+class BinEdgesWidget(ipw.HBox, ipw.ValueWidget, WidgetWithFieldsMixin):
     def __init__(
         self,
         name: str,

ess/reduce/widgets/_bounds_widget.py

@@ -4,9 +4,10 @@ import scipp as sc
 from ipywidgets import FloatText, GridBox, Label, Text, ValueWidget
 
 from ..parameter import ParamWithBounds
+from ._base import WidgetWithFieldsMixin
 
 
-class BoundsWidget(GridBox, ValueWidget):
+class BoundsWidget(GridBox, ValueWidget, WidgetWithFieldsMixin):
     def __init__(self):
         super().__init__()
 

ess/reduce/widgets/_linspace_widget.py

@@ -3,8 +3,10 @@
 import scipp as sc
 from ipywidgets import FloatText, GridBox, IntText, Label, ValueWidget
 
+from ._base import WidgetWithFieldsMixin
 
-class LinspaceWidget(GridBox, ValueWidget):
+
+class LinspaceWidget(GridBox, ValueWidget, WidgetWithFieldsMixin):
     def __init__(self, dim: str, unit: str):
         super().__init__()
 

ess/reduce/widgets/_optional_widget.py

@@ -4,6 +4,7 @@ from typing import Any
 
 from ipywidgets import HTML, HBox, Layout, RadioButtons, Widget
 
+from ._base import get_fields, set_fields
 from ._config import default_style
 
 
@@ -64,3 +65,26 @@ class OptionalWidget(HBox):
         else:
             self._option_box.value = self.name
             self.wrapped.value = value
+
+    def set_fields(self, new_values: dict[str, Any]) -> None:
+        new_values = dict(new_values)
+        # Set the value of the option box
+        opted_out_flag = new_values.pop(
+            # We assume ``essreduce-opted-out`` is not used in any wrapped widget
+            'essreduce-opted-out',
+            self._option_box.value is None,
+        )
+        if not isinstance(opted_out_flag, bool):
+            raise ValueError(
+                f"Invalid value for 'essreduce-opted-out' field: {opted_out_flag}."
+                " The value should be a boolean."
+            )
+        self._option_box.value = None if opted_out_flag else self.name
+        # Set the value of the wrapped widget
+        set_fields(self.wrapped, new_values)
+
+    def get_fields(self) -> dict[str, Any] | None:
+        return {
+            **(get_fields(self.wrapped) or {}),
+            'essreduce-opted-out': self._option_box.value is None,
+        }

ess/reduce/widgets/_spinner.py

@@ -0,0 +1,100 @@
+_spinner = '''
+<style>
+.lds-spinner {
+  /* change color here */
+  color: #1c4c5b
+}
+.lds-spinner,
+.lds-spinner div,
+.lds-spinner div:after {
+  box-sizing: border-box;
+}
+.lds-spinner {
+  color: currentColor;
+  display: inline-block;
+  position: relative;
+  width: 80px;
+  height: 80px;
+}
+.lds-spinner div {
+  transform-origin: 40px 40px;
+  animation: lds-spinner 1.2s linear infinite;
+}
+.lds-spinner div:after {
+  content: " ";
+  display: block;
+  position: absolute;
+  top: 3.2px;
+  left: 36.8px;
+  width: 6.4px;
+  height: 17.6px;
+  border-radius: 20%;
+  background: currentColor;
+}
+.lds-spinner div:nth-child(1) {
+  transform: rotate(0deg);
+  animation-delay: -1.1s;
+}
+.lds-spinner div:nth-child(2) {
+  transform: rotate(30deg);
+  animation-delay: -1s;
+}
+.lds-spinner div:nth-child(3) {
+  transform: rotate(60deg);
+  animation-delay: -0.9s;
+}
+.lds-spinner div:nth-child(4) {
+  transform: rotate(90deg);
+  animation-delay: -0.8s;
+}
+.lds-spinner div:nth-child(5) {
+  transform: rotate(120deg);
+  animation-delay: -0.7s;
+}
+.lds-spinner div:nth-child(6) {
+  transform: rotate(150deg);
+  animation-delay: -0.6s;
+}
+.lds-spinner div:nth-child(7) {
+  transform: rotate(180deg);
+  animation-delay: -0.5s;
+}
+.lds-spinner div:nth-child(8) {
+  transform: rotate(210deg);
+  animation-delay: -0.4s;
+}
+.lds-spinner div:nth-child(9) {
+  transform: rotate(240deg);
+  animation-delay: -0.3s;
+}
+.lds-spinner div:nth-child(10) {
+  transform: rotate(270deg);
+  animation-delay: -0.2s;
+}
+.lds-spinner div:nth-child(11) {
+  transform: rotate(300deg);
+  animation-delay: -0.1s;
+}
+.lds-spinner div:nth-child(12) {
+  transform: rotate(330deg);
+  animation-delay: 0s;
+}
+@keyframes lds-spinner {
+  0% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+  }
+}
+</style>
+<div class="lds-spinner"><div></div><div></div><div></div><div></div><div></div><div></div><div></div><div></div><div></div><div></div><div></div><div></div></div>
+'''  # noqa: E501
+
+
+class Spinner:
+    def _repr_html_(self, *args, **kwargs):
+        return _spinner
+
+    def _repr_pretty_(self, *args, **kwargs):
+        return '...in progress'

ess/reduce/widgets/_string_widget.py

@@ -27,6 +27,15 @@ class StringWidget(HBox, ValueWidget):
 
 
 class MultiStringWidget(StringWidget):
+    def __init__(
+        self, description: str, value: tuple[str, ...] | None = None, **kwargs
+    ):
+        # Special case handling to allow initialising with a single string
+        if not isinstance(value, str) and value is not None:
+            value = ', '.join(value)
+
+        super().__init__(description, value, **kwargs)
+
     @property
     def value(self) -> tuple[str, ...]:
         v = super().value