From 8162bb985546d64417719c0296f8a2406ab48d40 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Fri, 16 Oct 2026 01:03:07 +0200 Subject: [PATCH 1/8] feat(magic): add raw McStas event reader --- .../docs/api-reference/index.md | 2 + .../docs/user-guide/magic/index.md | 34 +++++ .../essdiffraction/src/ess/magic/__init__.py | 3 +- .../essdiffraction/src/ess/magic/mcstas.py | 68 ++++++++++ .../essdiffraction/src/ess/magic/types.py | 9 ++ .../essdiffraction/src/ess/magic/workflow.py | 15 +++ .../essdiffraction/tests/magic/mcstas_test.py | 124 ++++++++++++++++++ 7 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 packages/essdiffraction/src/ess/magic/mcstas.py create mode 100644 packages/essdiffraction/tests/magic/mcstas_test.py 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..eee2c0795 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -2,3 +2,37 @@ MAGIC — **Mag**netism Single-Crystal Diffractometer — is an ESS polarised time-of-flight single-crystal diffractometer for studying magnetic structures. + +## Reading McStas simulations + +`MagicMcStasWorkflow` currently reads raw events from one MAGIC absorption logger. +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, RawMcStasEvents, SampleRun + +workflow = MagicMcStasWorkflow() +workflow[Filename[SampleRun]] = 'simulation.h5' +events = workflow.compute(RawMcStasEvents[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 is a flat Scipp DataArray with an `event` dimension: + +| Field | Meaning | Unit | +| --- | --- | --- | +| Data | Original simulation weight `p` | `counts` (weighted-count convention) | +| Variances | `p**2`, assuming independent rows | `counts**2` | +| `x`, `y`, `z` | Absorption position in the logger's local frame | `m` | +| `vx`, `vy`, `vz` | Velocity in the logger's local frame | `m/s` | +| `t` | Original McStas arrival time | `s` | + +Weights are not normalized to an absolute count rate. +The variance convention matches the MAGIC Mantid converter, but does not represent correlations between rows introduced by McStas splitting. +Row order and zero-weight rows are preserved. +The reader does not apply detector acceptance cuts, assign pixels, correct times, or calculate wavelength. +These operations will be added as separate providers. 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..c79426bb7 --- /dev/null +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 Scipp contributors (https://github.com/scipp) +"""Read weighted events from MAGIC McStas absorption loggers.""" + +from pathlib import Path + +import mcstastox +import scipp as sc + +from .types import DetectorBank, Filename, RawMcStasEvents, RunType + +__all__ = ['load_mcstas_events'] + +_COORDINATE_UNITS = { + 'x': 'm', + 'y': 'm', + 'z': 'm', + 'vx': 'm/s', + 'vy': 'm/s', + 'vz': 'm/s', + 't': 's', +} + + +def load_mcstas_events( + filename: Filename[RunType], bank: DetectorBank +) -> RawMcStasEvents[RunType]: + """Read all rows of the selected bank's McStas absorption logger. + + The data contains the unnormalized simulation weights ``p``, using ``counts`` + as a weighted-count convention, not an absolute count rate. Variances are + ``p**2``, as in the MAGIC Mantid converter and other ESS McStas readers. + This assumes independent rows; correlations from McStas splitting are not + represented. + + Coordinates ``x``, ``y``, ``z`` (m) and ``vx``, ``vy``, ``vz`` (m/s) are in + the logger's local frame. ``t`` (s) is the original McStas arrival time, + without an offset or pulse folding. Row order and zero weights are retained. + No detector acceptance cuts, pixel assignment, or normalization are applied. + + The selected logger is loaded in full into memory. + """ + component = { + DetectorBank.detector_a: 'A_abs_logger', + DetectorBank.detector_b: 'B_abs_logger', + }[bank] + filename = Path(filename) + with mcstastox.Read(filename.parent, filename.name) as reader: + columns = reader.get_component_variables(component).split() + expected = ['p', *_COORDINATE_UNITS] + 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=expected, 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 RawMcStasEvents[RunType]( + sc.DataArray( + data, + coords={ + name: sc.array(dims=['event'], values=values.pop(name), unit=unit) + for name, unit in _COORDINATE_UNITS.items() + }, + ) + ) diff --git a/packages/essdiffraction/src/ess/magic/types.py b/packages/essdiffraction/src/ess/magic/types.py index 20dcb89c8..600e62862 100644 --- a/packages/essdiffraction/src/ess/magic/types.py +++ b/packages/essdiffraction/src/ess/magic/types.py @@ -4,6 +4,7 @@ from enum import Enum from typing import NewType +import sciline as sl import scipp as sc from ess.reduce.nexus.types import Filename, RawDetector, RunType, SampleRun @@ -19,6 +20,14 @@ class DetectorBank(Enum): detector_b = 'detector_b' +class RawMcStasEvents(sl.Scope[RunType, sc.DataArray], sc.DataArray): + """Flat weighted absorption-logger rows before geometry or timing corrections. + + Coordinates retain the McStas logger's local frame and original arrival time. + These events have not been assigned to detector pixels. + """ + + class PolarizationState(Enum): up = 'up' down = 'down' diff --git a/packages/essdiffraction/src/ess/magic/workflow.py b/packages/essdiffraction/src/ess/magic/workflow.py index b948ec378..1920e40a8 100644 --- a/packages/essdiffraction/src/ess/magic/workflow.py +++ b/packages/essdiffraction/src/ess/magic/workflow.py @@ -5,7 +5,9 @@ from ess.reduce.nexus.types import DetectorBankSizes +from . import mcstas from .beamline import DETECTOR_BANK_SIZES +from .types import DetectorBank, RunType, SampleRun default_parameters = { DetectorBankSizes: DETECTOR_BANK_SIZES, @@ -21,3 +23,16 @@ def MagicWorkflow() -> sl.Pipeline: pipeline is developed. """ return sl.Pipeline(providers=(), params=default_parameters) + + +def MagicMcStasWorkflow() -> sl.Pipeline: + """Workflow for reading raw MAGIC McStas events, with detector bank A by default. + + Currently provides only ``RawMcStasEvents[RunType]``. Geometry and reduction + providers are not yet included. + """ + return sl.Pipeline( + providers=(mcstas.load_mcstas_events,), + constraints={RunType: [SampleRun]}, + params={DetectorBank: DetectorBank.detector_a}, + ) diff --git a/packages/essdiffraction/tests/magic/mcstas_test.py b/packages/essdiffraction/tests/magic/mcstas_test.py new file mode 100644 index 000000000..c2054b8f0 --- /dev/null +++ b/packages/essdiffraction/tests/magic/mcstas_test.py @@ -0,0 +1,124 @@ +# 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 load_mcstas_events +from ess.magic.types import DetectorBank, Filename, RawMcStasEvents, SampleRun +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 _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_only_selected_bank_and_preserves_raw_events(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 = load_mcstas_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) == set(_COLUMNS[1:]) + for index, (name, unit) in enumerate(zip(_COLUMNS, _UNITS, strict=True)): + if name != 'p': + 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 = load_mcstas_events(filename, DetectorBank.detector_a) + filename = _write_mcstas(tmp_path) + expected = load_mcstas_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'): + load_mcstas_events(filename, DetectorBank.detector_a) + + +def test_loads_empty_logger(tmp_path): + filename = _write_mcstas(tmp_path, events=np.empty((0, 8))) + events = load_mcstas_events(filename, DetectorBank.detector_a) + assert events.sizes == {'event': 0} + assert set(events.coords) == set(_COLUMNS[1:]) + 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 = load_mcstas_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): + np.testing.assert_array_equal(events.coords[column].values, values[:, index]) + + +@pytest.mark.parametrize('bank', [None, DetectorBank.detector_b]) +def test_workflow_computes_raw_sample_events(tmp_path, bank): + filename = _write_mcstas(tmp_path) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + if bank is not None: + workflow[DetectorBank] = bank + actual = workflow.compute(RawMcStasEvents[SampleRun]) + expected = load_mcstas_events(filename, bank or DetectorBank.detector_a) + assert_identical(actual, expected) From 9b32255eece260e8af698a4ad89f25b78dfc230b Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Mon, 19 Oct 2026 09:37:29 +0200 Subject: [PATCH 2/8] feat(magic): add McStas detector geometry provider Construct bank A/B pixel IDs and positions independently of event loading. Reuse the common EmptyDetector type and McStasToX placement transform, with the MAGIC reference shared-plane cassette geometry. Add reference-coordinate, placement, metadata-validation, and workflow tests, plus user-guide documentation. --- .../docs/user-guide/magic/index.md | 29 ++- .../essdiffraction/src/ess/magic/mcstas.py | 122 +++++++++++- .../essdiffraction/src/ess/magic/types.py | 11 +- .../essdiffraction/src/ess/magic/workflow.py | 8 +- .../tests/magic/geometry_test.py | 185 ++++++++++++++++++ 5 files changed, 340 insertions(+), 15 deletions(-) create mode 100644 packages/essdiffraction/tests/magic/geometry_test.py diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index eee2c0795..dc1e32a84 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -5,8 +5,8 @@ time-of-flight single-crystal diffractometer for studying magnetic structures. ## Reading McStas simulations -`MagicMcStasWorkflow` currently reads raw events from one MAGIC absorption logger. -It loads every row of the selected bank into memory, so large simulations require substantial RAM. +`MagicMcStasWorkflow` reads raw events from one MAGIC absorption logger and can independently construct its detector geometry. +Raw-event loading reads every row of the selected bank into memory, so large simulations require substantial RAM. ```python from ess.magic import MagicMcStasWorkflow @@ -36,3 +36,28 @@ The variance convention matches the MAGIC Mantid converter, but does not represe Row order and zero-weight rows are preserved. The reader does not apply detector acceptance cuts, assign pixels, correct times, or calculate wavelength. These operations will be added as separate providers. + +## Detector geometry + +Compute the selected bank's geometry without loading its event data: + +```python +from ess.magic.types import EmptyDetector + +detector = 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 global McStas frame. +Bank A has IDs 1–491520; bank B has IDs 491521–622592. +The geometry uses the Mantid workflow's cassette model and its default shared-plane convention: +the two counters of each cassette share the same pixel-centre positions. + +Bank A uses the simulation's `A_r1`, `A_section_length`, `A_casette_gamma`, and `A_casette_omega` parameters. +Bank B uses the reference model's fixed radius, length, spacing and channel counts, and requires `B_casette_omega`. +Both banks require their absorption logger's position and rotation. +Missing parameters are not replaced with defaults. + +For comparison with Mantid's sample-centred instrument definition, subtract the global sample position from these pixel positions. +Mantid fixes bank A's radius, length and spacing to 1 m, 0.53 m and 1.05 degrees; comparisons with other values require adapting the reference model. +This provider constructs geometry only; assigning the raw events to these pixels is a separate step. diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py index c79426bb7..828a6dc04 100644 --- a/packages/essdiffraction/src/ess/magic/mcstas.py +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -1,15 +1,21 @@ # SPDX-License-Identifier: BSD-3-Clause # Copyright (c) 2026 Scipp contributors (https://github.com/scipp) -"""Read weighted events from MAGIC McStas absorption loggers.""" +"""Read weighted events and detector geometry from MAGIC McStas simulations.""" from pathlib import Path import mcstastox +import numpy as np import scipp as sc -from .types import DetectorBank, Filename, RawMcStasEvents, RunType +from .types import DetectorBank, EmptyDetector, Filename, RawMcStasEvents, RunType -__all__ = ['load_mcstas_events'] +__all__ = ['load_mcstas_events', 'mcstas_detector_geometry'] + +_LOGGERS = { + DetectorBank.detector_a: 'A_abs_logger', + DetectorBank.detector_b: 'B_abs_logger', +} _COORDINATE_UNITS = { 'x': 'm', @@ -40,10 +46,7 @@ def load_mcstas_events( The selected logger is loaded in full into memory. """ - component = { - DetectorBank.detector_a: 'A_abs_logger', - DetectorBank.detector_b: 'B_abs_logger', - }[bank] + component = _LOGGERS[bank] filename = Path(filename) with mcstastox.Read(filename.parent, filename.name) as reader: columns = reader.get_component_variables(component).split() @@ -66,3 +69,108 @@ def load_mcstas_events( }, ) ) + + +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 + + +def mcstas_detector_geometry( + filename: Filename[RunType], bank: DetectorBank +) -> EmptyDetector[RunType]: + """Construct pixel IDs and positions without reading detector events. + + Uses the cassette model of the MAGIC Mantid workflow's ``voxelization.py`` + and its IDF's default ``pairs=plane`` convention: both counters in a cassette + share the central absorption plane. IDs increase with counter first, then + anode, then cathode. Positions are in the global McStas 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. The selected absorption logger supplies placement. + + Mantid currently fixes A's radius, length and spacing to their nominal + values; agreement with that reference requires those same values. + """ + component = _LOGGERS[bank] + filename = Path(filename) + with mcstastox.Read(filename.parent, filename.name) as reader: + translation, rotation = reader.get_component_placement(component) + if ( + translation.shape != (3,) + or not np.all(np.isfinite(translation)) + or rotation.shape != (3, 3) + or not np.all(np.isfinite(rotation)) + or not np.allclose(rotation @ rotation.T, np.eye(3), rtol=0, atol=1e-10) + or not np.isclose(np.linalg.det(rotation), 1.0, rtol=0, atol=1e-10) + ): + raise ValueError( + f'{component} must have a finite position and proper rotation.' + ) + + 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) + else: + 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) + 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.' + ) + + cathodes = 32 + index = np.arange(2 * cassettes * anodes * cathodes) + counter = index % (2 * cassettes) + anode = (index // (2 * cassettes)) % anodes + cathode = index // (2 * cassettes * anodes) + fraction = (cathode + 0.5) / cathodes + depth = length * fraction + gamma = (counter // 2) * np.deg2rad(spacing) + tilt = np.deg2rad(tilt) + upper = top[0] + (top[1] - top[0]) * fraction + lower = bottom[0] + (bottom[1] - bottom[0]) * fraction + local = np.column_stack( + ( + radius * np.sin(gamma) + depth * np.sin(gamma + tilt), + upper + (lower - upper) * (anode + 0.5) / anodes, + radius * np.cos(gamma) + depth * np.cos(gamma + tilt), + ) + ) + # Reuse McStasToX's row-vector placement convention, as FREIA does. + position = reader.transform(local, component) + + pixel_id = sc.arange( + 'pixel_id', first_id, 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'), + }, + ) + ) diff --git a/packages/essdiffraction/src/ess/magic/types.py b/packages/essdiffraction/src/ess/magic/types.py index 600e62862..8d44b60eb 100644 --- a/packages/essdiffraction/src/ess/magic/types.py +++ b/packages/essdiffraction/src/ess/magic/types.py @@ -7,8 +7,15 @@ import sciline as sl 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 1920e40a8..79f37f819 100644 --- a/packages/essdiffraction/src/ess/magic/workflow.py +++ b/packages/essdiffraction/src/ess/magic/workflow.py @@ -26,13 +26,13 @@ def MagicWorkflow() -> sl.Pipeline: def MagicMcStasWorkflow() -> sl.Pipeline: - """Workflow for reading raw MAGIC McStas events, with detector bank A by default. + """Workflow for MAGIC McStas events and geometry, with detector bank A by default. - Currently provides only ``RawMcStasEvents[RunType]``. Geometry and reduction - providers are not yet included. + Provides ``RawMcStasEvents[RunType]`` and ``EmptyDetector[RunType]`` independently. + Event assignment and reduction providers are not yet included. """ return sl.Pipeline( - providers=(mcstas.load_mcstas_events,), + providers=(mcstas.load_mcstas_events, mcstas.mcstas_detector_geometry), constraints={RunType: [SampleRun]}, params={DetectorBank: DetectorBank.detector_a}, ) diff --git a/packages/essdiffraction/tests/magic/geometry_test.py b/packages/essdiffraction/tests/magic/geometry_test.py new file mode 100644 index 000000000..10b0ce1f7 --- /dev/null +++ b/packages/essdiffraction/tests/magic/geometry_test.py @@ -0,0 +1,185 @@ +# 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( + 'placement', + [{'position': [0.0, np.nan, 0.0]}, {'rotation': np.diag([-1.0, 1.0, 1.0])}], +) +def test_geometry_rejects_invalid_placement(tmp_path, placement): + filename = _write_geometry(tmp_path, **placement) + with pytest.raises(ValueError, match='finite position and proper rotation'): + 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) From 770ab451388cb3d1803825b8d63380fc6cb7e170 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 13:23:04 +0100 Subject: [PATCH 3/8] address review --- packages/essdiffraction/docs/user-guide/magic/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index dc1e32a84..6a94d0254 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -60,4 +60,3 @@ Missing parameters are not replaced with defaults. For comparison with Mantid's sample-centred instrument definition, subtract the global sample position from these pixel positions. Mantid fixes bank A's radius, length and spacing to 1 m, 0.53 m and 1.05 degrees; comparisons with other values require adapting the reference model. -This provider constructs geometry only; assigning the raw events to these pixels is a separate step. From 339801b1f7260c8bf57f138d05f462b45f0a23a9 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 13:24:31 +0100 Subject: [PATCH 4/8] address review --- .../essdiffraction/docs/user-guide/magic/index.md | 8 +------- packages/essdiffraction/src/ess/magic/mcstas.py | 13 +++++-------- 2 files changed, 6 insertions(+), 15 deletions(-) diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index 6a94d0254..27e45bece 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -48,15 +48,9 @@ detector = 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 global McStas frame. +and a `position` coordinate in metres in the common simulation frame. Bank A has IDs 1–491520; bank B has IDs 491521–622592. -The geometry uses the Mantid workflow's cassette model and its default shared-plane convention: -the two counters of each cassette share the same pixel-centre positions. - Bank A uses the simulation's `A_r1`, `A_section_length`, `A_casette_gamma`, and `A_casette_omega` parameters. Bank B uses the reference model's fixed radius, length, spacing and channel counts, and requires `B_casette_omega`. Both banks require their absorption logger's position and rotation. Missing parameters are not replaced with defaults. - -For comparison with Mantid's sample-centred instrument definition, subtract the global sample position from these pixel positions. -Mantid fixes bank A's radius, length and spacing to 1 m, 0.53 m and 1.05 degrees; comparisons with other values require adapting the reference model. diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py index 828a6dc04..2db9e31cc 100644 --- a/packages/essdiffraction/src/ess/magic/mcstas.py +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -86,19 +86,16 @@ def mcstas_detector_geometry( ) -> EmptyDetector[RunType]: """Construct pixel IDs and positions without reading detector events. - Uses the cassette model of the MAGIC Mantid workflow's ``voxelization.py`` - and its IDF's default ``pairs=plane`` convention: both counters in a cassette - share the central absorption plane. IDs increase with counter first, then - anode, then cathode. Positions are in the global McStas frame, in metres. + 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. The selected absorption logger supplies placement. - - Mantid currently fixes A's radius, length and spacing to their nominal - values; agreement with that reference requires those same values. + by the reference model. """ component = _LOGGERS[bank] filename = Path(filename) From 21127c1184d417a663fcfba0d1ef3440fe75ca77 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 13:26:41 +0100 Subject: [PATCH 5/8] address review --- packages/essdiffraction/src/ess/magic/mcstas.py | 13 ------------- .../essdiffraction/tests/magic/geometry_test.py | 10 ---------- 2 files changed, 23 deletions(-) diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py index 2db9e31cc..bc273d97a 100644 --- a/packages/essdiffraction/src/ess/magic/mcstas.py +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -100,19 +100,6 @@ def mcstas_detector_geometry( component = _LOGGERS[bank] filename = Path(filename) with mcstastox.Read(filename.parent, filename.name) as reader: - translation, rotation = reader.get_component_placement(component) - if ( - translation.shape != (3,) - or not np.all(np.isfinite(translation)) - or rotation.shape != (3, 3) - or not np.all(np.isfinite(rotation)) - or not np.allclose(rotation @ rotation.T, np.eye(3), rtol=0, atol=1e-10) - or not np.isclose(np.linalg.det(rotation), 1.0, rtol=0, atol=1e-10) - ): - raise ValueError( - f'{component} must have a finite position and proper rotation.' - ) - parameters = reader.file['entry1/simulation/Param'] if bank is DetectorBank.detector_a: cassettes, anodes, first_id = 60, 128, 1 diff --git a/packages/essdiffraction/tests/magic/geometry_test.py b/packages/essdiffraction/tests/magic/geometry_test.py index 10b0ce1f7..2d75a2828 100644 --- a/packages/essdiffraction/tests/magic/geometry_test.py +++ b/packages/essdiffraction/tests/magic/geometry_test.py @@ -163,16 +163,6 @@ def test_geometry_rejects_invalid_parameters(tmp_path, name, value): mcstas_detector_geometry(filename, DetectorBank.detector_a) -@pytest.mark.parametrize( - 'placement', - [{'position': [0.0, np.nan, 0.0]}, {'rotation': np.diag([-1.0, 1.0, 1.0])}], -) -def test_geometry_rejects_invalid_placement(tmp_path, placement): - filename = _write_geometry(tmp_path, **placement) - with pytest.raises(ValueError, match='finite position and proper rotation'): - 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) From 08819410c6f184967c651cab2159132dbea15014 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 13:56:02 +0100 Subject: [PATCH 6/8] use `event_time_offset` --- .../docs/user-guide/magic/index.md | 15 +- .../essdiffraction/src/ess/magic/mcstas.py | 36 +++-- .../essdiffraction/src/ess/magic/types.py | 2 +- .../essdiffraction/src/ess/magic/workflow.py | 9 +- .../essdiffraction/tests/magic/mcstas_test.py | 132 ++++++++++++++++-- 5 files changed, 171 insertions(+), 23 deletions(-) diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index 27e45bece..9e28e0256 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -30,13 +30,26 @@ The result is a flat Scipp DataArray with an `event` dimension: | `x`, `y`, `z` | Absorption position in the logger's local frame | `m` | | `vx`, `vy`, `vz` | Velocity in the logger's local frame | `m/s` | | `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. The variance convention matches the MAGIC Mantid converter, but does not represent correlations between rows introduced by McStas splitting. Row order and zero-weight rows are preserved. -The reader does not apply detector acceptance cuts, assign pixels, correct times, or calculate wavelength. +The reader does not apply detector acceptance cuts, assign pixels, apply emission-time corrections, or calculate wavelength. These operations will be added as separate providers. +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: diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py index bc273d97a..5422df40c 100644 --- a/packages/essdiffraction/src/ess/magic/mcstas.py +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -8,6 +8,8 @@ import numpy as np import scipp as sc +from ess.reduce.unwrap import PulsePeriod + from .types import DetectorBank, EmptyDetector, Filename, RawMcStasEvents, RunType __all__ = ['load_mcstas_events', 'mcstas_detector_geometry'] @@ -29,7 +31,7 @@ def load_mcstas_events( - filename: Filename[RunType], bank: DetectorBank + filename: Filename[RunType], bank: DetectorBank, pulse_period: PulsePeriod ) -> RawMcStasEvents[RunType]: """Read all rows of the selected bank's McStas absorption logger. @@ -41,11 +43,16 @@ def load_mcstas_events( Coordinates ``x``, ``y``, ``z`` (m) and ``vx``, ``vy``, ``vz`` (m/s) are in the logger's local frame. ``t`` (s) is the original McStas arrival time, - without an offset or pulse folding. Row order and zero weights are retained. + retained for diagnostics. 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. Row order and zero weights are retained. No detector acceptance cuts, pixel assignment, or normalization are applied. The selected logger is loaded in full into memory. """ + 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.') component = _LOGGERS[bank] filename = Path(filename) with mcstastox.Read(filename.parent, filename.name) as reader: @@ -60,15 +67,22 @@ def load_mcstas_events( weights = values.pop('p') data = sc.array(dims=['event'], values=weights, variances=weights**2, unit='counts') del weights - return RawMcStasEvents[RunType]( - sc.DataArray( - data, - coords={ - name: sc.array(dims=['event'], values=values.pop(name), unit=unit) - for name, unit in _COORDINATE_UNITS.items() - }, - ) - ) + coords = { + name: sc.array(dims=['event'], values=values.pop(name), unit=unit) + for name, unit in _COORDINATE_UNITS.items() + } + time = coords['t'] + if not sc.isfinite(time).all().value: + raise ValueError('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) + coords['event_time_offset'] = offset + coords['event_time_zero'] = sc.datetime(0, unit='ns') + sc.round( + (time - offset).to(unit='ns') + ).to(dtype='int64') + return RawMcStasEvents[RunType](sc.DataArray(data, coords=coords)) def _geometry_parameter(parameters, name: str) -> float: diff --git a/packages/essdiffraction/src/ess/magic/types.py b/packages/essdiffraction/src/ess/magic/types.py index 8d44b60eb..d41d5df3e 100644 --- a/packages/essdiffraction/src/ess/magic/types.py +++ b/packages/essdiffraction/src/ess/magic/types.py @@ -28,7 +28,7 @@ class DetectorBank(Enum): class RawMcStasEvents(sl.Scope[RunType, sc.DataArray], sc.DataArray): - """Flat weighted absorption-logger rows before geometry or timing corrections. + """Flat weighted absorption-logger rows before pixel assignment. Coordinates retain the McStas logger's local frame and original arrival time. These events have not been assigned to detector pixels. diff --git a/packages/essdiffraction/src/ess/magic/workflow.py b/packages/essdiffraction/src/ess/magic/workflow.py index 79f37f819..fc85a038e 100644 --- a/packages/essdiffraction/src/ess/magic/workflow.py +++ b/packages/essdiffraction/src/ess/magic/workflow.py @@ -2,8 +2,10 @@ # 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 @@ -29,10 +31,15 @@ def MagicMcStasWorkflow() -> sl.Pipeline: """Workflow for MAGIC McStas events and geometry, with detector bank A by default. Provides ``RawMcStasEvents[RunType]`` and ``EmptyDetector[RunType]`` independently. + Event times include pulse-relative offsets and timestamps, retaining McStas + ``t`` for diagnostics. The default pulse period is 1/14 s. Event assignment and reduction providers are not yet included. """ return sl.Pipeline( providers=(mcstas.load_mcstas_events, mcstas.mcstas_detector_geometry), constraints={RunType: [SampleRun]}, - params={DetectorBank: DetectorBank.detector_a}, + params={ + DetectorBank: DetectorBank.detector_a, + PulsePeriod: sc.scalar(1 / 14, unit='s'), + }, ) diff --git a/packages/essdiffraction/tests/magic/mcstas_test.py b/packages/essdiffraction/tests/magic/mcstas_test.py index c2054b8f0..484df46c5 100644 --- a/packages/essdiffraction/tests/magic/mcstas_test.py +++ b/packages/essdiffraction/tests/magic/mcstas_test.py @@ -10,6 +10,10 @@ from ess.magic.types import DetectorBank, Filename, RawMcStasEvents, SampleRun from scipp.testing import assert_identical +from ess.reduce.unwrap import PulsePeriod + +_PULSE_PERIOD = sc.scalar(1 / 14, unit='s') + _COLUMNS = ('p', 'x', 'y', 'z', 'vx', 'vy', 'vz', 't') _UNITS = ('counts', 'm', 'm', 'm', 'm/s', 'm/s', 'm/s', 's') _EVENTS = np.array( @@ -47,7 +51,7 @@ def test_loads_only_selected_bank_and_preserves_raw_events(tmp_path, bank): with h5py.File(filename, 'r+') as file: del file[f'entry1/instrument/components/{other}_abs_logger/output'] - events = load_mcstas_events(filename, bank) + events = load_mcstas_events(filename, bank, _PULSE_PERIOD) scale = 1 if bank is DetectorBank.detector_a else 2 expected = _EVENTS * scale @@ -63,7 +67,7 @@ def test_loads_only_selected_bank_and_preserves_raw_events(tmp_path, bank): unit='counts', ), ) - assert set(events.coords) == set(_COLUMNS[1:]) + assert set(events.coords) == {*_COLUMNS[1:], 'event_time_offset', 'event_time_zero'} for index, (name, unit) in enumerate(zip(_COLUMNS, _UNITS, strict=True)): if name != 'p': assert_identical( @@ -77,9 +81,9 @@ def test_uses_column_names_instead_of_column_order(tmp_path): filename = _write_mcstas( tmp_path, columns=tuple(_COLUMNS[i] for i in order), events=_EVENTS[:, order] ) - actual = load_mcstas_events(filename, DetectorBank.detector_a) + actual = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) filename = _write_mcstas(tmp_path) - expected = load_mcstas_events(filename, DetectorBank.detector_a) + expected = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) assert_identical(actual, expected) @@ -89,14 +93,14 @@ def test_rejects_missing_or_duplicate_columns(tmp_path, columns): tmp_path, columns=columns, events=_EVENTS[:, : len(columns)] ) with pytest.raises(ValueError, match='columns'): - load_mcstas_events(filename, DetectorBank.detector_a) + load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) def test_loads_empty_logger(tmp_path): filename = _write_mcstas(tmp_path, events=np.empty((0, 8))) - events = load_mcstas_events(filename, DetectorBank.detector_a) + events = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) assert events.sizes == {'event': 0} - assert set(events.coords) == set(_COLUMNS[1:]) + assert set(events.coords) == {*_COLUMNS[1:], 'event_time_offset', 'event_time_zero'} assert events.variances is not None @@ -104,7 +108,7 @@ def test_loads_float32_events(tmp_path): values = _EVENTS.astype('float32') values[0, 0] = 1e-30 filename = _write_mcstas(tmp_path, events=values) - events = load_mcstas_events(filename, DetectorBank.detector_a) + events = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) 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) @@ -120,5 +124,115 @@ def test_workflow_computes_raw_sample_events(tmp_path, bank): if bank is not None: workflow[DetectorBank] = bank actual = workflow.compute(RawMcStasEvents[SampleRun]) - expected = load_mcstas_events(filename, bank or DetectorBank.detector_a) + expected = load_mcstas_events( + filename, bank or DetectorBank.detector_a, _PULSE_PERIOD + ) assert_identical(actual, expected) + + +@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), + ] + ) + values = np.zeros((len(times), 8)) + # The fixture scales bank B's rows by two. + values[:, 7] = times / (1 if bank is DetectorBank.detector_a else 2) + filename = _write_mcstas(tmp_path, events=values) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + workflow[DetectorBank] = bank + events = workflow.compute(RawMcStasEvents[SampleRun]) + + 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' + # Round 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): + times = [0.025, 0.05, 0.1, 0.125] + values = np.zeros((len(times), 8)) + values[:, 7] = times + filename = _write_mcstas(tmp_path, events=values) + workflow = MagicMcStasWorkflow() + workflow[Filename[SampleRun]] = filename + workflow[PulsePeriod] = sc.scalar(50, unit='ms') + events = workflow.compute(RawMcStasEvents[SampleRun]) + 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_arrival_time_raises(tmp_path, time): + values = _EVENTS.copy() + values[0, 7] = time + filename = _write_mcstas(tmp_path, events=values) + with pytest.raises(ValueError, match='finite'): + load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + + +@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): + filename = _write_mcstas(tmp_path) + with pytest.raises(ValueError, match=r'(?i)period'): + load_mcstas_events(filename, DetectorBank.detector_a, period) From 781d01dc6343eb4daa504a94add3cfa1192a0a32 Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 14:11:21 +0100 Subject: [PATCH 7/8] address review --- .../docs/user-guide/magic/index.md | 23 +- .../essdiffraction/src/ess/magic/mcstas.py | 294 ++++++++++----- .../essdiffraction/src/ess/magic/types.py | 9 - .../essdiffraction/src/ess/magic/workflow.py | 4 +- .../essdiffraction/tests/magic/mcstas_test.py | 163 ++------ .../tests/magic/raw_detector_test.py | 356 ++++++++++++++++++ 6 files changed, 591 insertions(+), 258 deletions(-) create mode 100644 packages/essdiffraction/tests/magic/raw_detector_test.py diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index 9e28e0256..304064d46 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -5,40 +5,37 @@ time-of-flight single-crystal diffractometer for studying magnetic structures. ## Reading McStas simulations -`MagicMcStasWorkflow` reads raw events from one MAGIC absorption logger and can independently construct its detector geometry. -Raw-event loading reads every row of the selected bank into memory, so large simulations require substantial RAM. +`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, RawMcStasEvents, SampleRun +from ess.magic.types import DetectorBank, Filename, RawDetector, SampleRun workflow = MagicMcStasWorkflow() workflow[Filename[SampleRun]] = 'simulation.h5' -events = workflow.compute(RawMcStasEvents[SampleRun]) +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 is a flat Scipp DataArray with an `event` dimension: +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 | | --- | --- | --- | -| Data | Original simulation weight `p` | `counts` (weighted-count convention) | +| Event data | Original simulation weight `p` | `counts` (weighted-count convention) | | Variances | `p**2`, assuming independent rows | `counts**2` | -| `x`, `y`, `z` | Absorption position in the logger's local frame | `m` | -| `vx`, `vy`, `vz` | Velocity in the logger's local frame | `m/s` | +| `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. The variance convention matches the MAGIC Mantid converter, but does not represent correlations between rows introduced by McStas splitting. -Row order and zero-weight rows are preserved. -The reader does not apply detector acceptance cuts, assign pixels, apply emission-time corrections, or calculate wavelength. -These operations will be added as separate providers. - +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: @@ -57,7 +54,7 @@ Compute the selected bank's geometry without loading its event data: ```python from ess.magic.types import EmptyDetector -detector = workflow.compute(EmptyDetector[SampleRun]) +geometry = workflow.compute(EmptyDetector[SampleRun]) ``` The result has a `pixel_id` dimension, integer pixel IDs as data and a coordinate, diff --git a/packages/essdiffraction/src/ess/magic/mcstas.py b/packages/essdiffraction/src/ess/magic/mcstas.py index 5422df40c..bef68aefb 100644 --- a/packages/essdiffraction/src/ess/magic/mcstas.py +++ b/packages/essdiffraction/src/ess/magic/mcstas.py @@ -2,6 +2,7 @@ # 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 @@ -10,10 +11,13 @@ from ess.reduce.unwrap import PulsePeriod -from .types import DetectorBank, EmptyDetector, Filename, RawMcStasEvents, RunType +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', @@ -23,66 +27,31 @@ 'x': 'm', 'y': 'm', 'z': 'm', - 'vx': 'm/s', - 'vy': 'm/s', - 'vz': 'm/s', 't': 's', } -def load_mcstas_events( - filename: Filename[RunType], bank: DetectorBank, pulse_period: PulsePeriod -) -> RawMcStasEvents[RunType]: - """Read all rows of the selected bank's McStas absorption logger. - - The data contains the unnormalized simulation weights ``p``, using ``counts`` - as a weighted-count convention, not an absolute count rate. Variances are - ``p**2``, as in the MAGIC Mantid converter and other ESS McStas readers. - This assumes independent rows; correlations from McStas splitting are not - represented. - - Coordinates ``x``, ``y``, ``z`` (m) and ``vx``, ``vy``, ``vz`` (m/s) are in - the logger's local frame. ``t`` (s) is the original McStas arrival time, - retained for diagnostics. 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. Row order and zero weights are retained. - No detector acceptance cuts, pixel assignment, or normalization are applied. - - The selected logger is loaded in full into memory. - """ - 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.') - component = _LOGGERS[bank] - filename = Path(filename) - with mcstastox.Read(filename.parent, filename.name) as reader: - columns = reader.get_component_variables(component).split() - expected = ['p', *_COORDINATE_UNITS] - 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=expected, component_name=component, filter_zeros=False - ) - +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 - coords = { - name: sc.array(dims=['event'], values=values.pop(name), unit=unit) - for name, unit in _COORDINATE_UNITS.items() - } - time = coords['t'] - if not sc.isfinite(time).all().value: - raise ValueError('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) - coords['event_time_offset'] = offset - coords['event_time_zero'] = sc.datetime(0, unit='ns') + sc.round( - (time - offset).to(unit='ns') - ).to(dtype='int64') - return RawMcStasEvents[RunType](sc.DataArray(data, coords=coords)) + 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: @@ -95,6 +64,62 @@ def _geometry_parameter(parameters, name: str) -> float: 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]: @@ -114,54 +139,32 @@ def mcstas_detector_geometry( component = _LOGGERS[bank] filename = Path(filename) with mcstastox.Read(filename.parent, filename.name) as reader: - 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) - else: - 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) - 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.' - ) - - cathodes = 32 - index = np.arange(2 * cassettes * anodes * cathodes) - counter = index % (2 * cassettes) - anode = (index // (2 * cassettes)) % anodes - cathode = index // (2 * cassettes * anodes) - fraction = (cathode + 0.5) / cathodes - depth = length * fraction - gamma = (counter // 2) * np.deg2rad(spacing) - tilt = np.deg2rad(tilt) - upper = top[0] + (top[1] - top[0]) * fraction - lower = bottom[0] + (bottom[1] - bottom[0]) * fraction + 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( ( - radius * np.sin(gamma) + depth * np.sin(gamma + tilt), - upper + (lower - upper) * (anode + 0.5) / anodes, - radius * np.cos(gamma) + depth * np.cos(gamma + tilt), + 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', first_id, first_id + len(index), unit=None, dtype='int32' + 'pixel_id', + model.first_id, + model.first_id + len(index), + unit=None, + dtype='int32', ) return EmptyDetector[RunType]( sc.DataArray( @@ -172,3 +175,106 @@ def mcstas_detector_geometry( }, ) ) + + +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 d41d5df3e..d5993f218 100644 --- a/packages/essdiffraction/src/ess/magic/types.py +++ b/packages/essdiffraction/src/ess/magic/types.py @@ -4,7 +4,6 @@ from enum import Enum from typing import NewType -import sciline as sl import scipp as sc from ess.reduce.nexus.types import ( @@ -27,14 +26,6 @@ class DetectorBank(Enum): detector_b = 'detector_b' -class RawMcStasEvents(sl.Scope[RunType, sc.DataArray], sc.DataArray): - """Flat weighted absorption-logger rows before pixel assignment. - - Coordinates retain the McStas logger's local frame and original arrival time. - These events have not been assigned to detector pixels. - """ - - class PolarizationState(Enum): up = 'up' down = 'down' diff --git a/packages/essdiffraction/src/ess/magic/workflow.py b/packages/essdiffraction/src/ess/magic/workflow.py index fc85a038e..24f651979 100644 --- a/packages/essdiffraction/src/ess/magic/workflow.py +++ b/packages/essdiffraction/src/ess/magic/workflow.py @@ -30,10 +30,10 @@ def MagicWorkflow() -> sl.Pipeline: def MagicMcStasWorkflow() -> sl.Pipeline: """Workflow for MAGIC McStas events and geometry, with detector bank A by default. - Provides ``RawMcStasEvents[RunType]`` and ``EmptyDetector[RunType]`` independently. + 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. - Event assignment and reduction providers are not yet included. """ return sl.Pipeline( providers=(mcstas.load_mcstas_events, mcstas.mcstas_detector_geometry), diff --git a/packages/essdiffraction/tests/magic/mcstas_test.py b/packages/essdiffraction/tests/magic/mcstas_test.py index 484df46c5..618c1b042 100644 --- a/packages/essdiffraction/tests/magic/mcstas_test.py +++ b/packages/essdiffraction/tests/magic/mcstas_test.py @@ -2,18 +2,14 @@ # 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 import MagicMcStasWorkflow -from ess.magic.mcstas import load_mcstas_events -from ess.magic.types import DetectorBank, Filename, RawMcStasEvents, SampleRun +from ess.magic.mcstas import _load_events +from ess.magic.types import DetectorBank from scipp.testing import assert_identical -from ess.reduce.unwrap import PulsePeriod - -_PULSE_PERIOD = sc.scalar(1 / 14, unit='s') - _COLUMNS = ('p', 'x', 'y', 'z', 'vx', 'vy', 'vz', 't') _UNITS = ('counts', 'm', 'm', 'm', 'm/s', 'm/s', 'm/s', 's') _EVENTS = np.array( @@ -26,6 +22,12 @@ ) +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: @@ -45,13 +47,13 @@ def _write_mcstas(tmp_path, *, columns=_COLUMNS, events=_EVENTS): @pytest.mark.parametrize('bank', list(DetectorBank)) -def test_loads_only_selected_bank_and_preserves_raw_events(tmp_path, bank): +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 = load_mcstas_events(filename, bank, _PULSE_PERIOD) + events = _read_events(filename, bank) scale = 1 if bank is DetectorBank.detector_a else 2 expected = _EVENTS * scale @@ -67,9 +69,9 @@ def test_loads_only_selected_bank_and_preserves_raw_events(tmp_path, bank): unit='counts', ), ) - assert set(events.coords) == {*_COLUMNS[1:], 'event_time_offset', 'event_time_zero'} + assert set(events.coords) == {'x', 'y', 'z', 't'} for index, (name, unit) in enumerate(zip(_COLUMNS, _UNITS, strict=True)): - if name != 'p': + if name in events.coords: assert_identical( events.coords[name], sc.array(dims=['event'], values=expected[:, index], unit=unit), @@ -81,9 +83,9 @@ def test_uses_column_names_instead_of_column_order(tmp_path): filename = _write_mcstas( tmp_path, columns=tuple(_COLUMNS[i] for i in order), events=_EVENTS[:, order] ) - actual = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + actual = _read_events(filename, DetectorBank.detector_a) filename = _write_mcstas(tmp_path) - expected = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + expected = _read_events(filename, DetectorBank.detector_a) assert_identical(actual, expected) @@ -93,14 +95,14 @@ def test_rejects_missing_or_duplicate_columns(tmp_path, columns): tmp_path, columns=columns, events=_EVENTS[:, : len(columns)] ) with pytest.raises(ValueError, match='columns'): - load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + _read_events(filename, DetectorBank.detector_a) def test_loads_empty_logger(tmp_path): filename = _write_mcstas(tmp_path, events=np.empty((0, 8))) - events = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + events = _read_events(filename, DetectorBank.detector_a) assert events.sizes == {'event': 0} - assert set(events.coords) == {*_COLUMNS[1:], 'event_time_offset', 'event_time_zero'} + assert set(events.coords) == {'x', 'y', 'z', 't'} assert events.variances is not None @@ -108,131 +110,12 @@ def test_loads_float32_events(tmp_path): values = _EVENTS.astype('float32') values[0, 0] = 1e-30 filename = _write_mcstas(tmp_path, events=values) - events = load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) + 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): - np.testing.assert_array_equal(events.coords[column].values, values[:, index]) - - -@pytest.mark.parametrize('bank', [None, DetectorBank.detector_b]) -def test_workflow_computes_raw_sample_events(tmp_path, bank): - filename = _write_mcstas(tmp_path) - workflow = MagicMcStasWorkflow() - workflow[Filename[SampleRun]] = filename - if bank is not None: - workflow[DetectorBank] = bank - actual = workflow.compute(RawMcStasEvents[SampleRun]) - expected = load_mcstas_events( - filename, bank or DetectorBank.detector_a, _PULSE_PERIOD - ) - assert_identical(actual, expected) - - -@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), - ] - ) - values = np.zeros((len(times), 8)) - # The fixture scales bank B's rows by two. - values[:, 7] = times / (1 if bank is DetectorBank.detector_a else 2) - filename = _write_mcstas(tmp_path, events=values) - workflow = MagicMcStasWorkflow() - workflow[Filename[SampleRun]] = filename - workflow[DetectorBank] = bank - events = workflow.compute(RawMcStasEvents[SampleRun]) - - 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' - # Round 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): - times = [0.025, 0.05, 0.1, 0.125] - values = np.zeros((len(times), 8)) - values[:, 7] = times - filename = _write_mcstas(tmp_path, events=values) - workflow = MagicMcStasWorkflow() - workflow[Filename[SampleRun]] = filename - workflow[PulsePeriod] = sc.scalar(50, unit='ms') - events = workflow.compute(RawMcStasEvents[SampleRun]) - 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_arrival_time_raises(tmp_path, time): - values = _EVENTS.copy() - values[0, 7] = time - filename = _write_mcstas(tmp_path, events=values) - with pytest.raises(ValueError, match='finite'): - load_mcstas_events(filename, DetectorBank.detector_a, _PULSE_PERIOD) - - -@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): - filename = _write_mcstas(tmp_path) - with pytest.raises(ValueError, match=r'(?i)period'): - load_mcstas_events(filename, DetectorBank.detector_a, period) + 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) From a09e0e1f0a8599a0fb96758becba94fc6750a2df Mon Sep 17 00:00:00 2001 From: Mridul Seth Date: Thu, 19 Nov 2026 14:31:01 +0100 Subject: [PATCH 8/8] address review --- packages/essdiffraction/docs/user-guide/magic/index.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/essdiffraction/docs/user-guide/magic/index.md b/packages/essdiffraction/docs/user-guide/magic/index.md index 304064d46..db0ea5955 100644 --- a/packages/essdiffraction/docs/user-guide/magic/index.md +++ b/packages/essdiffraction/docs/user-guide/magic/index.md @@ -27,14 +27,12 @@ pixel positions in the common simulation frame, and weighted events in each pixe | Field | Meaning | Unit | | --- | --- | --- | | Event data | Original simulation weight `p` | `counts` (weighted-count convention) | -| Variances | `p**2`, assuming independent rows | `counts**2` | | `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. -The variance convention matches the MAGIC Mantid converter, but does not represent correlations between rows introduced by McStas splitting. 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. @@ -60,7 +58,3 @@ 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. -Bank A uses the simulation's `A_r1`, `A_section_length`, `A_casette_gamma`, and `A_casette_omega` parameters. -Bank B uses the reference model's fixed radius, length, spacing and channel counts, and requires `B_casette_omega`. -Both banks require their absorption logger's position and rotation. -Missing parameters are not replaced with defaults.