<?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 name="NXentry" 
	type="group" 
	extends="NXobject"
	category="base"
	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"
	>

	<attribute name="default">
		<doc>
			.. index:: plotting
			
			Declares which :ref:`NXdata` (or :ref:`NXsubentry`) group 
			contains the data to be shown by default.
			It is needed to resolve ambiguity when more than one :ref:`NXdata` group exists. 
			The value is the name of the default :ref:`NXdata` group.
			
			It is recommended (as of NIAC2014 [#]_) to use this attribute
			to help define the path to the default dataset to be plotted.
			
			.. [#] NIAC2014 discussion summary:
			    http://wiki.nexusformat.org/2014_How_to_find_default_data
		</doc>
	</attribute>
	
	<doc>
		(**required**) :ref:`NXentry` describes the measurement. 
		
		The top-level NeXus group which contains all the data and associated
		information that comprise a single measurement. 
		It is mandatory that there is at least one
		group of this type in the NeXus file.	</doc>
	
	<group type="NXdata">
		<doc>
			The data group
		
			.. note:: Before the NIAC2016 meeting [#]_, at least one
			   :ref:`NXdata` group was required in each :ref:`NXentry` group.
			   At the NIAC2016 meeting, it was decided to make :ref:`NXdata` 
			   an optional group in :ref:`NXentry` groups for data files that 
			   do not use an application definition.
			   It is recommended strongly that all NeXus data files provide 
			   a NXdata group.  
			   It is permissable to omit the NXdata group only when 
			   defining the default plot is not practical or possible
			   from the available data.
			   
			   For example, neutron event data may not have anything that 
			   makes a useful plot without extensive processing.
			   
			   Certain application definitions override this decision and
			   require an :ref:`NXdata` group
			   in the :ref:`NXentry` group.  The ``minOccurs=0`` attribute
			   in the application definition will indicate the 
			   :ref:`NXdata` group
			   is optional, otherwise, it is required.
	
			   .. [#] NIAC2016: 
			      http://wiki.nexusformat.org/NIAC2016,
			      https://github.com/nexusformat/NIAC/issues/16

		</doc>
	</group>

	<attribute name="IDF_Version">
		<!-- as ratified at NIAC2010 -->
		<doc>ISIS Muon IDF_Version</doc>
	</attribute>
	<field name="title">
		<doc>Extended title for entry</doc>
	</field>
	<field name="experiment_identifier">
		<doc>
			Unique identifier for the experiment, 
			defined by the facility, 
			possibly linked to the proposals
		</doc>
	</field>
	<field name="experiment_description">
		<doc>Brief summary of the experiment, including key objectives.</doc>
	</field>
	<group type="NXnote"  name="experiment_documentation">
		<doc>Description of the full experiment (document in pdf, latex, ...)</doc>
	</group>
	<field name="collection_identifier">
		<doc>User or Data Acquisition defined group of NeXus files or NXentry</doc>
	</field>
	<field name="collection_description">
		<doc>Brief summary of the collection, including grouping criteria.</doc>
	</field>
	<field name="entry_identifier">
		<doc>unique identifier for the measurement, defined by the facility.</doc>
	</field>
	<field name="features">
		<doc>
			Reserved for future use by NIAC.

			See https://github.com/nexusformat/definitions/issues/382
		</doc>
	</field>
	<field name="definition">
		<doc>
			(alternate use: see same field in :ref:`NXsubentry` for preferred)
			
			Official NeXus NXDL schema to which this entry conforms.
			
			This field is provided so that :ref:`NXentry` can be the overlay position
			in a NeXus data file for an application definition and its 
			set of groups, fields, and attributes.
			
			*It is advised* to use :ref:`NXsubentry`, instead, as the overlay position.
		</doc>
		<attribute name="version"><doc>NXDL version number</doc></attribute>
		<attribute name="URL"><doc>URL of NXDL file</doc></attribute>
	</field>
	<field name="definition_local" deprecated="see same field in :ref:`NXsubentry` for preferred use">
		<doc>
			Local NXDL schema extended from the entry
			specified in the ``definition`` field. 
			This contains any locally-defined,
			additional fields in the entry.
		</doc>
		<attribute name="version"><doc>NXDL version number</doc></attribute>
		<attribute name="URL"><doc>URL of NXDL file</doc></attribute>
	</field>
	<field name="start_time" type="NX_DATE_TIME">
		<doc>Starting time of measurement</doc>
	</field>
	<field name="end_time" type="NX_DATE_TIME">
		<doc>Ending time of measurement</doc>
	</field>
	<field name="duration" type="NX_INT" units="NX_TIME">
		<doc>Duration of measurement</doc>
	</field>
	<field name="collection_time" type="NX_FLOAT" units="NX_TIME">
		<doc>
			Time transpired actually collecting data i.e. taking out time when collection was
			suspended due to e.g. temperature out of range
		</doc>
	</field>
	<field name="run_cycle">
		<doc>Such as "2007-3". Some user facilities organize their beam time into run cycles.</doc>
	</field>
	<field name="program_name">
		<doc>Name of program used to generate this file</doc>
		<attribute name="version"><doc>Program version number</doc></attribute>
		<attribute name="configuration"><doc>configuration of the program</doc></attribute>
	</field>
	<field name="revision">
		<doc>
			Revision id of the file due to re-calibration, reprocessing, new analysis, new
			instrument definition format, ...
		</doc>
		<attribute name="comment"/>
	</field>
      <field name="pre_sample_flightpath" type="NX_FLOAT"
        units="NX_LENGTH">
		<doc>
			This is the flightpath before the sample position. This can be determined by a chopper,
			by the moderator or the source itself. In other words: it the distance to the component
			which gives the T0 signal to the detector electronics. If another component in the
			NXinstrument hierarchy provides this information, this should be a link.
		</doc>
      </field>
	<group name="notes" type="NXnote">
		<doc>Notes describing entry</doc>
	</group>
	<group name="thumbnail" type="NXnote">
		<doc>
			A small image that is representative of the entry. An example of this is a 640x480
			jpeg image automatically produced by a low resolution plot of the NXdata.
		</doc>
		<attribute name="type">
			<doc>The mime type should be an ``image/*``</doc>
			<enumeration>
				<!-- 
					This is not perfect.
					How do we set a default value for the type attribute?
				 -->
				<item value="image/*" />
			</enumeration>
		</attribute>
	</group>
	<group type="NXuser" />
	<group type="NXsample" />
	<group type="NXinstrument" />
	<group type="NXcollection" />
	<group type="NXmonitor" />
	<group type="NXparameters" />
	<group type="NXprocess" />
	<group type="NXsubentry" />
</definition>

