Merge branch 'main' into fairmat-2024-mpes

nexusformat · Dec 11, 2024 · 88ce3e6 · 88ce3e6
2 parents 034e884 + 54e0735
commit 88ce3e6
Show file tree

Hide file tree

Showing 32 changed files with 63 additions and 80 deletions.
diff --git a/applications/NXarchive.nxdl.xml b/applications/NXarchive.nxdl.xml
@@ -37,7 +37,7 @@
 	        a mechanism to link all aspects of ISIS research from 
 	        proposal through to publication. 
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <attribute name="index"></attribute>
       <field name="title" />
       <field name="experiment_identifier" type="NX_CHAR">

diff --git a/applications/NXarpes.nxdl.xml b/applications/NXarpes.nxdl.xml
@@ -38,12 +38,6 @@
     as well as a specialization for ARPES experiments, called :ref:`NXmpes_arpes`."
   </doc>
   <group type="NXentry">
-    <attribute name="entry">
-      <doc>
-        NeXus convention is to use "entry1", "entry2", ... 
-        for analysis software to locate each entry.
-      </doc>
-    </attribute>
     <field name="title" type="NX_CHAR"/>
     <field name="start_time" type="NX_DATE_TIME"/>
     <field name="definition">

diff --git a/applications/NXdirecttof.nxdl.xml b/applications/NXdirecttof.nxdl.xml
@@ -28,7 +28,7 @@
     xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
     >
     <doc>This is a application definition for raw data from a direct geometry TOF spectrometer</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXfluo.nxdl.xml b/applications/NXfluo.nxdl.xml
@@ -38,7 +38,7 @@
     <doc>
       This is an application definition for raw data from an X-ray fluorescence experiment
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXindirecttof.nxdl.xml b/applications/NXindirecttof.nxdl.xml
@@ -36,7 +36,7 @@
         </symbol>
     </symbols>
     <doc>This is a application definition for raw data from an indirect geometry TOF spectrometer</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXiqproc.nxdl.xml b/applications/NXiqproc.nxdl.xml
@@ -43,9 +43,6 @@
     </symbols>
     <doc>Application definition for any :math:`I(Q)` data.</doc>
     <group type="NXentry">
-        <attribute name="entry">
-          <!-- TODO documentation string needed here -->
-        </attribute>
         <field name="title"/>
       <field name="definition">
         <doc> Official NeXus NXDL schema to which this file conforms </doc>

diff --git a/applications/NXlauetof.nxdl.xml b/applications/NXlauetof.nxdl.xml
@@ -44,7 +44,7 @@
   <doc>
     This is the application definition for a TOF laue diffractometer
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/applications/NXmonopd.nxdl.xml b/applications/NXmonopd.nxdl.xml
@@ -47,7 +47,7 @@
         with a single detector or a powder diffractometer with a position 
         sensitive detector.
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
         <field name="title"/>
         <field name="start_time" type="NX_DATE_TIME"/>
         <field name="definition">

diff --git a/applications/NXrefscan.nxdl.xml b/applications/NXrefscan.nxdl.xml
@@ -41,7 +41,7 @@
     It does not have the information to calculate the resolution
     since it does not have any apertures.
   </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="end_time" type="NX_DATE_TIME" />

diff --git a/applications/NXreftof.nxdl.xml b/applications/NXreftof.nxdl.xml
@@ -42,7 +42,7 @@
 	  </symbol>
     </symbols>
     <doc>This is an application definition for raw data from a TOF reflectometer. </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="end_time" type="NX_DATE_TIME" />

diff --git a/applications/NXsastof.nxdl.xml b/applications/NXsastof.nxdl.xml
@@ -49,9 +49,6 @@
     at a time-of-flight source.
    </doc>
   <group type="NXentry">
-    <attribute name="entry">
-      <doc>NeXus convention is to use "entry1", "entry2", ... for analysis software to locate each entry</doc>
-    </attribute>
     <field name="title"/>
     <field name="start_time" type="NX_DATE_TIME"/>
     <field name="definition">

diff --git a/applications/NXsqom.nxdl.xml b/applications/NXsqom.nxdl.xml
@@ -43,7 +43,6 @@
     a sensible way.
   </doc>
   <group type="NXentry">
-    <attribute name="entry"> </attribute>
     <field name="title"/>
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>

diff --git a/applications/NXtas.nxdl.xml b/applications/NXtas.nxdl.xml
@@ -41,7 +41,7 @@
     It is for the trademark scan of the TAS, the Q-E scan. 
     For your alignment scans use the rules in :ref:`NXscan`.
   </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" type="NX_CHAR" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXtofnpd.nxdl.xml b/applications/NXtofnpd.nxdl.xml
@@ -39,7 +39,7 @@
       </symbol>
 	</symbols>
     <doc>This is a application definition for raw data from a TOF neutron powder diffractometer</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXtofraw.nxdl.xml b/applications/NXtofraw.nxdl.xml
@@ -39,7 +39,7 @@
       </symbol>
 	</symbols>
     <doc>This is an application definition for raw data from a generic TOF instrument</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXtofsingle.nxdl.xml b/applications/NXtofsingle.nxdl.xml
@@ -45,7 +45,7 @@
       </symbol>
 	</symbols>
     <doc>This is a application definition for raw data from a generic TOF instrument</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXtomo.nxdl.xml b/applications/NXtomo.nxdl.xml
@@ -48,7 +48,7 @@
           a number of dark field images are measured, some bright field images and, of course the sample. 
           In order to distinguish between them images carry a image_key.
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title"  minOccurs="0" maxOccurs="1"/> 
       <field name="start_time" type="NX_DATE_TIME"  minOccurs="0" maxOccurs="1"/> 
       <field name="end_time" type="NX_DATE_TIME"  minOccurs="0" maxOccurs="1"/> 

diff --git a/applications/NXtomophase.nxdl.xml b/applications/NXtomophase.nxdl.xml
@@ -55,7 +55,7 @@
       some dark field images are measured, some bright field images and, of course the sample. In order 
       to properly sort the order of the images taken, a sequence number is stored with each image.
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="end_time" type="NX_DATE_TIME" />

diff --git a/applications/NXtomoproc.nxdl.xml b/applications/NXtomoproc.nxdl.xml
@@ -40,7 +40,7 @@
         </symbol>
 	</symbols>
     <doc>This is an application definition for the final result of a tomography experiment: a 3D construction of some volume of physical properties.</doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="definition">
         <doc> Official NeXus NXDL schema to which this file conforms </doc>

diff --git a/applications/NXxas.nxdl.xml b/applications/NXxas.nxdl.xml
@@ -42,12 +42,6 @@
       absorbed beam.
     </doc>
     <group type="NXentry">
-        <attribute name="entry">
-            <doc>
-               NeXus convention is to use "entry1", "entry2", ... 
-               for analysis software to locate each entry.
-            </doc>
-        </attribute>
         <field name="title"/>
         <field name="start_time" type="NX_DATE_TIME"/>
         <field name="definition">

diff --git a/applications/NXxasproc.nxdl.xml b/applications/NXxasproc.nxdl.xml
@@ -39,12 +39,6 @@
        Processed data from XAS. This is energy versus I(incoming)/I(absorbed).
     </doc>
     <group type="NXentry">
-        <attribute name="entry">
-            <doc>
-                NeXus convention is to use "entry1", "entry2", ... 
-                for analysis software to locate each entry.
-            </doc>
-        </attribute>
         <field name="title"/>
       <field name="definition">
         <doc> Official NeXus NXDL schema to which this file conforms </doc>

diff --git a/applications/NXxbase.nxdl.xml b/applications/NXxbase.nxdl.xml
@@ -44,7 +44,7 @@
     <doc>
       This definition covers the common parts of all monochromatic single crystal raw data application definitions.
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="title" />
       <field name="start_time" type="NX_DATE_TIME" />
       <field name="definition">

diff --git a/applications/NXxeuler.nxdl.xml b/applications/NXxeuler.nxdl.xml
@@ -42,7 +42,7 @@
       of :ref:`NXxbase` plus the data defined here. All four angles are 
       logged in order to support arbitrary scans in reciprocal space.
     </doc>
-    <group type="NXentry" name="entry">
+    <group type="NXentry">
       <field name="definition">
         <doc> Official NeXus NXDL schema to which this file conforms </doc>
         <enumeration>

diff --git a/applications/NXxkappa.nxdl.xml b/applications/NXxkappa.nxdl.xml
@@ -44,7 +44,7 @@
     the content of :ref:`NXxbase` plus the
     data defined here.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/applications/NXxlaue.nxdl.xml b/applications/NXxlaue.nxdl.xml
@@ -41,7 +41,7 @@
     This is the application definition for raw data from a single crystal laue 
     camera. It extends :ref:`NXxrot`.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/applications/NXxlaueplate.nxdl.xml b/applications/NXxlaueplate.nxdl.xml
@@ -33,7 +33,7 @@
     This is the application definition for raw data from a single crystal Laue 
     camera with an image plate as a detector. It extends :ref:`NXxlaue`.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/applications/NXxnb.nxdl.xml b/applications/NXxnb.nxdl.xml
@@ -46,7 +46,7 @@
     logged in order to support arbitrary scans in
     reciprocal space.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/applications/NXxrot.nxdl.xml b/applications/NXxrot.nxdl.xml
@@ -42,7 +42,7 @@
     It extends :ref:`NXxbase`, so the full definition is the content of :ref:`NXxbase`
     plus the data defined here.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc>Official NeXus NXDL schema to which this file conforms.</doc>
       <enumeration>

diff --git a/base_classes/NXsource.nxdl.xml b/base_classes/NXsource.nxdl.xml
@@ -62,22 +62,16 @@
 			<item value="UV Plasma Source" />
 			<item value="Metal Jet X-ray" />
             <item value="Laser"/>
-            <item value="Dye-Laser"/>
+            <item value="Dye Laser"/>
             <item value="Broadband Tunable Light Source"/>
-            <item value="Halogen lamp"/>
+            <item value="Halogen Lamp"/>
             <item value="LED"/>
-            <item value="Mercury Cadmium Telluride"/>
+            <item value="Mercury Cadmium Telluride Lamp"/>
             <item value="Deuterium Lamp"/>
             <item value="Xenon Lamp"/>
             <item value="Globar"/>
-            <item value="other"/>
         </enumeration>
-    </field>
-    <field name="type_other">
-        <doc>
-             Specification of type, may also go to name.
-        </doc>
-    </field>
+	</field>
 	<field name="probe">
 		<doc>type of radiation probe (pick one from the enumerated list and spell exactly)</doc>
 		<enumeration>
@@ -246,11 +240,6 @@
 			 Deflectors inside the source.
 		</doc>
 	</group>
-	<group type="NXlens_em">
-		<doc>
-			 Individual electromagnetic lenses inside the source.
-		</doc>
-	</group>
 	<group type="NXfabrication"/>
 	<group type="NXoff_geometry" minOccurs="0">
 		<doc>

diff --git a/contributed_definitions/NXxpcs.nxdl.xml b/contributed_definitions/NXxpcs.nxdl.xml
@@ -47,7 +47,7 @@
     that this XPCS data will be part of multi-modal data set that could involve e.g., :ref:`NXcanSAS` or
     1D and/or 2D data.
   </doc>
-  <group type="NXentry" name="entry">
+  <group type="NXentry">
     <field name="definition">
       <doc> Official NeXus NXDL schema to which this file conforms </doc>
       <enumeration>

diff --git a/manual/source/design.rst b/manual/source/design.rst
@@ -519,6 +519,20 @@ But there are some base classes which have special uses which need to be mention
 These groups can appear anywhere in the NeXus hierarchy, where needed. Preferably close to the component they
 annotate or in a ``NXcollection``. All of the base classes are documented in the reference manual.
 
+.. _inheritance:
+
+Inheritance in NeXus
+--------------------
+
+Single inheritance is supported in NeXus for both base classes and application definitions (which are
+described below).  Extending a base class or application definition inherits the properties and objects of the
+parent class or definition, such as groups, fields, attributes, and symbol tables. These properties and objects
+of the parent can then be overridden by the subclass.  Only single inheritance is allowed (you can only inherit
+from a single parent).
+
+Use the ``@extends`` attribute of a definition to indicate which definition is being subclassed. Base classes
+should extend from ``NXobject`` unless they are being subclassed.
+
 .. _NXdata-facilitates-TheDefaultPlot:
 
 ``NXdata`` Facilitates Automatic Plotting
@@ -645,7 +659,7 @@ Yet another way to look at a NeXus application definition is to understand it as
 between data files and the software which uses this file. Much like an interface in the Java or other modern
 object oriented programming languages.
 
-In contrast to NeXus base classes, NeXus supports inheritance in application definitions.
+Like base classes, NeXus supports :ref:`inheritance` in application definitions.
 
 Please note that a NeXus Application Definition will only define the bare minimum of data necessary to perform
 common analysis with data. Practical files will nearly always contain more data. One of the beauties of NeXus is

diff --git a/manual/source/faq.rst b/manual/source/faq.rst
@@ -232,19 +232,24 @@ This is a list of commonly asked questions concerning the NeXus data format.
    class within the definition are valid instances of
    the original class, but not vice-versa?
 
-   Keep in mind that NeXus is not specifically object oriented.
-   The putative super class might be either
-   :ref:`NXentry` (for single-technique data, such as SAXS)
-   or :ref:`NXsubentry` (for multi-technique data
-   such as SAXS/WAXS/USAXS/GIWAXS or SAXS/SANS).
-
-   If you are thinking of a new application definition that uses
-   another as a starting point (like a super class), then there
-   is an ``extends`` attribute in the definition element of the
-   NXDL file (example here from :ref:`NXarpes`)::
-
-       <definition name="NXarpes" extends="NXobject" type="group"
-
-   which describes this relationship. For most (?all?) all NXDL
-   files to date, they extend the :ref:`NXobject` base class
-   (the base object of NeXus).
+   Yes.  When writing an application definition, you can
+   add additional metadata to base classes that are not in the
+   base class definition. This essentially sub-classes the
+   original base class.
+
+   This is different than using the ``extends`` attribute, which
+   can be used to make new base classes that inherit the properties
+   of the parent classes, or new application definitions that use
+   another as a starting point. For example the
+   ``NXelectron_detector`` base class extends the ``NXdetector``
+   base class::
+
+     <definition category="base" name="NXelectron_detector" extends="NXdetector">
+
+   This is similar to how the application definition ``NXdirecttof`` extends
+   the ``NXtofraw`` application definition::
+
+     <definition category="application" name="NXdirecttof" extends="NXtofraw">
+
+   Most NXDL files extend the :ref:`NXobject` base class (the base object
+   of NeXus).