ess.bifrost.io.sqw.save_sqw#

ess.bifrost.io.sqw.save_sqw(path, events, *, bin_sizes, energy_bins, beamline, measurement, sample, pulse_period, gravity)[source]#

Save events recorded at BIFROST to an SQW file.

The files written by this function can be read by Horace for further processing. For details on the file format, see the documentation for Horace as well as the SQW developer guide in ScippNeutron.

The input to this function should not yet contain inelastic coordinates like ‘energy_transfer’ or ‘sample_table_momentum_transfer’. Instead, save_sqw histograms the events according to detector number, experiment setting, and incident energy and computes inelastic coordinates on that histogram. This is done for consistency with Horace.

The data is encoded as a 4-dimensional array, and Horace calls the dimensions u1 ... u4. The first three correspond to the three dimensions of $vec{Q}$ and the u4 corresponds to energy transfer. Horace supports customizable projections onto the cardinal axes $Q_x, Q_y, Q_z$, but the implementation here has hard-coded (Qx, Qy, Qz) = (u1, u2, u3), however, you need to express the binning in terms of the u’s.

Note

This function requires large amounts of memory to construct intermediate arrays and fill those with null observations.

Parameters:

  • path (types.OutFilename (str)) – Path of the file to write.

  • events (IncidentEnergyDetector[ess.reduce.nexus.types.SampleRun (int)]) – Binned data array with shape (*logical, "a3", "a4") where logical is any number of logical detector dimensions (e.g., arc, tube). Must have an "incident_energy" event coordinate.

  • bin_sizes (types.SQWBinSizes (dict)) – Sizes of the output ‘image’ bins. The data will be ordered based on these bins, but it is possible to change the binning later in Horace. E.g., {'u1': 50, 'u2': 50, 'u3': 50, 'u4': 50}.

  • energy_bins (types.EnergyBins (scipp.Variable)) – Bin edges or number of bins for (incident) energy. The events are histogrammed according to these bins, so this determines the final energy resolution that is available in Horace. Should typically be larger than bin_sizes['energy_transfer'].

  • beamline (Beamline[NewType]) – Beamline metadata.

  • measurement (Measurement[NewType]) – Measurement metadata.

  • sample (SqwIXSample) – Sample metadata in SQW format.

  • pulse_period (ess.reduce.time_of_flight.lut.PulsePeriod (scipp.Variable)) – Pulse period of the neutron source.

  • gravity (ess.reduce.nexus.types.GravityVector (scipp.Variable)) – Vector indicating the direction of gravity. Used to define the lab coordinate system. See also ess.spectroscopy.indirect.conversion.rotate_to_sample_table_momentum_transfer().

Return type:

None

See also

scippneutron.io.sqw

For low-level SQW I/O and the underlying implementation of save_sqw.