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

.. index::
    ! NXbeam (base class)
    ! beam (base class)
    see: beam (base class); NXbeam

.. _NXbeam:

======
NXbeam
======

**Status**:

  base class, extends :ref:`NXobject`

**Description**:

  Properties of the neutron or X-ray beam at a given location.

  It will be referenced
  by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. Note
  that variables such as the incident energy could be scalar values or arrays. This group is
  especially valuable in storing the results of instrument simulations in which it is useful
  to specify the beam profile, time distribution etc. at each beamline component. Otherwise,
  its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron
  scattering by the sample, e.g., energy transfer, polarizations.

**Symbols**:

  No symbol table

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

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

**Structure**:

  .. _/NXbeam@default-attribute:

  .. index:: default (file attribute)

  **@default**: (optional) :ref:`NX_CHAR <NX_CHAR>`

    .. index:: plotting

    Declares which child group contains a path leading 
    to a :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.
    See https://www.nexusformat.org/2014_How_to_find_default_data.html
    for a summary of the discussion.

  .. _/NXbeam/distance-field:

  .. index:: distance (field)

  **distance**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Distance from sample. Note, it is recommended to use NXtransformations instead.

  .. _/NXbeam/incident_energy-field:

  .. index:: incident_energy (field)

  **incident_energy**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_ENERGY <NX_ENERGY>`}

    Energy on entering beamline component

  .. _/NXbeam/final_energy-field:

  .. index:: final_energy (field)

  **final_energy**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_ENERGY <NX_ENERGY>`}

    Energy on leaving beamline component

  .. _/NXbeam/energy_transfer-field:

  .. index:: energy_transfer (field)

  **energy_transfer**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_ENERGY <NX_ENERGY>`}

    Energy change caused by beamline component

  .. _/NXbeam/incident_wavelength-field:

  .. index:: incident_wavelength (field)

  **incident_wavelength**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_WAVELENGTH <NX_WAVELENGTH>`}

    Wavelength on entering beamline component

  .. _/NXbeam/incident_wavelength_spread-field:

  .. index:: incident_wavelength_spread (field)

  **incident_wavelength_spread**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_WAVELENGTH <NX_WAVELENGTH>`}

    Wavelength spread FWHM on entering component

  .. _/NXbeam/incident_beam_divergence-field:

  .. index:: incident_beam_divergence (field)

  **incident_beam_divergence**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 2, Dimensions: [2, j]) {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    Divergence of beam entering this component

  .. _/NXbeam/extent-field:

  .. index:: extent (field)

  **extent**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 2, Dimensions: [2, j]) {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Size of the beam entering this component

  .. _/NXbeam/final_wavelength-field:

  .. index:: final_wavelength (field)

  **final_wavelength**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_WAVELENGTH <NX_WAVELENGTH>`}

    Wavelength on leaving beamline component

  .. _/NXbeam/incident_polarization-field:

  .. index:: incident_polarization (field)

  **incident_polarization**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 2, Dimensions: [2, j]) {units=\ :ref:`NX_ANY <NX_ANY>`}

    Polarization vector on entering beamline component

  .. _/NXbeam/final_polarization-field:

  .. index:: final_polarization (field)

  **final_polarization**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 2, Dimensions: [2, j]) {units=\ :ref:`NX_ANY <NX_ANY>`}

    Polarization vector on leaving beamline component

  .. _/NXbeam/final_wavelength_spread-field:

  .. index:: final_wavelength_spread (field)

  **final_wavelength_spread**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_WAVELENGTH <NX_WAVELENGTH>`}

    Wavelength spread FWHM of beam leaving this component

  .. _/NXbeam/final_beam_divergence-field:

  .. index:: final_beam_divergence (field)

  **final_beam_divergence**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 2, Dimensions: [2, j]) {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    Divergence FWHM of beam leaving this component

  .. _/NXbeam/flux-field:

  .. index:: flux (field)

  **flux**: (optional) :ref:`NX_FLOAT <NX_FLOAT>` (Rank: 1, Dimensions: [i]) {units=\ :ref:`NX_FLUX <NX_FLUX>`}

    flux incident on beam plane area

  .. _/NXbeam/depends_on-field:

  .. index:: depends_on (field)

  **depends_on**: (optional) :ref:`NX_CHAR <NX_CHAR>`

    The NeXus coordinate system defines the Z axis to be along the nominal beam
    direction. This is the same as the McStas coordinate system (see :ref:Design-CoordinateSystem).
    However, the additional transformations needed to represent an altered beam
    direction can be provided using this depends_on field that contains the path
    to a NXtransformations group. This could represent redirection of the beam,
    or a refined beam direction.

  .. _/NXbeam/DATA-group:

  **DATA**: (optional) :ref:`NXdata`

    Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly
    useful for simulations which need to store plottable information at each beamline
    component.

  .. _/NXbeam/TRANSFORMATIONS-group:

  **TRANSFORMATIONS**: (optional) :ref:`NXtransformations`

    Direction (and location) for the beam. The location of the beam can be given by
    any point which it passes through as its offset attribute.

    .. _/NXbeam/TRANSFORMATIONS/DIRECTION-field:

    .. index:: DIRECTION (field)

    **DIRECTION**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_TRANSFORMATION <NX_TRANSFORMATION>`}

      Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1]
      and passes through the origin

      .. _/NXbeam/TRANSFORMATIONS/DIRECTION@transformation_type-attribute:

      .. index:: transformation_type (field attribute)

      **@transformation_type**: (optional) :ref:`NX_CHAR <NX_CHAR>`


        Obligatory value: ``translation``

      .. _/NXbeam/TRANSFORMATIONS/DIRECTION@vector-attribute:

      .. index:: vector (field attribute)

      **@vector**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`

        Three values that define the direction of beam vector

      .. _/NXbeam/TRANSFORMATIONS/DIRECTION@offset-attribute:

      .. index:: offset (field attribute)

      **@offset**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`

        Three values that define the location of a point through which the beam passes

      .. _/NXbeam/TRANSFORMATIONS/DIRECTION@depends_on-attribute:

      .. index:: depends_on (field attribute)

      **@depends_on**: (optional) :ref:`NX_CHAR <NX_CHAR>`

        Points to the path to a field defining the location on which this
        depends or the string "." for origin.

    .. _/NXbeam/TRANSFORMATIONS/reference_plane-field:

    .. index:: reference_plane (field)

    **reference_plane**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_TRANSFORMATION <NX_TRANSFORMATION>`}

      Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored.
      This also defines the parallel and perpendicular components of the beam's polarization.
      If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin

      .. _/NXbeam/TRANSFORMATIONS/reference_plane@transformation_type-attribute:

      .. index:: transformation_type (field attribute)

      **@transformation_type**: (optional) :ref:`NX_CHAR <NX_CHAR>`


        Obligatory value: ``translation``

      .. _/NXbeam/TRANSFORMATIONS/reference_plane@vector-attribute:

      .. index:: vector (field attribute)

      **@vector**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`

        Three values that define the direction of reference plane normal

      .. _/NXbeam/TRANSFORMATIONS/reference_plane@offset-attribute:

      .. index:: offset (field attribute)

      **@offset**: (optional) :ref:`NX_NUMBER <NX_NUMBER>`

        Not required as beam direction offset locates the plane

      .. _/NXbeam/TRANSFORMATIONS/reference_plane@depends_on-attribute:

      .. index:: depends_on (field attribute)

      **@depends_on**: (optional) :ref:`NX_CHAR <NX_CHAR>`

        Points to the path to a field defining the location on which this
        depends or the string "." for origin.


Hypertext Anchors
-----------------

List of hypertext anchors for all groups, fields,
attributes, and links defined in this class.


* :ref:`/NXbeam/DATA-group </NXbeam/DATA-group>`
* :ref:`/NXbeam/depends_on-field </NXbeam/depends_on-field>`
* :ref:`/NXbeam/distance-field </NXbeam/distance-field>`
* :ref:`/NXbeam/energy_transfer-field </NXbeam/energy_transfer-field>`
* :ref:`/NXbeam/extent-field </NXbeam/extent-field>`
* :ref:`/NXbeam/final_beam_divergence-field </NXbeam/final_beam_divergence-field>`
* :ref:`/NXbeam/final_energy-field </NXbeam/final_energy-field>`
* :ref:`/NXbeam/final_polarization-field </NXbeam/final_polarization-field>`
* :ref:`/NXbeam/final_wavelength-field </NXbeam/final_wavelength-field>`
* :ref:`/NXbeam/final_wavelength_spread-field </NXbeam/final_wavelength_spread-field>`
* :ref:`/NXbeam/flux-field </NXbeam/flux-field>`
* :ref:`/NXbeam/incident_beam_divergence-field </NXbeam/incident_beam_divergence-field>`
* :ref:`/NXbeam/incident_energy-field </NXbeam/incident_energy-field>`
* :ref:`/NXbeam/incident_polarization-field </NXbeam/incident_polarization-field>`
* :ref:`/NXbeam/incident_wavelength-field </NXbeam/incident_wavelength-field>`
* :ref:`/NXbeam/incident_wavelength_spread-field </NXbeam/incident_wavelength_spread-field>`
* :ref:`/NXbeam/TRANSFORMATIONS-group </NXbeam/TRANSFORMATIONS-group>`
* :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION-field </NXbeam/TRANSFORMATIONS/DIRECTION-field>`
* :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@depends_on-attribute </NXbeam/TRANSFORMATIONS/DIRECTION@depends_on-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@offset-attribute </NXbeam/TRANSFORMATIONS/DIRECTION@offset-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@transformation_type-attribute </NXbeam/TRANSFORMATIONS/DIRECTION@transformation_type-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@vector-attribute </NXbeam/TRANSFORMATIONS/DIRECTION@vector-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/reference_plane-field </NXbeam/TRANSFORMATIONS/reference_plane-field>`
* :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@depends_on-attribute </NXbeam/TRANSFORMATIONS/reference_plane@depends_on-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@offset-attribute </NXbeam/TRANSFORMATIONS/reference_plane@offset-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@transformation_type-attribute </NXbeam/TRANSFORMATIONS/reference_plane@transformation_type-attribute>`
* :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@vector-attribute </NXbeam/TRANSFORMATIONS/reference_plane@vector-attribute>`
* :ref:`/NXbeam@default-attribute </NXbeam@default-attribute>`

**NXDL Source**:
  https://github.com/nexusformat/definitions/blob/main/base_classes/NXbeam.nxdl.xml