.. auto-generated by dev_tools.docs.nxdl from the NXDL source base_classes/NXbeam.nxdl.xml -- DO NOT EDIT .. index:: ! NXbeam (base class) ! beam (base class) see: beam (base class); NXbeam .. _NXbeam: ====== NXbeam ====== .. Contributors List .. |contrib_name| replace:: Aaron Brewster|phyy-nx|https://avatars.githubusercontent.com/u/13471434?v=4|2022-06-17 .. |contrib_name| replace:: Peter Chang|PeterC-DLS|https://avatars.githubusercontent.com/u/1381719?v=4|2022-06-17 **Status**: base class, extends :ref:`NXobject` **Description**: .. collapse:: Properties of the neutron or X-ray beam at a given location. ... Properties of the neutron or X-ray beam at a given location. This group is intended to be referenced by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. 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. Finally, There are cases where the beam is considered as a beamline component and this group may be defined as a subgroup directly inside :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. **Symbols**: These symbols coordinate datasets with the same shape. **nP**: Number of scan points. **m**: Number of channels in the incident beam spectrum, if known **c**: Number of moments representing beam divergence (x, y, xy, etc.) **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 ` .. collapse:: Declares which child group contains a path leading ... .. 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 ` {units=\ :ref:`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 ` (Rank: 1, Dimensions: [m]) {units=\ :ref:`NX_ENERGY `} Energy carried by each particle of the beam on entering the beamline component .. _/NXbeam/final_energy-field: .. index:: final_energy (field) **final_energy**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [m]) {units=\ :ref:`NX_ENERGY `} Energy carried by each particle of the beam on leaving the beamline component .. _/NXbeam/energy_transfer-field: .. index:: energy_transfer (field) **energy_transfer**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [m]) {units=\ :ref:`NX_ENERGY `} Change in particle energy caused by the beamline component .. _/NXbeam/incident_wavelength-field: .. index:: incident_wavelength (field) **incident_wavelength**: (optional) :ref:`NX_FLOAT ` {units=\ :ref:`NX_WAVELENGTH `} .. collapse:: In the case of a monochromatic beam this is the scalar ... In the case of a monochromatic beam this is the scalar wavelength. Several other use cases are permitted, depending on the presence or absence of other incident_wavelength_X fields. In the case of a polychromatic beam this is an array of length **m** of wavelengths, with the relative weights in ``incident_wavelength_weights``. In the case of a monochromatic beam that varies shot- to-shot, this is an array of wavelengths, one for each recorded shot. Here, ``incident_wavelength_weights`` and incident_wavelength_spread are not set. In the case of a polychromatic beam that varies shot-to- shot, this is an array of length **m** with the relative weights in ``incident_wavelength_weights`` as a 2D array. In the case of a polychromatic beam that varies shot-to- shot and where the channels also vary, this is a 2D array of dimensions **nP** by **m** (slow to fast) with the relative weights in ``incident_wavelength_weights`` as a 2D array. Note, :ref:`variants ` are a good way to represent several of these use cases in a single dataset, e.g. if a calibrated, single-value wavelength value is available along with the original spectrum from which it was calibrated. Wavelength on entering beamline component .. _/NXbeam/incident_wavelength_weights-field: .. index:: incident_wavelength_weights (field) **incident_wavelength_weights**: (optional) :ref:`NX_FLOAT ` .. collapse:: In the case of a polychromatic beam this is an array of ... In the case of a polychromatic beam this is an array of length **m** of the relative weights of the corresponding wavelengths in ``incident_wavelength``. In the case of a polychromatic beam that varies shot-to- shot, this is a 2D array of dimensions **nP** by **m** (slow to fast) of the relative weights of the corresponding wavelengths in ``incident_wavelength``. .. _/NXbeam/incident_wavelength_spread-field: .. index:: incident_wavelength_spread (field) **incident_wavelength_spread**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [nP]) {units=\ :ref:`NX_WAVELENGTH `} .. collapse:: The wavelength spread FWHM for the corresponding ... The wavelength spread FWHM for the corresponding wavelength(s) in incident_wavelength. In the case of shot-to-shot variation in the wavelength spread, this is a 2D array of dimension **nP** by **m** (slow to fast) of the spreads of the corresponding wavelengths in incident_wavelength. .. _/NXbeam/incident_beam_divergence-field: .. index:: incident_beam_divergence (field) **incident_beam_divergence**: (optional) :ref:`NX_FLOAT ` (Rank: 2, Dimensions: [nP, c]) {units=\ :ref:`NX_ANGLE `} .. collapse:: Beam crossfire in degrees parallel to the laboratory X axis ... Beam crossfire in degrees parallel to the laboratory X axis The dimension **c** is a series of moments of that represent the standard uncertainty (e.s.d.) of the directions of of the beam. The first and second moments are in the XZ and YZ planes around the mean source beam direction, respectively. Further moments in **c** characterize co-variance terms, so the next moment is the product of the first two, and so on. .. _/NXbeam/extent-field: .. index:: extent (field) **extent**: (optional) :ref:`NX_FLOAT ` (Rank: 2, Dimensions: [nP, 2]) {units=\ :ref:`NX_LENGTH `} .. collapse:: Size of the beam entering this component. Note this represents ... Size of the beam entering this component. Note this represents a rectangular beam aperture, and values represent FWHM .. _/NXbeam/final_wavelength-field: .. index:: final_wavelength (field) **final_wavelength**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [m]) {units=\ :ref:`NX_WAVELENGTH `} Wavelength on leaving beamline component .. _/NXbeam/incident_polarization-field: .. index:: incident_polarization (field) **incident_polarization**: (optional) :ref:`NX_NUMBER ` (Rank: 2, Dimensions: [nP, 2]) {units=\ :ref:`NX_ANY `} Polarization vector on entering beamline component .. _/NXbeam/final_polarization-field: .. index:: final_polarization (field) **final_polarization**: (optional) :ref:`NX_NUMBER ` (Rank: 2, Dimensions: [nP, 2]) {units=\ :ref:`NX_ANY `} Polarization vector on leaving beamline component .. _/NXbeam/incident_polarization_stokes-field: .. index:: incident_polarization_stokes (field) **incident_polarization_stokes**: (optional) :ref:`NX_NUMBER ` (Rank: 2, Dimensions: [nP, 4]) {units=\ :ref:`NX_ANY `} .. collapse:: Polarization vector on entering beamline component using Stokes notation ... Polarization vector on entering beamline component using Stokes notation The Stokes parameters are four components labelled I,Q,U,V or S_0,S_1,S_2,S_3. These are defined with the standard Nexus coordinate frame unless it is overridden by an NXtransformations field pointed to by a depends_on attribute. The last component, describing the circular polarization state, is positive for a right-hand circular state - that is the electric field vector rotates clockwise at the sample and over time when observed from the source. I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale linearly with the total degree of polarization, and indicate the relative magnitudes of the pure linear and circular orientation contributions. Q (S_1) is linearly polarized along the x axis (Q > 0) or y axis (Q < 0). U (S_2) is linearly polarized along the x==y axis (U > 0) or the -x==y axis (U < 0). V (S_3) is circularly polarized. V > 0 when the electric field vector rotates clockwise at the sample with respect to time when observed from the source; V < 0 indicates the opposite rotation. .. _/NXbeam/final_polarization_stokes-field: .. index:: final_polarization_stokes (field) **final_polarization_stokes**: (optional) :ref:`NX_NUMBER ` (Rank: 2, Dimensions: [nP, 4]) {units=\ :ref:`NX_ANY `} .. collapse:: Polarization vector on leaving beamline component using Stokes notation ... Polarization vector on leaving beamline component using Stokes notation (see incident_polarization_stokes). .. _/NXbeam/final_wavelength_spread-field: .. index:: final_wavelength_spread (field) **final_wavelength_spread**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [m]) {units=\ :ref:`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 ` (Rank: 2, Dimensions: [nP, 2]) {units=\ :ref:`NX_ANGLE `} Divergence FWHM of beam leaving this component .. _/NXbeam/flux-field: .. index:: flux (field) **flux**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [nP]) {units=\ :ref:`NX_FLUX `} flux incident on beam plane area .. _/NXbeam/depends_on-field: .. index:: depends_on (field) **depends_on**: (optional) :ref:`NX_CHAR ` .. collapse:: The NeXus coordinate system defines the Z axis to be along the nominal beam ... 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` .. collapse:: Distribution of beam with respect to relevant variable e.g. wavelength. This i ... 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` .. collapse:: Direction (and location) for the beam. The location of the beam can be given b ... 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 ` {units=\ :ref:`NX_TRANSFORMATION `} :ref:`⤆ ` .. collapse:: Direction of beam vector, its value is ignored. If missing, then the beam di ... 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 ` :ref:`⤆ ` Obligatory value: ``translation`` .. _/NXbeam/TRANSFORMATIONS/DIRECTION@vector-attribute: .. index:: vector (field attribute) **@vector**: (optional) :ref:`NX_NUMBER ` :ref:`⤆ ` Three values that define the direction of beam vector .. _/NXbeam/TRANSFORMATIONS/DIRECTION@offset-attribute: .. index:: offset (field attribute) **@offset**: (optional) :ref:`NX_NUMBER ` :ref:`⤆ ` 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 ` :ref:`⤆ ` .. collapse:: Points to the path to a field defining the location on which this ... 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 ` {units=\ :ref:`NX_TRANSFORMATION `} :ref:`⤆ ` .. collapse:: Direction of normal to reference plane used to measure azimuth relative to t ... 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 ` :ref:`⤆ ` Obligatory value: ``translation`` .. _/NXbeam/TRANSFORMATIONS/reference_plane@vector-attribute: .. index:: vector (field attribute) **@vector**: (optional) :ref:`NX_NUMBER ` :ref:`⤆ ` 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 ` :ref:`⤆ ` 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 ` :ref:`⤆ ` .. collapse:: Points to the path to a field defining the location on which this ... 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 ` * :ref:`/NXbeam/depends_on-field ` * :ref:`/NXbeam/distance-field ` * :ref:`/NXbeam/energy_transfer-field ` * :ref:`/NXbeam/extent-field ` * :ref:`/NXbeam/final_beam_divergence-field ` * :ref:`/NXbeam/final_energy-field ` * :ref:`/NXbeam/final_polarization-field ` * :ref:`/NXbeam/final_polarization_stokes-field ` * :ref:`/NXbeam/final_wavelength-field ` * :ref:`/NXbeam/final_wavelength_spread-field ` * :ref:`/NXbeam/flux-field ` * :ref:`/NXbeam/incident_beam_divergence-field ` * :ref:`/NXbeam/incident_energy-field ` * :ref:`/NXbeam/incident_polarization-field ` * :ref:`/NXbeam/incident_polarization_stokes-field ` * :ref:`/NXbeam/incident_wavelength-field ` * :ref:`/NXbeam/incident_wavelength_spread-field ` * :ref:`/NXbeam/incident_wavelength_weights-field ` * :ref:`/NXbeam/TRANSFORMATIONS-group ` * :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION-field ` * :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@depends_on-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@offset-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@transformation_type-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/DIRECTION@vector-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/reference_plane-field ` * :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@depends_on-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@offset-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@transformation_type-attribute ` * :ref:`/NXbeam/TRANSFORMATIONS/reference_plane@vector-attribute ` * :ref:`/NXbeam@default-attribute ` **NXDL Source**: https://github.com/nexusformat/definitions/blob/main/base_classes/NXbeam.nxdl.xml