.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source NXguide.nxdl.xml

.. index::
    ! NXguide (base class)
    ! guide (base class)
    see: guide (base class); NXguide

.. _NXguide:

=======
NXguide
=======

**Status**:

  base class, extends :ref:`NXobject`, version 1.0

**Description**:

  A neutron optical element to direct the path of the beam.

  :ref:`NXguide` is used by neutron instruments to describe
  a guide consists of several mirrors building a shape through which 
  neutrons can be guided or directed. The simplest such form is box shaped
  although elliptical guides are gaining in popularity. 
  The individual parts of a guide usually have common characteristics 
  but there are cases where they are different.
  For example,  a neutron guide might consist of 2 or 4 coated walls or
  a supermirror bender with multiple, coated vanes.

  To describe polarizing supermirrors such as used in neutron reflection,
  it may be necessary to revise this definition of :ref:`NXguide`
  to include :ref:`NXpolarizer` and/or :ref:`NXmirror`.

  When even greater complexity exists in the definition of what
  constitutes a *guide*,  it has been suggested that :ref:`NXguide` 
  be redefined as a :ref:`NXcollection` of :ref:`NXmirror` each 
  having their own :ref:`NXgeometry` describing their location(s).

  For the more general case when describing mirrors, consider using 
  :ref:`NXmirror`.

  NOTE: The NeXus International Advisory Committee welcomes 
  comments for revision and improvement of 
  this definition of :ref:`NXguide`.


**Symbols**:


  **nsurf**: number of reflecting surfaces

  **nwl**: number of wavelengths

**Groups cited**:
  :ref:`NXdata`, :ref:`NXgeometry`

.. index:: NXgeometry (base class); used in base class, NXdata (base class); used in base class

**Structure**:

  .. index:: description (field)

  **description**: :ref:`NX_CHAR <NX_CHAR>`

    A description of this particular instance of ``NXguide``.

  .. index:: incident angle (field)

  **incident_angle**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    TODO: documentation needed

  .. index:: bend angle x (field)

  **bend_angle_x**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    TODO: documentation needed

  .. index:: bend angle y (field)

  **bend_angle_y**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    TODO: documentation needed

  .. index:: interior atmosphere (field)

  **interior_atmosphere**: :ref:`NX_CHAR <NX_CHAR>`


    Any of these values: ``vacuum`` | ``helium`` | ``argon``

  .. index:: external material (field)

  **external_material**: :ref:`NX_CHAR <NX_CHAR>`

    external material outside substrate

  .. index:: m value (field)

  **m_value[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>`

    The ``m`` value for a supermirror, which defines the supermirror 
    regime in multiples of the critical angle of Nickel.

  .. index:: substrate material (field)

  **substrate_material[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>`

    TODO: documentation needed

  .. index:: substrate thickness (field)

  **substrate_thickness[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    TODO: documentation needed

  .. index:: coating material (field)

  **coating_material[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>`

    TODO: documentation needed

  .. index:: substrate roughness (field)

  **substrate_roughness[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    TODO: documentation needed

  .. index:: coating roughness (field)

  **coating_roughness[nsurf]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    TODO: documentation needed

  .. index:: number sections (field)

  **number_sections**: :ref:`NX_INT <NX_INT>` {units=\ :ref:`NX_UNITLESS <NX_UNITLESS>`}

    number of substrate sections (also called ``nsurf`` as an 
    index in the ``NXguide`` specification)

  **(geometry)**: :ref:`NXgeometry`

    TODO:  Explain what this NXgeometry group means.  What is intended here?

  **reflectivity**: :ref:`NXdata`

    Reflectivity as function of reflecting surface and wavelength

    .. index:: signal (group attribute)

    **@signal**: :ref:`NX_CHAR <NX_CHAR>`


      Obligatory value:  ``data``

    .. index:: axes (group attribute)

    **@axes**: :ref:`NX_CHAR <NX_CHAR>`


      Obligatory value:  ``surface wavelength``

    .. index:: surface indices (group attribute)

    **@surface_indices**: :ref:`NX_CHAR <NX_CHAR>`


      Obligatory value:  ``0``

    .. index:: wavelength indices (group attribute)

    **@wavelength_indices**: :ref:`NX_CHAR <NX_CHAR>`


      Obligatory value:  ``1``

    .. index:: data (field)

    **data[nsurf, nwl]**: :ref:`NX_NUMBER <NX_NUMBER>`

      reflectivity of each surface as a function of wavelength

    .. index:: surface (field)

    **surface[nsurf]**: :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_ANY <NX_ANY>`}

      List of surfaces.  Probably best to use index 
      numbers but the specification is very loose.

    .. index:: wavelength (field)

    **wavelength[nwl]**: :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_WAVELENGTH <NX_WAVELENGTH>`}

      wavelengths at which reflectivity was measured

**NXDL Source**:
  https://github.com/nexusformat/definitions/blob/master/base_classes/NXguide.nxdl.xml