--- NXmx_1_4.nxdl.xml	2016-10-05 16:35:39.000000000 +0200
+++ definitions/applications/NXmx.nxdl.xml	2016-10-14 07:18:37.000000000 +0200
@@ -22,27 +22,36 @@
   # For further information, see http://www.nexusformat.org 
 -->
 <definition name="NXmx" extends="NXobject" type="group"
-	version="1.4" category="application"
+		version="1.5" category="application"
 	xmlns="http://definition.nexusformat.org/nxdl/3.1"
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
 	>
 
 	<symbols>
-		<!-- TODO define options for most fields to allow them to be either scaler 
-			np i,j np,i,j So indices can be aligned sensibly in an automated way. -->
+			<!-- TODO define options for most fields to allow them to be either scalar
+				or arrays indexed by np, i, j, k, ...,
+			-->
 		<doc>
                   These symbols will be used below to coordinate datasets
-                  with the same shape.
+				with the same shape.  Most MX x-ray detectors will produce
+				two-dimensional images.  Some will produce three-dimensional
+				images, using one of the indices to select a detector element. 
 		</doc>
+			<symbol name="dataRank">
+				<doc>rank of the ``data`` field</doc>
+			</symbol>
 		<symbol name="np">
 			<doc>number of scan points</doc>
 		</symbol>
 		<symbol name="i">
-			<doc>number of detector pixels in the slow direction</doc>
+				<doc>number of detector pixels in the slowest direction</doc>
 		</symbol>
 		<symbol name="j">
-			<doc>number of detector pixels in the fast direction</doc>
+				<doc>number of detector pixels in the second slowest direction</doc>
+			</symbol>
+			<symbol name="k">
+				<doc>number of detector pixels in the third slowest direction</doc>
 		</symbol>
 	</symbols>
 
@@ -70,8 +79,73 @@
 					minOccurs="0" />
 			</group>
 
+				<group type="NXdetector_group" minOccurs="0">
+					<doc>
+					Optional logical grouping of detector elements.
+
+					Each detector element is represented as an NXdetector group
+					with its own detector data array.  Each detector data array
+					may be further decomposed into array sections by use of
+					NXdetector_module groups.  The names are given in the
+					group names field.
+
+					The groups are defined hierarchically, with names given
+					in the group_names field, unique identifiing indices given
+					in the field group_index, and the level in the hierarchy
+					given in the group_parent field.  For example if an x-ray
+					detector, DET, consists of four elements in a rectangular array::
+							 
+							 DTL	DTR
+							 DLL	DLR
+							 
+					We could have::
+						
+						 group_names: ["DET", "DTL", "DTR", "DLL", "DLR"]
+						 group_index: [1, 2, 3, 4, 5]
+						 group_parent:  [-1, 1, 1, 1, 1]
+
+					</doc>
+
+					<field name="group_names" type="NX_CHAR">
+						<doc>
+						An array of the names of the detector elements or hierarchical
+						groupings of detector elements.
+						
+						Specified in the base classes as comma separated list of names,
+						but new code should use an array of names as quoted strings.
+						</doc>
+						<dimensions><dim index="1" ref="group_index"/></dimensions>
+					</field>
+
+					<field name="group_index" type="NX_INT">
+						<doc>
+						An array of unique indices for detector elements or groupings
+						of detector elements.
+						
+						Each element is a unique ID for the corresponding group named
+						in the field group_names.  The IDs are positive integers starting
+						with 1.
+						</doc>
+						<dimensions><dim index="1" value="i"/></dimensions>
+					</field>
+
+					<field name="group_parent" type="NX_INT">
+						<doc>
+						An array of the hierarchical levels of the parents of detector
+						elements or groupings of detector elements.
+						
+						A top-level element or grouping has parent level -1
+						</doc>
+						<dimensions><dim index="1" ref="group_index"/></dimensions>
+					</field>
+				</group>
 			<group type="NXdetector">
-				<field name="depends_on" type="NX_CHAR" /> <!-- better type for paths the need to resolve -->
+					<doc>
+						Normally the detector group will have the name ``detector``.
+						However, in the case of multiple detector elements, each element
+						needs a uniquely named NXdetector group. 
+					</doc>
+					<field name="depends_on" type="NX_CHAR" /> <!-- better type for paths needed  -->
 
 				<group type="NXtransformations" minOccurs="0">
 					<doc>
@@ -89,10 +163,17 @@
 				</group>
 
 				<field name="data" type="NX_NUMBER">
-					<dimensions rank="3">
+						<doc>
+							For a dimension-2 detector, the rank of the data array will be 3.
+							For a dimension-3 detector, the rank of the data array will be 4.
+							This allows for the introduction of the frame number as the
+							first index.
+						</doc>
+						<dimensions rank="dataRank">
 						<dim index="1" value="np" />
 						<dim index="2" value="i" />
 						<dim index="3" value="j" />
+							<dim index="4" value="k" minOccurs="0"/>
 					</dimensions>
 				</field>
 
@@ -113,17 +194,38 @@
 						To allow consistent parsing of the experimental geometry,
 						this application definiton requires all detectors to 
 						define a detector module, even if there is only one.
+
+							This group specifies the hyperslab of data in the data
+							array associated with the detector that contains the
+							data for this module.  If the module is associated with
+							a full data array, rather than with a hyperslab within
+							a larger array, then a single module should be defined,
+							spanning the entire array. 
 					</doc>
 					<field name="data_origin" type="NX_INT">
 						<doc>
-							A two value field which gives the index of the start of the
-							modules data in the
-							main area detector image in the underlying NXdetector module.
+								A dimension-2 or dimension-3  field which gives the indices
+								of the origin of the hyperslab of data for this module in the
+								main area detector image in the parent NXdetector module.
+
+								The data_origin is 0-based.
+
+								The frame number dimension (np) is omitted.  The order
+								of indices is i, j or i, j, k, i.e. slow to fast.
 						</doc>
 					</field>
 					<field name="data_size" type="NX_INT">
 						<doc>
-							Two values for the size of the module in pixels in each direction.
+								Two or three values for the size of the module in pixels in 
+								each direction.
+							</doc>
+						</field>
+						<field name="data_stride" type="NX_INT" minOccurs="0">
+							<doc>
+								Two or three values for the stride of the module in pixels in 
+								each direction.  By default the stride is [1,1] or [1,1,1],
+								and this is the most likely case.  This optional field is 
+								included for completeness.
 						</doc>
 					</field>
 
@@ -230,9 +332,10 @@
 
 				<field name="angular_calibration" type="NX_FLOAT" minOccurs="0">
 					<doc>Angular calibration data.</doc>
-					<dimensions rank="2">
+						<dimensions rank="dataRank">
 						<dim index="1" value="i" />
 						<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 					</dimensions>
 				</field>
 
@@ -245,17 +348,19 @@
 
 				<field name="flatfield" type="NX_FLOAT" minOccurs="0">
 					<doc>Flat field correction data.</doc>
-					<dimensions rank="2">
+						<dimensions rank="dataRank">
 						<dim index="1" value="i" />
 						<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 					</dimensions>
 				</field>
 
 				<field name="flatfield_error" type="NX_FLOAT" minOccurs="0">
 					<doc>Errors of the flat field correction data.</doc>
-					<dimensions rank="2">
+						<dimensions rank="dataRank">
 						<dim index="1" value="i" />
 						<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 					</dimensions>
 				</field>
 
@@ -300,9 +405,10 @@
 						If the full bit depths is not required, providing a 
 						mask with fewer bits is permissible.
 					</doc>
-					<dimensions rank="2">
+						<dimensions rank="dataRank">
 						<dim index="1" value="i" />
 						<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 					</dimensions>
 				</field>
 
@@ -399,26 +505,105 @@
 			<field name="depends_on" type="NX_CHAR" minOccurs="0">
 				<!-- better type for paths the need to resolve -->
 				<doc>
-					This should be an absolute requirement to have for any scan
-					experiment.
+						This is a requirement to describe for any scan experiment.
 					The reason it is optional is mainly to accommodate XFEL
 					single shot exposures.
+
+						The axis on which the sample position depends may be stored
+						anywhere, but is normally stored in the NXtransformations
+						NXtransformations group within the NXsample group.
 				</doc>
 			</field>
 
+				<group type="NXtransformations" minOccurs="0">
+					<doc>
+						This is the recommended location for sample goniometer
+						and other related axes.
+
+						This is a requirement to describe for any scan experiment.
+						The reason it is optional is mainly to accommodate XFEL
+						single shot exposures.
+
+						Use of the depends_on field and the NXtransformations group is
+						strongly recommended.  As noted above this should be an absolute 
+						requirement to have for any scan experiment.
+
+						The reason it is optional is mainly to accommodate XFEL
+						single shot exposures.
+					</doc>
+				</group>
+
 			<field name="temperature" units="NX_TEMPERATURE" minOccurs="0" />
 
 			<group type="NXbeam">
-				<field name="incident_wavelength" type="NX_NUMBER" units="NX_WAVELENGTH"
-					minOccurs="0" /> <!-- we write wavelength! -->
+					<field name="incident_wavelength" type="NX_FLOAT" units="NX_WAVELENGTH"
+						minOccurs="0" >
+						<doc>
+							In the case of a monchromatic beam this is the scalar
+							wavelength.
+
+							In the case of a polychromatic beam this is an array of
+							the wavelengths with the relative weights in
+							incident_wavelength_weight.
+						</doc>
+					</field>
+
+					<field name="incident_wavelength_weight" type="NX_FLOAT" minOccurs="0" >
+						<doc>
+							In the case of a polychromatic beam this is an array of the
+							relative weights of the corresponding wavelengths in 
+							incident_wavelength.
+						</doc>
+					</field>
+
+					<field name="incident_wavelength_spread" type="NX_FLOAT" units="NX_WAVELENGTH"
+						minOccurs="0" >
+						<doc>
+							The wavelength spread FWHM for the corresponding
+							wavelength(s) in incident_wavelength.
+						</doc>
+					</field>
 
 				<group name="incident_wavelength_spectrum" type="NXdata"
 					minOccurs="0" />
 
 				<field name="flux" type="NX_FLOAT" units="NX_FLUX" minOccurs="0">
-					<doc>flux incident on beam plane area</doc>
+						<doc>
+							flux incident on beam plane area in photons
+							per second per unit area
+						</doc>
+					</field>
+
+					<field name="total_flux" type="NX_FLOAT" units="NX_FREQUENCY" minOccurs="0">
+						<doc>
+							flux incident on beam plane in photons per second
+						</doc>
 				</field>
 
+					<field name="incident_beam_size" type="NX_FLOAT" units="NX_LENGTH"  minOccurs="0">
+						<doc>
+							Two-element array of FWHM (if Gaussian or Airy function) or
+							diameters (if top hat) or widths (if rectangular) of beam 
+							in the order x, y
+						</doc>
+						<dimensions rank="1" value="2" />
+					</field>
+
+					<field name="profile" type="NX_CHAR" minOccurs="0">
+						<doc>
+							The beam profile, Gaussian, Airy function, top-hat or
+							rectangular.  The profile is given in the plane of
+							incidence of the beam on the sample.
+						</doc>
+						<enumeration>
+							<item value="Gaussian"/>
+							<item value="Airy"/>
+							<item value="top-hat"/>
+							<item value="rectangular"/>
+						</enumeration>
+					</field>
+
+
 				<field name="incident_polarisation_stokes" minOccurs="0">
 					<dimensions rank="2">
 						<dim index="1" value="np" />
@@ -426,12 +611,6 @@
 					</dimensions>
 				</field>
 			</group>
-
-			<group type="NXtransformations" minOccurs="0">
-				<doc>
-					Suggested location for sample goniometer or other axes (transformations)
-				</doc>
-			</group>
 		</group>
 
 		<group type="NXdata" />
</pre>