diff --git a/Framework/DataHandling/src/LoadInstrument.cpp b/Framework/DataHandling/src/LoadInstrument.cpp
index f5068050463298994676e8d383a206d7226bd4bd..63183d5f17abf8d882a09ffe1c57e281c7d25b8f 100644
--- a/Framework/DataHandling/src/LoadInstrument.cpp
+++ b/Framework/DataHandling/src/LoadInstrument.cpp
@@ -62,7 +62,8 @@ void LoadInstrument::init() {
"monitors loaded in to the workspace.");
declareProperty(
"InstrumentName", "",
- "Name of instrument. Can be used instead of Filename to specify an IDF");
+ "Name of instrument. Can be used instead of Filename to specify an"
+ "instrument definition.");
declareProperty("InstrumentXML", "",
"The full XML instrument definition as a string.");
declareProperty(
diff --git a/docs/source/algorithms/LoadInstrument-v1.rst b/docs/source/algorithms/LoadInstrument-v1.rst
index 742ede74498275023f8e003273898033fa8aac3e..d1747cac7e6eac7d06ff47952ecd1cf1b7e7ab27 100644
--- a/docs/source/algorithms/LoadInstrument-v1.rst
+++ b/docs/source/algorithms/LoadInstrument-v1.rst
@@ -9,11 +9,12 @@
Description
-----------
-Loads an instrument definition file (:ref:`IDF <InstrumentDefinitionFile>`)
-into a workspace, which contains information about detector positions,
-their geometric shape, slit properties, links between values stored in
-ISIS log-files and components of the instrument and so on. For more on
-IDFs see: :ref:`InstrumentDefinitionFile <InstrumentDefinitionFile>`.
+Loads the instrument geometry from either an instrument definition file
+(:ref:`IDF <InstrumentDefinitionFile>`) 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:
+:ref:`InstrumentDefinitionFile <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
@@ -21,10 +22,26 @@ 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,
-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 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
-----
@@ -32,28 +49,42 @@ Usage
**Example - Load instrument to a workspace:**
.. testcode:: exLoadInstrument
-
- # create sample workspace
- ws=CreateSampleWorkspace();
- inst0=ws.getInstrument();
-
- print("Default workspace has instrument: {0} with {1} parameters".format(inst0.getName(),len(inst0.getParameterNames())))
-
- # load MARI
- det=LoadInstrument(ws,InstrumentName='MARI', RewriteSpectraMap=True)
- inst1=ws.getInstrument();
-
- print("Modified workspace has instrument: {0} with {1} parameters".format(inst1.getName(),len(inst1.getParameterNames())))
- print("Instrument {0} has the following detectors: {1}".format(inst1.getName(), det))
+ # 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:**
.. testoutput:: exLoadInstrument
Default workspace has instrument: basic_rect with 0 parameters
- Modified workspace has instrument: MARI with 74 parameters
- Instrument MARI has the following detectors: [1 2 3]
+ ===========================
+ 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