InstrumentDefinitionFile.rst

variable in the formula.

The optional 'result-unit' attribute tells what the unit is of the
output of the formula. In the example above this unit is "1/dSpacing^2"
(for the 'result-unit' this attribute can be set to an algebraic
expression of the units defined in :ref:`Unit Factory <Unit Factory>`). If
the x-axis unit of the data you are trying to fit is dSpacing then the
output of the formula is left as it is. But for example if the x-axis
unit of the data is TOF then the formula output is converted into, it in
this case, the unit "1/TOF^2". Examples where 'unit' and 'result-unit'
are used include:
`CreateBackToBackParameters <http://www.mantidproject.org/CreateBackToBackParameters>`_ and
`CreateIkedaCarpenterParameters <http://www.mantidproject.org/CreateIkedaCarpenterParameters>`_.

An example which demonstrate using a look-up-table is

.. code-block:: xml

      <parameter name="IkedaCarpenterPV:Alpha0" type="fitting">
        <lookuptable interpolation="linear" x-unit="TOF" y-unit="dSpacing">
          <point x="1" y="1" />
          <point x="3" y="100" />
          <point x="5" y="1120" />
          <point x="10" y="1140" />
        </lookuptable>
      </parameter>


As with a formula the look-up is done for the 'x'-value that corresponds
to the centre of the peak as known prior to the start of the fitting
process. The only interpolation option currently supported is 'linear'.
The optional 'x-unit' and 'y-unit' attributes must be set to one of the
units defined in :ref:`Unit Factory <Unit Factory>`. The 'x-unit' and
'y-unit' have very similar effect to the 'unit' and 'result-unit'
attributes for described above. 'x-unit' converts the unit of the centre
before lookup against the x-values. 'y-axis' is the unit of the y values
listed, which for the example above correspond to Alpha0.

.. _Using component-link:

Using <component-link>
~~~~~~~~~~~~~~~~~~~~~~

Allow <parameter>s to be linked to components without needing <parameter>s to be
defined inside, as sub-elements, of the components they belong to. The standard
approach for defining a parameter is

.. code-block:: xml

    <component type="bank" name="bank_90degnew">
      <location />
      <parameter name="test"> <value val="50.0" /> </parameter>
    </component>

where a parameter 'test' is defined to belong to the component with the
name 'bank\_90degnew'. However, alternatively the parameter can be
defined using the notation in the an example below. Note that if more
than one component e.g. have the name 'bank\_90degnew' then the
specified parameters are applied to all such components.

.. code-block:: xml

    <component type="bank" name="bank_90degnew">
      <location />
    </component>

    <component-link name="bank_90degnew" >
      <parameter name="test"> <value val="50.0" /> </parameter>
    </component-link>

<component-link> is the only way parameters can be defined in a **parameter file** used
by the :ref:`LoadParameterFile <algm-LoadParameterFile>` algorithm.

If there are several components with name 'bank\_90degnew' but you want
specified paramentes to apply to only one of them, then you can specify
the name by a path name.

.. code-block:: xml

    <component-link name="HRPD/leftside/bank_90degnew" >
      <parameter name="test"> <value val="50.0" /> </parameter>
    </component-link>

The path name need not be complete provided it specifies a unique
component. Here we drop the instrument name HRPD.

.. code-block:: xml

    <component-link name="leftside/bank_90degnew" >
      <parameter name="test"> <value val="50.0" /> </parameter>
    </component-link>

.. _Using combine-components-into-one-shape:

Using <combine-components-into-one-shape>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The standard way of making up geometric shapes as a collection of parts
is described here:
:ref:`HowToDefineGeometricShape <HowToDefineGeometricShape>`. However, <combine-components-into-one-shape>
offers in some circumstances a more convenient way of defining more
complicated shapes, as for example is the case for the ISIS POLARIS
instrument. This tag combining components into one shape as demonstrated
below:

.. code-block:: xml

    <component type="adjusted cuboid"
      <location />
    </component>

    <type name="adjusted cuboid" is="detector">
      <combine-components-into-one-shape />
      <component type="cuboid1">
        <location name="A"/>
        <!-- "A" translated by y=10 and rotated around x-axis by 90 degrees -->
        <location name="B" y="10" rot="90" axis-x="1" axis-y="0" axis-z="0" />
      </component>
      <algebra val="A : B" />

      <!-- this bounding box is used for this combined into one shape-->
      <bounding-box>
        <x-min val="-0.5"/>
        <x-max val="0.5"/>
        <y-min val="-5.0"/>
        <y-max val="10.5"/>
        <z-min val="-5.0"/>
        <z-max val="5.0"/>
      </bounding-box>

    </type>

    <type name="cuboid1" is="detector">
      <cuboid id="bob">
        <left-front-bottom-point x="0.5" y="-5.0" z="-0.5"  />
        <left-front-top-point  x="0.5" y="-5.0" z="0.5"  />
        <left-back-bottom-point  x="-0.5" y="-5.0" z="-0.5"  />
        <right-front-bottom-point  x="0.5" y="5.0" z="-0.5"  />
      </cuboid>

      <!-- this bounding box is not used in the combined shape -->
      <!-- Note you would not normally need to add a bounding box
           for a single cuboid shape. The reason for adding one
           here is just to illustrate that a bounding added here
           will not be used in created a combined shape as in
           "adjusted cuboid" above -->
      <bounding-box>
        <x-min val="-0.5"/>
        <x-max val="0.5"/>
        <y-min val="-5.0"/>
        <y-max val="5.0"/>
        <z-min val="-0.5"/>
        <z-max val="0.5"/>
      </bounding-box>
    </type>

which combines two components "A" and "B" into one shape. The resulting
shape is shape is shown here:

.. figure:: ../images/CombineIntoOneShapeExample.png
   :alt: CombineIntoOneShapeExample.png

   CombineIntoOneShapeExample.png

Note for this to work, a unique name for each component must be provided
and these names must be used in the algebra sting (here "A : B", see
:ref:`HowToDefineGeometricShape <HowToDefineGeometricShape>`). Further a
bounding-box may optionally be added to the to the type.
Note the above geometric shape can alternatively be defined with the XML
(Mantid behind the scene translates the above XML to the XML below
before proceeding):

.. code-block:: xml

    <component type="adjusted cuboid">
      <location />
    </component>

    <type name="adjusted cuboid" is="detector">
      <cuboid id="A">
        <left-front-bottom-point x="0.5" y="-5.0" z="-0.5"  />
        <left-front-top-point  x="0.5" y="-5.0" z="0.5"  />
        <left-back-bottom-point  x="-0.5" y="-5.0" z="-0.5"  />
        <right-front-bottom-point  x="0.5" y="5.0" z="-0.5"  />
      </cuboid>
      <!-- cuboid "A" translated along y by 10 and rotated around x by 90 degrees -->
      <cuboid id="B">
        <left-front-bottom-point x="0.5" y="10.5" z="-5.0"  />
        <left-front-top-point  x="0.5" y="9.5" z="-5.0"  />
        <left-back-bottom-point  x="-0.5" y="9.5" z="-5.0"  />
        <right-front-bottom-point  x="0.5" y="10.5" z="5.0"  />
      </cuboid>
      <algebra val="A : B" />
    </type>

<combine-components-into-one-shape> for now works only for combining cuboids. Please do not hesitate to
contact the Mantid team if you would like to extend this.

This applies when defining any geometric shape, but perhaps something which a user
has to be in particular aware of when defining more complicated geometry shapes, for
example, using the <combine-components-into-one-shape> tag: the coordinate system in
which a shape is defined can be chosen arbitrary, and the origin of this coordinate
system is the position returned when a user asked for its position. It is therefore
highly recommended that when a user define a detector geometric shape, this could be
simple cuboid, that it is defined with the origin at the centre of the front of the
detector. For detector shapes build up of for example multiple cuboids the origin
should be chosen perhaps for the center of the front face of the 'middle' cuboid.
When Mantid as for the position of such a shape it will be with reference to
coordinate system origin of the shape. However, sometimes it may simply be
inconvenient to build up a geometry shape with an coordinate system as explained above.
For this case, and for now only when using <combine-components-into-one-shape> it
possible to get around this by using the element <translate-rotate-combined-shape-to>,
which takes the same attributes as a <location> element. The effect of this element
is basically to redefine the shape coordinate system origin (in fact also rotate it
if requested).

.. _Using defaults:

Using <defaults>
~~~~~~~~~~~~~~~~

Used for setting various defaults.

.. _components-are-facing:

<components-are-facing>
^^^^^^^^^^^^^^^^^^^^^^^

Used to make the xy-plane of the geometric shape of any component by
default face a given location. For example

.. code-block:: xml

      <components-are-facing x="0.0" y="0.0" z="0.0" />

If this element is not specified the default is to *not* attempt to
apply facing.

.. _offsets:

<offsets>
^^^^^^^^^

Originally introduced to handle detector position coordinates as defined
by the
`Ariel <http://www.isis.rl.ac.uk/Disordered/GEM/ariel/index_ariel.htm>`__
software.

.. code-block:: xml

      <offsets spherical="delta" />

When this is set all components which have coordinates specified using
spherical coordinates (i.e. using the r, t, p attributes, see
description of <location>) are then treated as offsets to the spherical position
of the parent, i.e. the value given for :math:`r` are added to the
parent's :math:`r` to give the total radial coordinate, and the same for
:math:`\theta` and :math:`\phi`. Note using this option breaks the
symmetry that the <location> element of a child component equals the position of
this component relative to its parent component.

.. _reference-frame:

<reference-frame>
^^^^^^^^^^^^^^^^^

Reference frame in which instrument is described. The author/reader of
an IDF can chose the reference coordinate system in which the instrument
is described. The default reference system is the one shown below.

.. code-block:: xml

      <reference-frame>
        <!-- The z-axis is set parallel to and in the direction of the beam. the
             y-axis points up and the coordinate system is right handed. -->
        <along-beam axis="z"/>
        <pointing-up axis="y"/>
        <handedness val="right"/>
      </reference-frame>


This reference frame is e.g. used when a signed theta detector values
are calculated where it is needed to know which direction is defined as
up. The direction here means the direction of the beam if it was not
modified by any mirrors etc.

.. _default-view:

<default-view>
^^^^^^^^^^^^^^

This tag is used to control how the instrument first appears in the
`Instrument View <http://www.mantidproject.org/MantidPlot:_Instrument_View>`__. Attribute ``view``
defines the type of the view that opens by default. It can have the
following values: "3D", "cylindrical\_x", "cylindrical\_y",
"cylindrical\_z", "spherical\_x", "spherical\_y", "spherical\_z". If the
attribute is omitted value "3D" is assumed. Opening the 3D view on
start-up is also conditioned on the value of the
``MantidOptions.InstrumentView.UseOpenGL`` property in the :ref:`Properties
File <Properties File>`. If set to "Off" this property prevents the
Instrument View to start in 3D mode and "cylindrical\_y" is used
instead. The user can change to 3D later.

Another attribute, ``axis-view`` governs on which axis the instrument is
initially viewed from in 3D and can be set equal to one of "Z-", "Z+",
"X-", etc. If "Z-" were selected then the view point would be on the
z-axis on the negative of the origin looking in the +z direction.

.. _angle unit="radian":

<angle unit="radian">
^^^^^^^^^^^^^^^^^^^^^

If

.. code-block:: xml

      <angle unit="radian"/>


is set then all angles specified in <location> elements and <parameter>'s with names
"rotx", "roty", "rotz", "t-position" and "p-position" are assumed to in radians. The
default is to assume all angles are specified in degrees.

Other defaults
^^^^^^^^^^^^^^

.. code-block:: xml

      <length unit="meter"/>

This default, for now, does not do anything, but is the default unit for
length used by Mantid. If it would be useful for you to specify user
defined units do not hesitate to `request
this <mailto:mantid-help@mantidproject.org>`__.

Parameter Files
---------------

To prevent an IDF file from getting too long and complicated,
information not related to the geometry of the instrument may be put
into a separate file, whose content is automatically included into the
IDF file.

For more information see the :ref:`parameter file
page <InstrumentParameterFile>`.

Deprecated Features
-------------------

The following features are now deprecated and should no longer be used.

*mark-as="monitor"*

The following notation to mark a detector as a
monitor is now deprecated:

.. code-block:: xml

      <component type="monitor" idlist="monitor">
          <location r="3.25800" t="180.0" p="0.0" mark-as="monitor"/>
      </component>

      <type name="monitor" is="detector"/>

      <idlist idname="monitor">
        <id val="11" />
      </idlist>

The above XML should be replaced with

.. code-block:: xml

      <component type="monitor" idlist="monitor">
          <location r="3.25800" t="180.0" p="0.0"/>
      </component>

      <type name="monitor" is="monitor"/>

      <idlist idname="monitor">
        <id val="11" />
      </idlist>


.. categories:: Concepts