2.3.3.1.3. NXbeam

Status:

base class, extends NXobject

Description:

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

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

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

In the case of a monochromatic beam this is the scalar energy. Several other use cases are permitted, depending on the presence of other incident_energy_X fields.

  • In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights.

  • In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot. Here, incident_energy_weights and incident_energy_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_energy_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_energy_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 energy value is available along with the original spectrum from which it was calibrated.

incident_energy_spread: (optional) NX_NUMBER {units=NX_ENERGY}

The energy spread FWHM for the corresponding energy(ies) in incident_energy. I ...

The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in the energy spread, this is a 2D array of dimension nP by m (slow to fast) of the spreads of the corresponding wavelength in incident_wavelength.

incident_energy_weights: (optional) NX_NUMBER {units=NX_ENERGY}

In the case of a polychromatic beam this is an array of length m of the relati ...

In the case of a polychromatic beam this is an array of length m of the relative weights of the corresponding energies in incident_energy. 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 energies in incident_energy.

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

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

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

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

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

Size of the beam entering this component. Note this represents a rectangular beam aperture, and values represent FWHM. If applicable, the first dimension shall be the horizontal extent and the second dimension shall be the vertical extent.

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

@units: (optional) NX_CHAR

The units for this observable are not included in the NIAC list. ...

The units for this observable are not included in the NIAC list. Responsibility on correct formatting and parsing is handed to the user by using NX_ANY. Correct parsing can still be implemented by using this attribute.

Fill with:
  • The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla).

  • The unit unidata name if the unit has a name (Example: farad for capacitance).

  • A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and does not have a name.

Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). Here: SI units are V2/m2.

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

Polarization vector on leaving beamline component

@units: (optional) NX_CHAR

The units for this observable are not included in the NIAC list. ...

The units for this observable are not included in the NIAC list. Responsibility on correct formatting and parsing is handed to the user by using NX_ANY. Correct parsing can still be implemented by using this attribute.

Fill with:
  • The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla).

  • The unit unidata name if the unit has a name (Example: farad for capacitance).

  • A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and does not have a name.

Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). Here: SI units are V2/m2.

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

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.

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

Polarization vector on leaving beamline component using Stokes notation ...

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

pulse_energy: (optional) NX_FLOAT {units=NX_ENERGY}

Energy of a single pulse at the diagnostic point

average_power: (optional) NX_FLOAT {units=NX_POWER}

Average power at the diagnostic point

fluence: (optional) NX_FLOAT {units=NX_ANY}

Incident fluence at the diagnostic point

@units: (optional) NX_CHAR

Here: SI units are ‘J/m2’, customary ‘mJ/cm2’.

pulse_duration: (optional) NX_FLOAT {units=NX_TIME}

FWHM duration of the pulses at the diagnostic point

pulse_delay: (optional) NX_FLOAT {units=NX_TIME}

Delay time between two pulses of a pulsed beam.

@reference_beam: (optional) NX_CHAR

A reference to the beam in relation to which the delay is.

frog_trace: (optional) NX_FLOAT (Rank: 2, Dimensions: [nx, ny])

FROG trace of the pulse.

frog_delays: (optional) NX_FLOAT (Rank: 1, Dimensions: [nx]) {units=NX_TIME}

Horizontal axis of a FROG trace, i.e. delay.

frog_frequencies: (optional) NX_FLOAT (Rank: 1, Dimensions: [ny]) {units=NX_FREQUENCY}

Vertical axis of a FROG trace, i.e. frequency.

chirp_type: (optional) NX_CHAR

The type of chirp implemented

chirp_GDD: (optional) NX_FLOAT {units=NX_TIME}

Group delay dispersion of the pulse for linear chirp

depends_on: (optional) NX_CHAR

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

previous_device: (optional) NX_CHAR

Indicates the beam device from which this beam originates. ...

Indicates the beam device from which this beam originates. This defines, whether the beam in an “input” or “output” beam.

next_device: (optional) NX_CHAR

Gives the beam device which this beam will interact with next.

DATA: (optional) NXdata

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.

TRANSFORMATIONS: (optional) NXtransformations

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.

DIRECTION: (optional) NX_NUMBER {units=NX_TRANSFORMATION}

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

@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 ...

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

@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 ...

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/FAIRmat-NFDI/nexus_definitions/tree/fairmat/base_classes/NXbeam.nxdl.xml