diff --git a/contributed_definitions/NXxps.nxdl.xml b/contributed_definitions/NXxps.nxdl.xml new file mode 100644 index 0000000000..3aa82e8861 --- /dev/null +++ b/contributed_definitions/NXxps.nxdl.xml @@ -0,0 +1,352 @@ + + + + + + This is the application definition for X-ray photoelectron spectroscopy. + + + + + + + + + + A name of the experimental method according to `Clause 11`_ of + the `ISO 18115-1:2023`_ specification. + + Examples for XPS-related experiments include: + * X-ray photoelectron spectroscopy (XPS) + * angle-resolved X-ray photoelectron spectroscopy (ARXPS) + * ultraviolet photoelectron spectroscopy (UPS) + * hard X-ray photoemission spectroscopy (HAXPES) + * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) + * electron spectroscopy for chemical analysis (ESCA) + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 + + + + + + In traditional surface science, a left-handed coordinate system is used such that the positive z-axis + points along the normal of the sample stage, and the x- and y-axes lie in the plane of the sample stage. + However, in NeXus, a coordinate system that is the same as `McStas`_ is used. `xps_coordinate_system` + gives the user the opportunity to work in the traditional base coordinate system. + + .. _McStas: http://mcstas.org/ + + .. image:: xps/xps_cs.png + :width: 40% + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Link to transformations defining the XPS base coordinate system, + which is defined such that the positive z-axis points along the sample stage normal, and the + x- and y-axes lie in the plane of the sample stage. + + + + + Set of transformations, describing the orientation of the XPS coordinate system + with respect to the beam coordinate system (.) or any other coordinate system. + + The transformations in `coordinate_system_transformations` depend on the actual instrument geometry. + If the z-axis is pointing in the direction of gravity (i.e., if the sample is mounted horizontally), + the following transformations can be used for describing the XPS coordinate system + with respect to the beam coordinate system (.): + + .. code-block:: + + xps_coordinate_system:NXcoordinate_system + depends_on=entry/geometries/xps_coordinate_system/coordinate_transformations/z_rotation + coordinate_system_transformations:NXtransformations + z_rotation=beam_azimuth_angle + @depends_on=y_flip + @transformation_type=rotation + @vector=[0, 0, 1] + @units=degree + y_flip=180 + @depends_on=y_rotation + @transformation_type=rotation + @vector=[0, 1, 0] + @units=degree + y_rotation=beam_polar_angle_of_incidence + @depends_on=. + @transformation_type=rotation + @vector=[0, 1, 0] + @units=degree + + + + + + + Description of the XPS spectrometer and its individual parts. + + This concept is related to term `12.58`_ of the ISO 18115-1:2023 standard. + + .. _12.58: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 + + + + + + + + Reference to the transformation describing the orientation of the beam + relative to a defined coordinate system. + + + + + + Incidence angle of the beam with respect to the upward z-direction, defined by + the sample stage. + + + + + + + + + + + + + + + + + + + + Azimuthal rotation of the beam from the y-direction towards the operator, defined + by the sample stage. + + + + + + + + + + + + + + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + + + + + + + + + + + + + + + + + + Reference to the transformation describing the orientation of the analyzer + relative to a defined coordinate system. + + + + + + Polar tilt of the analyser with respect to the upward z-direction, defined by + the sample stage. + + The angle between the incoming beam and the analyser is given by + beam_analyser_angle = beam_polar_angle_of_incidence + analyser_take_off_polar_angle. + In practice, the analyser axis is often set as the z axis (analyser_take_off_polar_angle = 0), + so that beam_analyser_angle = beam_polar_angle_of_incidence. For magic angle configurations, + this angle is 54.5°. + + + + + + + + + + + + + + + + + + + + Azimuthal rotation of the analyser from the y-direction towards the operator, + defined by the sample stage. + + + + + + + + + + + + + + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + + + + + + + + + + + + + + Reference to the transformation describing the orientation of the sample + relative to a defined coordinate system. + + + + + + Clockwise rotation about the sample normal. + + + + + + + + + + + + + + + + + + + + Polar tilt of the sample with respect to the upward z-direction, defined by + the sample stage. + + + + + + + + + + + + + + + + + + + + Azimuthal rotation of the sample from the y-direction towards the operator, + defined by the sample stage. + + + + + + + + + + + + + + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + + + + + + + + + + + + + diff --git a/contributed_definitions/nyaml/NXxps.yaml b/contributed_definitions/nyaml/NXxps.yaml new file mode 100644 index 0000000000..8add5adc7e --- /dev/null +++ b/contributed_definitions/nyaml/NXxps.yaml @@ -0,0 +1,585 @@ +category: application +doc: | + This is the application definition for X-ray photoelectron spectroscopy. +type: group +NXxps(NXmpes): + (NXentry): + definition(NX_CHAR): + enumeration: [NXxps] + method: + doc: | + A name of the experimental method according to `Clause 11`_ of + the `ISO 18115-1:2023`_ specification. + + Examples for XPS-related experiments include: + * X-ray photoelectron spectroscopy (XPS) + * angle-resolved X-ray photoelectron spectroscopy (ARXPS) + * ultraviolet photoelectron spectroscopy (UPS) + * hard X-ray photoemission spectroscopy (HAXPES) + * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) + * electron spectroscopy for chemical analysis (ESCA) + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 + geometries(NXcoordinate_system_set): + xps_coordinate_system(NXcoordinate_system): + exists: optional + doc: | + In traditional surface science, a left-handed coordinate system is used such that the positive z-axis + points along the normal of the sample stage, and the x- and y-axes lie in the plane of the sample stage. + However, in NeXus, a coordinate system that is the same as `McStas`_ is used. `xps_coordinate_system` + gives the user the opportunity to work in the traditional base coordinate system. + + .. _McStas: http://mcstas.org/ + + .. image:: xps/xps_cs.png + :width: 40% + origin: + enumeration: [sample stage] + handedness: + enumeration: [left_handed] + z_direction: + enumeration: [sample stage normal] + x: + enumeration: [[-1, 0, 0]] + y: + enumeration: [[0, 1, 0]] + z: + enumeration: [[0, 0, 1]] + depends_on(NX_CHAR): + doc: | + Link to transformations defining the XPS base coordinate system, + which is defined such that the positive z-axis points along the sample stage normal, and the + x- and y-axes lie in the plane of the sample stage. + coordinate_system_transformations(NXtransformations): + doc: | + Set of transformations, describing the orientation of the XPS coordinate system + with respect to the beam coordinate system (.) or any other coordinate system. + + The transformations in `coordinate_system_transformations` depend on the actual instrument geometry. + If the z-axis is pointing in the direction of gravity (i.e., if the sample is mounted horizontally), + the following transformations can be used for describing the XPS coordinate system + with respect to the beam coordinate system (.): + + .. code-block:: + + xps_coordinate_system:NXcoordinate_system + depends_on=entry/geometries/xps_coordinate_system/coordinate_transformations/z_rotation + coordinate_system_transformations:NXtransformations + z_rotation=beam_azimuth_angle + @depends_on=y_flip + @transformation_type=rotation + @vector=[0, 0, 1] + @units=degree + y_flip=180 + @depends_on=y_rotation + @transformation_type=rotation + @vector=[0, 1, 0] + @units=degree + y_rotation=beam_polar_angle_of_incidence + @depends_on=. + @transformation_type=rotation + @vector=[0, 1, 0] + @units=degree + (NXinstrument): + doc: + - | + Description of the XPS spectrometer and its individual parts. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.58 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 + sourceTYPE(NXsource): + power(NX_FLOAT): + unit: NX_POWER + exists: recommended + beamTYPE(NXbeam): + depends_on: + exists: recommended + doc: | + Reference to the transformation describing the orientation of the beam + relative to a defined coordinate system. + transformations(NXtransformations): + exists: recommended + beam_polar_angle_of_incidence(NX_NUMBER): + unit: NX_ANGLE + doc: | + Incidence angle of the beam with respect to the upward z-direction, defined by + the sample stage. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, -1, 0]] + \@depends_on: + enumeration: [beam_azimuth_angle] + beam_azimuth_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Azimuthal rotation of the beam from the y-direction towards the operator, defined + by the sample stage. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, 0, -1]] + \@depends_on: + doc: | + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + (NXelectronanalyser): + work_function(NX_FLOAT): + transmission_function(NXdata): + exists: recommended + (NXcollectioncolumn): + magnification(NX_FLOAT): + exists: recommended + unit: NX_DIMENSIONLESS + (NXenergydispersion): + diameter(NX_NUMBER): + exists: recommended + unit: NX_LENGTH + energy_scan_mode: + depends_on: + exists: recommended + doc: | + Reference to the transformation describing the orientation of the analyzer + relative to a defined coordinate system. + transformations(NXtransformations): + exists: recommended + analyser_take_off_polar_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Polar tilt of the analyser with respect to the upward z-direction, defined by + the sample stage. + + The angle between the incoming beam and the analyser is given by + beam_analyser_angle = beam_polar_angle_of_incidence + analyser_take_off_polar_angle. + In practice, the analyser axis is often set as the z axis (analyser_take_off_polar_angle = 0), + so that beam_analyser_angle = beam_polar_angle_of_incidence. For magic angle configurations, + this angle is 54.5°. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, -1, 0]] + \@depends_on: + enumeration: [analyser_take_off_azimuth_angle] + analyser_take_off_azimuth_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Azimuthal rotation of the analyser from the y-direction towards the operator, + defined by the sample stage. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, 0, -1]] + \@depends_on: + doc: | + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + (NXprocess_mpes): + energy_referencing(NXcalibration): + exists: recommended + transmission_correction(NXcalibration): + exists: recommended + (NXsample): + depends_on: + exists: recommended + doc: | + Reference to the transformation describing the orientation of the sample + relative to a defined coordinate system. + transformations(NXtransformations): + exists: recommended + sample_rotation_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Clockwise rotation about the sample normal. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, 0, -1]] + \@depends_on: + enumeration: [sample_normal_polar_angle_of_tilt] + sample_normal_polar_angle_of_tilt(NX_NUMBER): + unit: NX_ANGLE + doc: | + Polar tilt of the sample with respect to the upward z-direction, defined by + the sample stage. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, -1, 0]] + \@depends_on: + enumeration: [sample_normal_tilt_azimuth_angle] + sample_normal_tilt_azimuth_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Azimuthal rotation of the sample from the y-direction towards the operator, + defined by the sample stage. + \@transformation_type: + enumeration: [rotation] + \@vector: + enumeration: [[0, 0, -1]] + \@depends_on: + doc: | + This should point to the last element of the coordinate system transformations defined in + /entry/geometries/xps_coordinate_system/coordinate_system_transformations. + data(NXdata): + energy(NX_NUMBER): + \@reference: + exists: recommended + \@energy_indices: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4e74c48e0373e4962f15d12f44b67a01cf518c750a3dcaa545701e4da36663cf +# +# +# +# +# +# This is the application definition for X-ray photoelectron spectroscopy. +# +# +# +# +# +# +# +# +# +# A name of the experimental method according to `Clause 11`_ of +# the `ISO 18115-1:2023`_ specification. +# +# Examples for XPS-related experiments include: +# * X-ray photoelectron spectroscopy (XPS) +# * angle-resolved X-ray photoelectron spectroscopy (ARXPS) +# * ultraviolet photoelectron spectroscopy (UPS) +# * hard X-ray photoemission spectroscopy (HAXPES) +# * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) +# * electron spectroscopy for chemical analysis (ESCA) +# +# .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html +# .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 +# +# +# +# +# +# In traditional surface science, a left-handed coordinate system is used such that the positive z-axis +# points along the normal of the sample stage, and the x- and y-axes lie in the plane of the sample stage. +# However, in NeXus, a coordinate system that is the same as `McStas`_ is used. `xps_coordinate_system` +# gives the user the opportunity to work in the traditional base coordinate system. +# +# .. _McStas: http://mcstas.org/ +# +# .. image:: xps/xps_cs.png +# :width: 40% +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Link to transformations defining the XPS base coordinate system, +# which is defined such that the positive z-axis points along the sample stage normal, and the +# x- and y-axes lie in the plane of the sample stage. +# +# +# +# +# Set of transformations, describing the orientation of the XPS coordinate system +# with respect to the beam coordinate system (.) or any other coordinate system. +# +# The transformations in `coordinate_system_transformations` depend on the actual instrument geometry. +# If the z-axis is pointing in the direction of gravity (i.e., if the sample is mounted horizontally), +# the following transformations can be used for describing the XPS coordinate system +# with respect to the beam coordinate system (.): +# +# .. code-block:: +# +# xps_coordinate_system:NXcoordinate_system +# depends_on=entry/geometries/xps_coordinate_system/coordinate_transformations/z_rotation +# coordinate_system_transformations:NXtransformations +# z_rotation=beam_azimuth_angle +# @depends_on=y_flip +# @transformation_type=rotation +# @vector=[0, 0, 1] +# @units=degree +# y_flip=180 +# @depends_on=y_rotation +# @transformation_type=rotation +# @vector=[0, 1, 0] +# @units=degree +# y_rotation=beam_polar_angle_of_incidence +# @depends_on=. +# @transformation_type=rotation +# @vector=[0, 1, 0] +# @units=degree +# +# +# +# +# +# +# Description of the XPS spectrometer and its individual parts. +# +# This concept is related to term `12.58`_ of the ISO 18115-1:2023 standard. +# +# .. _12.58: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 +# +# +# +# +# +# +# +# Reference to the transformation describing the orientation of the beam +# relative to a defined coordinate system. +# +# +# +# +# +# Incidence angle of the beam with respect to the upward z-direction, defined by +# the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Azimuthal rotation of the beam from the y-direction towards the operator, defined +# by the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should point to the last element of the coordinate system transformations defined in +# /entry/geometries/xps_coordinate_system/coordinate_system_transformations. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Reference to the transformation describing the orientation of the analyzer +# relative to a defined coordinate system. +# +# +# +# +# +# Polar tilt of the analyser with respect to the upward z-direction, defined by +# the sample stage. +# +# The angle between the incoming beam and the analyser is given by +# beam_analyser_angle = beam_polar_angle_of_incidence + analyser_take_off_polar_angle. +# In practice, the analyser axis is often set as the z axis (analyser_take_off_polar_angle = 0), +# so that beam_analyser_angle = beam_polar_angle_of_incidence. For magic angle configurations, +# this angle is 54.5°. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Azimuthal rotation of the analyser from the y-direction towards the operator, +# defined by the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should point to the last element of the coordinate system transformations defined in +# /entry/geometries/xps_coordinate_system/coordinate_system_transformations. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Reference to the transformation describing the orientation of the sample +# relative to a defined coordinate system. +# +# +# +# +# +# Clockwise rotation about the sample normal. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Polar tilt of the sample with respect to the upward z-direction, defined by +# the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Azimuthal rotation of the sample from the y-direction towards the operator, +# defined by the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should point to the last element of the coordinate system transformations defined in +# /entry/geometries/xps_coordinate_system/coordinate_system_transformations. +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/xps/xps_cs.png b/contributed_definitions/xps/xps_cs.png new file mode 100644 index 0000000000..f83b15e707 Binary files /dev/null and b/contributed_definitions/xps/xps_cs.png differ diff --git a/manual/source/mpes-structure.rst b/manual/source/mpes-structure.rst index 88cf42b6aa..e0091995cb 100644 --- a/manual/source/mpes-structure.rst +++ b/manual/source/mpes-structure.rst @@ -30,4 +30,7 @@ Here's a list of application definitions related to photoemission spectroscopy: A universal application definition with minimal metadata requirements for describing all photoemission experiments. :ref:`NXmpes_arpes`: - An appdef for angle-resolved photoemission spectroscopy (ARPES) experiments. \ No newline at end of file + An appdef for angle-resolved photoemission spectroscopy (ARPES) experiments. + + :ref:`NXxps`: + An application definition for XPS/UPS measurements. \ No newline at end of file