Added feedback from the June2022 nexus code camp in preparation for p…

…ulling fairmat-em into NeXus 2022.06

contributed_definitions/NXaperture_em.nxdl.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" ?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+<definition category="base" extends="NXobject" name="NXaperture_em" type="group" xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/XMLSchema-instance">
+    <doc>
+         Details of an individual aperture for electron beams.
+    </doc>
+    <field name="name" type="NX_CHAR">
+        <doc>
+             Given name/alias of the aperture.
+        </doc>
+    </field>
+    <group type="NXmanufacturer"/>
+    <field name="value" type="NX_NUMBER" units="NX_ANY">
+        <doc>
+             Relevant value from the control software.
+
+             This is not always just the diameter of (not even in the case)
+             of a circular aperture. Usually it is a mode setting value which
+             is selected in the control software.
+             Which settings are behind the value should be defined
+             for now in the description field, if these are known
+             in more detail.
+        </doc>
+    </field>
+    <field name="description" type="NX_CHAR">
+        <doc>
+             Ideally, a (globally) unique persistent identifier, link, or text to a
+             resource which gives further details. Alternatively a free-text field.
+        </doc>
+    </field>
+    <group type="NXtransformations">
+        <doc>
+             Affine transformation which detail the arrangement in the 
+             microscope relative to the optical axis and beam path.
+        </doc>
+    </group>
+</definition>

contributed_definitions/NXcoordinate_system_set.nxdl.xml

@@ -4,38 +4,59 @@
     <doc>
          Container to hold different coordinate systems conventions.
 
-         By default NeXus uses the McStas coordinate system, whose axis convention 
-         is so that the z axis is along the neutron propagation axis, 
-         the y axis is vertical up, and the x axis points left when looking along
-         the z-axis, completing a right-handed coordinate system.
-         Assuming the McStas coordinate system as the reference (indicated by &quot;.&quot;),
-         a specific experiment or simulation may defined further coordinate systems.
-
          It is the purpose of this base class to define these conventions and
-         offer a place to store mappings between coordinate systems.
+         offer a place to store mappings between different coordinate systems
+         which are relevant for the interpretation of the data described
+         by the application definition and base class instances.
+
+         For each Cartesian coordinate system users should use a set of
+         NXtransformations:
 
-         For each coordinate system one should use a set of NXtransformations to define:
-         * The axis conventions
-         * The affine transformations which bring each axis of this coordinate system
-         into registration with the McStas coordinate system.
-         * Equally affine transformations from the inverse mapping should be specified.
+         * These should define the three base vectors.  
+         * The location of the origin.  
+         * The affine transformations which bring each axis of this coordinate system  
+           into registration with the McStas coordinate system.  
+         * Equally, affine transformations should be given for the inverse mapping.  
 
          As an example one may take an experiment or computer simulation where
          there is a laboratory (lab) coordinate system, a sample/specimen coordinate
          system, a crystal coordinate system, and additional coordinate systems,
          which are eventually attached to components of the instrument.
 
          If no additional transformation is specified in this group or if an
-         instance of an NXcoordinate_system_set is absent it should be assumed the
-         McStas coordinate system is used.
+         instance of an NXcoordinate_system_set is absent it should be assumed
+         the so-called McStas coordinate system is used.
+
+         Many application definitions in NeXus refer to this `McStas &lt;https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html&gt;`_ coordinate system.
+         This is a Cartesian coordinate system whose z axis points along the neutron 
+         propagation axis. The systems y axis is vertical up, while the x axis points
+         left when looking along the z-axis. Thus, McStas is a right-handed coordinate system.
+
+         Within each NXtransformations a depends_on section is required. The depends_on
+         field specifies if the coordinate system is the root/reference
+         (which is indicated by writing &quot;.&quot; in the depends_on section.)
     </doc>
     <group type="NXtransformations">
         <doc>
              A group of transformations which specify:
-             * Base vectors of a coordinate system.
-             * How to map each base vector to the McStas coordinate system.
-             * How to map each McStas base vector to the coordinate system,
-             i.e. the inverse mapping.
+
+             * Three base vectors of the coordinate system.  
+             * Origin of the coordinate system.  
+             * A depends_on keyword. Its value can be &quot;.&quot; or the name of an  
+               NXtransformations instance which needs to exist in the  
+               NXcoordinate_system_set instance.  
+             * If the coordinate system is the reference one it has to be named  
+               reference.  
+
+             In case of having more than one NXtransformations there has to be for  
+             each additional coordinate system, i.e. the one not the reference:
+
+             * A set of translations and rotations which map each base vector to the reference.  
+             * A set of translations and rotations which map each reference base vector  
+               to the coordinate system.  
+
+             The NXtransformations for these mappings need to be formatted
+             according to the descriptions in NXtransformations.
         </doc>
     </group>
 </definition>

contributed_definitions/NXion.nxdl.xml

@@ -18,7 +18,7 @@
         </symbol>
     </symbols>
     <doc>
-         Set of atoms of a molecular ion or fragment in ToF mass spectrometry.
+         Set of atoms of a molecular ion or fragment in e.g. ToF mass spectrometry.
     </doc>
     <field name="ion_type" type="NX_UINT" units="NX_UNITLESS">
         <doc>
@@ -29,14 +29,16 @@
     <field name="isotope_vector" type="NX_UINT" units="NX_UNITLESS">
         <doc>
              A vector of isotope hash values.
-             These values have to be stored in a decreasingly sorted array.
+             These values have to be stored in an array, sorted in decreasing order.
              The array is filled with zero hash values indicating unused places.
              The individual hash values are built with the following hash function:
-             * hash_value = Z + N*256 with Z the number of protons and N the
-             number of neutrons of the isotope respectively.
+
+             The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z`
+             the number of protons and :math:`N` the number of neutrons
+             of each isotope respectively.
+
              Z and N have to be 8-bit unsigned integers.
-             For the rationale behind this:
-             * [M. Kühbach et al.](https://doi.org/10.1017/S1431927621012241)
+             For the rationale behind this `M. Kühbach et al. (2021) &lt;https://doi.org/10.1017/S1431927621012241&gt;`_
         </doc>
         <dimensions rank="1">
             <dim index="1" value="n_ivecmax"/>
@@ -58,18 +60,17 @@
              surplus the mass-to-charge-state-ratio interval.
              With this it is possible to recover the charge state only for
              specific molecular ions as the accumulated mass of the molecular ion
-             is defined by the isotopes which without knowing the charge leads
+             is defined by the isotopes, which without knowing the charge leads
              to an underconstrained problem.
-             Details on ranging can be found in the literature:
-             * [M. K. Miller](https://doi.org/10.1002/sia.1719)
+             Details on ranging can be found in the literature: `M. K. Miller &lt;https://doi.org/10.1002/sia.1719&gt;`_
         </doc>
     </field>
     <field name="name" type="NX_CHAR">
         <doc>
              Human-readable ion type name (e.g. Al +++)
              The string should consists of ASCII UTF-8 characters, 
              ideally using LaTeX notation to specify the isotopes, ions, and charge
-             state. Examples are 12C+ or Al+++.
+             state. Examples are 12C + or Al +++.
              Although this name may be human-readable and intuitive, parsing such
              names becomes impractical for more complicated cases. Therefore, the
              isotope_vector should be the preferred machine-readable format to use.

contributed_definitions/NXlens_em.nxdl.xml

@@ -4,15 +4,16 @@
     <doc>
          Description of an electro-magnetic lens or a compound lens.
 
-         Details of an [electro-magnetic lens](https://dx.doi.org/10.1007/978-3-540-38967-5).
-
          For NXtransformations the origin of the coordinate system is placed
-         in the center of the lens (its polepiece, pinhole, or another point of
-         reference. The origin should be specified in the NXtransformations.
+         in the center of the lens
+         (its polepiece, pinhole, or another point of reference).
+         The origin should be specified in the NXtransformations.
+
+         For details of electro-magnetic lenses in the literature see e.g. `L. Reimer &lt;https://doi.org/10.1007/978-3-540-38967-5&gt;`_
     </doc>
     <field name="type" type="NX_CHAR">
         <doc>
-             Qualitative type of lens with respect to the number of pole pieces
+             Qualitative type of lens with respect to the number of pole pieces.
         </doc>
         <enumeration>
             <item value="single"/>
@@ -24,8 +25,8 @@
     </field>
     <field name="name" type="NX_CHAR">
         <doc>
-             Colloquial or short name for the lens. For manufacturer names and identifiers
-             use respective manufacturer fields.
+             Given name, alias, colloquial, or short name for the lens.
+             For manufacturer names and identifiers use respective manufacturer fields.
         </doc>
     </field>
     <field name="manufacturer_name" type="NX_CHAR">
@@ -66,10 +67,11 @@
     </field>
     <group type="NXtransformations">
         <doc>
-             Collection of axis-based translations and rotations to describe the location and
-             geometry of the lens as a component in the instrument. Typically, the components
-             of a system should all be related relative to each other and only one component
-             should relate to the reference coordinate system.
+             Collection of axis-based translations and rotations to describe the
+             location and geometry of the lens as a component in the instrument.
+             Typically, the components of a system should all be related relative to
+             each other and only one component should relate to the reference
+             coordinate system.
         </doc>
     </group>
 </definition>

contributed_definitions/NXpeak.nxdl.xml

@@ -23,13 +23,18 @@
     <field name="peak_model" type="NX_CHAR">
         <doc>
              Is the peak described analytically via a functional form
-             or is it empirically via measured/reported intensity/counts
-             as a function of an independent variable.
+             or is it empirically defined via measured/reported
+             intensity/counts as a function of an independent variable.
+
+             If the functional form is not empirical or gaussian, users
+             should enter other for the peak_model and add relevant details
+             in the NXcollection.
         </doc>
         <enumeration>
             <item value="empirical"/>
             <item value="gaussian"/>
             <item value="lorentzian"/>
+            <item value="other"/>
         </enumeration>
     </field>
     <field name="position" type="NX_NUMBER" units="NX_ANY">
@@ -52,9 +57,10 @@
     </field>
     <group type="NXcollection">
         <doc>
-             In the case of an analytical description holds parameter(s)
-             of the functional form. For example in the case of Gaussians
-             mu, sigma, cut-off values, and background intensity.
+             In the case of an analytical description (or if peak_model is other) this
+             collection holds parameter of (and eventually) the functional form.
+             For example in the case of Gaussians mu, sigma, cut-off values, 
+             and background intensity are relevant parameter.
         </doc>
     </group>
 </definition>

contributed_definitions/NXpulser_apm.nxdl.xml

@@ -12,13 +12,17 @@
         </symbol>
     </symbols>
     <doc>
-         Laser-, voltage-, or combined- pulsing to trigger field evaporation.
+         Metadata for laser-, voltage-, or combined pulsing triggering field evaporation.
     </doc>
     <field name="pulse_mode" type="NX_CHAR">
         <doc>
              How is field evaporation physically triggered.
-             enumeration: [laser, high_voltage, laser_and_high_voltage]
         </doc>
+        <enumeration>
+            <item value="laser"/>
+            <item value="high_voltage"/>
+            <item value="laser_and_high_voltage"/>
+        </enumeration>
     </field>
     <field name="pulse_frequency" type="NX_NUMBER" units="NX_FREQUENCY">
         <doc>
@@ -46,12 +50,12 @@
             <dim index="1" value="n_ions"/>
         </dimensions>
     </field>
-    <group name="laser_pulser" type="NXsource">
+    <group name="laser_gun" type="NXsource">
         <doc>
              Atom probe microscopes use controlled laser, voltage,
              or a combination of pulsing strategies to trigger the
              excitation and eventual field evaporation/emission of
-             an ion in an atom probe microscopy experiment.
+             an ion during an atom probe microscopy experiment.
         </doc>
         <field name="name" type="NX_CHAR">
             <doc>

contributed_definitions/NXreflectron.nxdl.xml

@@ -13,7 +13,7 @@
     <field name="description" type="NX_CHAR">
         <doc>
              Free-text field to specify further details about the reflectron.
-             The field inform e.g. if the reflectron is flat or curved.
+             The field can be used to inform e. g. if the reflectron is flat or curved.
         </doc>
     </field>
     <group type="NXtransformations">