From Mantid to Scipp#

Data types#

Workspaces#

Mantid workspaces are converted into Scipp data groups. Those data groups contain a number of entries converted from properties of the workspace and one entry called 'data' which holds the histogram or event data. The type of the latter depends on the type of workspace according to the following table.

Mantid	Scipp
`Workspace2D`	`DataArray`
`EventWorkspace`	`DataArray`
`WorkspaceSingleValue`	`DataArray`
`MDHistoWorkspace`	`DataArray`
`MDEventWorkspace`	`DataArray`
`TableWorkspace`	`Dataset`
`WorkspaceGroup`	`Dataset` (aligned dimensions), otherwise Python `list` or `dict`

Notes#

In many cases it may be desirable to use Dataset instead of DataArray. You can easily create a Dataset directly from a DataArray.
Scipp takes basic geometric information from Mantid’s instrument in the form of positions. Detector grouping by spectrum is respected. Upon conversion, Scipp will perform spherical coordinate averaging for the group based on the beam direction, this preserves the average scattering angle between a group of detectors and the spectra representing the group. This may yield slightly different detector and spectrum positions between what is natively stored in Mantid’s instrument and Scipp.
Run and Sample are copied over to scipp from any MatrixWorkspace derived Workspaces.
Scipp (or rather conversion to scipp) is currently still incomplete and does not carry over all information from a workspace.

Other#

Mantid	Scipp
`DetectorInfo`	`Dataset`

Concepts#

Mantid’s MatrixWorkspace (the common base class of Workspace2D and EventWorkspace) uses the terms “X”, “Y”, and “E” to refer to one of its axes, the data values, and the uncertainties.

Mantid stores standard-deviations in “E”, whereas scipp stores variances.
Typically Mantid’s “X” is the coordinate axis for the time-of-flight dimension, or the dimension derived from it.
Mantid’s “Y” is not the axis for the second dimension, but the data.
Mantid’s “X”, “Y”, and “E” are 1-D arrays of 1-D arrays, whereas scipp stores 2-D (or higher) arrays, if applicable.

We have the following “equivalence”:

Mantid	Scipp	comment
`ws.readY(i)`	`data.values`
`ws.readE(i)`	`data.variances`	square former, or `sqrt` latter
`ws.readX(i)`	`data.coords['tof'].values`	dimension label may vary
`ws.getAxis(0).getUnit()`	`data.coords['tof'].unit`	dimension label may vary
`ws.getAxis(1)`	`data.coords['spectrum']`	dimension label may vary

Here i is the index along the second axis (axis index 1). Mantid’s readX, readY, and readE always return 1-D arrays, whereas the values and variances properties in scipp return a multi-dimensional array. That is, there is no actual equivalence.

Algorithms#

Notes#

In Mantid a Python variable referencing a workspace is under the hood a global variable. Unless specified otherwise the variable name is the name of the workspace in the AnalysisDataService. For marginally more clarity, the examples in the following therefore use the string-based syntax for specifying output workspaces. In scipp there is no such limitation and everything behaves just like normal variables in Python.
Unless stated otherwise, the following code examples assume datasets or data arrays have 'tof' for what Mantid calls “X” and 'spectrum' why Mantid calls “Y” or “spectrum axis”.
There is no strict 1:1 equivalence between Mantid workspaces and functionality in scipp. The examples below give the most common examples, but in many cases exceptions apply and detailed behavior may differ. If in doubt, consult the Mantid algorithm documentation and the scipp documentation.

[1]:

import mantid.simpleapi as mantid
import scipp as sc
import scippneutron as scn
import numpy as np

FrameworkManager-[Notice] Welcome to Mantid 6.8.0
FrameworkManager-[Notice] Please cite: http://dx.doi.org/10.1016/j.nima.2014.07.029 and this release: http://dx.doi.org/10.5286/Software/Mantid6.8
CheckMantidVersion-[Notice] A new version of Mantid(6.9.0) is available for download from https://download.mantidproject.org
DownloadInstrument-[Notice] All instrument definitions up to date

Test Data#

[2]:

input_bin_edges = mantid.CreateSampleWorkspace()
input_point_data = mantid.ConvertToPointData(input_bin_edges)
a_mantid = mantid.ExtractSpectra(
    input_point_data, StartWorkspaceIndex=0, EndWorkspaceIndex=10
)
b_mantid = mantid.ExtractSpectra(
    input_point_data, StartWorkspaceIndex=10, EndWorkspaceIndex=20
)
a_scipp = scn.from_mantid(a_mantid)
b_scipp = scn.from_mantid(b_mantid)

CreateSampleWorkspace-[Notice] CreateSampleWorkspace started
CreateSampleWorkspace-[Notice] CreateSampleWorkspace successful, Duration 0.00 seconds
ConvertToPointData-[Notice] ConvertToPointData started
ConvertToPointData-[Notice] ConvertToPointData successful, Duration 0.00 seconds
ExtractSpectra-[Notice] ExtractSpectra started
ExtractSpectra-[Notice] ExtractSpectra successful, Duration 0.00 seconds
ExtractSpectra-[Notice] ExtractSpectra started
ExtractSpectra-[Notice] ExtractSpectra successful, Duration 0.00 seconds

Generic algorithms#

CloneWorkspace#

[3]:

cloned = mantid.CloneWorkspace(InputWorkspace=input_point_data, OutputWorkspace='copy')
cloned

CloneWorkspace-[Notice] CloneWorkspace started
CloneWorkspace-[Notice] CloneWorkspace successful, Duration 0.00 seconds

[3]:

Workspace2D
Title: Test Workspace
Histograms: 200
Bins: 100
Data points
X axis: Time-of-flight / microsecond
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp:

[4]:

copy = a_scipp.copy()
copy

[4]:

scipp.DataGroup

(spectrum: 11, tof: 100)

data
scipp
DataArray
(spectrum: 11, tof: 100)
float64
counts
0.3, 0.3, ..., 0.3, 0.3
sample
scipp
Variable
()
PyObject
<mantid.api._api.Sample object at 0x7f9b21d80580>
instrument_name
str
()
basic_rect
run_title
scipp
Variable
()
string
𝟙
Test Workspace
start_time
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
end_time
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00
run_start
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
run_end
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00

DeleteWorkspace#

[5]:

mantid.DeleteWorkspace(Workspace=cloned)

DeleteWorkspace-[Notice] DeleteWorkspace started

DeleteWorkspace-[Notice] DeleteWorkspace successful, Duration 0.00 seconds

Equivalent in scipp:

[6]:

del copy

ExtractSingleSpectrum#

[7]:

spec = mantid.ExtractSingleSpectrum(
    InputWorkspace=input_point_data, OutputWorkspace='spec', WorkspaceIndex=7
)

ExtractSingleSpectrum-[Notice] ExtractSingleSpectrum started

Equivalent in scipp:

[8]:

spec = a_scipp['spectrum', 7]

ExtractSingleSpectrum-[Notice] ExtractSingleSpectrum successful, Duration 0.00 seconds

If an actual copy is required use:

[9]:

spec = a_scipp['spectrum', 7].copy()

ExtractSpectra / CropWorkspace#

[10]:

mantid.ExtractSpectra(
    InputWorkspace=input_point_data,
    OutputWorkspace='spectra',
    StartWorkspaceIndex=1,
    EndWorkspaceIndex=4,
)

ExtractSpectra-[Notice] ExtractSpectra started
ExtractSpectra-[Notice] ExtractSpectra successful, Duration 0.00 seconds

[10]:

Workspace2D
Title: Test Workspace
Histograms: 4
Bins: 100
Data points
X axis: Time-of-flight / microsecond
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp:

[11]:

a_scipp['spectrum', 1:5]

[11]:

scipp.DataGroup

(spectrum: 4, tof: 100)

data
scipp
DataArray
(spectrum: 4, tof: 100)
float64
counts
0.3, 0.3, ..., 0.3, 0.3
sample
scipp
Variable
()
PyObject
<mantid.api._api.Sample object at 0x7f9b21d82c70>
instrument_name
str
()
basic_rect
run_title
scipp
Variable
()
string
𝟙
Test Workspace
start_time
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
end_time
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00
run_start
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
run_end
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00

If an actual copy is required use:

[12]:

spectra = a_scipp['spectrum', 1:5].copy()

Transpose#

[13]:

mantid.Transpose(InputWorkspace=input_point_data, OutputWorkspace='data')

Transpose-[Notice] Transpose started
Transpose-[Notice] Transpose successful, Duration 0.00 seconds

[13]:

Workspace2D
Title: Test Workspace
Histograms: 100
Bins: 200
Data points
X axis: Spectrum /
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp: Transposing is implicit and automatic based on dimension labels and not required for any of the common operations, including plotting.

Scale (multiplication)#

[34]:

mantid.Scale(
    InputWorkspace=input_point_data,
    OutputWorkspace=input_point_data,
    Factor=7.5,
    Operation="Multiply",
)

Scale-[Notice] Scale started
Scale-[Notice] Scale successful, Duration 0.00 seconds

[34]:

Workspace2D
Title: Test Workspace
Histograms: 200
Bins: 100
Data points
X axis: Time-of-flight / microsecond
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp:

[35]:

a_scipp['data'] *= 7.5
a_scipp

[35]:

scipp.DataGroup

(spectrum: 11, tof: 100)

data
scipp
DataArray
(spectrum: 11, tof: 100)
float64
counts
2.25, 2.25, ..., 2.25, 2.25
sample
scipp
Variable
()
PyObject
<mantid.api._api.Sample object at 0x7f9b21d82c70>
instrument_name
str
()
basic_rect
run_title
scipp
Variable
()
string
𝟙
Test Workspace
start_time
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
end_time
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00
run_start
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
run_end
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00

Scale (addition)#

[36]:

mantid.Scale(
    InputWorkspace=input_point_data,
    OutputWorkspace='summed',
    Factor=7.5,
    Operation="Add",
)

Scale-[Notice] Scale started
Scale-[Notice] Scale successful, Duration 0.00 seconds

[36]:

Workspace2D
Title: Test Workspace
Histograms: 200
Bins: 100
Data points
X axis: Time-of-flight / microsecond
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp:

[37]:

a_scipp['data'] += 7.5 * sc.units.counts
a_scipp

[37]:

scipp.DataGroup

(spectrum: 11, tof: 100)

data
scipp
DataArray
(spectrum: 11, tof: 100)
float64
counts
9.75, 9.75, ..., 9.75, 9.75
sample
scipp
Variable
()
PyObject
<mantid.api._api.Sample object at 0x7f9b21d82c70>
instrument_name
str
()
basic_rect
run_title
scipp
Variable
()
string
𝟙
Test Workspace
start_time
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
end_time
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00
run_start
scipp
Variable
()
string
𝟙
2010-01-01T00:00:00
run_end
scipp
Variable
()
string
𝟙
2010-01-01T01:00:00

If the data is not dimensionless, the correct unit must be specified:

[38]:

a_scipp['data'].unit = sc.units.us
try:
    a_scipp['data'] += 7.5
except RuntimeError as err:
    print(str(err))
a_scipp['data'] += 7.5 * sc.units.us  # This is fine now RHS has units

Cannot add µs and dimensionless.

Mantid does not have this safety net.

ScaleX#

[39]:

mantid.ScaleX(
    InputWorkspace=input_point_data,
    OutputWorkspace='output',
    Factor=7.5,
    Operation="Multiply",
)

ScaleX-[Notice] ScaleX started

ScaleX-[Notice] ScaleX successful, Duration 0.00 seconds

[39]:

Workspace2D
Title: Test Workspace
Histograms: 200
Bins: 100
Data points
X axis: Time-of-flight / microsecond
Y axis: Counts
Distribution: False
Instrument: basic_rect (1990-Jan-01 to 1990-Jan-01)
Run start: 2010-Jan-01 00:00:00
Run end:  2010-Jan-01 01:00:00

Equivalent in scipp:

[40]:

data.coords['tof'] *= 7.5

From Mantid to Scipp#

Data types#

Workspaces#

Notes#

Other#

Concepts#

Algorithms#

Notes#

Test Data#

Generic algorithms#

CloneWorkspace#

DeleteWorkspace#

ExtractSingleSpectrum#

ExtractSpectra / CropWorkspace#

Transpose#

AppendSpectra#

ConjoinXRuns#

ConjoinSpectra#

GroupWorkspaces#

Rebin `Workspace2D` into `Workspace2D`#

Rebin `EventWorkspace` preserving events#

Rebin `EventWorkspace` into `Workspace2D`#

Rebin with logarithmic bins#

Scale (multiplication)#

Scale (addition)#

ScaleX#

SumSpectra#

Neutron-scattering specific algorithms#

ConvertUnits#

From Mantid to Scipp#

Data types#

Workspaces#

Notes#

Other#

Concepts#

Algorithms#

Notes#

Test Data#

Generic algorithms#

CloneWorkspace#

DeleteWorkspace#

ExtractSingleSpectrum#

ExtractSpectra / CropWorkspace#

Transpose#

AppendSpectra#

ConjoinXRuns#

ConjoinSpectra#

GroupWorkspaces#

Rebin Workspace2D into Workspace2D#

Rebin EventWorkspace preserving events#

Rebin EventWorkspace into Workspace2D#

Rebin with logarithmic bins#

Scale (multiplication)#

Scale (addition)#

ScaleX#

SumSpectra#

Neutron-scattering specific algorithms#

ConvertUnits#

Rebin `Workspace2D` into `Workspace2D`#

Rebin `EventWorkspace` preserving events#

Rebin `EventWorkspace` into `Workspace2D`#