DownloadInstrument v1


Checks the Mantid instrument repository against the local instrument files, and downloads updates as appropriate.

See Also

LoadInstrument, UpdateScriptRepository











Ignore cache information




The number of files downloaded by this algorithm


This algorithm connects with the cloud based Mantid Instrument Definition Repository and downloads any updated instrument files for use within Mantid.

This algorithm is normally run on startup of Mantid for official installed releases of Mantid from version 3.3 onwards.

Mantid Property Keys

The code is configured using he following Mantid.Property, or Mantid.User.Property keys.

UpdateInstrumentDefinitions.OnStartup = 1

This controls whether this algorithm is run on startup of Mantid. 1 = Run on startup, 0 = don’t.

UpdateInstrumentDefinitions.URL = https://api.github.com/repos/mantidproject/mantid/contents/instrument

This stores the url used to access the contents of the Mantid Instrument Definition Repository.

network.github.api_token = (not shown)

This overrides the github api token that is used by the algorithm. To use unauthenticated requests, set it to an empty string or the values unset.

Output Messages

The following may be logged at Notice

All instrument definitions up to date

Everything is fine, there are no updates to download.

Downloading n files from the instrument repository

Some files have changed or been added to the Instrument Repository, they are being downloaded.

Internet Connection Failed - cannot update instrument definitions.

The connection to the instrument Repository failed. This could be down to your network connection, proxy settings (we use the system proxy settings). More details will be logged as another message at information level.

Instrument Definition Update: The Github API rate limit has been reached, try again after 19-Feb-2015 11:23:34

There is a limit of how many calls we are allowed to make to Github per hour. Try again after the time specified. If this keeps occurring let the development team know.

The details

The Mantid Instrument Definition Repository is currently a directory within the Mantid code repository on Github. https://github.com/mantidproject/mantid

The instrument files within Mantid can be accessed in three locations.

  1. The mantid install directory [Install Dir] (windows default “C:mantidinstallinstrument”).

  2. The local user appdata directory [Appdata Dir] (windows “%APPDATA%mantidprojectmantidinstrument”, linux/Mac “~/.mantid/instrument”).

  3. Mantid Instrument repository [Instrument Repo] on Github

When running the algorithm the processing takes the following steps.

  1. The description of the contents of the Instrument Repo is downloaded and stored in a file github.json to the Appdata Dir.

  2. A file of the description of xml files in Appdata Dir and Install Dir are updated or created and saved into AppData Dir as install.json and appdata.json.

  3. The contents of all 3 are inspected and new or updated files (based on the git checksum) are added to a download list.

  4. The list of files are downloaded to the Appdata Dir.

  5. LoadInstrument v1 will load files in Appdata Dir in preference to those in the Install Dir if both are valid.



updatedFileCount = DownloadInstrument()
print("The number of files updated was " + str(updatedFileCount))


The number of files updated was ...

Categories: AlgorithmIndex | DataHandling\Instrument


C++ header: DownloadInstrument.h

C++ source: DownloadInstrument.cpp