4.3.1.3. NXbeam

Status:

base class, extends NXobject

Description:

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 NXinstrument group or by the 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 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 NXinstrument, in which case it is recommended that the position of the beam is specified by an 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:

NXdata, NXtransformations

Structure:

@default: (optional) NX_CHAR

Declares which child group contains a path leading to a 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.

distance: (optional) NX_FLOAT {units=NX_LENGTH}

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

incident_energy: (optional) NX_FLOAT (Rank: 1, Dimensions: [m]) {units=NX_ENERGY}

Energy carried by each particle of the beam on entering the beamline component

final_energy: (optional) NX_FLOAT (Rank: 1, Dimensions: [m]) {units=NX_ENERGY}

Energy carried by each particle of the beam on leaving the beamline component

energy_transfer: (optional) NX_FLOAT (Rank: 1, Dimensions: [m]) {units=NX_ENERGY}

Change in particle energy caused by the beamline component

incident_wavelength: (optional) NX_FLOAT {units=NX_WAVELENGTH}

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, 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

incident_wavelength_weights: (optional) NX_FLOAT

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.

incident_wavelength_spread: (optional) NX_FLOAT (Rank: 1, Dimensions: [nP]) {units=NX_WAVELENGTH}

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.

incident_beam_divergence: (optional) NX_FLOAT (Rank: 2, Dimensions: [nP, c]) {units=NX_ANGLE}

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.

extent: (optional) NX_FLOAT (Rank: 2, Dimensions: [nP, 2]) {units=NX_LENGTH}

Size of the beam entering this component. Note this represents a rectangular beam aperture, and values represent FWHM

final_wavelength: (optional) NX_FLOAT (Rank: 1, Dimensions: [m]) {units=NX_WAVELENGTH}

Wavelength on leaving beamline component

incident_polarization: (optional) NX_NUMBER (Rank: 2, Dimensions: [nP, 2]) {units=NX_ANY}

Polarization vector on entering beamline component

final_polarization: (optional) NX_NUMBER (Rank: 2, Dimensions: [nP, 2]) {units=NX_ANY}

Polarization vector on leaving beamline component

incident_polarization_stokes: (optional) NX_NUMBER (Rank: 2, Dimensions: [nP, 4]) {units=NX_ANY}

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.

final_polarization_stokes: (optional) NX_NUMBER (Rank: 2, Dimensions: [nP, 4]) {units=NX_ANY}

Polarization vector on leaving beamline component using Stokes notation (see incident_polarization_stokes).

final_wavelength_spread: (optional) NX_FLOAT (Rank: 1, Dimensions: [m]) {units=NX_WAVELENGTH}

Wavelength spread FWHM of beam leaving this component

final_beam_divergence: (optional) NX_FLOAT (Rank: 2, Dimensions: [nP, 2]) {units=NX_ANGLE}

Divergence FWHM of beam leaving this component

flux: (optional) NX_FLOAT (Rank: 1, Dimensions: [nP]) {units=NX_FLUX}

flux incident on beam plane area

depends_on: (optional) 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 The NeXus Coordinate System). 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.

DATA: (optional) 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.

TRANSFORMATIONS: (optional) 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.

DIRECTION: (optional) NX_NUMBER {units=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

@transformation_type: (optional) NX_CHAR

Obligatory value: translation

@vector: (optional) NX_NUMBER

Three values that define the direction of beam vector

@offset: (optional) NX_NUMBER

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

@depends_on: (optional) NX_CHAR

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

reference_plane: (optional) NX_NUMBER {units=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

@transformation_type: (optional) NX_CHAR

Obligatory value: translation

@vector: (optional) NX_NUMBER

Three values that define the direction of reference plane normal

@offset: (optional) NX_NUMBER

Not required as beam direction offset locates the plane

@depends_on: (optional) 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.

NXDL Source:

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