Positioners#

Consider the SPEC scan data shown in section Scan above, associated with the scan header data shown in section File header. The #O lines in the header provide the names of the positioners while the #P lines report the positioner values at the start of the scan. The lines are numbered with a sequential index (starting at 0) to keep the line lengths within page limits. When present (such as this example), the #o lines provide the mnemonic (also known as mne) names corresponding to the positioner names from the #O lines.

The data from the #O and #P lines is written to /SCAN/positioners (a NXnote 1 group). /SCAN/positioners is also linked to /SCAN/instrument/positioners. See the Instrument section below.

Within the /SCAN/positioners/ group, each positioner (name and value) is written to a /SCAN/positioners/CLEAN_NAME NXpositioner 2 group. CLEAN_NAME is derived (via clean_name(spec_positioner_name)()). This change of names ensures the field 3 names in the NeXus HDF5 file conform to the NeXus standard. 4

If the SPEC menmonic for the positioner is available in the data file (from the #o control lines), it is also written as a @spec_mne attribute with both the name and value fields.

Note

Engineering units are not written

Generally, the @units attribute is not provided for any of the values written by spec2nexus (except where provided by custom support or for diffractometers as described later in section Geometry). SPEC data files do not provide the engineering units for any of the values and it is not possible to guess the appropriate type of units 5 to use. The NeXus documentation about data units 6 states:

… any field must have a units attribute which describes the units.

yet this is not a strict requirement. (The @units attribute is not marked required in the NeXus NXDL schema.)

 1positioners:NXnote
 2   @NX_class = "NXnote"
 3   @description = "SPEC positioners (#P & #O lines)"
 4   @target = "/S1/positioners"
 5   Theta:NXpositioner
 6     @NX_class = "NXpositioner"
 7     name:NX_CHAR = [b'Theta']
 8       @spec_mne = "th"
 9       @spec_name = "Theta"
10     value:NX_FLOAT64 = -0.80000004
11       @spec_mne = "th"
12       @spec_name = "Theta"
13   Two_Theta:NXpositioner
14     @NX_class = "NXpositioner"
15     name:NX_CHAR = [b'Two_Theta']
16       @spec_mne = "tth"
17       @spec_name = "Two Theta"
18     value:NX_FLOAT64 = -0.60000003
19       @spec_mne = "tth"
20       @spec_name = "Two Theta"
21   sample_x:NXpositioner
22     @NX_class = "NXpositioner"
23     name:NX_CHAR = [b'sample_x']
24       @spec_mne = "samx"
25       @spec_name = "sample x"
26     value:NX_FLOAT64 = -0.15875
27       @spec_mne = "samx"
28       @spec_name = "sample x"
29   sample_y:NXpositioner
30     @NX_class = "NXpositioner"
31     name:NX_CHAR = [b'sample_y']
32       @spec_mne = "samy"
33       @spec_name = "sample y"
34     value:NX_FLOAT64 = 0.16375
35       @spec_mne = "samy"
36       @spec_name = "sample y"

When the #o lines are present in the scan’s header, a cross-reference between mnemonic and name is written in /SCAN/positioner_cross_reference (a NXnote 1 group). This group describes a cross-reference between the field names of the positioner group and the positioner names used in the SPEC scan.

 1positioner_cross_reference:NXnote
 2   @NX_class = "NXnote"
 3   @comment = "keys are SPEC positioner mnemonics, values are SPEC positioner names"
 4   @description = "cross-reference SPEC positioner mnemonics and names"
 5   samx:NX_CHAR = [b'sample x']
 6     @field_name = "sample_x"
 7     @mne = "samx"
 8   samy:NX_CHAR = [b'sample y']
 9     @field_name = "sample_y"
10     @mne = "samy"
11   th:NX_CHAR = [b'Theta']
12     @field_name = "Theta"
13     @mne = "th"
14   tth:NX_CHAR = [b'Two Theta']
15     @field_name = "Two_Theta"
16     @mne = "tth"
1(1,2)

NXnote: https://manual.nexusformat.org/classes/base_classes/NXnote.html

2

NXpositioner: https://manual.nexusformat.org/classes/base_classes/NXpositioner.html

3

A NeXus field is the same as an HDF5 dataset. The rename is due to historical reasons in NeXus when XML was used as a back-end data file storage format.

4

https://manual.nexusformat.org/datarules.html#naming-conventions

5

List of NeXus unit categories: https://manual.nexusformat.org/nxdl-types.html#unit-categories-allowed-in-nxdl-specifications

6

https://manual.nexusformat.org/datarules.html#design-units