diff --git a/base_classes/NXsource.nxdl.xml b/base_classes/NXsource.nxdl.xml index 10b6bb4db6..b331872977 100644 --- a/base_classes/NXsource.nxdl.xml +++ b/base_classes/NXsource.nxdl.xml @@ -63,8 +63,23 @@ + + + + + + + + + + + + + Specification of type, may also go to name. + + type of radiation probe (pick one from the enumerated list and spell exactly) @@ -265,6 +280,17 @@ Gas pressure inside ionization source. + + + Single instance or list of instances of NXsource pointing to the sources from which a beam originated to reach this source. + This can be used, for example, for secondary sources to describe which other source(s) they are derived from. + + An example is the white light source in transient absorption spectroscopy, which is a supercontinuum crystal that is pumped by a + another laser. + + In case of a primary source, this field should not be filled. + + "Engineering" location of source. diff --git a/base_classes/nyaml/NXsource.yaml b/base_classes/nyaml/NXsource.yaml index dd6fffc147..67c89f77ae 100644 --- a/base_classes/nyaml/NXsource.yaml +++ b/base_classes/nyaml/NXsource.yaml @@ -21,7 +21,10 @@ NXsource(NXobject): type: doc: | type of radiation source (pick one from the enumerated list and spell exactly) - enumeration: [Spallation Neutron Source, Pulsed Reactor Neutron Source, Reactor Neutron Source, Synchrotron X-ray Source, Pulsed Muon Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Free-Electron Laser, Optical Laser, Ion Source, UV Plasma Source, Metal Jet X-ray] + enumeration: [Spallation Neutron Source, Pulsed Reactor Neutron Source, Reactor Neutron Source, Synchrotron X-ray Source, Pulsed Muon Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Free-Electron Laser, Optical Laser, Ion Source, UV Plasma Source, Metal Jet X-ray, Laser, Dye-Laser, Broadband Tunable Light Source, Halogen lamp, LED, Mercury Cadmium Telluride, Deuterium Lamp, Xenon Lamp, Globar, other] + type_other: + doc: | + Specification of type, may also go to name. probe: doc: | type of radiation probe (pick one from the enumerated list and spell exactly) @@ -160,6 +163,15 @@ NXsource(NXobject): unit: NX_PRESSURE doc: | Gas pressure inside ionization source. + previous_source(NX_CHAR): + doc: | + Single instance or list of instances of NXsource pointing to the sources from which a beam originated to reach this source. + This can be used, for example, for secondary sources to describe which other source(s) they are derived from. + + An example is the white light source in transient absorption spectroscopy, which is a supercontinuum crystal that is pumped by a + another laser. + + In case of a primary source, this field should not be filled. geometry(NXgeometry): deprecated: | Use the field `depends_on` and :ref:`NXtransformations` to position the source and NXoff_geometry to describe its shape instead @@ -215,7 +227,7 @@ NXsource(NXobject): other component groups. # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ -# 2e2112dcd5b309b4339af1ac92e7ff2d12e639c98146519a85e6f4bdd85adbb2 +# a6e859a68a9cf9c4326794a135f8d28f1bb5634237378a108afc31d12763b73d # # # +Fields should be named according to new following convention: +- **pixel_x**: Detector pixel in x direction. +- **pixel_y**: Detector pixel in y direction. +- **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). +- **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). +- **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). +- **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). +- **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). +Unit category: NX_ANGLE +- **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +Unit category: NX_ANGLE +- **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) +Unit category: NX_LENGTH +- **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +Unit category: NX_LENGTH +- **delay**: Calibrated delay time. Unit category: NX_TIME (s). +- **polarization_angle**: Linear polarization angle of the incoming or +outgoing beam. +Unit category: NX_ANGLE (° or rad) +- **ellipticity**: Ellipticity of the incoming or outgoing beam. +Unit category: NX_ANGLE (° or rad) +- **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT +- **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. +- **external_AXIS**: Describes an axis which is coming from outside the detectors scope.--> @@ -387,7 +385,7 @@ TODO: - Specify respective hardware which was used for the detector. For + Specify respective hardware which was used for the detector. For example special electronics required for time-correlated single photon counting (TCSPC). @@ -397,17 +395,20 @@ TODO: - - - - - - + + + + + + + + + - - - - + + + + @@ -454,7 +455,7 @@ TODO: plane#1 = spanned by incidence beam and detection and detection. If Chi=0°, then plane#1 is the plane of incidence in reflection setups) - - Phi (inplane rotation of sample, rotation axis is the samples + - Phi (inplane rotation of sample, rotation axis is the samples surface normal) @@ -604,7 +605,7 @@ TODO: - Specify if there is a lateral offset on the sample surface, between the focal + Specify if there is a lateral offset on the sample surface, between the focal points of the incident beam and the detection beam. @@ -659,7 +660,7 @@ TODO: - polarization filter to prepare light to be measured or to be incident + polarization filter to prepare light to be measured or to be incident on the sample. Genereric polarization filter porperties may be implemented via NXfilter_pol at a later stage. @@ -740,9 +741,9 @@ TODO: +exists: optional +doc: | +Can be used to describe a beam splitter as optical element.--> Allows description of beam properties via matrices, which relate ingoing with @@ -777,7 +778,7 @@ TODO: This allows a description of the stages relation or orientation and - position with respect to the sample or beam, if an laboratory or + position with respect to the sample or beam, if an laboratory or an stage coordinate system is defined. @@ -786,7 +787,7 @@ TODO: Description of relation of the beam with the sample. How dit the sample hit the beam, e.g. 'center of sample, long edge parallel to the plane of incidence'. - Is redundent, if a full orientation description is done via the + Is redundent, if a full orientation description is done via the stages "transformations" entry. @@ -1065,15 +1066,13 @@ TODO: - + (Measured) sample thickness. The information is recorded to qualify if the light used was likely - able to shine through the sample. + able to shine through the sample. In this case the value should be set to the actual thickness of the specimen viewed for an illumination situation where the nominal @@ -1086,9 +1085,7 @@ Make something like NXlayer_structure_sample? determined. - + Qualitative description of the layer structure for the sample, @@ -1116,7 +1113,7 @@ Maybe consider here to include NXsample_component_set. Here generic types of data may be saved.. This may refer to data derived from single or multiple raw measurements (i.e. several intensities are evaluated for different parameters: ellipsometry -> psi and delta) - - i.e. non-raw data. + i.e. non-raw data. As well plotable data may be stored/linked here, which provides the most suitable representation of the data (for the respective community). @@ -1149,7 +1146,7 @@ psi and delta values), will be done later after the NXopt workshop.--> Parameters that are derived from the measured data. diff --git a/contributed_definitions/nyaml/NXoptical_spectroscopy.yaml b/contributed_definitions/nyaml/NXoptical_spectroscopy.yaml index 923e2f5023..73d2e6ce76 100644 --- a/contributed_definitions/nyaml/NXoptical_spectroscopy.yaml +++ b/contributed_definitions/nyaml/NXoptical_spectroscopy.yaml @@ -1,14 +1,14 @@ category: application doc: | - A general application definition of optical spectroscopy elements, which may + A general application definition of optical spectroscopy elements, which may be used as a template to derive specialized optical spectroscopy experiments. Possible specializations are ellipsometry, Raman spectroscopy, photoluminescence, reflectivity/transmission spectroscopy. - + A general optical experiment consists of (i) a light/photon source, (ii) a sample, (iii) a detector. - + For any free text descriptions, it is recommended to enter data in english language, as this is the most FAIR representation. symbols: @@ -26,17 +26,16 @@ symbols: # 04/2024 # Extension of the Draft Version (05/2023) of a NeXus application definition which # serves as a template for various optical spectroscopy experiments -# # TODO: # - Add NXlens_opt and NXwaveplate to NXinstrument? -# - Make polfilter_TYPE(NXbeam_device) own base class --> rework NXpolarizer_opt. and add them to NXinstrument. -# - Make spectralfilter_TYPE(NXbeam_device) own base class --> extend NXfilter? and add them to NXinstrument. -# - Make offset angles for polar and azimutal? +# - Make polfilter_TYPE(NXbeam_device) own base class -\-> rework NXpolarizer_opt. and add them to NXinstrument. +# - Make spectralfilter_TYPE(NXbeam_device) own base class -\-> extend NXfilter? and add them to NXinstrument. +# - Make offset angles for polar and azimutal? # - Can angle_reference_frame be replaced later by only using reference_frames and generic angle description? -# - Add optical elements and rework them: NXfiber, NXbeam_splitter, +# - Add optical elements and rework them: NXfiber, NXbeam_splitter, # - Consider to make power flux recommended? Difficult parameter to measure. Relevant for some samples/techniques, but not for all. Powder density? Nominal vs. measured? # - Is there something to describe the spot size? -# - Restructure the concept "type" in "source_TYPE" to medium and model(NXfabication) --> suggestion from Markus: "splitting up the concept into type(NXfabrication) and emitting medium(NXion/NXatom) is a better alternative?" +# - Restructure the concept "type" in "source_TYPE" to medium and model(NXfabication) -\-> suggestion from Markus: "splitting up the concept into type(NXfabrication) and emitting medium(NXion/NXatom) is a better alternative?" # - How to describe beam size properties? NXbeam/extend? Is this enough? or do we need more abitrary shapes as elliptically? Maybe as well focus spot size? # - Think of removing/reworking of (optional) NXfabrications? Con: bloats up the NeXus def (move it to base classes?) Pro: as the fixed name device_information is used, the structure is more FAIR / clean designed? type: group @@ -70,7 +69,7 @@ NXoptical_spectroscopy(NXobject): Datetime of the end of the measurement. Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, otherwise the local time zone is assumed per ISO8601. - + It is required to enter at least one of both measurement times, either "start_time" or "end_time". experiment_identifier(NXidentifier): exists: recommended @@ -101,7 +100,7 @@ NXoptical_spectroscopy(NXobject): Users are strongly advised to parameterize the description of their experiment by using respective groups and fields and base classes instead of writing prose into this field. - + The reason is that such a free-text field is difficult to machine-interpret. The motivation behind keeping this field for now is to learn how far the current base classes need extension based on user feedback. @@ -111,7 +110,7 @@ NXoptical_spectroscopy(NXobject): Chose other if none of these methods are suitable. You may specify fundamental characteristics or properties in the experimental sub-type. - + For Raman spectroscopy or ellipsometry use the respective specializations of NXoptical_spectroscopy. enumeration: [photoluminescence, transmission spectroscopy, reflection spectroscopy, other] @@ -132,7 +131,7 @@ NXoptical_spectroscopy(NXobject): doc: | Description of one or more coordinate systems that are specific to the experiment. Examples are beam centered, sample-normal centered, - laboratory-system centered, sample-stage centered, crystal-symmetry centered. + laboratory-system centered, sample-stage centered, crystal-symmetry centered. beam_ref_frame(NXcoordinate_system): exists: optional depends_on(NX_CHAR): @@ -159,14 +158,14 @@ NXoptical_spectroscopy(NXobject): Set of transformations, describing the orientation of the sample-normal coordinate system with respect to the beam coordinate system (.). (NXuser): - exists: [min, 0, max, infty] + exists: ['min', '0', 'max', 'unbounded'] doc: | Contact information and eventually details of at persons who performed the measurements. This can be for example the principal investigator or student. Examples are: name, affiliation, address, telephone - number, email, role as well as identifiers such as orcid or similar. + number, email, role as well as identifiers such as orcid or similar. It is recommended to add multiple users if relevant. - + Due to data privacy concerns, there is no minimum requirement. If no user with specific name is allowed to be given, it is required to assign at least an affiliation @@ -186,19 +185,18 @@ NXoptical_spectroscopy(NXobject): - Stages(NXmanipulator) - Sensors and actuators to control or measure sample or beam properties beam_TYPE(NXbeam): - exists: [min, 1, max, infty] + exists: ['min', '1', 'max', 'unbounded'] doc: | This can be used to describe properties of a photon beam. A beam is always defined between two beam_devices, via "previous_device" and "next_device". - + It is required to define at least one incident beam which is incident to the sample. You may specify if this beam parameters are acutally measured or just nominal. If this beam is the output of a source, chose the same name appendix as for the NXsource instance (e.g. TYPE=532nm) parameter_reliability: - exists: required doc: | Select the reliability of the respective beam characteristics. Either, the parameters are measured via another device or method or just given @@ -216,7 +214,7 @@ NXoptical_spectroscopy(NXobject): exists: optional doc: | The path to the device which emitted this beam (light source or frequency doubler). - + This parameter is recommended, if the previous optical element is a photon source. In this way, the properties of the laser or light souce can be described and associated. @@ -225,20 +223,21 @@ NXoptical_spectroscopy(NXobject): "source_532nmlaser" and a NXbeam named "beam_532nmlaser". Example: /entry/instrument/source_532nmlaser + # The two polarization descriptions may be completely replaced by polarization beam_polarization_type: exists: optional enumeration: [linear, circular, ellipically, unpolarized] linear_beam_sample_polarization(NX_NUMBER): exists: optional + unit: NX_ANGLE doc: | Angle of the linear polarized light, with respect to a fixed arbitrary defined 0° position. This can be used if no definition of respective cooridnate systems for beam and sample normal is done. If coordinate systems are defined, refer to beam "incident_polarization". - unit: NX_ANGLE detector_TYPE(NXdetector): - exists: [min, 1, max, infty] + exists: ['min', '1', 'max', 'unbounded'] detector_channel_type: enumeration: [single-channel, multichannel] detector_type: @@ -258,33 +257,32 @@ NXoptical_spectroscopy(NXobject): due to hardware pre-processing of the data. This field ideally collects the data with the lowest level of processing possible. - - # Define a similar convention for NXoptical_spectroscopy? Or only for NXraman, NXellipsometry and NXphotoluminescence? - # Fields should be named according to new following convention: - # - # - **pixel_x**: Detector pixel in x direction. - # - **pixel_y**: Detector pixel in y direction. - # - **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). - # - **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). - # - **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). - # - **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). - # - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). - # Unit category: NX_ANGLE - # - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) - # Unit category: NX_ANGLE - # - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) - # Unit category: NX_LENGTH - # - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) - # Unit category: NX_LENGTH - # - **delay**: Calibrated delay time. Unit category: NX_TIME (s). - # - **polarization_angle**: Linear polarization angle of the incoming or - # outgoing beam. - # Unit category: NX_ANGLE (° or rad) - # - **ellipticity**: Ellipticity of the incoming or outgoing beam. - # Unit category: NX_ANGLE (° or rad) - # - **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT - # - **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. - # - **external_AXIS**: Describes an axis which is coming from outside the detectors scope. + + # Define a similar convention for NXoptical_spectroscopy? Or only for NXraman, NXellipsometry and NXphotoluminescence? + # Fields should be named according to new following convention: + # - **pixel_x**: Detector pixel in x direction. + # - **pixel_y**: Detector pixel in y direction. + # - **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). + # - **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). + # - **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). + # - **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). + # - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). + # Unit category: NX_ANGLE + # - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + # Unit category: NX_ANGLE + # - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) + # Unit category: NX_LENGTH + # - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + # Unit category: NX_LENGTH + # - **delay**: Calibrated delay time. Unit category: NX_TIME (s). + # - **polarization_angle**: Linear polarization angle of the incoming or + # outgoing beam. + # Unit category: NX_ANGLE (° or rad) + # - **ellipticity**: Ellipticity of the incoming or outgoing beam. + # Unit category: NX_ANGLE (° or rad) + # - **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT + # - **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. + # - **external_AXIS**: Describes an axis which is coming from outside the detectors scope. \@signal: enumeration: [raw] raw(NX_NUMBER): @@ -293,16 +291,16 @@ NXoptical_spectroscopy(NXobject): additional_detector_hardware: exists: optional doc: | - Specify respective hardware which was used for the detector. For - example special electronics required for time-correlated single photon - counting (TCSPC). + Specify respective hardware which was used for the detector. For + example special electronics required for time-correlated single photon + counting (TCSPC). device_information(NXfabrication): exists: recommended source_TYPE(NXsource): exists: recommended type: exists: recommended - enumeration: [laser, dye-laser, broadband tunable light source, X-ray Source, arc lamp, halogen lamp, LED, mercury cadmium telluride, deuterium lamp, xenon lamp, globar, other] + enumeration: [Synchrotron X-ray Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Optical Laser, Laser, Dye-Laser, Broadband Tunable Light Source, Halogen lamp, LED, Mercury Cadmium Telluride, Deuterium Lamp, Xenon Lamp, Globar, other] type_other: exists: optional doc: | @@ -331,13 +329,12 @@ NXoptical_spectroscopy(NXobject): exists: recommended device_information(NXfabrication): exists: recommended - angle_reference_frame: exists: recommended doc: | Defines the reference frame which is used to describe the sample orientation with respect to the beam directions. - + A beam centered description is the default and uses 4 angles(similar to XRD): - Omega (angle between sample surface and incident beam) - 2Theta (angle between the transmitted beam and the detection beam) @@ -345,21 +342,19 @@ NXoptical_spectroscopy(NXobject): plane#1 = spanned by incidence beam and detection and detection. If Chi=0°, then plane#1 is the plane of incidence in reflection setups) - - Phi (inplane rotation of sample, rotation axis is the samples + - Phi (inplane rotation of sample, rotation axis is the samples surface normal) - - + + A sample normal centered description is as well possible: - angle of incidence (angle between incident beam and sample surface) - angle of detection (angle between detection beam and sample surface) - angle of incident and detection beam - angle of in-plane sample rotation (direction along the sample's surface normal) - + An arbitrary reference frame can be defined by "reference_frames" and used via "instrument/angle_sample_and_beam_TYPE" - enumeration: [beam centered, sample-normal centered] - omega(NX_NUMBER): exists: optional unit: NX_ANGLE @@ -381,7 +376,6 @@ NXoptical_spectroscopy(NXobject): unit: NX_ANGLE doc: | Inplane rotation of the sample, with rotation axis along sample normal. - angle_of_incidence(NX_NUMBER): exists: optional unit: NX_ANGLE @@ -416,7 +410,6 @@ NXoptical_spectroscopy(NXobject): angle without specific relation to the sample symmetry, of the angle to a specific sample property (i.e. crystallographic axis or sample shape such as wafer flat) - generic_beam_sample_angle_TYPE(NXtransformations): exists: recommended doc: | @@ -426,16 +419,16 @@ NXoptical_spectroscopy(NXobject): angles to define the direction via sperical coordinates. This allows consistent defintion between different coordinate system. You may refer to self defined coordinate system as well. - - + + If "angle_reference_frame = beam centered", then this coordinate system is used: McStas system (NeXus default) (https://manual.nexusformat.org/design.html#mcstas-and-nxgeometry-system) - + i.e. the z-coordinate math:`[0,0,1]` is along the incident beam direction and the x-coordinate math:`[1,0,0]` is in the horizontal plane. Hence, usually math:`[0,1,0]` is vertically oriented. - + If "angle_reference_frame = sample-normal centered", then this coordinate system is used z - math:`[0,0,1]` along sample surface normal @@ -467,17 +460,14 @@ NXoptical_spectroscopy(NXobject): enumeration: [[0, 0, 1]] \@depends_on: enumeration: [offset_tilt] - - lateral_focal_point_offset(NX_NUMBER): exists: optional unit: NX_LENGTH doc: | - Specify if there is a lateral offset on the sample surface, between the focal + Specify if there is a lateral offset on the sample surface, between the focal points of the incident beam and the detection beam. - (NXbeam_device): - exists: [min, 0, max, infty] + exists: ['min', '0', 'max', 'unbounded'] doc: | Describes the order of respective beam devices in the optical beam path. @@ -485,7 +475,7 @@ NXoptical_spectroscopy(NXobject): Everything object which interacts or modifies optical beam properties, may be an beam device, e.g. Filter, Window, Beamsplitter, Photon Source, Detector, etc, - + It is intended, to include this functionality later to "older" beam components, such as NXsource, NXdetector, NXlens, etc. Until this is possbible, auxillary beam devices have to be created, @@ -520,7 +510,7 @@ NXoptical_spectroscopy(NXobject): polfilter_TYPE(NXbeam_device): exists: optional doc: | - polarization filter to prepare light to be measured or to be incident + polarization filter to prepare light to be measured or to be incident on the sample. Genereric polarization filter porperties may be implemented via NXfilter_pol at a later stage. @@ -536,7 +526,7 @@ NXoptical_spectroscopy(NXobject): Specific name or type of the polarizer used. Free text, for example: Glan-Thompson, Glan-Taylor, Rochon Prism, Wollaston - Polarizer... + Polarizer... device_information(NXfabrication): exists: optional spectralfilter_TYPE(NXbeam_device): @@ -570,22 +560,22 @@ NXoptical_spectroscopy(NXobject): enumeration: [transmission, reflection] device_information(NXfabrication): exists: optional + # Later for rework of specific optical elements - #(NXbeam_splitter): - # exists: optional - # doc: | - # Can be used to describe a beam splitter as optical element. - + # (NXbeam_splitter): + # exists: optional + # doc: | + # Can be used to describe a beam splitter as optical element. (NXbeam_transfer_matrix_table): exists: optional doc: | Allows description of beam properties via matrices, which relate ingoing with - outgoing beam properties. + outgoing beam properties. sample_stage(NXmanipulator): exists: optional doc: | Sample stage (or manipulator) for positioning of the sample. This should - only contain the spatial orientation of movement. + only contain the spatial orientation of movement. stage_type: exists: optional doc: | @@ -600,7 +590,7 @@ NXoptical_spectroscopy(NXobject): exists: optional doc: | This allows a description of the stages relation or orientation and - position with respect to the sample or beam, if an laboratory or + position with respect to the sample or beam, if an laboratory or an stage coordinate system is defined. beam_sample_relation: exists: optional @@ -608,7 +598,7 @@ NXoptical_spectroscopy(NXobject): Description of relation of the beam with the sample. How dit the sample hit the beam, e.g. 'center of sample, long edge parallel to the plane of incidence'. - Is redundent, if a full orientation description is done via the + Is redundent, if a full orientation description is done via the stages "transformations" entry. device_information(NXfabrication): exists: optional @@ -624,10 +614,10 @@ NXoptical_spectroscopy(NXobject): device_information(NXfabrication): exists: optional temp_control_TYPE(NXactuator): - doc: - Type of control for the sample temperature. Replace TYPE by - "cryostat" or "heater" to specify it. exists: optional + doc: | + Type of control for the sample temperature. Replace TYPE by "cryostat" or + "heater" to specify it. name: exists: recommended physical_quantity: @@ -645,7 +635,6 @@ NXoptical_spectroscopy(NXobject): exists: recommended device_information(NXfabrication): exists: optional - device_information(NXfabrication): exists: recommended doc: | @@ -682,7 +671,6 @@ NXoptical_spectroscopy(NXobject): doc: | Description of the software by persistent resource, where the program, code, script etc. can be found. - instrument_calibration_DEVICE(NXcalibration): exists: recommended doc: | @@ -718,8 +706,6 @@ NXoptical_spectroscopy(NXobject): doc: | Generic data which does not fit to the 'NX_FLOAT' fields in NXproces. This can be for example the instrument response function. - - wavelength_resolution(NXresolution): exists: optional doc: | @@ -743,8 +729,6 @@ NXoptical_spectroscopy(NXobject): dimensions: rank: 2 dim: [[1, 2], [2, N_spectrum]] - - (NXsample): doc: | Properties of the sample, such as sample type, layer structure, @@ -838,25 +822,28 @@ NXoptical_spectroscopy(NXobject): doc: | Medium, in which the sample is placed. enumeration: [air, vacuum, inert atmosphere, oxidising atmosphere, reducing atmosphere, sealed can, water, other] + + # Make something like NXlayer_structure_sample? thickness(NX_NUMBER): - # Make something like NXlayer_structure_sample? exists: optional + unit: NX_LENGTH doc: | (Measured) sample thickness. The information is recorded to qualify if the light used was likely - able to shine through the sample. + able to shine through the sample. In this case the value should be set to the actual thickness of the specimen viewed for an illumination situation where the nominal surface normal of the specimen is parallel to the optical axis. - unit: NX_LENGTH thickness_determination: exists: optional doc: | - If a thickness if given, please specify how this thickness was estimated or determined. - layer_structure: + If a thickness if given, please specify how this thickness was estimated or + determined. + # Maybe consider here to include NXsample_component_set. + layer_structure: exists: optional doc: | Qualitative description of the layer structure for the sample, @@ -879,10 +866,10 @@ NXoptical_spectroscopy(NXobject): Here generic types of data may be saved.. This may refer to data derived from single or multiple raw measurements (i.e. several intensities are evaluated for different parameters: ellipsometry -> psi and delta) - - i.e. non-raw data. + i.e. non-raw data. As well plotable data may be stored/linked here, which provides the most suitable representation of the data (for the respective community). - + You may provide multiple instances of NXdata \@axes: doc: | @@ -898,14 +885,16 @@ NXoptical_spectroscopy(NXobject): exists: recommended doc: | Location to save the calibrated wavelength data. + # The old "data_collection(NXprocess)" is now replaced by more flexbile # NXdata. The detailed inclusion of a data collection description (i.e. # raw data from ellipsometry as polarization values to the usually used # psi and delta values), will be done later after the NXopt workshop. derived_parameters(NXprocess): exists: optional - # >>>This section is transfered from the first NXoptical_spectroscopy version and might - # require a reqwork.<<< + + # >>>This section is transfered from the first NXoptical_spectroscopy version and might + # require a reqwork.<<< doc: | Parameters that are derived from the measured data. depolarization(NX_NUMBER): @@ -957,14 +946,14 @@ NXoptical_spectroscopy(NXobject): deterministic manner. # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ -# 7d68d553b6c55f5cdd8fe8d92c325b137c71c875c2bd742f5cf2150df56f4398 -# +# ca33e218a147369b3b40f5226c80c7835f166ed7c1a1358c38e1f76181b92ad8 +# # # -# -# -# +# +# # # # Variables used throughout the document, e.g. dimensions or parameters. @@ -999,12 +997,6 @@ NXoptical_spectroscopy(NXobject): # data. # # -# -# -# Number of sensors used to measure parameters that influence the sample, -# such as temperature or pressure. -# -# # # # Number of measurements (1st dimension of measured_data array). This is @@ -1013,38 +1005,21 @@ NXoptical_spectroscopy(NXobject): # N_measurements = 2*3 = 6. # # -# -# -# Number of detection angles of the beam reflected or scattered off the -# sample. -# -# -# -# -# Number of angles of incidence of the incident beam. -# -# -# -# -# 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. -# -# # # -# An application definition for optical spectroscopy experiments. +# A general application definition of optical spectroscopy elements, which may +# be used as a template to derive specialized optical spectroscopy experiments. +# +# Possible specializations are ellipsometry, Raman spectroscopy, photoluminescence, +# reflectivity/transmission spectroscopy. +# +# A general optical experiment consists of (i) a light/photon source, (ii) a sample, +# (iii) a detector. +# +# For any free text descriptions, it is recommended to enter data in english +# language, as this is the most FAIR representation. # # -# -# 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. -# # # # An application definition describing a general optical experiment. @@ -1055,229 +1030,681 @@ NXoptical_spectroscopy(NXobject): # definition was used for this entry/data. # # -# +# # # URL where to find further material (documentation, examples) relevant # to the application definition. # # # -# +# # # -# +# +# +# +# Datetime of the start of the measurement. +# Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, +# otherwise, the local time zone is assumed per ISO8601. +# +# It is required to enter at least one of both measurement times, either "start_time" or "end_time". +# +# +# +# +# Datetime of the end of the measurement. +# Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, +# otherwise the local time zone is assumed per ISO8601. +# +# It is required to enter at least one of both measurement times, either "start_time" or "end_time". +# +# +# # # A (globally persistent) unique identifier of the experiment. -# (i) The identifier is usually defined by the facility or principle -# investigator. +# (i) The identifier is usually defined by the facility, laboratory or +# principal investigator. # (ii) The identifier enables to link experiments to e.g. proposals. # -# +# +# +# +# +# Select the range of validity of this identier. +# Local: Setup#1 at Institute building #2 in Room #3 +# Global: Unique identification of with by unique location and unique +# globally persistent time stamp. +# +# +# +# +# +# +# +# # # # 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. +# Users are strongly advised to parameterize the description of their experiment +# by using respective groups and fields and base classes instead of writing prose +# into this field. +# +# The reason is that such a free-text field is difficult to machine-interpret. +# The motivation behind keeping this field for now is to learn how far the +# current base classes need extension based on user feedback. # # # # # Specify the type of the optical experiment. +# +# Chose other if none of these methods are suitable. You may specify +# fundamental characteristics or properties in the experimental sub-type. +# +# For Raman spectroscopy or ellipsometry use the respective specializations +# of NXoptical_spectroscopy. # +# +# +# +# +# +# # -# +# # -# Start time of the experiment. UTC offset should be specified. +# Specify a special property or characteristic of the experiment, which specifies +# the generic experiment type. # +# +# +# +# +# +# # -# +# # -# Contact information of at least the user of the instrument or the -# investigator who performed this experiment. -# Adding multiple users, if relevant, is recommended. +# If "other" was selected in "experiment_type" and/or in "experiment_sub_type", +# specify the experiment here with a free text name, which is knwon in the +# respective community of interest. # -# +# +# +# +# Description of one or more coordinate systems that are specific to the +# experiment. Examples are beam centered, sample-normal centered, +# laboratory-system centered, sample-stage centered, crystal-symmetry centered. +# +# +# +# +# This refers to the coordinate system along the beam path. The origin and +# base is defined at z=0, where the incident beam hits the sample at the surface. +# +# +# +# +# This is the default NeXus coordinate system (McStas), if the transformation +# does not change the coordinate system at all - i.e. it is unity. +# Otherwise, by this a respective transformation of the beam +# reference frame to the default reference frame could be made. i.e. +# exchange of x and z coordinate, rotation of respective coordinates +# towards each other. +# +# +# +# +# +# +# Link to transformations defining the sample-normal base coordinate system, +# which is defined such that the positive z-axis is parallel to the sample normal, +# and the x-y-plane lies inside the sample surface. +# +# +# +# +# Set of transformations, describing the orientation of the sample-normal coordinate system +# with respect to the beam coordinate system (.). +# +# +# +# +# +# +# Contact information and eventually details of at persons who +# performed the measurements. This can be for example the principal +# investigator or student. Examples are: name, affiliation, address, telephone +# number, email, role as well as identifiers such as orcid or similar. +# It is recommended to add multiple users if relevant. +# +# Due to data privacy concerns, there is no minimum requirement. +# If no user with specific name is allowed to be given, it is required to +# assign at least an affiliation +# +# +# +# +# Devices or elements of the optical spectroscopy setup described with its +# properties and general information. +# +# This includes for example: +# - The beam device's or instrument's model, company, serial number, construction year, etc. +# - Used software or code +# - Experiment descriptive parameters as reference frames, resolution, calibration +# - Photon beams with their respective properties such as angles and polarization +# - Various optical beam path devices, which interact, manipulate or measure optical beams +# - Characteristics of the medium surrounding the sample +# - "Beam devices" for a beam path description +# - Stages(NXmanipulator) +# - Sensors and actuators to control or measure sample or beam properties +# +# +# +# This can be used to describe properties of a photon beam. +# A beam is always defined between two beam_devices, via +# "previous_device" and "next_device". +# +# It is required to define at least one incident beam which is incident +# to the sample. You may specify if this beam parameters are acutally measured +# or just nominal. +# If this beam is the output of a source, chose the same +# name appendix as for the NXsource instance (e.g. TYPE=532nm) +# +# +# +# Select the reliability of the respective beam characteristics. Either, +# the parameters are measured via another device or method or just given +# nominally via the properties of a light source properties (532nm, 100mW). +# +# +# +# +# +# +# +# +# +# +# +# +# The path to the device which emitted this beam (light source or frequency doubler). +# +# This parameter is recommended, if the previous optical element is a photon source. +# In this way, the properties of the laser or light souce can be described +# and associated. +# The beam should be named with the same appendix as the source, e.g., +# for TYPE=532nmlaser, there should be both a NXsource named +# "source_532nmlaser" and a NXbeam named "beam_532nmlaser". +# +# Example: /entry/instrument/source_532nmlaser +# +# +# +# +# +# +# +# +# +# +# +# +# +# Angle of the linear polarized light, with respect to a fixed arbitrary +# defined 0° position. This can be used if no definition of respective +# cooridnate systems for beam and sample normal is done. If coordinate systems +# are defined, refer to beam "incident_polarization". +# +# +# +# +# +# +# +# +# +# +# +# +# Description of the detector type. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Type of detector, if "other" was selected in "detector_type". +# +# +# +# +# Contains the raw data collected by the detector before calibration. +# The data which is considered raw might change from experiment to experiment +# due to hardware pre-processing of the data. +# This field ideally collects the data with the lowest level of processing +# possible. +# +# +# +# +# +# +# +# +# +# Raw data before calibration. +# +# +# +# +# +# Specify respective hardware which was used for the detector. For +# example special electronics required for time-correlated single photon +# counting (TCSPC). +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specification of type, may also go to name. +# +# +# +# +# +# If available, name/ID/norm of the light source standard. +# +# +# +# +# Details about the device information. +# +# +# +# +# The path to a beam emitted by this source. +# Should be named with the same appendix, e.g., +# for TYPE=532nmlaser, there should as well be +# a NXbeam named "beam_532nmlaser" together with this source +# instance named "source_532nmlaser" +# +# Example: /entry/instrument/beam_532nmlaser +# +# +# +# +# +# +# # -# Name of the user. +# Defines the reference frame which is used to describe the sample orientation +# with respect to the beam directions. +# +# A beam centered description is the default and uses 4 angles(similar to XRD): +# - Omega (angle between sample surface and incident beam) +# - 2Theta (angle between the transmitted beam and the detection beam) +# - Chi (sample tilt angle, angle between plane#1 and the surface normal, +# plane#1 = spanned by incidence beam and detection +# and detection. If Chi=0°, then plane#1 is the plane of +# incidence in reflection setups) +# - Phi (inplane rotation of sample, rotation axis is the samples +# surface normal) +# +# +# A sample normal centered description is as well possible: +# - angle of incidence (angle between incident beam and sample surface) +# - angle of detection (angle between detection beam and sample surface) +# - angle of incident and detection beam +# - angle of in-plane sample rotation (direction along the sample's surface normal) +# +# An arbitrary reference frame can be defined by "reference_frames" +# and used via "instrument/angle_sample_and_beam_TYPE" # +# +# +# +# # -# +# # -# Name of the affiliation of the user at the point in time when the -# experiment was performed. +# Angle between sample incident beam and sample surface. # # -# +# # -# Street address of the user's affiliation. +# Angle between incident and detection beam # # -# +# # -# Email address of the user. +# Sample tilt between sample normal, and the plane spanned by detection and +# incident beam. # # -# +# # -# Author ID defined by https://orcid.org/. +# Inplane rotation of the sample, with rotation axis along sample normal. # # -# +# # -# Telephone number of the user. +# Angle(s) of the incident beam vs. the normal of the bottom reflective +# (substrate) surface in the sample. These two directions span the plane +# of incidence. # # -# -# -# -# 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. -# -# +# # -# The name of the instrument. +# 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. +# These two directions span the plane of detection. # -# -# -# The used version of the hardware if available. If not a commercial -# instrument use date of completion of the hardware. -# -# # -# +# # -# Name of the company which build the instrument. +# Angle between the incident and detection beam. +# If angle_of_detection + angle_of_incidence = angle_of_incident_and_detection_beam, +# then the setup is a reflection setup. +# If angle_of_detection + angle_of_incidence != angle_of_incident_and_detection_beam +# then the setup may be a light scattering setup. +# (i.e. 90° + 90° != 90°, i.e. incident and detection beam in the sample surface, but +# the angle source-sample-detector is 90°) # # -# +# # -# ISO8601 date when the instrument was constructed. -# UTC offset should be specified. +# Angle of the inplane orientation of the sample. This might be an arbitrary, +# angle without specific relation to the sample symmetry, +# of the angle to a specific sample property (i.e. crystallographic axis or sample +# shape such as wafer flat) # # -# -# -# -# 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. -# +# +# +# Set of transformations, describing the relative orientation of different +# parts of the experiment (beams or sample). You may select one of the specified +# angles for incident and detection beam or sample, and then use polar and azimuthal +# angles to define the direction via sperical coordinates. +# This allows consistent defintion between different coordinate system. +# You may refer to self defined coordinate system as well. +# +# +# If "angle_reference_frame = beam centered", then this coordinate system is used: +# McStas system (NeXus default) +# (https://manual.nexusformat.org/design.html#mcstas-and-nxgeometry-system) +# +# i.e. the z-coordinate math:`[0,0,1]` is along the incident beam direction and +# the x-coordinate math:`[1,0,0]` is in the horizontal plane. Hence, usually math:`[0,1,0]` +# is vertically oriented. +# +# If "angle_reference_frame = sample-normal centered", then this coordinate +# system is used +# z - math:`[0,0,1]` along sample surface normal +# x - math:`[1,0,0]` defined by sample surface projected incident beam. +# y - math:`[0,1,0]` in the sample surface, orthogonal to z and x. +# For this case, x may be ill defined, if the incident beam is perpendicular +# to the sample surface. In this case, use the beam centered description. +# +# +# +# +# +# +# # -# +# # -# 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. +# Rotation about the y axis (polar rotation within the sample plane). # +# +# +# +# +# +# +# +# +# +# +# +# +# Path to a transformation that places the sample surface +# into the origin of the arpes_geometry coordinate system. +# +# # -# +# # -# Website of the software. +# Rotation about the z axis (azimuthal rotation within the sample plane). # -# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# # -# +# +# +# Specify if there is a lateral offset on the sample surface, between the focal +# points of the incident beam and the detection beam. +# +# +# # -# Commercial or otherwise defined name of the firmware that was used -# for the measurement - if available. +# Describes the order of respective beam devices in the optical beam +# path. +# +# Everything object which interacts or modifies optical beam properties, +# may be an beam device, e.g. Filter, Window, Beamsplitter, Photon Source, +# Detector, etc, +# +# It is intended, to include this functionality later to "older" beam +# components, such as NXsource, NXdetector, NXlens, etc. +# Until this is possbible, auxillary beam devices have to be created, +# for each "older" beam component instead, to allow a beam path description. +# To link the auxillary beam device to the real device properties, the +# attribute \@device should be used. # -# +# # -# Version and build number or commit hash of the software source code. +# Reference to beam device, which is described by a NeXus concept +# (e.g. for NXsource, entry/instrument/source_TYPE). # # -# +# # -# Website of the software. +# Reference to the previous beam device, from which the photon beam came +# to reach this beam device. A photon source is related as origin by ".". +# This enables a logical order description of the optical setup. # -# +# # -# +# # -# 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. +# This is the optical element used to focus or collect light. This may +# be a genereic lens or microcope objectives which are used for the +# Raman scattering process. # -# -# -# -# -# -# -# -# -# +# +# +# +# +# +# +# +# +# +# +# +# +# +# # -# The calibration data and metadata should be described in a separate NeXus file -# with the link provided in 'calibration_link'. +# polarization filter to prepare light to be measured or to be incident +# on the sample. +# Genereric polarization filter porperties may be implemented via NXfilter_pol +# at a later stage. # -# +# # -# If calibtration status is 'calibration time provided', specify the -# ISO8601 date when calibration was last performed before this -# measurement. UTC offset should be specified. +# Physical principle of the polarization filter used to create a +# defined incident or scattered light state. # +# +# +# +# +# +# +# # -# +# # -# Link to the NeXus file containing the calibration data and metadata. +# Specific name or type of the polarizer used. +# +# Free text, for example: Glan-Thompson, Glan-Taylor, Rochon Prism, Wollaston +# Polarizer... # # +# # -# +# # -# 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. +# Spectral filter used to modify properties of the scattered or incident light. +# Genereric spectral filter porperties may be implemented via NXfilter_spec +# at a later stage. # +# +# +# Type of laserline filter used to supress the laser, if measurements +# close to the laserline are performed. +# +# +# +# +# +# +# +# +# +# +# +# +# Type of laserline filter used to supress the laser, if measurements +# close to the laserline are performed. +# +# +# +# +# +# +# +# +# +# +# +# Properties of the spectral filter such as wavelength dependent Transmission +# or reflectivity. +# +# +# +# Which property is used to form the spectral properties of light, +# i.e. transmission or reflection properties. +# +# +# +# +# +# +# +# # -# -# -# Angle(s) of the incident beam vs. the normal of the bottom reflective -# (substrate) surface in 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. +# Allows description of beam properties via matrices, which relate ingoing with +# outgoing beam properties. # -# -# -# -# -# +# +# # -# 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). +# Sample stage (or manipulator) for positioning of the sample. This should +# only contain the spatial orientation of movement. # -# +# # # Specify the type of the sample stage. # @@ -1287,238 +1714,184 @@ NXoptical_spectroscopy(NXobject): # # # +# +# # # -# +# # -# 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'. +# If "other" was chosen in stage_type, enter here a free text description +# of the stage type. # # -# +# # -# 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. +# This allows a description of the stages relation or orientation and +# position with respect to the sample or beam, if an laboratory or +# an stage coordinate system is defined. # -# -# -# 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.). -# -# -# -# -# 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. -# -# -# -# -# -# -# -# -# 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. -# -# -# -# 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. -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# If the parameter_type is `other` a name should be specified here. -# -# -# -# -# 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. -# -# -# -# -# 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] -# -# -# -# -# -# # -# +# # -# 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. +# Description of relation of the beam with the sample. How dit the +# sample hit the beam, e.g. 'center of sample, long edge parallel +# to the plane of incidence'. +# Is redundent, if a full orientation description is done via the +# stages "transformations" entry. # -# -# -# Specify the position of the window in the beam path by pointing -# to the preceding element in the sequence of beam path elements. -# -# -# -# -# Was a window correction performed? If 'True' describe the window -# correction procedure in 'window_correction/procedure'. -# -# -# -# -# Was a window correction performed? If 'True' describe the -# window correction procedure in '' -# -# -# -# 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'. -# -# -# -# -# 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. -# -# -# -# -# -# The material of the window. -# -# -# -# -# -# -# -# -# -# -# -# -# -# -# If you specified 'other' as material, decsribe here what it is. -# -# -# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Type of control for the sample temperature. Replace TYPE by "cryostat" or +# "heater" to specify it. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Hardware used for actuation, i.e. laser, gas lamp, filament, resistive +# +# +# +# +# +# +# +# +# +# General device information of the optical spectroscopy setup, if +# suitable (e.g. for a tabletop spectrometer or other non-custom build setups). +# For custom build setups, this may be limited to the construction year. +# +# +# +# +# +# +# +# +# +# Commercial or otherwise defined given name of the program that was +# used to control any parts of the optical spectroscopy setup. +# The uppercase TYPE should be replaced by a specification name, i.e. +# "software_detector" or "software_stage" to specify the respective +# program or software components. +# +# # -# Thickness of the window. +# 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. # -# -# +# +# # -# Angle of the window normal (outer) vs. the substrate normal -# (similar to the angle of incidence). +# Description of the software by persistent resource, where the program, +# code, script etc. can be found. # -# +# +# +# +# +# +# Pre-calibration of an arbitrary device of the instrumental setup, which +# has the name DEVICE. You can specify here how, at which time by which method +# the calibration was done. As well the accuracy and a link to the calibration +# dataset. +# +# +# +# Path to the device, which was calibrated. +# Example: entry/instrument/DEVICE +# +# +# +# +# Provide data about the determined accuracy of the device, this may +# may be a single value or a dataset like wavelength error vs. wavelength etc. +# +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# +# +# If calibtration status is 'calibration time provided', specify the +# ISO8601 date when calibration was last performed before this +# measurement. UTC offset should be specified. +# +# +# +# +# Generic data which does not fit to the 'NX_FLOAT' fields in NXproces. +# This can be for example the instrument response function. +# # # +# +# +# The overall resolution of the optical instrument. +# +# +# +# +# +# +# +# +# +# Minimum distinguishable wavelength separation of peaks in spectra. +# +# +# +# +# +# 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. +# +# +# +# +# +# # # # @@ -1527,32 +1900,26 @@ NXoptical_spectroscopy(NXobject): # Information about the sample stage and sample environment should be # described in ENTRY/INSTRUMENT/sample_stage. # -# +# +# # -# Descriptive name of the sample +# Locally unique ID of the sample, used in the reasearch institute or group. # # -# +# # -# Specify the type of sample, e.g. thin film, single crystal etc. +# State the form of the sample, examples are: +# thin film, single crystal, poly crystal, amorphous, single layer, +# multi layer, liquid, gas, pellet, powder. +# Generic properties of liquids or gases see NXsample properties. # -# -# -# -# -# -# -# # -# +# # -# 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. +# Free text description of the sample. # # -# +# # # Chemical formula of the sample. Use the Hill system (explained here: # https://en.wikipedia.org/wiki/Chemical_formula#Hill_system) to write @@ -1563,7 +1930,7 @@ NXoptical_spectroscopy(NXobject): # The order must be consistent with layer_structure # # -# +# # # List of comma-separated elements from the periodic table that are # contained in the sample. If the sample substance has multiple @@ -1571,184 +1938,165 @@ NXoptical_spectroscopy(NXobject): # 'atom_types'. # # -# -# -# 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. -# -# # # -# ISO8601 date with time zone (UTC offset) specified. +# ISO 8601 time code with local time zone offset to UTC information +# when the specimen was prepared. +# +# Ideally, report the end of the preparation, i.e. the last known timestamp when +# the measured specimen surface was actively prepared. # # -# +# # -# Description of the substrate. +# A set of activities that occurred to the sample prior to/during the experiment. # -# -# +# +# # -# Specify the sample orientation. +# Sample temperature (either controlled or just measured). # -# -# -# -# -# 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. -# -# +# +# +# If no sensor was available for the determination of temperature, selected +# a nominal value which represents approximately the situation of sample temperature. +# +# +# +# +# +# +# +# +# +# +# If temperature_nominal is "other", enter here a nominal/assumed/estimated +# sample temperature. +# +# +# +# +# Temperature sensor measuring the sample temperature. +# This should be a link to /entry/instrument/manipulator/temperature_sensor. +# +# +# +# +# Device to heat the sample. +# This should be a link to /entry/instrument/manipulator/sample_heater. +# +# +# +# +# Device for cooling the sample (Cryostat, Airflow cooler, etc.). +# This should be a link to /entry/instrument/manipulator/cryostat. +# +# +# +# # -# An identifier to correlate data to the experimental conditions, -# if several were used in this measurement; typically an index of 0-N. +# Arbirary sample property which may be varied during the experiment +# and controlled by a device. Examples are pressure, voltage, magnetic field etc. +# Similar to the temperautre description of the sample. # -# -# +# +# +# Medium, in which the sample is placed. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# # -# 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. +# (Measured) sample thickness. +# +# The information is recorded to qualify if the light used was likely +# able to shine through the sample. +# +# In this case the value should be set to the actual thickness of +# the specimen viewed for an illumination situation where the nominal +# surface normal of the specimen is parallel to the optical axis. # -# -# -# -# -# -# -# -# -# -# -# # -# -# +# # -# 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. +# If a thickness if given, please specify how this thickness was estimated or +# determined. # -# -# -# -# -# -# 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. -# -# # -# +# +# # -# 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. +# 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. # -# -# -# -# -# -# -# -# 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. -# -# # -# +# # -# Specified uncertainties (errors) of the data described by 'data_type' -# and provided in 'measured_data'. +# Specify the sample orientation, how is its sample normal oriented +# relative in the laboratory reference frame, incident beam reference +# frame. # -# -# -# -# -# -# -# -# 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. -# -# # -# +# # -# List of links to the values of the sensors. Add a link for each -# varied parameter (i.e. for each sensor). +# If the sample is grown or fixed on a substrate, specify this here by +# a free text description. # -# -# -# # -# +# +# +# +# Here generic types of data may be saved.. This may refer to data derived +# from single or multiple raw measurements (i.e. several intensities are +# evaluated for different parameters: ellipsometry -> psi and delta) - +# i.e. non-raw data. +# As well plotable data may be stored/linked here, which provides the most suitable +# representation of the data (for the respective community). +# +# You may provide multiple instances of NXdata +# +# # -# 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. +# Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) # -# -# -# -# -# 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. -# -# -# -# -# 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. -# -# -# -# -# Website of the software. -# -# -# -# +# +# # -# A plot of the multi-dimensional data array provided in -# ENTRY/data/measured_data. +# Spectrum, i.e. y-axis of the data (e.g. counts, intensity) # -# +# +# +# +# +# # -# Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) +# Location to save the calibrated wavelength data. # -# +# # # +# # +# # # Parameters that are derived from the measured data. # @@ -1762,7 +2110,7 @@ NXoptical_spectroscopy(NXobject): # # # -# +# # # Jones quality factor. # @@ -1812,17 +2160,5 @@ NXoptical_spectroscopy(NXobject): # # # -# -# -# 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. -# -# -# -# Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) -# -# -# # #