Merge branch 'main' into nxbeam_fixup

nexusformat · Jun 17, 2022 · 30e3eaf · 30e3eaf
2 parents 7c3eeeb + 2bc28e8
commit 30e3eaf
Show file tree

Hide file tree

Showing 159 changed files with 2,562 additions and 1,323 deletions.
diff --git a/.github/workflows/publish-sphinx.yml b/.github/workflows/publish-sphinx.yml
@@ -1,5 +1,10 @@
 name: Publish Sphinx Docs to GitHub Pages
-on: [push]
+
+on:
+  # Triggers the workflow on push events but only for the main branch
+  push:
+    branches:
+      - main
 
 # see: https://sphinx-notes.github.io/pages/
 # see: https://github.com/marketplace/actions/sphinx-to-github-pages

diff --git a/.github/workflows/syntax-checks.yml b/.github/workflows/syntax-checks.yml
@@ -1,6 +1,13 @@
 name: Syntax Checks
 
-on: [push, pull_request]
+on:
+  # Triggers the workflow on push or pull request events but only for the main branch
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   build-linux:

diff --git a/applications/NXarpes.nxdl.xml b/applications/NXarpes.nxdl.xml
@@ -80,13 +80,13 @@
         <field name="entrance_slit_setting" type="NX_NUMBER" units="NX_ANY">
           <doc>dial setting of the entrance slit</doc>
         </field>
-        <field name="entrance_slit_size" units="NX_LENGTH">
+        <field name="entrance_slit_size" type="NX_NUMBER" units="NX_LENGTH">
           <doc>size of the entrance slit</doc>
         </field>
-        <field name="pass_energy" units="NX_ENERGY">
+        <field name="pass_energy" type="NX_NUMBER" units="NX_ENERGY">
           <doc>energy of the electrons on the mean path of the analyser</doc>
         </field>
-        <field name="time_per_channel" units="NX_TIME">
+        <field name="time_per_channel" type="NX_NUMBER" units="NX_TIME">
           <doc>todo: define more clearly</doc>
         </field>
         <field name="angles" type="NX_NUMBER" units="NX_ANGLE">

diff --git a/base_classes/NXaperture.nxdl.xml b/base_classes/NXaperture.nxdl.xml
@@ -27,10 +27,36 @@
     name="NXaperture" 
     type="group" extends="NXobject">
 
-    <doc>A beamline aperture.</doc>
+    <doc>A beamline aperture. This group is deprecated, use NXslit instead.</doc>
     <!-- TODO compare with "screens" in SHADOW -->
 
-    <group type="NXgeometry">
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        NeXus positions components by applying a set of translations and rotations
+        to apply to the component starting from 0, 0, 0. The order of these operations
+        is critical and forms what NeXus calls a dependency chain. The depends_on
+        field defines the path to the top most operation of the dependency chain or the
+        string "." if located in the origin. Usually these operations are stored in a
+        NXtransformations group. But NeXus allows them to be stored anywhere.
+
+        The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the
+        surface of the aperture pointing towards the source.
+
+        In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference.
+
+        .. image:: aperture/aperture.png
+            :width: 40%
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        This is the group recommended for holding the chain of translation
+        and rotation operations necessary to position the component within
+        the instrument. The dependency chain may however traverse similar groups in
+        other component groups.
+       </doc>
+    </group>
+    <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` to position the aperture and :ref:`NXoff_geometry` to describe its shape">
         <doc>
             location and shape of aperture
 
@@ -41,9 +67,10 @@
                 * Similar throughout base classes
                 * Some base classes do this much better
                 * Such as where is the gap written?
+
         </doc>
     </group>
-    <group name="BLADE_GEOMETRY" type="NXgeometry">
+    <group name="BLADE_GEOMETRY" type="NXgeometry" deprecated="Use :ref:`NXoff_geometry` instead to describe the shape of the aperture">
         <doc>location and shape of each blade</doc>
     </group>
     <field name="material"><!-- TODO Uniformity problem, "type" is used elsewhere for same context -->

diff --git a/base_classes/NXattenuator.nxdl.xml b/base_classes/NXattenuator.nxdl.xml
@@ -40,11 +40,11 @@
     </doc>
     <!-- 
         TODO compare with SHADOW definition "screen"
-        TODO  SHADOW: http://ftp.esrf.eu/pub/scisoft/shadow       or (older)   http://www.nanotech.wisc.edu/shadow  
+        TODO  SHADOW: https://github.com/oasys-kit/shadow3
     -->
 
     <field name="distance" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>Distance from sample</doc>
+        <doc>Distance from sample. Note, it is recommended to use NXtransformations instead.</doc>
     </field>
     <field name="type">
         <doc>Type or composition of attenuator, e.g. polythene</doc>
@@ -88,4 +88,36 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        NeXus positions components by applying a set of translations and rotations
+        to apply to the component starting from 0, 0, 0. The order of these operations
+        is critical and forms what NeXus calls a dependency chain. The depends_on
+        field defines the path to the top most operation of the dependency chain or the
+        string "." if located in the origin. Usually these operations are stored in a
+        NXtransformations group. But NeXus allows them to be stored anywhere.
+
+        The reference point of the attenuator is its center in the x and y axis. The reference point on the z axis is the
+        surface of the attenuator pointing towards the source.
+
+        In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference.
+
+        .. image:: attenuator/attenuator.png
+            :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        This is the group recommended for holding the chain of translation
+        and rotation operations necessary to position the component within
+        the instrument. The dependency chain may however traverse similar groups in
+        other component groups.
+      </doc>
+    </group>
+    <group name="shape" type="NXoff_geometry">
+      <doc>
+        Shape of this component. Particulary useful to define the origin for position and orientation in non-standard cases.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXbeam.nxdl.xml b/base_classes/NXbeam.nxdl.xml
@@ -55,7 +55,7 @@
         by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam.
         </doc>
     <field name="distance" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>Distance from sample</doc>
+        <doc>Distance from sample. Note, it is recommended to use NXtransformations instead.</doc>
     </field>
     <field name="incident_energy" type="NX_FLOAT" units="NX_ENERGY">
         <doc>Energy carried by each particle of the beam on entering the beamline component</doc>
@@ -261,4 +261,77 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+
+    <field name="depends_on" minOccurs="0" type="NX_CHAR">
+        <doc>
+            The NeXus coordinate system defines the Z axis to be along the nominal beam
+            direction. This is the same as the McStas coordinate system (see :ref:Design-CoordinateSystem).
+            However, the additional transformations needed to represent an altered beam
+            direction can be provided using this depends_on field that contains the path
+            to a NXtransformations group. This could represent redirection of the beam,
+            or a refined beam direction.
+        </doc>
+    </field>
+
+    <group type="NXtransformations" minOccurs="0">
+        <doc>
+            Direction (and location) for the beam. The location of the beam can be given by
+            any point which it passes through as its offset attribute.
+        </doc>
+        <field name="DIRECTION" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER">
+            <doc>
+                Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1]
+                and passes through the origin
+            </doc>
+            <attribute name="transformation_type">
+                <enumeration>
+                    <item value="translation" />
+                </enumeration>
+            </attribute>
+            <attribute name="vector" type="NX_NUMBER">
+                <doc>
+                    Three values that define the direction of beam vector
+                </doc>
+            </attribute>
+            <attribute name="offset" type="NX_NUMBER">
+                <doc>
+                    Three values that define the location of a point through which the beam passes
+                </doc>
+            </attribute>
+            <attribute name="depends_on" type="NX_CHAR">
+                <doc>
+                    Points to the path to a field defining the location on which this
+                    depends or the string "." for origin.
+                </doc>
+            </attribute>
+        </field>
+        <field name="reference_plane" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER">
+            <doc>
+                Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored.
+                This also defines the parallel and perpendicular components of the beam's polarization.
+                If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin
+            </doc>
+            <attribute name="transformation_type">
+                <enumeration>
+                    <item value="translation" />
+                </enumeration>
+            </attribute>
+            <attribute name="vector" type="NX_NUMBER">
+                <doc>
+                    Three values that define the direction of reference plane normal
+                </doc>
+            </attribute>
+            <attribute name="offset" type="NX_NUMBER">
+                <doc>
+                    Not required as beam direction offset locates the plane
+                </doc>
+            </attribute>
+            <attribute name="depends_on" type="NX_CHAR">
+                <doc>
+                    Points to the path to a field defining the location on which this
+                    depends or the string "." for origin.
+                </doc>
+            </attribute>
+        </field>
+    </group>
 </definition>
diff --git a/base_classes/NXbeam_stop.nxdl.xml b/base_classes/NXbeam_stop.nxdl.xml
@@ -33,7 +33,7 @@
         Beamstops and their positions are important for SANS
         and SAXS experiments.
     </doc>
-    <group type="NXgeometry">
+    <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` to position the beamstop and NXoff_geometry to describe its shape instead">
         <doc>engineering shape, orientation and position of the beam stop.</doc>
     </group>
     <field name="description">
@@ -43,17 +43,40 @@
             <item value="rectangular"/>
         </enumeration>
         </field>
-    <field name="size" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>size of beamstop</doc>
-    </field>
+<group type="NXoff_geometry" minOccurs="0">
+ <doc>
+   This group describes the shape of the beam line component
+  </doc>
+</group>
+<group type="NXcylindrical_geometry" minOccurs="0">
+ <doc>
+   This group is an alternative to NXoff_geometry for describing the shape
+   of the beam stop. 
+  </doc>
+</group>
+<field name="size" type="NX_FLOAT" units="NX_LENGTH">
+  <doc>
+    Size of beamstop. If this is not sufficient to describe the beam stop use
+    NXoff_geometry instead.
+  </doc>
+</field>
     <field name="x" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>x position of the beamstop in relation to the detector</doc>
+        <doc>
+          x position of the beamstop in relation to the detector.
+          Note, it is recommended to use NXtransformations instead.
+        </doc>
     </field>
     <field name="y" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>y position of the beamstop in relation to the detector</doc>
+        <doc>
+          y position of the beamstop in relation to the detector.
+          Note, it is recommended to use NXtransformations instead.
+        </doc>
     </field>
     <field name="distance_to_detector" type="NX_FLOAT" units="NX_LENGTH">
-        <doc>distance of the beamstop to the detector</doc>
+        <doc>
+          distance of the beamstop to the detector.
+          Note, it is recommended to use NXtransformations instead.
+        </doc>
     </field>
     <field name="status">
         <enumeration>
@@ -74,4 +97,29 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        NeXus positions components by applying a set of translations and rotations
+        to apply to the component starting from 0, 0, 0. The order of these operations
+        is critical and forms what NeXus calls a dependency chain. The depends_on
+        field defines the path to the top most operation of the dependency chain or the
+        string "." if located in the origin. Usually these operations are stored in a
+        NXtransformations group. But NeXus allows them to be stored anywhere.
+
+        The reference point of the beam stop is its center in the x and y axis. The reference point on the z axis is the
+        surface of the beam stop pointing towards the source.
+
+        .. image:: beam_stop/beam_stop.png
+          :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        This is the group recommended for holding the chain of translation
+        and rotation operations necessary to position the component within
+        the instrument. The dependency chain may however traverse similar groups in
+        other component groups.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXbending_magnet.nxdl.xml b/base_classes/NXbending_magnet.nxdl.xml
@@ -41,11 +41,13 @@
   <field name="source_distance_x" type="NX_FLOAT" units="NX_LENGTH">
     <doc>
       Distance of source point from particle beam waist in X (horizontal) direction.
+      Note, it is recommended to use NXtransformations instead to place component.
     </doc>
   </field>
   <field name="source_distance_y" type="NX_FLOAT" units="NX_LENGTH">
     <doc>
       Distance of source point from particle beam waist in Y (vertical) direction.
+      Note, it is recommended to use NXtransformations instead to place component.
     </doc>
   </field>
   <field name="divergence_x_plus" type="NX_FLOAT" units="NX_ANGLE">
@@ -73,7 +75,12 @@
     </doc>
   </field>
 	<group name="spectrum" type="NXdata"><doc>bending magnet spectrum</doc></group>
-  <group type="NXgeometry"><doc>"Engineering" position of bending magnet</doc></group>
+  <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` to position the bending magnet and NXoff_geometry to describe its shape instead"><doc>"Engineering" position of bending magnet</doc></group>
+  <group type="NXoff_geometry" minOccurs="0">
+   <doc>
+     This group describes the shape of the beam line component
+    </doc>
+  </group>
   <attribute name="default">
       <doc>
           .. index:: plotting
@@ -87,5 +94,27 @@
           for a summary of the discussion.
       </doc>
   </attribute>
+  <field name="depends_on" type="NX_CHAR">
+    <doc>
+        NeXus positions components by applying a set of translations and rotations
+        to apply to the component starting from 0, 0, 0. The order of these operations
+        is critical and forms what NeXus calls a dependency chain. The depends_on
+        field defines the path to the top most operation of the dependency chain or the
+        string "." if located in the origin. Usually these operations are stored in a
+        NXtransformations group. But NeXus allows them to be stored anywhere.
+
+        .. todo::
+          Add a definition for the reference point of a bending magnet.
+
+    </doc>
+  </field>
+  <group type="NXtransformations">
+    <doc>
+        This is the group recommended for holding the chain of translation
+        and rotation operations necessary to position the component within
+        the instrument. The dependency chain may however traverse similar groups in
+        other component groups.
+    </doc>
+  </group>
 
 </definition>