4.2

Instrument

What are Instruments?

The Instrument in Mantid is a geometrical description of the components that make up the beam line. The components described will generally include:

  • The source
  • The sample position
  • Each detector ‘pixel’
  • Each monitor

Other components may also be included such as

  • Slits
  • Mirrows
  • Guides
  • Choppers
  • Engineering obstacles in the beam path
  • Link between log-files and variable parameters of the instrument (such as the height of a detector table)

An instrument is described using an instrument definition file.

The Mantid geometry is further explained here.

Why do we have a full instrument description, and not just a list of L2 and 2Theta values?

A list of L2 and 2Theta values will provide information to perform unit conversions and several other algorithms, however a full geometric instrument description allows much more.

  • Visualization of the instrument internals with data overlays
  • Complex absorption corrections
  • Montecarlo simulations of experiments
  • Updating the instrument geometry according to values stored in log-files

Working with Instruments in Python

Getting the Instrument from a workspace

You can get access to the Instrument for a workspace with

instrument = ws.getInstrument()

Instrument Properties

ws = CreateSampleWorkspace()
instrument = ws.getInstrument()

# get the instrument name
print(instrument.getName())
# Get the validity dates for this instrument definition
print(instrument.getValidToDate())
print(instrument.getValidFromDate())
# Get the X,Y,Z position of the source and sample
source = instrument.getSource()
sample = instrument.getSample()
print(source.getPos())
print(sample.getPos())
# Get the distance from the source to the sample
print(sample.getDistance(source))

Finding Specific Components of the instrument

The instrument class has several methods to help in finding the objects that describe specific parts of the instrument.

ws = CreateSampleWorkspace()
instrument = ws.getInstrument()

# Get the source and sample
source = instrument.getSource()
sample = instrument.getSample()

# You can get a component by name
bank1 = instrument.getComponentByName("bank1")
# Or by Detector_id
det101 = instrument.getDetector(101)

Instrument Parameters

Instruments, or any component within them (bank, detector, chopper, slit etc) can have parameters defined for them. These can be accessed from Python. Any search for instrument parameters cascades up the instrument tree, so a detector will inherit any parameters from it’s back, and it’s instrument.

# setup
ws = CreateSampleWorkspace()
#set a string parameter on the whole instrument
SetInstrumentParameter(ws,ParameterName="TestParam",Value="Hello")

#set a Number parameter just for bank 1
SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3", ComponentName="bank1",ParameterType="Number")

#set a different value on bank 2
SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3.5", ComponentName="bank2",ParameterType="Number")


instrument=ws.getInstrument()
bank1=instrument.getComponentByName("bank1")
bank2=instrument.getComponentByName("bank2")

print("The whole instrument parameter can be read from anywhere.")
print("  The instrument: " + instrument.getStringParameter("TestParam")[0])
print("  bank 1: " + bank1.getStringParameter("TestParam")[0])
print("  bank 2: " + bank2.getStringParameter("TestParam")[0])

print("The parameters  on the Bank 1 can be read from the bank or below.")
#For this one call getIntParameter as the number was an int
print("  bank 1: " + str(bank1.getIntParameter("NumberParam")[0]))
#For this one call getNumberParameter as the number was a float
print("  bank 2: " + str(bank2.getNumberParameter("NumberParam")[0]))
#if you are not sure of the type of a parameter you can call getParameterType
print("  The type of NumberParam in bank 1: " + bank1.getParameterType("NumberParam"))
print("  The type of NumberParam in bank 2: " + bank2.getParameterType("NumberParam"))

Output:

The whole instrument parameter can be read from anywhere.
  The instrument: Hello
  bank 1: Hello
  bank 2: Hello
The parameters  on the Bank 1 can be read from the bank or below.
  bank 1: 3
  bank 2: 3.5
  The type of NumberParam in bank 1: int
  The type of NumberParam in bank 2: double

Getting all the Parameters on an instrument component

# setup as above
instrument=ws.getInstrument()
det101=instrument.getDetector(101)

for name in det101.getParameterNames() :
    if det101.getParameterType(name) == "int":
        value = det101.getIntParameter(name)
    if det101.getParameterType(name) == "double":
        value = det101.getNumberParameter(name)
    if det101.getParameterType(name) == "string":
        value = det101.getStringParameter(name)
    print("{0} {1}".format(name,value))

Output:

NumberParam [3]
TestParam ['Hello']

Category: Concepts