diff --git a/packages/essdiffraction/docs/api-reference/index.md b/packages/essdiffraction/docs/api-reference/index.md index cf04faf3d..09121e396 100644 --- a/packages/essdiffraction/docs/api-reference/index.md +++ b/packages/essdiffraction/docs/api-reference/index.md @@ -185,6 +185,7 @@ function's documentation and deprecation warning. :toctree: ../generated/functions MagicWorkflow + MagicMcStasWorkflow ``` ### Submodules @@ -197,6 +198,7 @@ function's documentation and deprecation warning. beamline data + mcstas types workflow ``` diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index 872e9da43..db0ea5955 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -2,3 +2,59 @@ MAGIC — **Mag**netism Single-Crystal Diffractometer — is an ESS polarised time-of-flight single-crystal diffractometer for studying magnetic structures. + +## Reading McStas simulations + +`MagicMcStasWorkflow` reads weighted events from one MAGIC absorption logger and groups them by detector pixel. +It loads every row of the selected bank into memory, so large simulations require substantial RAM. + +```python +from ess.magic import MagicMcStasWorkflow +from ess.magic.types import DetectorBank, Filename, RawDetector, SampleRun + +workflow = MagicMcStasWorkflow() +workflow[Filename[SampleRun]] = 'simulation.h5' +detector = workflow.compute(RawDetector[SampleRun]) +``` + +Bank A (`A_abs_logger`) is the default. +To read bank B (`B_abs_logger`) from a simulation that contains it, set +`workflow[DetectorBank] = DetectorBank.detector_b` before computing. + +The result uses the shared `RawDetector` type, with a `pixel_id` dimension, +pixel positions in the common simulation frame, and weighted events in each pixel: + +| Field | Meaning | Unit | +| --- | --- | --- | +| Event data | Original simulation weight `p` | `counts` (weighted-count convention) | +| `position` | Detector pixel centre | `m` | +| `t` | Original McStas arrival time | `s` | +| `event_time_offset` | Arrival time relative to the most recent pulse | `s` | +| `event_time_zero` | Pulse timestamp using a synthetic Unix-epoch origin | `datetime64[ns]` | + +Weights are not normalized to an absolute count rate. +Zero-weight events and empty pixels are retained; events outside the detector are excluded. +The default pulse period is 1/14 s. Arrival times are folded into that period, +with pulse timestamps rounded to the nearest nanosecond; `t` is retained for diagnostics. +No emission-time correction is applied. To override the pulse period: + +```python +import scipp as sc +from ess.reduce.unwrap import PulsePeriod + +workflow[PulsePeriod] = sc.scalar(1 / 14, unit='s') +``` + +## Detector geometry + +Compute the selected bank's geometry without loading its event data: + +```python +from ess.magic.types import EmptyDetector + +geometry = workflow.compute(EmptyDetector[SampleRun]) +``` + +The result has a `pixel_id` dimension, integer pixel IDs as data and a coordinate, +and a `position` coordinate in metres in the common simulation frame. +Bank A has IDs 1–491520; bank B has IDs 491521–622592. diff --git a/packages/essdiffraction/src/ess/magic/__init__.py b/packages/essdiffraction/src/ess/magic/__init__.py index afe8eda19..ba86e0fa0 100644 --- a/packages/essdiffraction/src/ess/magic/__init__.py +++ b/packages/essdiffraction/src/ess/magic/__init__.py @@ -3,7 +3,7 @@ import importlib.metadata -from .workflow import MagicWorkflow, default_parameters +from .workflow import MagicMcStasWorkflow, MagicWorkflow, default_parameters try: __version__ = importlib.metadata.version("essdiffraction") @@ -13,6 +13,7 @@ del importlib __all__ = [ + 'MagicMcStasWorkflow', 'MagicWorkflow', '__version__', 'default_parameters', diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py new file mode 100644 index 000000000..bef68aefb --- /dev/null +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -0,0 +1,280 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 Scipp contributors (https://github.com/scipp) +"""Read weighted events and detector geometry from MAGIC McStas simulations.""" + +from dataclasses import dataclass +from pathlib import Path + +import mcstastox +import numpy as np +import scipp as sc + +from ess.reduce.unwrap import PulsePeriod + +from .types import DetectorBank, EmptyDetector, Filename, RawDetector, RunType + +__all__ = ['load_mcstas_events', 'mcstas_detector_geometry'] + +# Bound arithmetic temporaries without limiting the number of loaded events. +_ASSIGNMENT_CHUNK_SIZE = 2_000_000 + +_LOGGERS = { + DetectorBank.detector_a: 'A_abs_logger', + DetectorBank.detector_b: 'B_abs_logger', +} + +_COORDINATE_UNITS = { + 'x': 'm', + 'y': 'm', + 'z': 'm', + 't': 's', +} + + +def _load_events(reader: mcstastox.Read, component: str) -> sc.DataArray: + """Read all weighted logger rows in their local frame, before pixel assignment.""" + columns = reader.get_component_variables(component).split() + expected = ['p', 'x', 'y', 'z', 'vx', 'vy', 'vz', 't'] + if len(columns) != len(expected) or set(columns) != set(expected): + raise ValueError(f'{component} columns must be {expected}; got {columns}') + values = reader.get_event_data( + variables=['p', *_COORDINATE_UNITS], + component_name=component, + filter_zeros=False, + ) + weights = values.pop('p') + data = sc.array(dims=['event'], values=weights, variances=weights**2, unit='counts') + del weights + return sc.DataArray( + data, + coords={ + name: sc.array(dims=['event'], values=values.pop(name), unit=unit) + for name, unit in _COORDINATE_UNITS.items() + }, + ) + + +def _geometry_parameter(parameters, name: str) -> float: + try: + value = float(np.asarray(parameters[name][()]).item()) + except (TypeError, ValueError) as error: + raise ValueError(f'McStas parameter {name} must be a scalar number.') from error + if not np.isfinite(value): + raise ValueError(f'McStas parameter {name} must be finite.') + return value + + +@dataclass(frozen=True) +class _DetectorModel: + """Shared cassette parameters for pixel centres and their inverse mapping.""" + + cassettes: int + anodes: int + first_id: int + radius: float + length: float + spacing: float # radians + tilt: float # radians + top: tuple[float, float] + bottom: tuple[float, float] + cathodes: int = 32 + + +def _detector_model(reader: mcstastox.Read, bank: DetectorBank) -> _DetectorModel: + parameters = reader.file['entry1/simulation/Param'] + if bank is DetectorBank.detector_a: + cassettes, anodes, first_id = 60, 128, 1 + radius, length, spacing, tilt = ( + _geometry_parameter(parameters, name) + for name in ( + 'A_r1', + 'A_section_length', + 'A_casette_gamma', + 'A_casette_omega', + ) + ) + top, bottom = (0.252863, 0.416545), (-0.722903, -1.077999) + elif bank is DetectorBank.detector_b: + cassettes, anodes, first_id = 128, 16, 491521 + radius, length, spacing = 1.0, 0.53, -0.94 + tilt = _geometry_parameter(parameters, 'B_casette_omega') + top, bottom = (0.051016, 0.077887), (-0.051016, -0.077887) + else: + raise ValueError(f'Unknown MAGIC detector bank: {bank!r}') + if radius <= 0 or length <= 0 or spacing == 0 or abs(tilt) >= 90: + raise ValueError( + 'Detector geometry requires positive radius and length, nonzero ' + 'cassette spacing, and a cassette tilt strictly between ' + '-90 and 90 degrees.' + ) + return _DetectorModel( + cassettes, + anodes, + first_id, + radius, + length, + np.deg2rad(spacing), + np.deg2rad(tilt), + top, + bottom, + ) + + +def mcstas_detector_geometry( + filename: Filename[RunType], bank: DetectorBank +) -> EmptyDetector[RunType]: + """Construct pixel IDs and positions without reading detector events. + + Uses the MAGIC cassette model from ``magic-notebooks``' ``voxelization.py``: + both counters in a cassette share the central absorption plane. IDs increase + with counter first, then anode, then cathode. McStasToX applies the logger's + placement to put positions in the common simulation frame, in metres. + + Bank A reads ``A_r1`` (m), ``A_section_length`` (m), ``A_casette_gamma`` + (deg) and ``A_casette_omega`` (deg). Bank B uses the reference model's + 1 m radius, 0.53 m length and -0.94 degree cassette spacing, and requires + ``B_casette_omega`` (deg). Channel counts and trapezoid heights are fixed + by the reference model. + """ + component = _LOGGERS[bank] + filename = Path(filename) + with mcstastox.Read(filename.parent, filename.name) as reader: + model = _detector_model(reader, bank) + index = np.arange(2 * model.cassettes * model.anodes * model.cathodes) + counter = index % (2 * model.cassettes) + anode = (index // (2 * model.cassettes)) % model.anodes + cathode = index // (2 * model.cassettes * model.anodes) + fraction = (cathode + 0.5) / model.cathodes + depth = model.length * fraction + gamma = (counter // 2) * model.spacing + upper = model.top[0] + (model.top[1] - model.top[0]) * fraction + lower = model.bottom[0] + (model.bottom[1] - model.bottom[0]) * fraction + local = np.column_stack( + ( + model.radius * np.sin(gamma) + depth * np.sin(gamma + model.tilt), + upper + (lower - upper) * (anode + 0.5) / model.anodes, + model.radius * np.cos(gamma) + depth * np.cos(gamma + model.tilt), + ) + ) + # Reuse McStasToX's row-vector placement convention, as FREIA does. + position = reader.transform(local, component) + + pixel_id = sc.arange( + 'pixel_id', + model.first_id, + model.first_id + len(index), + unit=None, + dtype='int32', + ) + return EmptyDetector[RunType]( + sc.DataArray( + pixel_id, + coords={ + 'pixel_id': pixel_id, + 'position': sc.vectors(dims=['pixel_id'], values=position, unit='m'), + }, + ) + ) + + +def _assign_pixel_ids(events: sc.DataArray, model: _DetectorModel) -> np.ndarray: + # Keep the reference voxelization.py operation order at pixel boundaries. + x, y, z = ( + events.coords[c].to(unit='m', dtype='float64', copy=False) for c in 'xyz' + ) + radius_squared = x * x + z * z + depth = ( + sc.sqrt( + radius_squared + - sc.scalar((model.radius * np.sin(model.tilt)) ** 2, unit='m^2') + ) + - sc.scalar(model.radius * np.cos(model.tilt), unit='m') + ) / sc.scalar(model.length, unit='m') + cathode = sc.floor(model.cathodes * depth).values + top, bottom = ( + sc.scalar(front, unit='m') + sc.scalar(back - front, unit='m') * depth + for front, back in (model.top, model.bottom) + ) + anode = sc.floor(model.anodes * ((y - top) / (bottom - top))).values + correction = sc.asin( + np.sin(model.tilt) + * depth + * sc.scalar(model.length, unit='m') + / sc.sqrt(radius_squared) + ) + fraction = ( + sc.atan2(y=x, x=z) - correction + sc.scalar(model.spacing * 0.5, unit='rad') + ) / sc.scalar(model.cassettes * model.spacing, unit='rad') + counter = sc.floor(2 * model.cassettes * fraction).values + accepted = ( + (cathode >= 0) + & (cathode < model.cathodes) + & (anode >= 0) + & (anode < model.anodes) + & (counter >= 0) + & (counter < 2 * model.cassettes) + ) + pixel = np.full(events.sizes['event'], -1, dtype=np.int32) + # Accepted indices are integral floats; IDs <= 622592 are exact in float64. + pixel[accepted] = ( + counter[accepted] + + 2 * model.cassettes * (anode[accepted] + model.anodes * cathode[accepted]) + + model.first_id + ).astype(np.int32) + return pixel + + +def load_mcstas_events( + filename: Filename[RunType], + bank: DetectorBank, + detector: EmptyDetector[RunType], + pulse_period: PulsePeriod, +) -> RawDetector[RunType]: + """Load weighted events grouped by the selected bank's detector pixels. + + Pixel assignment uses logger-local positions and the MAGIC cassette model. + Outside or invalid positions are excluded. Empty pixels, zero weights and + detector masks are retained. Weights are unnormalized ``p`` with variances + ``p**2``. Original arrival times remain in ``t`` (s). Pulse-relative offsets + are in ``event_time_offset`` (s); ``event_time_zero`` uses the Unix epoch as + the simulation origin, with pulse timestamps rounded to nanoseconds. + """ + period = pulse_period.to(unit='s', dtype='float64') + if period.ndim or not np.isfinite(period.value) or period.value <= 0: + raise ValueError('PulsePeriod must be a finite positive scalar duration.') + filename = Path(filename) + with mcstastox.Read(filename.parent, filename.name) as reader: + model = _detector_model(reader, bank) + span = np.arctan2( + model.length * np.sin(model.tilt), + model.radius + model.length * np.cos(model.tilt), + ) + ends = (-0.5 * model.spacing, (model.cassettes - 0.5) * model.spacing) + if min(ends) + min(0.0, span) <= -np.pi or max(ends) + max(0.0, span) >= np.pi: + raise ValueError('Detector angular footprint must stay within (-pi, pi).') + raw = _load_events(reader, _LOGGERS[bank]) + + pixel_id = sc.empty(sizes=raw.sizes, dtype='int32', unit=None) + for start in range(0, raw.sizes['event'], _ASSIGNMENT_CHUNK_SIZE): + stop = start + _ASSIGNMENT_CHUNK_SIZE + pixel_id.values[start:stop] = _assign_pixel_ids(raw['event', start:stop], model) + # Group only weights and times, avoiding copies of the absorption positions. + events = sc.DataArray(raw.data, coords={'pixel_id': pixel_id, 't': raw.coords['t']}) + del raw + grouped = events.group(detector.coords['pixel_id']) + if grouped.bins.size().sum().value != np.count_nonzero(pixel_id.values >= 0): + raise ValueError('Detector geometry does not contain all accepted pixel IDs.') + time = grouped.bins.coords['t'] + if not sc.isfinite(time.bins.constituents['data']).all().value: + raise ValueError('Accepted McStas arrival times must be finite.') + offset = time % period + # Keep round-off at frame boundaries inside the half-open pulse interval. + offset = sc.where(offset < sc.scalar(0.0, unit='s'), offset + period, offset) + offset = sc.where(offset >= period, offset - period, offset) + grouped.bins.coords['event_time_offset'] = offset + grouped.bins.coords['event_time_zero'] = sc.datetime(0, unit='ns') + sc.round( + (time - offset).to(unit='ns') + ).to(dtype='int64') + return RawDetector[RunType]( + grouped.assign_coords(detector.coords).assign_masks(detector.masks) + ) diff --git a/packages/essdiffraction/src/ess/magic/types.py b/packages/essdiffraction/src/ess/magic/types.py index 20dcb89c8..d5993f218 100644 --- a/packages/essdiffraction/src/ess/magic/types.py +++ b/packages/essdiffraction/src/ess/magic/types.py @@ -6,8 +6,15 @@ import scipp as sc -from ess.reduce.nexus.types import Filename, RawDetector, RunType, SampleRun - +from ess.reduce.nexus.types import ( + EmptyDetector, + Filename, + RawDetector, + RunType, + SampleRun, +) + +EmptyDetector = EmptyDetector RawDetector = RawDetector Filename = Filename RunType = RunType diff --git a/packages/essdiffraction/src/ess/magic/workflow.py b/packages/essdiffraction/src/ess/magic/workflow.py index b948ec378..24f651979 100644 --- a/packages/essdiffraction/src/ess/magic/workflow.py +++ b/packages/essdiffraction/src/ess/magic/workflow.py @@ -2,10 +2,14 @@ # Copyright (c) 2026 Scipp contributors (https://github.com/scipp) import sciline as sl +import scipp as sc from ess.reduce.nexus.types import DetectorBankSizes +from ess.reduce.unwrap import PulsePeriod +from . import mcstas from .beamline import DETECTOR_BANK_SIZES +from .types import DetectorBank, RunType, SampleRun default_parameters = { DetectorBankSizes: DETECTOR_BANK_SIZES, @@ -21,3 +25,21 @@ def MagicWorkflow() -> sl.Pipeline: pipeline is developed. """ return sl.Pipeline(providers=(), params=default_parameters) + + +def MagicMcStasWorkflow() -> sl.Pipeline: + """Workflow for MAGIC McStas events and geometry, with detector bank A by default. + + Provides ``RawDetector[RunType]`` with weighted events grouped by pixel and + ``EmptyDetector[RunType]`` geometry that can be loaded independently. + Event times include pulse-relative offsets and timestamps, retaining McStas + ``t`` for diagnostics. The default pulse period is 1/14 s. + """ + return sl.Pipeline( + providers=(mcstas.load_mcstas_events, mcstas.mcstas_detector_geometry), + constraints={RunType: [SampleRun]}, + params={ + DetectorBank: DetectorBank.detector_a, + PulsePeriod: sc.scalar(1 / 14, unit='s'), + }, + ) diff --git a/packages/essdiffraction/tests/magic/geometry_test.py b/packages/essdiffraction/tests/magic/geometry_test.py new file mode 100644 index 000000000..2d75a2828 --- /dev/null +++ b/packages/essdiffraction/tests/magic/geometry_test.py @@ -0,0 +1,175 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 Scipp contributors (https://github.com/scipp) + +import h5py +import numpy as np +import pytest +import scipp as sc +from ess.magic import MagicMcStasWorkflow +from ess.magic.mcstas import mcstas_detector_geometry +from ess.magic.types import DetectorBank, EmptyDetector, Filename, SampleRun +from scipp.testing import assert_identical + +# calc_xyz_by_id from magic-notebooks/mantid_worfkflow/dependencies/voxelization.py, +# commit da5844563df1a51442171c8178241879b52a06b0. Counter pairs share one plane. +# Landmarks: first pixel, next cassette, next anode, next cathode, last pixel. +_REFERENCE = { + DetectorBank.detector_a: ( + [1, 3, 121, 15361, 491520], + [ + [-0.0013098892101839482, 0.25157728161621096, 1.0081769977265218], + [0.017165105059185757, 0.25157728161621096, 1.0080317126573515], + [-0.0013098892101839482, 0.24389078234863285, 1.0081769977265218], + [-0.003929667630551845, 0.2566290167236328, 1.0245309931795656], + [1.2983717665556587, -1.066644226196289, 0.7853170846571818], + ], + ), + DetectorBank.detector_b: ( + [491521, 491523, 491777, 495617, 622592], + [ + [0.001438023971304267, 0.0482211181640625, 1.0081554392046324], + [-0.015101321462914348, 0.0482211181640625, 1.0080433560124786], + [0.001438023971304267, 0.0417916357421875, 1.0081554392046324], + [0.0043140719139128005, 0.0490083544921875, 1.024466317613897], + [-1.3635425231286782, -0.0726254443359375, -0.6637225184556543], + ], + ), +} + + +def _write_geometry( + tmp_path, *, parameters=None, position=(0.0, 0.0, 0.0), rotation=None +): + values = { + 'A_r1': 1.0, + 'A_section_length': 0.53, + 'A_casette_gamma': 1.05, + 'A_casette_omega': -9.101, + 'B_casette_omega': 10.0, + } | (parameters or {}) + filename = tmp_path / 'geometry.h5' + with h5py.File(filename, 'w') as file: + file.create_group('entry1/data') + simulation = file.create_group('entry1/simulation') + simulation.attrs['program'] = np.bytes_('McStas 3.5.32') + params = simulation.create_group('Param') + for name, value in values.items(): + params[name] = [np.bytes_(str(value))] + for index, bank in enumerate(('A', 'B'), start=1): + component = file.create_group( + f'entry1/instrument/components/{index:04d}_{bank}_abs_logger' + ) + component['Position'] = position + component['Rotation'] = np.eye(3) if rotation is None else rotation + # No output or event datasets: geometry must be independent of events. + return filename + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_geometry_matches_mantid_voxel_centres_without_reading_events(tmp_path, bank): + filename = _write_geometry(tmp_path) + other = '0002_B' if bank is DetectorBank.detector_a else '0001_A' + with h5py.File(filename, 'r+') as file: + del file[f'entry1/instrument/components/{other}_abs_logger'] + detector = mcstas_detector_geometry(filename, bank) + ids, expected = _REFERENCE[bank] + first, last = ids[0], ids[-1] + assert detector.sizes == {'pixel_id': last - first + 1} + assert set(detector.coords) == {'pixel_id', 'position'} + assert detector.coords['position'].unit == 'm' + assert_identical(detector.data, detector.coords['pixel_id']) + assert_identical( + detector.coords['pixel_id'], + sc.arange('pixel_id', first, last + 1, dtype='int32', unit=None), + ) + positions = detector.coords['position'].values + np.testing.assert_allclose( + positions[np.array(ids) - first], expected, atol=1e-14, rtol=0 + ) + np.testing.assert_array_equal(positions[::2], positions[1::2]) + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_geometry_uses_recorded_component_placement(tmp_path, bank): + filename = _write_geometry( + tmp_path, + position=[1.0, 2.0, 3.0], + rotation=[[0, 0, -1], [0, 1, 0], [1, 0, 0]], + ) + detector = mcstas_detector_geometry(filename, bank) + ids, local = _REFERENCE[bank] + x, y, z = np.array(local).T + expected = np.column_stack((z + 1, y + 2, 3 - x)) + np.testing.assert_allclose( + detector.coords['position'].values[np.array(ids) - ids[0]], + expected, + atol=1e-14, + rtol=0, + ) + + +def test_geometry_uses_recorded_a_dimensions_and_spacing(tmp_path): + filename = _write_geometry( + tmp_path, + parameters={ + 'A_r1': 2.0, + 'A_section_length': 0.64, + 'A_casette_gamma': 1.0, + 'A_casette_omega': 0.0, + }, + ) + # Accept numeric scalar parameters as well as the usual one-element strings. + with h5py.File(filename, 'r+') as file: + params = file['entry1/simulation/Param'] + del params['A_r1'] + params['A_r1'] = 2.0 + positions = ( + mcstas_detector_geometry(filename, DetectorBank.detector_a) + .coords['position'] + .values + ) + np.testing.assert_allclose( + positions[[0, 2]][:, [0, 2]], + [[0.0, 2.01], [0.03507933693893986, 2.0096938672643465]], + atol=1e-14, + rtol=0, + ) + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_geometry_requires_recorded_cassette_tilt(tmp_path, bank): + filename = _write_geometry(tmp_path) + name = 'A_casette_omega' if bank is DetectorBank.detector_a else 'B_casette_omega' + with h5py.File(filename, 'r+') as file: + del file[f'entry1/simulation/Param/{name}'] + with pytest.raises(KeyError, match=name): + mcstas_detector_geometry(filename, bank) + + +@pytest.mark.parametrize( + ('name', 'value'), + [ + ('A_r1', 0.0), + ('A_section_length', -1.0), + ('A_casette_gamma', 0.0), + ('A_casette_omega', 90.0), + ('A_casette_omega', np.nan), + ('A_r1', np.inf), + ], +) +def test_geometry_rejects_invalid_parameters(tmp_path, name, value): + filename = _write_geometry(tmp_path, parameters={name: value}) + with pytest.raises(ValueError, match=f'{name}|Detector geometry'): + mcstas_detector_geometry(filename, DetectorBank.detector_a) + + +@pytest.mark.parametrize('bank', [None, DetectorBank.detector_b]) +def test_workflow_computes_geometry_without_events(tmp_path, bank): + filename = _write_geometry(tmp_path) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + if bank is not None: + workflow[DetectorBank] = bank + actual = workflow.compute(EmptyDetector[SampleRun]) + expected = mcstas_detector_geometry(filename, bank or DetectorBank.detector_a) + assert_identical(actual, expected) diff --git a/packages/essdiffraction/tests/magic/mcstas_test.py b/packages/essdiffraction/tests/magic/mcstas_test.py new file mode 100644 index 000000000..618c1b042 --- /dev/null +++ b/packages/essdiffraction/tests/magic/mcstas_test.py @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 Scipp contributors (https://github.com/scipp) + +import h5py +import mcstastox +import numpy as np +import pytest +import scipp as sc +from ess.magic.mcstas import _load_events +from ess.magic.types import DetectorBank +from scipp.testing import assert_identical + +_COLUMNS = ('p', 'x', 'y', 'z', 'vx', 'vy', 'vz', 't') +_UNITS = ('counts', 'm', 'm', 'm', 'm/s', 'm/s', 'm/s', 's') +_EVENTS = np.array( + [ + [2.0, -100.0, 2.0, 3.0, 4.0, -5.0, 6.0, 0.2], + [0.0, 7.0, 8.0, 9.0, -10.0, 11.0, 12.0, 0.01], + [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], + [1.0, 0.1, 0.2, 0.3, 0.0, 0.0, 0.0, 0.03], + ] +) + + +def _read_events(filename, bank): + component = 'A_abs_logger' if bank is DetectorBank.detector_a else 'B_abs_logger' + with mcstastox.Read(filename.parent, filename.name) as reader: + return _load_events(reader, component) + + +def _write_mcstas(tmp_path, *, columns=_COLUMNS, events=_EVENTS): + filename = tmp_path / 'mccode.h5' + with h5py.File(filename, 'w') as file: + # Conflicting data here must not replace the selected component's events. + file.create_dataset('entry1/data/unrelated/events', data=np.ones((1, 8))) + simulation = file.create_group('entry1/simulation') + simulation.attrs['program'] = np.bytes_('McStas 3.5.32') + simulation.create_group('Param') + for index, bank in enumerate(('A', 'B'), start=1): + output = file.create_group( + f'entry1/instrument/components/{index:04d}_{bank}_abs_logger/' + 'output/events_list' + ) + output.attrs['variables'] = np.bytes_(' '.join(columns)) + output.create_dataset('events', data=events * index) + return filename + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_loads_selected_bank_weights_positions_and_times(tmp_path, bank): + filename = _write_mcstas(tmp_path) + other = '0002_B' if bank is DetectorBank.detector_a else '0001_A' + with h5py.File(filename, 'r+') as file: + del file[f'entry1/instrument/components/{other}_abs_logger/output'] + + events = _read_events(filename, bank) + + scale = 1 if bank is DetectorBank.detector_a else 2 + expected = _EVENTS * scale + assert events.sizes == {'event': len(_EVENTS)} + assert events.bins is None + assert not events.masks + assert_identical( + events.data, + sc.array( + dims=['event'], + values=expected[:, 0], + variances=expected[:, 0] ** 2, + unit='counts', + ), + ) + assert set(events.coords) == {'x', 'y', 'z', 't'} + for index, (name, unit) in enumerate(zip(_COLUMNS, _UNITS, strict=True)): + if name in events.coords: + assert_identical( + events.coords[name], + sc.array(dims=['event'], values=expected[:, index], unit=unit), + ) + + +def test_uses_column_names_instead_of_column_order(tmp_path): + order = [7, 5, 1, 0, 6, 3, 2, 4] + filename = _write_mcstas( + tmp_path, columns=tuple(_COLUMNS[i] for i in order), events=_EVENTS[:, order] + ) + actual = _read_events(filename, DetectorBank.detector_a) + filename = _write_mcstas(tmp_path) + expected = _read_events(filename, DetectorBank.detector_a) + assert_identical(actual, expected) + + +@pytest.mark.parametrize('columns', [_COLUMNS[:-1], (*_COLUMNS[:-1], 'p')]) +def test_rejects_missing_or_duplicate_columns(tmp_path, columns): + filename = _write_mcstas( + tmp_path, columns=columns, events=_EVENTS[:, : len(columns)] + ) + with pytest.raises(ValueError, match='columns'): + _read_events(filename, DetectorBank.detector_a) + + +def test_loads_empty_logger(tmp_path): + filename = _write_mcstas(tmp_path, events=np.empty((0, 8))) + events = _read_events(filename, DetectorBank.detector_a) + assert events.sizes == {'event': 0} + assert set(events.coords) == {'x', 'y', 'z', 't'} + assert events.variances is not None + + +def test_loads_float32_events(tmp_path): + values = _EVENTS.astype('float32') + values[0, 0] = 1e-30 + filename = _write_mcstas(tmp_path, events=values) + events = _read_events(filename, DetectorBank.detector_a) + assert events.dtype == sc.DType.float64 + np.testing.assert_array_equal(events.values, values[:, 0]) + np.testing.assert_array_equal(events.variances, values[:, 0].astype('float64') ** 2) + for index, column in enumerate(_COLUMNS[1:], start=1): + if column in events.coords: + np.testing.assert_array_equal( + events.coords[column].values, values[:, index] + ) diff --git a/packages/essdiffraction/tests/magic/raw_detector_test.py b/packages/essdiffraction/tests/magic/raw_detector_test.py new file mode 100644 index 000000000..f9c4cc5ad --- /dev/null +++ b/packages/essdiffraction/tests/magic/raw_detector_test.py @@ -0,0 +1,356 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 Scipp contributors (https://github.com/scipp) + +import h5py +import numpy as np +import pytest +import scipp as sc +from ess.magic import MagicMcStasWorkflow, mcstas +from ess.magic.types import DetectorBank, Filename, RawDetector, SampleRun +from scipp.testing import assert_identical + +from ess.reduce.unwrap import PulsePeriod + +_PULSE_PERIOD = sc.scalar(1 / 14, unit='s') + +# voxelization_of_mcstas_events_for_detector_a/b in magic-notebooks, +# mantid_worfkflow/dependencies/voxelization.py at +# da5844563df1a51442171c8178241879b52a06b0. A tilt -9.101 deg; B tilt +10 deg. +_REFERENCE = { + DetectorBank.detector_a: ( + [ + [0, -0.1, 1.2], + [0.01, 0.1, 1.1], + [0.7, -0.4, 1], + [1, -0.5, 0.8], + [-0.005, 0, 1.2], + ], + [189724, 94684, 208991, 271423, 188404], + ), + DetectorBank.detector_b: ( + [ + [0, 0, 1.2], + [-0.01, 0.02, 1.1], + [-0.7, -0.04, 1], + [-1, 0, 0.8], + [0.005, 0, 1.2], + ], + [542725, 517381, 548176, 563315, 542725], + ), +} + + +def _write_events(tmp_path, bank, xyz, *, weights=None, parameters=None, times=None): + xyz = np.asarray(xyz, dtype=float).reshape(-1, 3) + events = np.zeros((len(xyz), 8)) + events[:, 0] = 1.0 if weights is None else weights + events[:, 1:4] = xyz + events[:, 7] = np.arange(len(xyz))[::-1] * 0.03 if times is None else times + values = { + 'A_r1': 1.0, + 'A_section_length': 0.53, + 'A_casette_gamma': 1.05, + 'A_casette_omega': -9.101, + 'B_casette_omega': 10.0, + } | (parameters or {}) + filename = tmp_path / 'simulation.h5' + with h5py.File(filename, 'w') as file: + file.create_group('entry1/data') + simulation = file.create_group('entry1/simulation') + simulation.attrs['program'] = np.bytes_('McStas 3.5.32') + params = simulation.create_group('Param') + for name, value in values.items(): + params[name] = [np.bytes_(str(value))] + for index, selected in enumerate(DetectorBank, start=1): + label = 'A' if selected is DetectorBank.detector_a else 'B' + component = file.create_group( + f'entry1/instrument/components/{index:04d}_{label}_abs_logger' + ) + component['Position'] = [0.25, -0.5, 154.0] + component['Rotation'] = [[0, 0, -1], [0, 1, 0], [1, 0, 0]] + if selected is bank: + output = component.create_group('output/events_list') + output.attrs['variables'] = np.bytes_('p x y z vx vy vz t') + output['events'] = events + return filename, events + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_raw_detector_matches_reference_and_preserves_events_and_geometry( + tmp_path, bank +): + xyz, ids = _REFERENCE[bank] + filename, events = _write_events( + tmp_path, bank, [*xyz, xyz[0], [0, 0, 0]], weights=[2, 0, 3, 4, 5, 7, 11] + ) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + geometry.masks['disabled'] = geometry.coords['pixel_id'] == sc.scalar( + ids[0], unit=None + ) + original = geometry.copy(deep=True) + + actual = mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + + assert actual.sizes == geometry.sizes + assert_identical(geometry, original) + for name, coord in geometry.coords.items(): + assert_identical(actual.coords[name], coord) + assert_identical(actual.masks['disabled'], geometry.masks['disabled']) + assert actual.bins.size().values.sum() == 6 + expected_ids = np.array([*ids, ids[0]]) + for pixel_id in np.unique(expected_ids): + index = pixel_id - geometry.coords['pixel_id'].values[0] + pixel = actual['pixel_id', int(index)].value + rows = events[:-1][expected_ids == pixel_id] + np.testing.assert_array_equal(pixel.values, rows[:, 0]) + np.testing.assert_array_equal(pixel.variances, rows[:, 0] ** 2) + np.testing.assert_array_equal(pixel.coords['t'].values, rows[:, 7]) + assert pixel.unit == 'counts' + assert pixel.coords['t'].unit == 's' + assert set(pixel.coords) <= { + 'pixel_id', + 't', + 'event_time_offset', + 'event_time_zero', + } + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +@pytest.mark.parametrize( + 'xyz', [[], [[0, 0, 0], [0, 100, 1.2], [np.nan, 0, 1.2], [0, np.inf, 1.2]]] +) +def test_empty_and_rejected_events_retain_empty_pixels(tmp_path, bank, xyz): + filename, _ = _write_events(tmp_path, bank, xyz) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + actual = mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + assert actual.sizes == geometry.sizes + assert actual.bins.size().values.sum() == 0 + assert_identical(actual.coords['position'], geometry.coords['position']) + + +@pytest.mark.parametrize( + ('bank', 'top', 'bottom', 'expected'), + [ + (DetectorBank.detector_a, 0.252863, -0.722903, [3962, 2]), + (DetectorBank.detector_b, 0.051016, -0.051016, [493570, 491522]), + ], +) +def test_acceptance_includes_front_and_top_excludes_back_and_bottom( + tmp_path, bank, top, bottom, expected +): + filename, _ = _write_events( + tmp_path, + bank, + [[0, 0, 1], [0, 0, 1.53], [0, top, 1], [0, bottom, 1]], + parameters={'A_casette_omega': 0.0, 'B_casette_omega': 0.0}, + ) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + actual = mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + populated = actual.bins.size().values != 0 + np.testing.assert_array_equal( + actual.coords['pixel_id'].values[populated], sorted(expected) + ) + assert actual.bins.size().values.sum() == 2 + + +def test_geometry_missing_accepted_pixel_ids_raises(tmp_path): + bank = DetectorBank.detector_a + filename, _ = _write_events(tmp_path, bank, _REFERENCE[bank][0]) + wrong = mcstas.mcstas_detector_geometry(filename, DetectorBank.detector_b) + with pytest.raises(ValueError, match=r'pixel|geometry|detector'): + mcstas.load_mcstas_events(filename, bank, wrong, _PULSE_PERIOD) + + +def test_assignment_chunk_size_does_not_change_output(tmp_path, monkeypatch): + bank = DetectorBank.detector_a + filename, _ = _write_events(tmp_path, bank, _REFERENCE[bank][0]) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + expected = mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + monkeypatch.setattr(mcstas, '_ASSIGNMENT_CHUNK_SIZE', 2) + assert_identical( + mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD), expected + ) + + +def test_assignment_uses_recorded_a_dimensions_and_spacing(tmp_path): + # First/last cathode centres and first anode. 0.51 degrees selects counter 2 + # with the recorded spacing, but counter 1 with the nominal 1.05 degrees. + depth = np.array([0.01, 0.63]) + fraction = depth / 0.64 + top = 0.252863 + (0.416545 - 0.252863) * fraction + bottom = -0.722903 + (-1.077999 + 0.722903) * fraction + angle = np.deg2rad(0.51) + xyz = np.column_stack( + ( + (2 + depth) * np.sin(angle), + top + (bottom - top) * (0.5 / 128), + (2 + depth) * np.cos(angle), + ) + ) + bank = DetectorBank.detector_a + filename, _ = _write_events( + tmp_path, + bank, + xyz, + parameters={ + 'A_r1': 2.0, + 'A_section_length': 0.64, + 'A_casette_gamma': 1.0, + 'A_casette_omega': 0.0, + }, + ) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + actual = mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + np.testing.assert_array_equal( + actual.coords['pixel_id'].values[actual.bins.size().values != 0], [3, 476163] + ) + + +def test_assignment_rejects_angular_footprint_crossing_atan2_branch(tmp_path): + bank = DetectorBank.detector_a + filename, _ = _write_events( + tmp_path, bank, [[0, 0, 1.2]], parameters={'A_casette_gamma': 4.0} + ) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + with pytest.raises(ValueError, match='angular footprint'): + mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + + +@pytest.mark.parametrize('bank', [None, DetectorBank.detector_b]) +def test_workflow_computes_shared_raw_detector(tmp_path, bank): + selected = bank or DetectorBank.detector_a + filename, _ = _write_events(tmp_path, selected, _REFERENCE[selected][0]) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + if bank is not None: + workflow[DetectorBank] = bank + actual = workflow.compute(RawDetector[SampleRun]) + geometry = mcstas.mcstas_detector_geometry(filename, selected) + assert_identical( + actual, mcstas.load_mcstas_events(filename, selected, geometry, _PULSE_PERIOD) + ) + assert actual.bins.size().values.sum() == 5 + + +@pytest.mark.parametrize('bank', list(DetectorBank)) +def test_timing_preserves_arrival_times_at_frame_boundaries(tmp_path, bank): + period = 1 / 14 + times = np.array( + [ + -0.01, + 0.0, + np.nextafter(period, 0), + period, + np.nextafter(period, np.inf), + 0.15, + 0.22, + np.nextafter(7 * period, 0), + 7 * period, + np.nextafter(7 * period, np.inf), + np.nextafter(14 * period, 0), + 14 * period, + np.nextafter(14 * period, np.inf), + ] + ) + filename, _ = _write_events( + tmp_path, bank, [_REFERENCE[bank][0][0]] * len(times), times=times + ) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + workflow[DetectorBank] = bank + events = workflow.compute(RawDetector[SampleRun]).bins.constituents['data'] + + np.testing.assert_array_equal(events.coords['t'].values, times) + offset = events.coords['event_time_offset'] + zero = events.coords['event_time_zero'] + np.testing.assert_allclose( + offset.values, np.remainder(times, period), atol=1e-16, rtol=0 + ) + assert offset.unit == 's' + assert np.all((offset.values >= 0) & (offset.values < period)) + assert zero.dtype == sc.DType.datetime64 + assert zero.unit == 'ns' + # MAGIC's converter rounds pulse timestamps to nearest ns, rather than truncating. + np.testing.assert_array_equal( + zero.values.astype('int64'), + [ + -71428571, + 0, + 0, + 71428571, + 71428571, + 142857143, + 214285714, + 428571429, + 500000000, + 500000000, + 928571429, + 1000000000, + 1000000000, + ], + ) + np.testing.assert_allclose( + zero.values.astype('int64') * 1e-9 + offset.values, + times, + atol=0.5e-9, + rtol=0, + ) + + +def test_workflow_accepts_integer_millisecond_pulse_period(tmp_path): + bank = DetectorBank.detector_a + times = [0.025, 0.05, 0.1, 0.125] + filename, _ = _write_events( + tmp_path, bank, [_REFERENCE[bank][0][0]] * len(times), times=times + ) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + workflow[PulsePeriod] = sc.scalar(50, unit='ms') + events = workflow.compute(RawDetector[SampleRun]).bins.constituents['data'] + np.testing.assert_allclose( + events.coords['event_time_offset'].values, + [0.025, 0.0, 0.0, 0.025], + atol=1e-17, + rtol=0, + ) + np.testing.assert_array_equal( + events.coords['event_time_zero'].values.astype('int64'), + [0, 50000000, 100000000, 100000000], + ) + np.testing.assert_array_equal(events.coords['t'].values, times) + + +@pytest.mark.parametrize('time', [np.nan, np.inf, -np.inf]) +def test_nonfinite_accepted_time_raises(tmp_path, time): + bank = DetectorBank.detector_a + filename, _ = _write_events(tmp_path, bank, [_REFERENCE[bank][0][0]], times=[time]) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + with pytest.raises(ValueError, match='finite'): + mcstas.load_mcstas_events(filename, bank, geometry, _PULSE_PERIOD) + + +def test_nonfinite_rejected_time_does_not_contaminate_timing(tmp_path): + bank = DetectorBank.detector_a + filename, _ = _write_events( + tmp_path, bank, [_REFERENCE[bank][0][0], [0, 0, 0]], times=[0.08, np.nan] + ) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + events = mcstas.load_mcstas_events( + filename, bank, geometry, _PULSE_PERIOD + ).bins.constituents['data'] + np.testing.assert_array_equal(events.coords['t'].values, [0.08]) + assert np.isfinite(events.coords['event_time_offset'].values).all() + assert not np.isnat(events.coords['event_time_zero'].values).any() + + +@pytest.mark.parametrize( + 'period', + [sc.scalar(value, unit='s') for value in (0.0, -0.1, np.nan, np.inf)] + + [sc.array(dims=['period'], values=[0.05, 0.1], unit='s')], +) +def test_invalid_pulse_period_raises(tmp_path, period): + bank = DetectorBank.detector_a + filename, _ = _write_events(tmp_path, bank, [_REFERENCE[bank][0][0]]) + geometry = mcstas.mcstas_detector_geometry(filename, bank) + with pytest.raises(ValueError, match=r'(?i)period'): + mcstas.load_mcstas_events(filename, bank, geometry, period)