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

ess/reduce/__init__.py

@@ -4,7 +4,7 @@
 
 import importlib.metadata
 
-from . import nexus, uncertainty
+from . import nexus, uncertainty, time_of_flight
 
 try:
     __version__ = importlib.metadata.version("essreduce")
@@ -13,4 +13,4 @@ except importlib.metadata.PackageNotFoundError:
 
 del importlib
 
-__all__ = ['nexus', 'uncertainty']
+__all__ = ["nexus", "uncertainty", "time_of_flight"]

ess/reduce/live/raw.py

@@ -111,6 +111,19 @@ class LogicalView:
     Logical view of a multi-dimensional detector.
 
     Instances can be used as a "projection" function for a detector view.
+
+    Parameters
+    ----------
+    fold:
+        Dimensions to fold. This is useful is the raw data has a single dimension that
+        corresponds to multiple dimensions in the logical view.
+    transpose:
+        Dimensions to transpose. This is useful for reordering dimensions.
+    select:
+        Dimensions with associated index to select from the data. This extracts a slice
+        of the data for each given dimension.
+    flatten:
+        Dimensions to flatten.
     """
 
     fold: dict[str, int] | None = None
@@ -281,7 +294,7 @@ class RollingDetectorView(Detector):
             noise_replica_count = 0
         else:
             noise_replica_count = 4
-        wf = GenericNeXusWorkflow()
+        wf = GenericNeXusWorkflow(run_types=[SampleRun], monitor_types=[])
         wf[RollingDetectorViewWindow] = window
         if isinstance(projection, LogicalView):
             wf[LogicalView] = projection

ess/reduce/nexus/_nexus_loader.py

@@ -3,6 +3,7 @@
 
 """NeXus loaders."""
 
+import errno
 from collections.abc import Generator, Mapping
 from contextlib import AbstractContextManager, contextmanager, nullcontext
 from dataclasses import dataclass
@@ -91,6 +92,8 @@ def compute_component_position(dg: sc.DataGroup) -> sc.DataGroup:
 def _open_nexus_file(
     file_path: FilePath | NeXusFile | NeXusGroup,
     definitions: Mapping | None | NoNewDefinitionsType = NoNewDefinitions,
+    *,
+    locking: bool | None = None,
 ) -> AbstractContextManager[snx.Group]:
     if isinstance(file_path, getattr(NeXusGroup, '__supertype__', type(None))):
         if (
@@ -101,9 +104,42 @@ def _open_nexus_file(
                 "Cannot apply new definitions to open nexus file or nexus group."
             )
         return nullcontext(file_path)
+
+    try:
+        return _open_nexus_file_from_path(file_path, definitions, locking=locking)
+    except OSError as err:
+        if err.errno == errno.EROFS:
+            # Failed to open because the filesystem is read-only.
+            # (According to https://www.ioplex.com/%7Emiallen/errcmpp.html
+            # this error code is universal.)
+            #
+            # On ESS machines, this happens for network filesystems of data that was
+            # ingested into SciCat, including raw data.
+            # In this case, it is safe to open the file without locking because:
+            # - For raw files, they were written on a separate machine and are synced
+            #   with the one running reduction software. So there cannot be concurrent
+            #   write and read accesses to the same file on the same filesystem.
+            #   The ground truth on the filesystem used by the file writer is protected
+            #   and cannot be corrupted by our reader.
+            # - For processed data, the file was copied to the read-only filesystem.
+            #   So the copy we are opening was not written by HDF5 directly and thus
+            #   locking has no effect anyway.
+            #
+            # When running on user machines, disabling locking can potentially corrupt
+            # files. But the risk is minimal because very few users will have read-only
+            # filesystems and do concurrent reads and writes.
+            return _open_nexus_file_from_path(file_path, definitions, locking=False)
+        raise
+
+
+def _open_nexus_file_from_path(
+    file_path: FilePath,
+    definitions: Mapping | None | NoNewDefinitionsType,
+    **kwargs: object,
+) -> AbstractContextManager[snx.Group]:
     if definitions is NoNewDefinitions:
-        return snx.File(file_path)
-    return snx.File(file_path, definitions=definitions)
+        return snx.File(file_path, **kwargs)
+    return snx.File(file_path, definitions=definitions, **kwargs)
 
 
 @contextmanager

ess/reduce/nexus/types.py

@@ -107,6 +107,16 @@ IncidentMonitor = NewType('IncidentMonitor', int)
 """Incident monitor"""
 TransmissionMonitor = NewType('TransmissionMonitor', int)
 """Transmission monitor"""
+FrameMonitor0 = NewType('FrameMonitor', int)
+"""Frame monitor number 0"""
+FrameMonitor1 = NewType('FrameMonitor', int)
+"""Frame monitor number 1"""
+FrameMonitor2 = NewType('FrameMonitor', int)
+"""Frame monitor number 2"""
+FrameMonitor3 = NewType('FrameMonitor', int)
+"""Frame monitor number 3"""
+CaveMonitor = NewType('CaveMonitor', int)
+"""A monitor located in the instrument cave"""
 MonitorType = TypeVar(
     'MonitorType',
     Monitor1,
@@ -117,6 +127,11 @@ MonitorType = TypeVar(
     Monitor6,
     IncidentMonitor,
     TransmissionMonitor,
+    FrameMonitor0,
+    FrameMonitor1,
+    FrameMonitor2,
+    FrameMonitor3,
+    CaveMonitor,
 )
 """TypeVar for specifying what monitor some data belongs to.
 
@@ -130,6 +145,11 @@ Possible values:
 - :class:`Monitor6`
 - :class:`IncidentMonitor`
 - :class:`TransmissionMonitor`
+- :class:`FrameMonitor0`
+- :class:`FrameMonitor1`
+- :class:`FrameMonitor2`
+- :class:`FrameMonitor3`
+- :class:`CaveMonitor`
 """
 
 
@@ -148,6 +168,11 @@ Component = TypeVar(
     Monitor6,
     IncidentMonitor,
     TransmissionMonitor,
+    FrameMonitor0,
+    FrameMonitor1,
+    FrameMonitor2,
+    FrameMonitor3,
+    CaveMonitor,
 )
 UniqueComponent = TypeVar('UniqueComponent', snx.NXsample, snx.NXsource)
 """Components that can be identified by their type as there will only be one."""

ess/reduce/time_of_flight/__init__.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""
+Utilities for computing real neutron time-of-flight from chopper settings and
+neutron time-of-arrival at the detectors.
+"""
+
+from .toa_to_tof import default_parameters, resample_tof_data, providers, TofWorkflow
+from .simulation import simulate_beamline
+from .types import (
+    DistanceResolution,
+    FrameFoldedTimeOfArrival,
+    FramePeriod,
+    LookupTableRelativeErrorThreshold,
+    Ltotal,
+    LtotalRange,
+    MaskedTimeOfFlightLookupTable,
+    PivotTimeAtDetector,
+    PulsePeriod,
+    PulseStride,
+    PulseStrideOffset,
+    RawData,
+    ResampledTofData,
+    SimulationResults,
+    TimeOfArrivalMinusPivotTimeModuloPeriod,
+    TimeOfFlightLookupTable,
+    TofData,
+    UnwrappedTimeOfArrival,
+    UnwrappedTimeOfArrivalMinusPivotTime,
+)
+
+
+__all__ = [
+    "DistanceResolution",
+    "FrameFoldedTimeOfArrival",
+    "FramePeriod",
+    "LookupTableRelativeErrorThreshold",
+    "Ltotal",
+    "LtotalRange",
+    "MaskedTimeOfFlightLookupTable",
+    "PivotTimeAtDetector",
+    "PulsePeriod",
+    "PulseStride",
+    "PulseStrideOffset",
+    "RawData",
+    "ResampledTofData",
+    "SimulationResults",
+    "TimeOfArrivalMinusPivotTimeModuloPeriod",
+    "TimeOfFlightLookupTable",
+    "TofData",
+    "TofWorkflow",
+    "UnwrappedTimeOfArrival",
+    "UnwrappedTimeOfArrivalMinusPivotTime",
+    "default_parameters",
+    "providers",
+    "resample_tof_data",
+    "simulate_beamline",
+]

ess/reduce/time_of_flight/fakes.py

@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+"""
+A fake time-of-flight neutron beamline for documentation and testing.
+
+This provides detector event data in a structure as typically provided in a NeXus file,
+with event_time_offset and event_time_zero information.
+"""
+
+from collections.abc import Callable
+
+import numpy as np
+import scipp as sc
+from scippneutron.chopper import DiskChopper
+
+
+class FakeBeamline:
+    def __init__(
+        self,
+        choppers: dict[str, DiskChopper],
+        monitors: dict[str, sc.Variable],
+        run_length: sc.Variable,
+        events_per_pulse: int = 200000,
+        source: Callable | None = None,
+    ):
+        import math
+
+        import tof as tof_pkg
+        from tof.facilities.ess_pulse import pulse
+
+        self.frequency = pulse.frequency
+        self.npulses = math.ceil((run_length * self.frequency).to(unit="").value)
+        self.events_per_pulse = events_per_pulse
+
+        # Create a source
+        if source is None:
+            self.source = tof_pkg.Source(
+                facility="ess", neutrons=self.events_per_pulse, pulses=self.npulses
+            )
+        else:
+            self.source = source(pulses=self.npulses)
+
+        # Convert the choppers to tof.Chopper
+        self.choppers = [
+            tof_pkg.Chopper(
+                frequency=abs(ch.frequency),
+                direction=tof_pkg.AntiClockwise
+                if (ch.frequency.value > 0.0)
+                else tof_pkg.Clockwise,
+                open=ch.slit_begin,
+                close=ch.slit_end,
+                phase=abs(ch.phase),
+                distance=ch.axle_position.fields.z,
+                name=name,
+            )
+            for name, ch in choppers.items()
+        ]
+
+        # Add detectors
+        self.monitors = [
+            tof_pkg.Detector(distance=distance, name=key)
+            for key, distance in monitors.items()
+        ]
+
+        #  Propagate the neutrons
+        self.model = tof_pkg.Model(
+            source=self.source, choppers=self.choppers, detectors=self.monitors
+        )
+        self.model_result = self.model.run()
+
+    def get_monitor(self, name: str) -> sc.DataGroup:
+        # Create some fake pulse time zero
+        start = sc.datetime("2024-01-01T12:00:00.000000")
+        period = sc.reciprocal(self.frequency)
+
+        detector = self.model_result.detectors[name]
+        raw_data = detector.data.flatten(to="event")
+        # Select only the neutrons that make it to the detector
+        raw_data = raw_data[~raw_data.masks["blocked_by_others"]].copy()
+        raw_data.coords["Ltotal"] = detector.distance
+
+        # Format the data in a way that resembles data loaded from NeXus
+        event_data = raw_data.copy(deep=False)
+        dt = period.to(unit="us")
+        event_time_zero = (dt * (event_data.coords["toa"] // dt)).to(dtype=int) + start
+        raw_data.coords["event_time_zero"] = event_time_zero
+        event_data.coords["event_time_zero"] = event_time_zero
+        event_data.coords["event_time_offset"] = (
+            event_data.coords.pop("toa").to(unit="s") % period
+        )
+        del event_data.coords["tof"]
+        del event_data.coords["speed"]
+        del event_data.coords["time"]
+        del event_data.coords["wavelength"]
+
+        return (
+            event_data.group("event_time_zero").rename_dims(event_time_zero="pulse"),
+            raw_data.group("event_time_zero").rename_dims(event_time_zero="pulse"),
+        )
+
+
+wfm1_chopper = DiskChopper(
+    frequency=sc.scalar(-70.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(-47.10, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 6.6], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([83.71, 140.49, 193.26, 242.32, 287.91, 330.3]) + 15.0,
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([94.7, 155.79, 212.56, 265.33, 314.37, 360.0]) + 15.0,
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+wfm2_chopper = DiskChopper(
+    frequency=sc.scalar(-70.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(-76.76, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 7.1], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([65.04, 126.1, 182.88, 235.67, 284.73, 330.32]) + 15.0,
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([76.03, 141.4, 202.18, 254.97, 307.74, 360.0]) + 15.0,
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+foc1_chopper = DiskChopper(
+    frequency=sc.scalar(-56.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(-62.40, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 8.8], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([74.6, 139.6, 194.3, 245.3, 294.8, 347.2]),
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([95.2, 162.8, 216.1, 263.1, 310.5, 371.6]),
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+foc2_chopper = DiskChopper(
+    frequency=sc.scalar(-28.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(-12.27, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 15.9], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([98.0, 154.0, 206.8, 255.0, 299.0, 344.65]),
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([134.6, 190.06, 237.01, 280.88, 323.56, 373.76]),
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+pol_chopper = DiskChopper(
+    frequency=sc.scalar(-14.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(0.0, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 17.0], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([40.0]),
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([240.0]),
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+pulse_skipping = DiskChopper(
+    frequency=sc.scalar(-7.0, unit="Hz"),
+    beam_position=sc.scalar(0.0, unit="deg"),
+    phase=sc.scalar(0.0, unit="deg"),
+    axle_position=sc.vector(value=[0, 0, 30.0], unit="m"),
+    slit_begin=sc.array(
+        dims=["cutout"],
+        values=np.array([40.0]),
+        unit="deg",
+    ),
+    slit_end=sc.array(
+        dims=["cutout"],
+        values=np.array([140.0]),
+        unit="deg",
+    ),
+    slit_height=sc.scalar(10.0, unit="cm"),
+    radius=sc.scalar(30.0, unit="cm"),
+)
+
+
+def wfm_choppers():
+    return {
+        "wfm1": wfm1_chopper,
+        "wfm2": wfm2_chopper,
+        "foc1": foc1_chopper,
+        "foc2": foc2_chopper,
+        "pol": pol_chopper,
+    }
+
+
+def psc_choppers():
+    return {
+        name: DiskChopper(
+            frequency=ch.frequency,
+            beam_position=ch.beam_position,
+            phase=ch.phase,
+            axle_position=ch.axle_position,
+            slit_begin=ch.slit_begin[0:1],
+            slit_end=ch.slit_end[0:1],
+            slit_height=ch.slit_height[0:1],
+            radius=ch.radius,
+        )
+        for name, ch in wfm_choppers().items()
+    }

ess/reduce/time_of_flight/simulation.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+from collections.abc import Mapping
+
+import scipp as sc
+from scippneutron.chopper import DiskChopper
+
+from .types import SimulationResults
+
+
+def simulate_beamline(
+    choppers: Mapping[str, DiskChopper],
+    neutrons: int = 1_000_000,
+    seed: int | None = None,
+    facility: str = 'ess',
+) -> SimulationResults:
+    """
+    Simulate a pulse of neutrons propagating through a chopper cascade using the
+    ``tof`` package (https://tof.readthedocs.io).
+
+    Parameters
+    ----------
+    choppers:
+        A dict of DiskChopper objects representing the choppers in the beamline. See
+        https://scipp.github.io/scippneutron/user-guide/chopper/processing-nexus-choppers.html#Build-DiskChopper
+        for more information.
+    neutrons:
+        Number of neutrons to simulate.
+    seed:
+        Seed for the random number generator used in the simulation.
+    facility:
+        Facility where the experiment is performed.
+    """
+    import tof
+
+    tof_choppers = [
+        tof.Chopper(
+            frequency=abs(ch.frequency),
+            direction=tof.AntiClockwise
+            if (ch.frequency.value > 0.0)
+            else tof.Clockwise,
+            open=ch.slit_begin,
+            close=ch.slit_end,
+            phase=abs(ch.phase),
+            distance=ch.axle_position.fields.z,
+            name=name,
+        )
+        for name, ch in choppers.items()
+    ]
+    source = tof.Source(facility=facility, neutrons=neutrons, seed=seed)
+    if not tof_choppers:
+        events = source.data.squeeze()
+        return SimulationResults(
+            time_of_arrival=events.coords["time"],
+            speed=events.coords["speed"],
+            wavelength=events.coords["wavelength"],
+            weight=events.data,
+            distance=0.0 * sc.units.m,
+        )
+    model = tof.Model(source=source, choppers=tof_choppers)
+    results = model.run()
+    # Find name of the furthest chopper in tof_choppers
+    furthest_chopper = max(tof_choppers, key=lambda c: c.distance)
+    events = results[furthest_chopper.name].data.squeeze()
+    events = events[
+        ~(events.masks["blocked_by_others"] | events.masks["blocked_by_me"])
+    ]
+    return SimulationResults(
+        time_of_arrival=events.coords["toa"],
+        speed=events.coords["speed"],
+        wavelength=events.coords["wavelength"],
+        weight=events.data,
+        distance=furthest_chopper.distance,
+    )

ess/reduce/time_of_flight/to_events.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+from functools import reduce
+
+import numpy as np
+import scipp as sc
+
+
+def to_events(
+    da: sc.DataArray, event_dim: str, events_per_bin: int = 500
+) -> sc.DataArray:
+    """
+    Convert a histogrammed data array to an event list.
+    The generated events have a uniform distribution within each bin.
+    Each dimension with a bin-edge coordinate is converted to an event coordinate.
+    The contract is that if we re-histogram the event list with the same bin edges,
+    we should get the original counts back.
+    Masks on non-bin-edge dimensions are preserved.
+    If there are masks on bin-edge dimensions, the masked values are zeroed out in the
+    original data before the conversion to events.
+
+    Parameters
+    ----------
+    da:
+        DataArray to convert to events.
+    event_dim:
+        Name of the new event dimension.
+    events_per_bin:
+        Number of events to generate per bin.
+    """
+    if da.bins is not None:
+        raise ValueError("Cannot convert a binned DataArray to events.")
+    rng = np.random.default_rng()
+    event_coords = {}
+    edge_dims = []
+    midp_dims = []
+    # Separate bin-edge and midpoints coords
+    for dim in da.dims:
+        if da.coords.is_edges(dim):
+            edge_dims.append(dim)
+        else:
+            midp_dims.append(dim)
+
+    edge_sizes = {dim: da.sizes[dim] for dim in edge_dims}
+    for dim in edge_dims:
+        coord = da.coords[dim]
+        low = sc.broadcast(coord[dim, :-1], sizes=edge_sizes).values
+        high = sc.broadcast(coord[dim, 1:], sizes=edge_sizes).values
+
+        # The numpy.random.uniform function below does not support NaNs, so we need to
+        # replace them with zeros, and then replace them back after the random numbers
+        # have been generated.
+        nans = np.isnan(low) | np.isnan(high)
+        low = np.where(nans, 0.0, low)
+        high = np.where(nans, 0.0, high)
+
+        # In each bin, we generate a number of events with a uniform distribution.
+        events = rng.uniform(
+            low, high, size=(events_per_bin, *list(edge_sizes.values()))
+        )
+        events[..., nans] = np.nan
+        event_coords[dim] = sc.array(
+            dims=[event_dim, *edge_dims], values=events, unit=coord.unit
+        )
+
+    # Find and apply masks that are on a bin-edge dimension
+    event_masks = {}
+    other_masks = {}
+    edge_dims_set = set(edge_dims)
+    for key, mask in da.masks.items():
+        if set(mask.dims) & edge_dims_set:
+            event_masks[key] = mask
+        else:
+            other_masks[key] = mask
+
+    data = da.data
+    if event_masks:
+        inv_mask = (~reduce(lambda a, b: a | b, event_masks.values())).to(dtype=int)
+        inv_mask.unit = ''
+        data = data * inv_mask
+
+    # Create the data counts, which are the original counts divided by the number of
+    # events per bin
+    sizes = {event_dim: events_per_bin} | da.sizes
+    val = sc.broadcast(sc.values(data) / float(events_per_bin), sizes=sizes)
+    kwargs = {'dims': sizes.keys(), 'values': val.values, 'unit': data.unit}
+    if data.variances is not None:
+        # Note here that all the events are correlated.
+        # If we later histogram the events with different edges than the original
+        # histogram, then neighboring bins will be correlated, and the error obtained
+        # will be too small. It is however not clear what can be done to improve this.
+        kwargs['variances'] = sc.broadcast(
+            sc.variances(data) / float(events_per_bin), sizes=sizes
+        ).values
+    new_data = sc.array(**kwargs)
+
+    new = sc.DataArray(data=new_data, coords=event_coords)
+    new = new.transpose((*midp_dims, *edge_dims, event_dim)).flatten(
+        dims=[*edge_dims, event_dim], to=event_dim
+    )
+    return new.assign_coords(
+        {dim: da.coords[dim].copy() for dim in midp_dims}
+    ).assign_masks({key: mask.copy() for key, mask in other_masks.items()})