\(\renewcommand\AA{\unicode{x212B}}\)

LoadInstrument v1¶

../_images/ImageNotFound.png — Enable screenshots using DOCS_SCREENSHOTS in CMake¶

Summary ¶

Loads an Instrument Definition File (IDF) into a workspace. After the IDF has been read this algorithm will attempt to run the Child Algorithm LoadParameterFile; where if IDF filename is of the form IDENTIFIER_Definition.xml then the instrument parameters in the file named IDENTIFIER_Parameters.xml would be loaded.

Properties ¶

Name	Direction	Type	Default	Description
Workspace	InOut	MatrixWorkspace	Mandatory	The name of the workspace to load the instrument definition into. Any existing instrument will be replaced.
Filename	Input	string		The filename (including its full or relative path) of an instrument definition file. The file extension must either be .xml or .XML when specifying an instrument definition file. Files can also be .hdf5 or .nxs for usage with NeXus Geometry files. Note Filename or InstrumentName must be specified but not both. Allowed extensions: [‘.xml’, ‘.nxs’, ‘.hdf5’]
MonitorList	Output	int list		Will be filled with a list of the detector ids of any monitors loaded in to the workspace.
InstrumentName	Input	string		Name of instrument. Can be used instead of Filename to specify aninstrument definition.
InstrumentXML	Input	string		The full XML instrument definition as a string.
RewriteSpectraMap	Input	optional boolean	Mandatory	If set to True then a 1:1 map between the spectrum numbers and detector/monitor IDs is set up such that the detector/monitor IDs in the IDF are ordered from smallest to largest number and then assigned in that order to the spectra in the workspace. For example if the IDF has defined detectors/monitors with IDs 1, 5, 10 and the workspace contains 3 spectra with numbers 1, 2, 3 (and workspace indices 0, 1, 2) then spectrum number 1 is associated with detector ID 1, spectrum number 2 with detector ID 5 and spectrum number 3 with detector ID 10.If the number of spectra and detectors do not match then the operation is performed until the maximum number of either is reached. For example if there are 12 spectra and 50 detectors then the first 12 detectors are assigned to the 12 spectra in the workspace.If set to False then the spectrum numbers and detector IDs of the workspace are not modified.This property must be set to either True or False. Allowed values: [‘Unset’, ‘True’, ‘False’]

Description ¶

Loads the instrument geometry from either an instrument definition file (IDF) or a Nexus file into a workspace. The geometry contains information about detector positions, their geometric shape, slit properties, links between values stored in log-files and components of the instrument and so on. For more on IDFs see: InstrumentDefinitionFile.

By default the algorithm will write a 1:1 map between the spectrum number and detector ID. Any custom loading algorithm that calls this as a Child Algorithm will therefore get this 1:1 map be default. If the custom loader is to write its own map then it is advised to set RewriteSpectraMap to false to avoid extra work.

The instrument to load can be specified by either the InstrumentXML (IDFs only), Filename and InstrumentName properties (given here in order of precedence if more than one is set). At present, if the InstrumentXML is used the InstrumentName property should also be set.

The Filename can either be an absolute or relative path. In the latter case, both the datasearch.directories and instrument directories (accessible via getInstrumentDirectories() and setInstrumentDirectories()) are searched for the specified file. The filename is required to be of the form InstrumentName + _Definition + Identifier + extension. The identifier then is the part of a filename that identifies the instrument definition valid at a given date. If several instrument files files are valid at the given date the file with the most recent from date is selected. If no such files are found the file with the latest from date is selected.

If only the InstrumentName is specified, a filename is built on-the-fly to have the form InstrumentName + _Definition.(xml|hdf5|nxs). Short instrument names can also be used, such as seq; they get translated to long instrument names (e.g. SEQUOIA) through the ConfigServiceImp::getInstrument().name() method.

Usage ¶

Example - Load instrument to a workspace:

# create sample workspace
ws1 = CreateSampleWorkspace();
inst1 = ws1.getInstrument();
print("Default workspace has instrument: {0} with {1} parameters".format(inst1.getName(),len(inst1.getParameterNames())))

# load MARI from instrument name
print("===========================")
mon1 = LoadInstrument(ws1, InstrumentName="MARI", RewriteSpectraMap=True)
inst1 = ws1.getInstrument()
di1 = ws1.detectorInfo()
ci1 = ws1.componentInfo()
print("Modified workspace {0} has instrument: {1}".format(ws1.getName(), inst1.getName()))
print("Instrument {0} has {1} components, including {2} monitors and {3} detectors".format(inst1.getName(), ci1.size(), len(mon1), di1.size()))

# load LOKI from file name
print("===========================")
ws2 = CreateSampleWorkspace();
mon2 = LoadInstrument(ws2, FileName="LOKI_Definition.hdf5", RewriteSpectraMap=True)
inst2 = ws2.getInstrument()
di2 = ws2.detectorInfo()
ci2 = ws2.componentInfo()
print("Workspace {0} has instrument: {1}".format(ws2.getName(), inst2.getName()))
print("Instrument {0} has {1} components, including {2} monitors and {3} detectors".format(inst2.getName(), ci2.size(), len(mon2), di2.size()))

Output:

Default workspace has instrument: basic_rect with 0 parameters
===========================
Modified workspace ws1 has instrument: MARI
Instrument MARI has 963 components, including 3 monitors and 921 detectors
===========================
Workspace ws2 has instrument: LOKI
Instrument LOKI has 8011 components, including 0 monitors and 8000 detectors

Categories: AlgorithmIndex | DataHandling\Instrument