3.3.3.128. NXopt

Status:

application definition (contribution), extends NXobject

Description:

An application definition for optical spectroscopy experiments.

Symbols:

Variables used throughout the document, e.g. dimensions or parameters.

N_spectrum: Length of the spectrum array (e.g. wavelength or energy) of the measured data.

N_sensors: Number of sensors used to measure parameters that influence the sample, such as temperature or pressure.

N_measurements: Number of measurements (1st dimension of measured_data array). This is equal to the number of parameters scanned. For example, if the experiment was performed at three different temperatures and two different pressures N_measurements = 2*3 = 6.

N_detection_angles: Number of detection angles of the beam reflected or scattered off the sample.

N_incident_angles: Number of angles of incidence of the incident beam.

N_observables: Number of observables that are saved in a measurement. e.g. one for intensity, reflectivity or transmittance, two for Psi and Delta etc. This is equal to the second dimension of the data array ‘measured_data’ and the number of column names.

Groups cited:

NXaperture, NXbeam_path, NXdata, NXentry, NXenvironment, NXinstrument, NXprocess, NXprogram, NXsample, NXsensor, NXsubentry, NXuser

Structure:

ENTRY: (required) NXentry

An application definition template for optical spectroscopy experiments. ...

An application definition template for optical spectroscopy experiments.

A general optical experiment consists of a light or excitation source, a beam path, a sample + its stage + its environment, and a detection unit. Examples are reflection or transmission measurements, photoluminescence, Raman spectroscopy, ellipsometry etc.

definition: (required) NX_CHAR ⤆

An application definition describing a general optical experiment. ...

An application definition describing a general optical experiment.

Obligatory value: NXopt

@version: (required) NX_CHAR ⤆

Version number to identify which definition of this application ...

Version number to identify which definition of this application definition was used for this entry/data.

@url: (required) NX_CHAR

URL where to find further material (documentation, examples) relevant ...

URL where to find further material (documentation, examples) relevant to the application definition.

experiment_identifier: (required) NX_CHAR ⤆

A (globally persistent) unique identifier of the experiment. ...

A (globally persistent) unique identifier of the experiment. (i) The identifier is usually defined by the facility or principle investigator. (ii) The identifier enables to link experiments to e.g. proposals.

experiment_description: (optional) NX_CHAR ⤆

An optional free-text description of the experiment. ...

An optional free-text description of the experiment.

However, details of the experiment should be defined in the specific fields of this application definition rather than in this experiment description.

experiment_type: (required) NX_CHAR

Specify the type of the optical experiment.

start_time: (required) NX_DATE_TIME ⤆

Start time of the experiment. UTC offset should be specified.

USER: (required) NXuser ⤆

Contact information of at least the user of the instrument or the ...

Contact information of at least the user of the instrument or the investigator who performed this experiment. Adding multiple users, if relevant, is recommended.

name: (required) NX_CHAR ⤆

Name of the user.

affiliation: (recommended) NX_CHAR ⤆

Name of the affiliation of the user at the point in time when the ...

Name of the affiliation of the user at the point in time when the experiment was performed.

address: (recommended) NX_CHAR ⤆

Street address of the user’s affiliation.

email: (required) NX_CHAR ⤆

Email address of the user.

orcid: (recommended) NX_CHAR

Author ID defined by https://orcid.org/.

telephone_number: (recommended) NX_CHAR ⤆

Telephone number of the user.

INSTRUMENT: (required) NXinstrument ⤆

Properties of the experimental setup. This includes general information ...

Properties of the experimental setup. This includes general information about the instrument (such as model, company etc.), information about the calibration of the instrument, elements of the beam path including the excitation or light source and the detector unit, the sample stage (plus the sample environment, which also includes sensors used to monitor external conditions) and elements of the beam path.

Meta data describing the sample should be specified in ENTRY/SAMPLE outside of ENTRY/INSTRUMENT.

model: (required) NX_CHAR

The name of the instrument.

@version: (required) NX_CHAR

The used version of the hardware if available. If not a commercial ...

The used version of the hardware if available. If not a commercial instrument use date of completion of the hardware.

company: (optional) NX_CHAR

Name of the company which build the instrument.

construction_year: (optional) NX_DATE_TIME

ISO8601 date when the instrument was constructed. ...

ISO8601 date when the instrument was constructed. UTC offset should be specified.

calibration_status: (required) NX_CHAR

Was a calibration performed? If yes, when was it done? If the ...

Was a calibration performed? If yes, when was it done? If the calibration time is provided, it should be specified in ENTRY/INSTRUMENT/calibration/calibration_time.

Any of these values:

  • calibration time provided

  • no calibration

  • within 1 hour

  • within 1 day

  • within 1 week

angle_of_incidence: (required) NX_NUMBER (Rank: 1, Dimensions: [N_incident_angles]) {units=NX_ANGLE}

Angle(s) of the incident beam vs. the normal of the bottom reflective ...

Angle(s) of the incident beam vs. the normal of the bottom reflective (substrate) surface in the sample.

@units: (required) NX_CHAR

detection_angle: (optional) NX_NUMBER (Rank: 1, Dimensions: [N_detection_angles]) {units=NX_ANGLE}

Detection angle(s) of the beam reflected or scattered off the sample ...

Detection angle(s) of the beam reflected or scattered off the sample vs. the normal of the bottom reflective (substrate) surface in the sample if not equal to the angle(s) of incidence.

software: (required) NXprocess

@url: (optional) NX_CHAR

Website of the software.

program: (required) NX_CHAR ⤆

Commercial or otherwise defined given name of the program that was ...

Commercial or otherwise defined given name of the program that was used to measure the data, i.e. the software used to start and record the measured data and/or metadata. If home written, one can provide the actual steps in the NOTE subfield here.

version: (required) NX_CHAR ⤆

Either version with build number, commit hash, or description of a ...

Either version with build number, commit hash, or description of a (online) repository where the source code of the program and build instructions can be found so that the program can be configured in such a way that result files can be created ideally in a deterministic manner.

firmware: (recommended) NXprogram

Commercial or otherwise defined name of the firmware that was used ...

Commercial or otherwise defined name of the firmware that was used for the measurement - if available.

@version: (required) NX_CHAR

Version and build number or commit hash of the software source code.

@url: (optional) NX_CHAR

Website of the software.

calibration: (recommended) NXsubentry

The calibration data and metadata should be described in a separate NeXus ...

The calibration data and metadata should be described in a separate NeXus file with the link provided in ‘calibration_link’.

calibration_time: (optional) NX_DATE_TIME

If calibtration status is 'calibration time provided', specify the ...

If calibtration status is ‘calibration time provided’, specify the ISO8601 date when calibration was last performed before this measurement. UTC offset should be specified.

calibration_data_link: (required) NX_CHAR

Link to the NeXus file containing the calibration data and metadata.

BEAM_PATH: (required) NXbeam_path

Describes an arrangement of optical or other elements, e.g. the beam ...

Describes an arrangement of optical or other elements, e.g. the beam path between the light source and the sample, or between the sample and the detector unit (including the sources and detectors themselves).

If a beam splitter (i.e. a device that splits the incoming beam into two or more beams) is part of the beam path, two or more NXbeam_path fields may be needed to fully describe the beam paths and the correct sequence of the beam path elements. Use as many beam paths as needed to describe the setup.

sample_stage: (required) NXsubentry

Sample stage, holding the sample at a specific position in X,Y,Z ...

Sample stage, holding the sample at a specific position in X,Y,Z (Cartesian) coordinate system and at an orientation defined by three Euler angles (alpha, beta, gamma).

stage_type: (required) NX_CHAR

Specify the type of the sample stage. ...

Specify the type of the sample stage.

Any of these values:

  • manual stage

  • scanning stage

  • liquid stage

  • gas cell

  • cryostat

alternative: (optional) NX_CHAR

If there is no motorized stage, we should at least qualify where ...

If there is no motorized stage, we should at least qualify where the beam hits the sample and in what direction the sample stands in a free-text description, e.g. ‘center of sample, long edge parallel to the plane of incidence’.

environment_conditions: (required) NXenvironment

Specify external parameters that have influenced the sample, such ...

Specify external parameters that have influenced the sample, such as the surrounding medium, and varied parameters e.g. temperature, pressure, pH value, optical excitation etc.

medium: (required) NX_CHAR

Describe what was the medium above or around the sample. The ...

Describe what was the medium above or around the sample. The common model is built up from the substrate to the medium on the other side. Both boundaries are assumed infinite in the model. Here, define the name of the medium (e.g. water, air, UHV, etc.).

medium_refractive_indices: (optional) NX_FLOAT (Rank: 2, Dimensions: [2, N_spectrum]) {units=NX_UNITLESS}

Array of pairs of complex refractive indices n + ik of the medium ...

Array of pairs of complex refractive indices n + ik of the medium for every measured spectral point/wavelength/energy. Only necessary if the measurement was performed not in air, or something very well known, e.g. high purity water.

PARAMETER: (optional) NXsensor ⤆

A sensor used to monitor an external condition influencing the ...

A sensor used to monitor an external condition influencing the sample, such as temperature or pressure. It is suggested to replace ‘PARAMETER’ by the type of the varied parameter defined in ‘parameter_type’. The measured parameter values should be provided in ‘values’. For each parameter, a ‘PARAMETER(NXsensor)’ field needs to exist. In other words, there are N_sensors ‘PARAMETER(NXsensor)’ fields.

parameter_type: (required) NX_CHAR

Indicates which parameter was changed. Its definition must exist ...

Indicates which parameter was changed. Its definition must exist below. The specified variable has to be N_measurements long, providing the parameters for each data set. If you vary more than one parameter simultaneously. If the measured parameter is not contained in the list other should be specified and the parameter_type_name should be provided.

Any of these values:

  • conductivity

  • detection_angle

  • electric_field

  • flow

  • incident_angle

  • magnetic_field

  • optical_excitation

  • pH

  • pressure

  • resistance

  • shear

  • stage_positions

  • strain

  • stress

  • surface_pressure

  • temperature

  • voltage

  • other

parameter_type_name: (optional) NX_CHAR

If the parameter_type is other a name should be specified here.

number_of_parameters: (required) NX_POSINT {units=NX_UNITLESS}

Number of different parameter values at which the measurement ...

Number of different parameter values at which the measurement was performed. For example, if the measurement was performed at temperatures of 4, 77 and 300 K, then number_of_parameters = 3.

values: (required) NX_FLOAT (Rank: 1, Dimensions: [N_measurements]) {units=NX_ANY}

Vector containing the values of the varied parameter. Its ...

Vector containing the values of the varied parameter. Its length is equal to N_measurements. The order of the values should be as follows:

  • Order the sensors according to number_of_parameters starting with the lowest number. If number_of_parameters is equal for two sensors order them alphabetically (sensor/parameter name).

  • The first sensor’s j parameters should be ordered in the following way. The first N_measurements/number_of_parameters entries of the vector contain the first parameter (a1), the second N_measurements/number_of_parameters contain the second parameter (a2) etc., so the vector looks like: [ a1,a1,…,a1, a2,a2,…,a2, … aj,aj,…aj ]

  • The kth sensor’s m parameters should be ordered in the following way: [ p1,…p1,p2,…,p2,…pm,…,pm, p1,…p1,p2,…,p2,…pm,…,pm, … p1,…p1,p2,…,p2,…pm,…,pm ]

  • The last sensor’s n parameters should be ordered in the following way: [ z1,z2,…,zn, z1,z2,…,zn, … z1,z2,…,zn]

For example, if the experiment was performed at three different temperatures (T1, T2, T3), two different pressures (p1, p2) and two different angles of incidence (a1, a2), then N_measurements = 12 and the order of the values for the various parameter vectors is:

  • angle_of_incidence: [a1,a1,a1,a1,a1,a1,a2,a2,a2,a2,a2,a2]

  • pressure: [p1,p1,p1,p2,p2,p2,p1,p1,p1,p2,p2,p2]

  • temperature: [T1,T2,T3,T1,T2,T3,T1,T2,T3,T1,T2,T3]

WINDOW: (optional) NXaperture

For environmental measurements, the environment (liquid, vapor ...

For environmental measurements, the environment (liquid, vapor etc.) is enclosed in a cell, which has windows both in the direction of the source (entry window) and the detector (exit window) (looking from the sample). In case that the entry and exit windows are not the same type and do not have the same properties, use a second ‘WINDOW(MXaperture)’ field.

The windows also add a phase shift to the light altering the measured signal. This shift has to be corrected based on measuring a known sample (reference sample) or the actual sample of interest in the environmental cell. State if a window correction has been performed in ‘window_effects_corrected’. Reference data should be considered as a separate experiment, and a link to the NeXus file should be added in reference_data_link in measured_data.

The window is considered to be a part of the sample stage but also beam path. Hence, its position within the beam path should be defined by the ‘depends_on’ field.

depends_on: (recommended) NX_CHAR ⤆

Specify the position of the window in the beam path by pointing ...

Specify the position of the window in the beam path by pointing to the preceding element in the sequence of beam path elements.

window_effects_corrected: (required) NX_BOOLEAN

Was a window correction performed? If 'True' describe the window ...

Was a window correction performed? If ‘True’ describe the window correction procedure in ‘window_correction/procedure’.

material: (required) NX_CHAR ⤆

The material of the window. ...

The material of the window.

Any of these values:

  • quartz

  • diamond

  • calcium fluoride

  • zinc selenide

  • thallium bromoiodide

  • alkali halide compound

  • Mylar

  • other

other_material: (optional) NX_CHAR

If you specified ‘other’ as material, decsribe here what it is.

thickness: (required) NX_FLOAT {units=NX_LENGTH}

Thickness of the window.

orientation_angle: (required) NX_FLOAT {units=NX_ANGLE}

Angle of the window normal (outer) vs. the substrate normal ...

Angle of the window normal (outer) vs. the substrate normal (similar to the angle of incidence).

window_correction: (optional) NXprocess

Was a window correction performed? If 'True' describe the ...

Was a window correction performed? If ‘True’ describe the window correction procedure in ‘’

procedure: (required) NX_CHAR

Describe when (before or after the main measurement + time ...

Describe when (before or after the main measurement + time stamp in ‘date’) and how the window effects have been corrected, i.e. either mathematically or by performing a reference measurement. In the latter case, provide the link to to the reference data in ‘reference_data_link’.

reference_data_link: (optional) NX_CHAR

Link to the NeXus file which describes the reference data if a ...

Link to the NeXus file which describes the reference data if a reference measurement for window correction was performed. Ideally, the reference measurement was performed on a reference sample and on the same sample, and using the same conditions as for the actual measurement with and without windows. It should have been conducted as close in time to the actual measurement as possible.

SAMPLE: (required) NXsample ⤆

Properties of the sample, such as sample type, layer structure, ...

Properties of the sample, such as sample type, layer structure, chemical formula, atom types, its history etc. Information about the sample stage and sample environment should be described in ENTRY/INSTRUMENT/sample_stage.

sample_name: (required) NX_CHAR

Descriptive name of the sample

sample_type: (required) NX_CHAR

Specify the type of sample, e.g. thin film, single crystal etc. ...

Specify the type of sample, e.g. thin film, single crystal etc.

Any of these values:

  • thin film

  • single crystal

  • poly crystal

  • single layer

  • multi layer

layer_structure: (required) NX_CHAR

Qualitative description of the layer structure for the sample, ...

Qualitative description of the layer structure for the sample, starting with the top layer (i.e. the one on the front surface, on which the light incident), e.g. native oxide/bulk substrate, or Si/native oxide/thermal oxide/polymer/peptide.

chemical_formula: (required) NX_CHAR ⤆

Chemical formula of the sample. Use the Hill system (explained here: ...

Chemical formula of the sample. Use the Hill system (explained here: https://en.wikipedia.org/wiki/Chemical_formula#Hill_system) to write the chemical formula. In case the sample consists of several layers, this should be a list of the chemical formulas of the individual layers, where the first entry is the chemical formula of the top layer (the one on the front surface, on which the light incident). The order must be consistent with layer_structure

atom_types: (required) NX_CHAR

List of comma-separated elements from the periodic table that are ...

List of comma-separated elements from the periodic table that are contained in the sample. If the sample substance has multiple components, all elements from each component must be included in ‘atom_types’.

sample_history: (required) NX_CHAR

Ideally, a reference to the location or a unique (globally ...

Ideally, a reference to the location or a unique (globally persistent) identifier (e.g.) of e.g. another file which gives as many as possible details of the material, its microstructure, and its thermo-chemo-mechanical processing/preparation history. In the case that such a detailed history of the sample is not available, use this field as a free-text description to specify details of the sample and its preparation.

preparation_date: (recommended) NX_DATE_TIME ⤆

ISO8601 date with time zone (UTC offset) specified.

substrate: (recommended) NX_CHAR

Description of the substrate.

sample_orientation: (optional) NX_CHAR

Specify the sample orientation.

data_collection: (required) NXprocess ⤆

Measured data, data errors, and varied parameters. If reference data ...

Measured data, data errors, and varied parameters. If reference data were measured they should be considered a separate experiment and a link to its NeXus file should be added in reference_data_link.

data_identifier: (required) NX_NUMBER

An identifier to correlate data to the experimental conditions, ...

An identifier to correlate data to the experimental conditions, if several were used in this measurement; typically an index of 0-N.

data_type: (required) NX_CHAR

Select which type of data was recorded, for example intensity, ...

Select which type of data was recorded, for example intensity, reflectivity, transmittance, Psi and Delta etc. It is possible to have multiple selections. The enumeration list depends on the type of experiment and may differ for different application definitions.

Any of these values:

  • intensity

  • reflectivity

  • transmittance

  • Psi/Delta

  • tan(Psi)/cos(Delta)

  • Mueller matrix

  • Jones matrix

  • N/C/S

  • raw data

NAME_spectrum: (optional) NX_FLOAT (Rank: 1, Dimensions: [N_spectrum]) {units=NX_ANY}

Spectral values (e.g. wavelength or energy) used for the measurement. ...

Spectral values (e.g. wavelength or energy) used for the measurement. An array of 1 or more elements. Length defines N_spectrum. Replace ‘SPECTRUM’ by the physical quantity that is used, e.g. wavelength.

@units: (optional) NX_CHAR

If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. ...

If applicable, change ‘unit: NX_ANY’ to the appropriate NXDL unit. If the unit of the measured data is not covered by NXDL units state here which unit was used.

measured_data: (required) NX_FLOAT (Rank: 3, Dimensions: [N_measurements, N_observables, N_spectrum]) {units=NX_ANY}

Resulting data from the measurement, described by 'data_type'. ...

Resulting data from the measurement, described by ‘data_type’.

The first dimension is defined by the number of measurements taken, (N_measurements). The instructions on how to order the values contained in the parameter vectors given in the doc string of INSTRUMENT/sample_stage/environment_conditions/PARAMETER/values, define the N_measurements parameter sets. For example, if the experiment was performed at three different temperatures (T1, T2, T3), two different pressures (p1, p2) and two different angles of incidence (a1, a2), the first measurement was taken at the parameters {a1,p1,T1}, the second measurement at {a1,p1,T2} etc.

@units: (optional) NX_CHAR

If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. ...

If applicable, change ‘unit: NX_ANY’ to the appropriate NXDL unit. If the unit of the measured data is not covered by NXDL units state here which unit was used.

measured_data_errors: (optional) NX_FLOAT (Rank: 3, Dimensions: [N_measurements, N_observables, N_spectrum]) {units=NX_ANY}

Specified uncertainties (errors) of the data described by 'data_type' ...

Specified uncertainties (errors) of the data described by ‘data_type’ and provided in ‘measured_data’.

@units: (optional) NX_CHAR

If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. ...

If applicable, change ‘unit: NX_ANY’ to the appropriate NXDL unit. If the unit of the measured data is not covered by NXDL units state here which unit was used.

varied_parameter_link: (optional) NX_CHAR (Rank: 1, Dimensions: [N_sensors])

List of links to the values of the sensors. Add a link for each ...

List of links to the values of the sensors. Add a link for each varied parameter (i.e. for each sensor).

reference_data_link: (optional) NX_CHAR

Link to the NeXus file which describes the reference data if a ...

Link to the NeXus file which describes the reference data if a reference measurement was performed. Ideally, the reference measurement was performed using the same conditions as the actual measurement and should be as close in time to the actual measurement as possible.

data_software: (optional) NXprocess

@url: (optional) NX_CHAR

Website of the software.

program: (required) NX_CHAR ⤆

Commercial or otherwise defined given name of the program that was ...

Commercial or otherwise defined given name of the program that was used to generate the result file(s) with measured data and/or metadata (in most cases, this is the same as INSTRUMENT/software). If home written, one can provide the actual steps in the NOTE subfield here.

version: (required) NX_CHAR ⤆

Either version with build number, commit hash, or description of a ...

Either version with build number, commit hash, or description of a (online) repository where the source code of the program and build instructions can be found so that the program can be configured in such a way that result files can be created ideally in a deterministic manner.

DATA: (optional) NXdata

A plot of the multi-dimensional data array provided in ...

A plot of the multi-dimensional data array provided in ENTRY/data/measured_data.

@axes: (required) NX_CHAR ⤆

Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.)

derived_parameters: (optional) NXprocess ⤆

Parameters that are derived from the measured data.

depolarization: (optional) NX_NUMBER (Rank: 3, Dimensions: [N_measurements, 1, N_spectrum]) {units=NX_UNITLESS}

Light loss due to depolarization as a value in [0-1].

Jones_quality_factor: (optional) NX_NUMBER (Rank: 3, Dimensions: [N_measurements, 1, N_spectrum]) {units=NX_UNITLESS}

Jones quality factor.

reflectivity: (optional) NX_NUMBER (Rank: 3, Dimensions: [N_measurements, 1, N_spectrum]) {units=NX_UNITLESS}

Reflectivity.

transmittance: (optional) NX_NUMBER (Rank: 3, Dimensions: [N_measurements, 1, N_spectrum]) {units=NX_UNITLESS}

Transmittance.

ANALYSIS_program: (optional) NXprocess

program: (required) NX_CHAR ⤆

Commercial or otherwise defined given name of the program that was ...

Commercial or otherwise defined given name of the program that was used to generate or calculate the derived parameters. If home written, one can provide the actual steps in the NOTE subfield here.

version: (required) NX_CHAR ⤆

Either version with build number, commit hash, or description of a ...

Either version with build number, commit hash, or description of a (online) repository where the source code of the program and build instructions can be found so that the program can be configured in such a way that result files can be created ideally in a deterministic manner.

plot: (required) NXdata ⤆

A default view of the data provided in ENTRY/data_collection/measured_data. ...

A default view of the data provided in ENTRY/data_collection/measured_data. This should be the part of the data set which provides the most suitable representation of the data.

@axes: (required) NX_CHAR ⤆

Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.)

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/contributed_definitions/NXopt.nxdl.xml