LoadInstrument.cpp

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2018 ISIS Rutherford Appleton Laboratory UKRI,
//   NScD Oak Ridge National Laboratory, European Spallation Source,
//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
// SPDX - License - Identifier: GPL - 3.0 +
#include "MantidDataHandling/LoadInstrument.h"
#include "MantidAPI/FileProperty.h"
#include "MantidAPI/InstrumentDataService.h"
#include "MantidAPI/InstrumentFileFinder.h"
#include "MantidAPI/MatrixWorkspace.h"
#include "MantidAPI/Progress.h"
#include "MantidDataHandling/LoadGeometry.h"
#include "MantidGeometry/Instrument.h"
#include "MantidGeometry/Instrument/InstrumentDefinitionParser.h"
#include "MantidKernel/ArrayProperty.h"
#include "MantidKernel/ConfigService.h"
#include "MantidKernel/MandatoryValidator.h"
#include "MantidKernel/OptionalBool.h"
#include "MantidKernel/Strings.h"
#include "MantidNexusGeometry/NexusGeometryParser.h"
 
#include <boost/algorithm/string.hpp>
 
namespace Mantid::DataHandling {
 
DECLARE_ALGORITHM(LoadInstrument)
 
using namespace Kernel;
using namespace API;
using namespace Geometry;
 
std::recursive_mutex LoadInstrument::m_mutex;
 
// This enum class is used to remember easily which instrument loader should be
// used. There are 3 different loaders: from XML string, from an IDF file and
// from a Nexus file. Some parts of the exec() function are common to Xml and
// Idf, some parts are common to Idf and Nxs, and some parts are common to all
// three. Assigning numbers to the 3 types allows us to write statements like
// if (loader_type < LoaderType::Nxs) then do all things common to Xml and Idf.
enum class LoaderType { Xml = 1, Idf = 2, Nxs = 3 };
 
void LoadInstrument::init() {
  // When used as a Child Algorithm the workspace name is not used - hence the
  // "Anonymous" to satisfy the validator
  declareProperty(std::make_unique<WorkspaceProperty<MatrixWorkspace>>("Workspace", "Anonymous", Direction::InOut),
                  "The name of the workspace to load the instrument definition "
                  "into. Any existing instrument will be replaced.");
  declareProperty(
      std::make_unique<FileProperty>("Filename", "", FileProperty::OptionalLoad, LoadGeometry::validExtensions()),
      "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.");
  declareProperty(std::make_unique<ArrayProperty<detid_t>>("MonitorList", Direction::Output),
                  "Will be filled with a list of the detector ids of any "
                  "monitors loaded in to the workspace.");
  declareProperty("InstrumentName", "",
                  "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(std::make_unique<PropertyWithValue<OptionalBool>>(
                      "RewriteSpectraMap", OptionalBool::Unset, std::make_shared<MandatoryValidator<OptionalBool>>()),
                  "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.");
}
 
//------------------------------------------------------------------------------------------------------------------------------
void LoadInstrument::exec() {
  // Get the input workspace
  std::shared_ptr<API::MatrixWorkspace> ws = getProperty("Workspace");
  std::string filename = getPropertyValue("Filename");
  std::string instname = getPropertyValue("InstrumentName");
  // std::pair<std::string, std::string> loader_type;
  LoaderType loader_type;
 
  // If instrumentXML is not default (i.e. it has been defined), then use that
  // Note: this is part of the IDF loader
  const Property *const InstrumentXML = getProperty("InstrumentXML");
  if (!InstrumentXML->isDefault()) {
    // We need the instrument name to be set as well because, for whatever
    // reason, this isn't pulled out of the XML.
    if (instname.empty())
      throw std::runtime_error("The InstrumentName property must be set when "
                               "using the InstrumentXML property.");
    // If the Filename property is not set, set it to the same as the instrument
    // name
    if (filename.empty())
      filename = instname;
 
    // Assign the loader type to Xml
    loader_type = LoaderType::Xml;
 
  } else {
    // This part of the loader searches through the instrument directories for
    // a valid IDF or Nexus geometry file
 
    // The first step is to define a valid filename
 
    // If the filename is empty, try to find a file from the instrument name
    if (filename.empty()) {
      // look to see if an Instrument name provided in which case create
      // filename on the fly
      if (instname.empty()) {
        g_log.error("Either the InstrumentName or Filename property of "
                    "LoadInstrument most be specified");
        throw Kernel::Exception::FileError("Either the InstrumentName or Filename property of LoadInstrument "
                                           "must be specified to load an instrument",
                                           filename);
      } else {
        filename = InstrumentFileFinder::getInstrumentFilename(instname, ws->getWorkspaceStartDate());
        setPropertyValue("Filename", filename);
      }
    }
    if (filename.empty()) {
      throw Exception::NotFoundError("Unable to find an Instrument File for instrument: ", instname);
    }
 
    // Remove the path from the filename for use with the InstrumentDataService
    const std::string::size_type stripPath = filename.find_last_of("\\/");
    std::string instrumentFile = filename.substr(stripPath + 1, filename.size());
 
    // Strip off "_Definition.xml"
    auto definitionRange = boost::ifind_first(instrumentFile, "_Def");
    if (definitionRange) {
      instname = instrumentFile.substr(0, std::distance(instrumentFile.begin(), definitionRange.begin()));
    } else {
      g_log.warning("The instrument definition filename does not contain "
                    "_Definition. Your instrument name will be set to: " +
                    instrumentFile);
      instname = instrumentFile;
    }
 
    // Now that we have a file name, decide whether to use Nexus or IDF loading
    if (LoadGeometry::isIDF(filename)) {
      // Assign the loader type to Idf
      loader_type = LoaderType::Idf;
    } else if (LoadGeometry::isNexus(filename)) {
      // Assign the loader type to Nxs
      loader_type = LoaderType::Nxs;
    } else {
      throw Kernel::Exception::FileError("No valid loader found for instrument file ", filename);
    }
  }
 
  InstrumentDefinitionParser parser;
  std::string instrumentNameMangled;
  Instrument_sptr instrument;
 
  // Define a parser if using IDFs
  if (loader_type == LoaderType::Xml)
    parser = InstrumentDefinitionParser(filename, instname, InstrumentXML->value());
  else if (loader_type == LoaderType::Idf)
    parser = InstrumentDefinitionParser(filename, instname, Strings::loadFile(filename));
 
  // Find the mangled instrument name that includes the modified date
  if (loader_type < LoaderType::Nxs)
    instrumentNameMangled = parser.getMangledName();
  else if (loader_type == LoaderType::Nxs)
    instrumentNameMangled = NexusGeometry::NexusGeometryParser::getMangledName(filename, instname);
  else
    throw std::runtime_error("Unknown instrument LoaderType");
 
  {
    // Make InstrumentService access thread-safe
    std::lock_guard<std::recursive_mutex> lock(m_mutex);
 
    // Check whether the instrument is already in the InstrumentDataService
    if (InstrumentDataService::Instance().doesExist(instrumentNameMangled)) {
      // If it does, just use the one from the one stored there
      instrument = InstrumentDataService::Instance().retrieve(instrumentNameMangled);
    } else {
 
      if (loader_type < LoaderType::Nxs) {
        // Really create the instrument
        Progress prog(this, 0.0, 1.0, 100);
        instrument = parser.parseXML(&prog);
        // Parse the instrument tree (internally create ComponentInfo and
        // DetectorInfo). This is an optimization that avoids duplicate parsing
        // of the instrument tree when loading multiple workspaces with the same
        // instrument. As a consequence less time is spent and less memory is
        // used. Note that this is only possible since the tree in `instrument`
        // will not be modified once we add it to the IDS.
        instrument->parseTreeAndCacheBeamline();
      } else {
        Instrument_const_sptr ins =
            NexusGeometry::NexusGeometryParser::createInstrument(filename, NexusGeometry::makeLogger(&m_log));
        instrument = std::const_pointer_cast<Instrument>(ins);
      }
      // Add to data service for later retrieval
      InstrumentDataService::Instance().add(instrumentNameMangled, instrument);
    }
    ws->setInstrument(instrument);
 
    // populate parameter map of workspace
    ws->populateInstrumentParameters();
 
    // LoadParameterFile modifies the base instrument stored in the IDS so this
    // must also be protected by the lock until LoadParameterFile is fixed.
    // check if default parameter file is also present, unless loading from
    if (!filename.empty() && (loader_type < LoaderType::Nxs))
      runLoadParameterFile(ws, filename);
  } // end of mutex scope
 
  // Set the monitors output property
  setProperty("MonitorList", (ws->getInstrument())->getMonitors());
 
  // Rebuild the spectra map for this workspace so that it matches the
  // instrument, if required
  const OptionalBool RewriteSpectraMap = getProperty("RewriteSpectraMap");
  if (RewriteSpectraMap == OptionalBool::True)
    ws->rebuildSpectraMapping();
}
 
//-----------------------------------------------------------------------------------------------------------------------
void LoadInstrument::runLoadParameterFile(const std::shared_ptr<API::MatrixWorkspace> &ws,
                                          const std::string &filename) {
  g_log.debug("Loading the parameter definition...");
 
  // First search for XML parameter file in same folder as IDF file
  const std::string::size_type dir_end = filename.find_last_of("\\/");
  std::string directoryName = filename.substr(0, dir_end + 1); // include final '/'.
  std::string fullPathParamIDF = InstrumentFileFinder::getParameterPath(filename, directoryName);
 
  if (!fullPathParamIDF.empty()) {
 
    g_log.debug() << "Parameter file: " << fullPathParamIDF << '\n';
    // Now execute the Child Algorithm. Catch and log any error, but don't stop.
    try {
      // To allow the use of ExperimentInfo instead of workspace, we call it
      // manually
      Algorithm_sptr loadParamAlg = createChildAlgorithm("LoadParameterFile");
      loadParamAlg->setProperty("Filename", fullPathParamIDF);
      loadParamAlg->setProperty("Workspace", ws);
      loadParamAlg->execute();
      g_log.debug("Parameters loaded successfully.");
    } catch (std::invalid_argument &e) {
      g_log.information("LoadParameterFile: No parameter file found for this instrument");
      g_log.information(e.what());
    } catch (std::runtime_error &e) {
      g_log.information("Unable to successfully run LoadParameterFile Child Algorithm");
      g_log.information(e.what());
    }
  } else {
    g_log.information("No parameter file found for this instrument");
  }
}
 
} // namespace Mantid::DataHandling