<?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) 2008-2020 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" category="base"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
	name="NXevent_data" 
	type="group" extends="NXobject">
  <doc>
    NXevent_data is a special group for storing data from neutron
    detectors in event mode.  In this mode, the detector electronics
    emits a stream of detectorID, timestamp pairs. With detectorID
    describing the detector element in which the neutron was detected
    and timestamp the timestamp at which the neutron event was
    detected. In NeXus detectorID maps to event_id, event_time_offset
    to the timestamp.

    As this kind of data is common at pulsed neutron
    sources, the timestamp is almost always relative to the start of a
    neutron pulse. Thus the pulse timestamp is recorded too together
    with an index in the event_id, event_time_offset pair at which data for
    that pulse starts. At reactor source the same pulsed data effect
    may be achieved through the use of choppers or in stroboscopic
    measurement setups. 

    In order to make random access to timestamped data
    faster there is an optional array pair of
    cue_timestamp_zero and cue_index. The cue_timestamp_zero will
    contain courser timestamps then in the time array, say
    every five minutes. The cue_index will then contain the
    index into the event_id,event_time_offset pair of arrays for that
    courser cue_timestamp_zero. 
  </doc>
	<field name="event_time_offset" type="NX_NUMBER" units="NX_TIME_OF_FLIGHT">
		<doc>
			A list of timestamps for each event as it comes in. 
		</doc>
		<dimensions rank="1"><dim index="1" value="i"/></dimensions>
	</field>
	<field name="event_id" type="NX_INT" units="NX_DIMENSIONLESS">
		<doc>
			There will be extra information in the NXdetector to convert 
			event_id to detector_number.
		</doc>
		<dimensions rank="1"><dim index="1" value="i"/></dimensions>
	</field>
	<field name="event_time_zero" type="NX_NUMBER" units="NX_TIME">
		<doc>
			The time that each pulse started with respect to the offset
		</doc>
		<dimensions rank="1"><dim index="1" value="j"/></dimensions>
		<attribute name="offset" type="NX_DATE_TIME">
			<doc>ISO8601</doc>
		</attribute>
	</field>
	<field name="event_index" type="NX_INT" units="NX_DIMENSIONLESS">
	  <doc>
	    The index into the event_time_offset, event_id pair for
	    the pulse occurring at the matching entry in event_time_zero.
	  </doc>
		<dimensions rank="1"><dim index="1" value="j"/></dimensions>
	</field>
	<field name="pulse_height" type="NX_FLOAT" units="NX_DIMENSIONLESS">
		<doc>
			If voltages from the ends of the detector are read out this 
			is where they go. This list is for all events with information 
			to attach to a particular pulse height. The information to 
			attach to a particular pulse is located in events_per_pulse.
		</doc>
		<dimensions rank="2"><!--i,k?-->
			<dim index="1" value="i"/>
			<dim index="2" value="k"/>
		</dimensions>
	</field>
	<field name="cue_timestamp_zero"  type="NX_DATE_TIME"
	       units="NX_TIME">
	  <doc>
	    Timestamps matching the corresponding cue_index into the
	    event_id, event_time_offset pair.
	  </doc>
	   <attribute name="start" type="NX_DATE_TIME" />
	</field>
	<field name="cue_index" type="NX_INT">
	  <doc>
	    Index into the event_id, event_time_offset pair matching the corresponding
	    cue_timestamp. 
	  </doc>
	</field>
</definition>
