Fairmat 2024: proposal on photoemission spectroscopy (MPES)

applications/NXarpes.nxdl.xml

@@ -30,7 +30,12 @@
   <doc>
     This is an application definition for angular resolved photo electron spectroscopy.
 
-    It has been drawn up with hemispherical electron analysers in mind. 
+    It has been drawn up with hemispherical electron analysers in mind.
+
+    This definition is a legacy support for older NXarpes experiments.
+    There is, however, a newer definition to collect data &amp; metadata
+    for general photoemission experiments, called :ref:`NXmpes`,
+    as well as a specialization for ARPES experiments, called :ref:`NXmpes_arpes`."
   </doc>
   <group type="NXentry">
     <field name="title" type="NX_CHAR"/>
@@ -125,4 +130,4 @@
     </group>
     <group type="NXdata"/>
   </group>
-</definition>
+</definition>

base_classes/NXactivity.nxdl.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+<!--
+# NeXus - Neutron and X-ray Common Data Format
+# 
+# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
+# 
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# For further information, see http://www.nexusformat.org
+-->
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXactivity" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <doc>
+         A planned or unplanned action that has a temporal extension and for some time depends on some entity.
+
+         This class is planned be used in the future as the super class for all other activities if inheritance 
+         in base classes is supported in NeXus.
+    </doc>
+    <field name="start_time" type="NX_DATE_TIME">
+        <doc>
+             ISO 8601 formatted time code (with local time zone offset to UTC information
+             included) when this activity started.
+        </doc>
+    </field>
+    <field name="end_time" type="NX_DATE_TIME">
+        <doc>
+             ISO 8601 formatted time code (with local time zone offset to UTC information
+             included) when this activity ended.
+        </doc>
+    </field>
+    <field name="description">
+        <doc>
+             Short description of the activity.
+        </doc>
+    </field>
+    <group name="notes" type="NXnote">
+        <doc>
+             This can be any data or other descriptor acquired during the activity
+             (NXnote allows to add pictures, audio, movies). Alternatively, a
+             reference to the location or a unique identifier or other metadata file. In the
+             case these are not available, free-text description.
+        </doc>
+    </group>
+</definition>

base_classes/NXbeam.nxdl.xml

@@ -61,11 +61,45 @@
         <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>
+        <doc>
+            Energy carried by each particle of the beam on entering the beamline component.
+
+            In the case of a monochromatic beam this is the scalar energy.
+            Several other use cases are permitted, depending on the
+            presence of other incident_energy_X fields.
+
+            * In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights.
+            * In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot.
+              Here, incident_energy_weights and incident_energy_spread are not set.
+            * In the case of a polychromatic beam that varies shot-to-shot,
+              this is an array of length m with the relative weights in incident_energy_weights as a 2D array.
+            * In the case of a polychromatic beam that varies shot-to-shot and where the channels also vary,
+              this is a 2D array of dimensions nP by m (slow to fast) with the relative weights in incident_energy_weights as a 2D array.
+
+            Note, variants are a good way to represent several of these use cases in a single dataset,
+            e.g. if a calibrated, single-value energy value is available along with the original spectrum from which it was calibrated.
+       </doc>
         <dimensions rank="1">
             <dim index="1" value="m"/>
         </dimensions>
     </field>
+    <field name="incident_energy_spread" type="NX_NUMBER" units="NX_ENERGY">
+        <doc>
+             The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in
+             the energy spread, this is a 2D array of dimension nP by m
+             (slow to fast) of the spreads of the corresponding
+             wavelength in incident_wavelength.
+        </doc>
+    </field>
+    <field name="incident_energy_weights" type="NX_NUMBER" units="NX_ENERGY">
+        <doc>
+             In the case of a polychromatic beam this is an array of length m of the relative
+             weights of the corresponding energies in incident_energy. In the case of a
+             polychromatic beam that varies shot-to-shot, this is a 2D array of dimensions np
+             by m (slow to fast) of the relative weights of the corresponding energies in
+             incident_energy.
+        </doc>
+    </field>
     <field name="final_energy" type="NX_FLOAT" units="NX_ENERGY">
         <doc>Energy carried by each particle of the beam on leaving the beamline component</doc>
         <dimensions rank="1">
@@ -160,7 +194,9 @@
     <field name="extent" type="NX_FLOAT" units="NX_LENGTH">
         <doc>
             Size of the beam entering this component. Note this represents
-            a rectangular beam aperture, and values represent FWHM
+            a rectangular beam aperture, and values represent FWHM.
+            If applicable, the first dimension shall be the horizontal extent
+            and the second dimension shall be the vertical extent.
         </doc>
         <dimensions rank="2">
             <dim index="1" value="nP"/>
@@ -179,13 +215,49 @@
             <dim index="1" value="nP"/>
             <dim index="2" value="2"/>
         </dimensions>
+        <attribute name="units" type="NX_CHAR">
+            <doc>
+                 The units for this observable are not included in the NIAC list.
+                 Responsibility on correct formatting and parsing is handed to the user
+                 by using `NX_ANY`. Correct parsing can still be implemented by using
+                 this attribute.
+
+                 | Fill with:
+
+                 * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla).
+                 * The unit unidata name if the unit has a name (Example: farad for capacitance).
+                 * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and
+                   does not have a name.
+
+                 Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2).
+                 Here: SI units are V2/m2.
+            </doc>
+        </attribute>
     </field>
     <field name="final_polarization" type="NX_NUMBER" units="NX_ANY">
         <doc>Polarization vector on leaving beamline component</doc>
         <dimensions rank="2">
             <dim index="1" value="nP"/>
             <dim index="2" value="2"/>
         </dimensions>
+        <attribute name="units" type="NX_CHAR">
+            <doc>
+                 The units for this observable are not included in the NIAC list.
+                 Responsibility on correct formatting and parsing is handed to the user
+                 by using `NX_ANY`. Correct parsing can still be implemented by using
+                 this attribute.
+
+                 | Fill with:
+
+                 * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla).
+                 * The unit unidata name if the unit has a name (Example: farad for capacitance).
+                 * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and
+                   does not have a name.
+
+                 Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2).
+                 Here: SI units are V2/m2.
+            </doc>
+        </attribute>
     </field>
     <field name="incident_polarization_stokes" type="NX_NUMBER" units="NX_ANY">
         <doc>
@@ -245,6 +317,87 @@
             <dim index="1" value="nP"/>
         </dimensions>
     </field>
+    <field name="pulse_energy" type="NX_FLOAT" units="NX_ENERGY">
+        <doc>
+             Energy of a single pulse at the diagnostic point
+        </doc>
+    </field>
+    <field name="average_power" type="NX_FLOAT" units="NX_POWER">
+        <doc>
+             Average power at the diagnostic point
+        </doc>
+    </field>
+    <field name="fluence" type="NX_FLOAT" units="NX_ANY">
+        <doc>
+             Incident fluence at the diagnostic point
+        </doc>
+        <attribute name="units" type="NX_CHAR">
+            <doc>
+                 Here: SI units are 'J/m2', customary 'mJ/cm2'.
+            </doc>
+        </attribute>
+    </field>
+    <field name="pulse_duration" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             FWHM duration of the pulses at the diagnostic point
+        </doc>
+    </field>
+    <field name="pulse_delay" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             Delay time between two pulses of a pulsed beam.
+        </doc>
+        <attribute name="reference_beam" type="NX_CHAR">
+            <doc>
+                 A reference to the beam in relation to which the delay is.
+            </doc>
+        </attribute>
+    </field>
+    <field name="frog_trace" type="NX_FLOAT">
+        <doc>
+             FROG trace of the pulse.
+        </doc>
+        <dimensions rank="2">
+            <dim index="1" value="nx"/>
+            <dim index="2" value="ny"/>
+        </dimensions>
+    </field>
+    <field name="frog_delays" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             Horizontal axis of a FROG trace, i.e. delay.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="nx"/>
+        </dimensions>
+    </field>
+    <field name="frog_frequencies" type="NX_FLOAT" units="NX_FREQUENCY">
+        <doc>
+             Vertical axis of a FROG trace, i.e. frequency.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="ny"/>
+        </dimensions>
+    </field>
+    <field name="chirp_type" type="NX_CHAR">
+        <doc>
+             The type of chirp implemented
+        </doc>
+    </field>
+    <field name="chirp_GDD" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             Group delay dispersion of the pulse for linear chirp
+        </doc>
+    </field>
+    <field name="previous_device">
+        <doc>
+             Indicates the beam device from which this beam originates.
+             This defines, whether the beam in an "input" or "output" beam.
+        </doc>
+    </field>
+    <field name="next_device">
+        <doc>
+             Gives the beam device which this beam will interact with next.
+        </doc>
+    </field>
     <group type="NXdata">
         <doc>
             Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly