diff --git a/base_classes/nyaml/NXbeam.yaml b/base_classes/nyaml/NXbeam.yaml new file mode 100644 index 0000000000..e72d0cb7cd --- /dev/null +++ b/base_classes/nyaml/NXbeam.yaml @@ -0,0 +1,218 @@ +doc: | + Properties of a beam of radiation or matter 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: + doc: | + 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.) + +category: base +NXbeam: + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance from sample. Note, it is recommended to use NXtransformations instead. + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy carried by each particle of the beam at the given location. + + 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. + dim: (m,) + energy_spread(NX_NUMBER): + unit: NX_ENERGY + doc: | + The energy spread FWHM for the corresponding energy(ies) in 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. + energy_weights(NX_NUMBER): + unit: NX_ENERGY + doc: | + In the case of a polychromatic beam this is an array of length m of the relative + weights of the corresponding energies in 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. + energy_transfer(NX_FLOAT): + unit: NX_ENERGY + doc: | + Change in particle energy caused by the beamline component + dim: (m,) + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + 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 + wavelength_weights(NX_FLOAT): + doc: | + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``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``. + wavelength_spread(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + The wavelength spread FWHM for the corresponding + wavelength(s) in 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. + dim: (nP,) + beam_divergence(NX_FLOAT): + unit: NX_ANGLE + doc: | + 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. + dim: (nP, c) + extent(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of the beam entering this component. Note this represents + a rectangular beam aperture, and values represent FWHM + dim: (nP, 2) + flux(NX_FLOAT): + unit: NX_FLUX + doc: | + Flux incident on beam plane area + dim: (nP,) + (NXdata): + doc: | + 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. + \@default: + doc: | + .. 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. + depends_on(NX_CHAR): + doc: | + 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. + (NXtransformations): + doc: | + 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(NX_NUMBER): + unit: NX_TRANSFORMATION + doc: | + 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: + enumeration: [translation] + \@vector: + doc: | + Three values that define the direction of beam vector + \@offset: + doc: | + Three values that define the location of a point through which the beam passes + \@depends_on: + doc: | + Points to the path to a field defining the location on which this + depends or the string "." for origin. + reference_plane(NX_NUMBER): + unit: NX_TRANSFORMATION + doc: | + 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: + enumeration: [translation] + \@vector: + doc: | + Three values that define the direction of reference plane normal + \@offset: + doc: | + Not required as beam direction offset locates the plane + \@depends_on: + doc: | + Points to the path to a field defining the location on which this + depends or the string "." for origin. diff --git a/base_classes/nyaml/NXbeam_electron.yaml b/base_classes/nyaml/NXbeam_electron.yaml new file mode 100644 index 0000000000..2f894f9d39 --- /dev/null +++ b/base_classes/nyaml/NXbeam_electron.yaml @@ -0,0 +1,4 @@ +doc: | + Properties of an electron beam at a given location. +category: base +NXbeam_electron(NXbeam): \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_neutron.yaml b/base_classes/nyaml/NXbeam_neutron.yaml new file mode 100644 index 0000000000..acba6f62a8 --- /dev/null +++ b/base_classes/nyaml/NXbeam_neutron.yaml @@ -0,0 +1,4 @@ +doc: | + Properties of a neutron beam at a given location. +category: base +NXbeam_neutron(NXbeam): \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_optical.yaml b/base_classes/nyaml/NXbeam_optical.yaml new file mode 100644 index 0000000000..2a11065df0 --- /dev/null +++ b/base_classes/nyaml/NXbeam_optical.yaml @@ -0,0 +1,4 @@ +doc: | + Properties of an optical beam at a given location. +category: base +NXbeam_optical(NXbeam): \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_polarized.yaml b/base_classes/nyaml/NXbeam_polarized.yaml new file mode 100644 index 0000000000..2837750c8f --- /dev/null +++ b/base_classes/nyaml/NXbeam_polarized.yaml @@ -0,0 +1,51 @@ +doc: | + Properties of an optical beam at a given location. +category: base +NXbeam_polarized(NXbeam): + polarization(NX_NUMBER): + unit: NX_ANY + doc: | + Polarization as a Stokes vector at the given location + of the beam. + dim: (nP, 2) + \@units: + doc: | + 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. + polarization_stokes(NX_NUMBER): + unit: NX_ANY + doc: | + Polarization vector at the given location of the beam 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. + dim: (nP, 4) \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_polarized_time_resolved.yaml b/base_classes/nyaml/NXbeam_polarized_time_resolved.yaml new file mode 100644 index 0000000000..5eb1a7c882 --- /dev/null +++ b/base_classes/nyaml/NXbeam_polarized_time_resolved.yaml @@ -0,0 +1,4 @@ +doc: | + A polarized and time-resolved beam +category: base +NXbeam_polarized_time_resolved(NXbeam_polarized, NXbeam_time_resolved): \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_time_resolved.yaml b/base_classes/nyaml/NXbeam_time_resolved.yaml new file mode 100644 index 0000000000..ab959e9a7f --- /dev/null +++ b/base_classes/nyaml/NXbeam_time_resolved.yaml @@ -0,0 +1,52 @@ +doc: | + Properties of an optical time resolved beam at a given location. +symbols: + nx: Number of x-axis points of the FROG trace + ny: Number of y-axis points of the FROG trace +category: base +NXbeam_time_resolved(NXbeam): + pulse_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy of a single pulse at the diagnostic point + average_power(NX_FLOAT): + unit: NX_POWER + doc: | + Average power at the diagnostic point + fluence(NX_FLOAT): + unit: NX_ANY + doc: | + Incident fluence at the diagnostic point + \@units: + doc: | + Here: SI units are 'J/m2', customary 'mJ/cm2'. + pulse_duration(NX_FLOAT): + unit: NX_TIME + doc: | + FWHM duration of the pulses at the diagnostic point + frog_trace(NX_FLOAT): + doc: | + FROG trace of the pulse. + exists: optional + dim: (nx, ny) + frog_delays(NX_FLOAT): + unit: NX_TIME + doc: | + Horizontal axis of a FROG trace, i.e. delay. + exists: optional + dim: (nx,) + frog_frequencies(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Vertical axis of a FROG trace, i.e. frequency. + exists: optional + dim: (ny,) + chirp_type(NX_CHAR): + doc: | + The type of chirp implemented + exists: optional + chirp_GDD(NX_FLOAT): + unit: NX_TIME + doc: | + Group delay dispersion of the pulse for linear chirp + exists: optional \ No newline at end of file diff --git a/base_classes/nyaml/NXbeam_xray.yaml b/base_classes/nyaml/NXbeam_xray.yaml new file mode 100644 index 0000000000..37710fbaf6 --- /dev/null +++ b/base_classes/nyaml/NXbeam_xray.yaml @@ -0,0 +1,4 @@ +doc: | + Properties of an x-ray beam at a given location. +category: base +NXbeam_xray(NXbeam_optical): \ No newline at end of file