NXcanSAS v1.1 - Revision history

Smk: /* Pseudo-code Examples */

2024-10-24T16:24:30Z

Pseudo-code Examples

Smk: /* For NeXus */

2024-10-24T16:21:59Z

For NeXus

← Older revision		Revision as of 16:21, 24 October 2024
Line 108:		Line 108:
	=== For NeXus ===		=== For NeXus ===

	In formulating the proposals for NXcanSAS above it became clear that there were places where the type association between NXcanSAs and NeXus broke down. To remedy this, the following additions to the [https://manual.nexusformat.org/index.html\| NeXus standard] are proposed:		In formulating the proposals for NXcanSAS above it became clear that there were places where the type association between NXcanSAs and NeXus broke down. To remedy this, the following additions to the [https://manual.nexusformat.org/index.html NeXus standard] are proposed:

	'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@decay_time'''.		'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@decay_time'''.

	''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He MEOP cell. In fact, it would be more sensible to deprecate the type "3He" and introduce either an umbrella type "hyperpolarization", or introduce three new types: "SEOP", "MEOP" and "DNP".''		''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He MEOP cell. In fact, it would be more sensible to deprecate the type "3He" and introduce either an umbrella type "hyperpolarization", or introduce three new types: "SEOP", "MEOP" and "DNP".''

	Note: NeXus has no ''NXanalyzer'' base class, it is presumed because it would be just be a copy of ''NXpolarizer'' with a different name. That works provided it can be made clear what role a given ''NXpolarizer'' instance in a file represents. At present this can only be inferred from the position of the device; ie, an analyzer must be after a polarizer. Proposal NX4 would help to further resolve any ambiguity. Or, of course, NeXus could introduce an ''NXanalyzer'' base class!		Note: NeXus has no ''NXanalyzer'' base class, it is presumed because it would be just be a copy of ''NXpolarizer'' with a different name. That works provided it can be made clear what role a given ''NXpolarizer'' instance in a file represents. At present this can only be inferred from the position of the device; ie, an analyzer must be after a polarizer. Proposal NX4 would help to further resolve any ambiguity. Or, of course, NeXus could introduce an ''NXanalyzer'' base class!
Line 122:		Line 122:
	'''PROPOSAL NX3:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameters '''@magnetic_field''' and '''@direction'''.		'''PROPOSAL NX3:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameters '''@magnetic_field''' and '''@direction'''.

	''Aside: This proposal would give [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] and [https://manual.nexusformat.org/classes/base_classes/NXflipper.html#nxflipper\| NXflipper] the same functionality as NXsample.''		''Aside: This proposal would give [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer NXpolarizer] and [https://manual.nexusformat.org/classes/base_classes/NXflipper.html#nxflipper NXflipper] the same functionality as NXsample.''

	Note: @direction in NeXus is defined as ''"Any of these values: x \| y \| z"''; ie, just a single axis. This is too limiting for modern experiments. Proposal 7b above suggests an alternative for NXcanSAS but it is noted that other solutions may exist in [https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#index-0\| NXtransformations].		Note: @direction in NeXus is defined as ''"Any of these values: x \| y \| z"''; ie, just a single axis. This is too limiting for modern experiments. Proposal 7b above suggests an alternative for NXcanSAS but it is noted that other solutions may exist in [https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#index-0 NXtransformations].

	'''PROPOSAL NX4:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameter '''@description'''.		'''PROPOSAL NX4:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameter '''@description'''.

	''Aside: This proposal would give [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] and [https://manual.nexusformat.org/classes/base_classes/NXflipper.html#nxflipper\| NXflipper] the same functionality as some other classes in NXinstrument (eg, [https://manual.nexusformat.org/classes/base_classes/NXaperture.html#nxaperture\| NXaperture], [https://manual.nexusformat.org/classes/base_classes/NXdetector.html#nxdetector\| NXdetector]) and allow multiple instances of these devices, as is required for some types of Magnetic-SANS experiment, to be distinguished. It would also provide another way to distinguish whether a polarizer device is being used as a polarizer or an analyzer!.''		''Aside: This proposal would give [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer NXpolarizer] and [https://manual.nexusformat.org/classes/base_classes/NXflipper.html#nxflipper NXflipper] the same functionality as some other classes in NXinstrument (eg, [https://manual.nexusformat.org/classes/base_classes/NXaperture.html#nxaperture NXaperture], [https://manual.nexusformat.org/classes/base_classes/NXdetector.html#nxdetector NXdetector]) and allow multiple instances of these devices, as is required for some types of Magnetic-SANS experiment, to be distinguished. It would also provide another way to distinguish whether a polarizer device is being used as a polarizer or an analyzer!.''

	= Units =		= Units =

Smk: /* For NXcanSAS v1.1 */

2024-10-24T16:20:36Z

For NXcanSAS v1.1

Smk: /* For NeXus */

2024-10-16T09:49:02Z

For NeXus

← Older revision		Revision as of 09:49, 16 October 2024
Line 112:		Line 112:
	'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@decay_time'''.		'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@decay_time'''.

	''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He cell.''		''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He MEOP cell. In fact, it would be more sensible to deprecate the type "3He" and introduce either an umbrella type "hyperpolarization", or introduce three new types: "SEOP", "MEOP" and "DNP".''

	Note: NeXus has no ''NXanalyzer'' base class, it is presumed because it would be just be a copy of ''NXpolarizer'' with a different name. That works provided it can be made clear what role a given ''NXpolarizer'' instance in a file represents. At present this can only be inferred from the position of the device; ie, an analyzer must be after a polarizer. Proposal NX4 would help to further resolve any ambiguity. Or, of course, NeXus could introduce an ''NXanalyzer'' base class!		Note: NeXus has no ''NXanalyzer'' base class, it is presumed because it would be just be a copy of ''NXpolarizer'' with a different name. That works provided it can be made clear what role a given ''NXpolarizer'' instance in a file represents. At present this can only be inferred from the position of the device; ie, an analyzer must be after a polarizer. Proposal NX4 would help to further resolve any ambiguity. Or, of course, NeXus could introduce an ''NXanalyzer'' base class!

Smk: /* For NXcanSAS v1.1 */

2024-10-16T09:45:04Z

For NXcanSAS v1.1

← Older revision		Revision as of 09:45, 16 October 2024
Line 60:		Line 60:
	Note: The astute reader will realise that this definition must invert in the Southern hemisphere! Data reduction software for polarized-SANS data measured at facilities there would need to correctly compensate when writing NXcanSAS files.		Note: The astute reader will realise that this definition must invert in the Southern hemisphere! Data reduction software for polarized-SANS data measured at facilities there would need to correctly compensate when writing NXcanSAS files.

	'''PROPOSAL 5a:''' (Recommended) That the wavelength-dependent ''neutron transmissions'' and associated uncertainties of polarizers, flippers or analyzers be written as separate '''<SAStransmission_spectrum/>''' blocks with appropriate names (eg, '''<SAStransmission_spectrum name="polarizer">''') and the labels '''T''' and '''Tdev''', respectively. In the case of ~~3He~~ cells the transmission of the empty cell should also be recorded (eg, '''<SAStransmission_spectrum name="polarizer_empty">''').		'''PROPOSAL 5a:''' (Recommended) That the wavelength-dependent ''neutron transmissions'' and associated uncertainties of polarizers, flippers or analyzers be written as separate '''<SAStransmission_spectrum/>''' blocks with appropriate names (eg, '''<SAStransmission_spectrum name="polarizer">''') and the labels '''T''' and '''Tdev''', respectively. In the case of hyperpolarization cells (ie, SEOP, MEOP & DNP) the transmission of the empty cell should also be recorded (eg, '''<SAStransmission_spectrum name="polarizer_empty">''').

	''Aside: This proposal simply makes use of existing functionality in NXcanSAS v1.0, replicating how TOF-SANS CanSAS1D / NXcanSAS files presently incorporate the sample or background transmissions.''		''Aside: This proposal simply makes use of existing functionality in NXcanSAS v1.0, replicating how TOF-SANS CanSAS1D / NXcanSAS files presently incorporate the sample or background transmissions.''

	'''PROPOSAL 5b:''' (Recommended) That the fixed-wavelength ''neutron transmissions'' and associated uncertainties of polarizers, flippers or analyzers be written as the single values '''@T''' and '''@Tdev''' , respectively, under the relevant sub-class in <SASinstrument/>. In the case of ~~3He~~ cells the transmission of the empty cell should also be recorded (eg, '''@T_empty''' and '''@Tdev_empty''').		'''PROPOSAL 5b:''' (Recommended) That the fixed-wavelength ''neutron transmissions'' and associated uncertainties of polarizers, flippers or analyzers be written as the single values '''@T''' and '''@Tdev''' , respectively, under the relevant sub-class in <SASinstrument/>. In the case of hyperpolarization cells (ie, SEOP, MEOP & DNP) the transmission of the empty cell should also be recorded (eg, '''@T_empty''' and '''@Tdev_empty''').

	''Aside: This proposal represents an addition to NXcanSAS. It is also noted that neither NXpolarizer or NXflipper provide for transmission values.''		''Aside: This proposal represents an addition to NXcanSAS. It is also noted that neither NXpolarizer or NXflipper provide for transmission values.''
Line 92:		Line 92:
	''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the magnetic field in NXpolarizer or NXflipper.''		''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the magnetic field in NXpolarizer or NXflipper.''

	'''PROPOSAL 9:''' (Recommended) That the initial polarization ('''@polarization_initial''') and decay time ('''@decay_time''') of ~~3He~~ polarizers/analyzers and their respective uncertainties ('''@polarization_initial_dev''' and '''@decay_time_dev'''), along with the gas pressure ('''@pressure''') and exchange distance ('''@length'''), be written under <SASpolarizer/> / <SASanalyzer/>.		'''PROPOSAL 9:''' (Recommended) That the initial polarization ('''@polarization_initial''') and decay time ('''@decay_time''') of hyperpolarization (SEOP, MEOP & DNP) polarizers/analyzers and their respective uncertainties ('''@polarization_initial_dev''' and '''@decay_time_dev'''), along with the gas pressure ('''@pressure''') and exchange distance ('''@length'''), be written under <SASpolarizer/> / <SASanalyzer/>.

	''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a ~~3He~~ cell in NXpolarizer.''		''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a hyperpolarization (ie, SEOP, MEOP & DNP) cell in NXpolarizer.''

	Note: The decay of polarization in a gas spin-exchange polarizer is a relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @decay_time).		Note: The decay of polarization in a gas spin-exchange polarizer is a relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @decay_time).

Smk: /* For NXcanSAS v1.1 */

2024-10-15T11:01:32Z

For NXcanSAS v1.1

← Older revision		Revision as of 11:01, 15 October 2024
Line 86:		Line 86:
	'''PROPOSAL 7b:''' (Recommended) That wherever @direction may be used, an optional alternative ('''@direction_spherical''') be permitted. This would record the ''two'' angles required to describe the field direction in spherical coordinates.		'''PROPOSAL 7b:''' (Recommended) That wherever @direction may be used, an optional alternative ('''@direction_spherical''') be permitted. This would record the ''two'' angles required to describe the field direction in spherical coordinates.

	''Aside: '''@direction_spherical''' would follow the axes coordinate system of Mantid and [https://www.sasview.org/docs/user/qtgui/Perspectives/Fitting/orientation/orientation.html\| SasView], where the neutrons travel horizontally in the direction of -z. Thus, the first angle, θ (theta), would record the angle of the field above (if positive) or below (if negative) the x-z plane. And the second angle, ψ (psi), would record the rotation of the field in the x-y plane with zero degrees at the 3 O'clock position.		''Aside: '''@direction_spherical''' would follow the axes coordinate system of Mantid and [https://www.sasview.org/docs/user/qtgui/Perspectives/Fitting/orientation/orientation.html\| SasView], where the neutrons travel horizontally in the direction of -z. Thus, the first angle, θ (theta), would record the angle of the field above (if positive) or below (if negative) the x-z plane. And the second angle, ψ (psi), would record the rotation of the field in the x-y plane with zero degrees at the 3 O'clock position. A positive angle corresponds to a counter-clockwise rotation.

	'''PROPOSAL 8:''' (Recommended) That the magnitude ('''@magnetic_field''') and direction ('''@direction''', or '''@direction_spherical''' if Proposal 7b is adopted) of the magnetic field across polarizers, flippers or analyzers be written under the respective sub-class in <SASinstrument/>.		'''PROPOSAL 8:''' (Recommended) That the magnitude ('''@magnetic_field''') and direction ('''@direction''', or '''@direction_spherical''' if Proposal 7b is adopted) of the magnetic field across polarizers, flippers or analyzers be written under the respective sub-class in <SASinstrument/>.
Line 96:		Line 96:
	''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a 3He cell in NXpolarizer.''		''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a 3He cell in NXpolarizer.''

	Note: The decay of polarization in a gas spin-exchange polarizer is a ~~spin-lattice~~ relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @decay_time).		Note: The decay of polarization in a gas spin-exchange polarizer is a relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @decay_time).

	'''PROPOSAL 10:''' (Mandatory) That the order with which the neutron encounters polarizers, flippers or analyzers be specified as the distance ('''@distance''') from the sample (positive = before; negative = after) and written under the respective sub-class in <SASinstrument/>.		'''PROPOSAL 10:''' (Mandatory) That the order with which the neutron encounters polarizers, flippers or analyzers be specified as the distance ('''@distance''') from the sample (positive = before; negative = after) and written under the respective sub-class in <SASinstrument/>.

Smk: /* Overview */

2024-10-14T15:47:08Z

Overview

← Older revision		Revision as of 15:47, 14 October 2024
Line 7:		Line 7:
	= Overview =		= Overview =

	Since its release in 2017, the [[Data_Formats_Working_Group\|NXcanSAS format]] has served the community well, but mostly in the role of an HDF equivalent to the [[Data_Formats_Working_Group\|CanSAS1D XML format]]. However, as is evident in its [[2012_Data_Discussion\|founding discussions]], far greater functionality was originally envisaged. Advances in instrumentation and science are now starting to push at the boundaries of NXcanSAS v1.0. One such area is what may be termed [https://doi.org/10.1103/RevModPhys.91.015004\| Magnetic-SANS] which encompasses a number of different SANS techniques involving manipulation of the neutron spin. To meet the needs of this area revisions are required to NXcanSAS v1.0 and, ideally, [https://www.nexusformat.org/\| NeXus].		Since its release in 2017, the [[Data_Formats_Working_Group\|NXcanSAS format]] has served the community well, but mostly in the role of an HDF equivalent to the [[Data_Formats_Working_Group\|CanSAS1D XML format]]. However, as is evident in its [[2012_Data_Discussion\|founding discussions]], far greater functionality was originally envisaged. Advances in instrumentation and science are now starting to push at the boundaries of NXcanSAS v1.0. One such area is what may be termed [https://doi.org/10.1103/RevModPhys.91.015004\| Magnetic-SANS] which encompasses a number of different SANS techniques involving manipulation of the neutron spin. To meet the needs of this area revisions (in the form of additions) are required to NXcanSAS v1.0 and, ideally, [https://www.nexusformat.org/\| NeXus].

	NXcanSAS is currently implemented by [https://www.mantidproject.org/\| Mantid] and [https://www.sasview.org/\| SasView].		NXcanSAS is currently implemented by [https://www.mantidproject.org/\| Mantid] and [https://www.sasview.org/\| SasView].

Smk at 15:46, 14 October 2024

2024-10-14T15:46:15Z

Smk: /* For NeXus */

2024-10-07T13:22:41Z

For NeXus

← Older revision		Revision as of 13:22, 7 October 2024
Line 117:		Line 117:

	'''PROPOSAL NX2:''' That the '''NXflipper''' base class be granted the additional parameters '''@transmission''' and '''@efficiency'''.		'''PROPOSAL NX2:''' That the '''NXflipper''' base class be granted the additional parameters '''@transmission''' and '''@efficiency'''.

			''Aside: This proposal would give NXflipper the same functionality as NXpolarizer if Proposal NX1 is adopted.''

	'''PROPOSAL NX3:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameters '''@magnetic_field''' and '''@direction'''.		'''PROPOSAL NX3:''' That the '''NXpolarizer''' and '''NXflipper''' base classes be granted the additional parameters '''@magnetic_field''' and '''@direction'''.

Smk: /* Pseudo-code Examples */

2024-10-07T13:15:53Z

Pseudo-code Examples

← Older revision		Revision as of 16:20, 24 October 2024
Line 40:		Line 40:
	=== For NXcanSAS v1.1 ===		=== For NXcanSAS v1.1 ===

	'''PROPOSAL 1:''' (Mandatory) That the polarization simply be included as additional, optional, data axes within <SASdata/>. [https://github.com/canSAS-org/NXcanSAS_examples/tree/master/canSAS2012_examples\| This functionality is already part of v1.0], but perhaps had not been envisaged for this particular use case!		'''PROPOSAL 1:''' (Mandatory) That the polarization simply be included as additional, optional, data axes within <SASdata/>. [https://github.com/canSAS-org/NXcanSAS_examples/tree/master/canSAS2012_examples This functionality is already part of v1.0], but perhaps had not been envisaged for this particular use case!

	''Aside: This proposal does mean that every Q point will have associated polarization information (if the file contains Magnetic-SANS data), but this can be leveraged to address other requirements (see below), and the overhead is tiny. It also means the polarization data is directly available to a file reader. An alternative that was considered was something like <SASdata name="title" polarization="value"/>, but this was rejected because it would a) require processing of "value" and b) require introducing something to denote the different types of Magnetic-SANS measurement.''		''Aside: This proposal does mean that every Q point will have associated polarization information (if the file contains Magnetic-SANS data), but this can be leveraged to address other requirements (see below), and the overhead is tiny. It also means the polarization data is directly available to a file reader. An alternative that was considered was something like <SASdata name="title" polarization="value"/>, but this was rejected because it would a) require processing of "value" and b) require introducing something to denote the different types of Magnetic-SANS measurement.''
Line 52:		Line 52:
	Note: The values of the polarisation axes define the type of Magnetic-SANS data stored in the file: eg, PA-SANS: [Pin, Pout]; Polarizer Pol-SANS: [Pin, 0]; Analyzer Pol-SANS: [0, Pout]. When ''both'' polarization axes would take the value 0 - ie, a conventional, unpolarised, SANS measurement - the polarization axes need not be specified.		Note: The values of the polarisation axes define the type of Magnetic-SANS data stored in the file: eg, PA-SANS: [Pin, Pout]; Polarizer Pol-SANS: [Pin, 0]; Analyzer Pol-SANS: [0, Pout]. When ''both'' polarization axes would take the value 0 - ie, a conventional, unpolarised, SANS measurement - the polarization axes need not be specified.

	''Aside: Other options considered were: "0" / "1" (eg, denoting a flipper is off / on), but this carries the risk that a coding error could be interpreted as off or not polarized), and "+" / "-", "p" / "m" (eg, denoting plus / minus), or "p" / "a" (eg, denoting parallel / antiparallel), but which require translation into a number or boolean for use in a program. It was noted that [https://www.reflectometry.org/advanced_and_expert_level/file_format\| ORSO] have opted for "p" / "m" in their emerging NR data format but their reasoning was not known.''		''Aside: Other options considered were: "0" / "1" (eg, denoting a flipper is off / on), but this carries the risk that a coding error could be interpreted as off or not polarized), and "+" / "-", "p" / "m" (eg, denoting plus / minus), or "p" / "a" (eg, denoting parallel / antiparallel), but which require translation into a number or boolean for use in a program. It was noted that [https://www.reflectometry.org/advanced_and_expert_level/file_format ORSO] have opted for "p" / "m" in their emerging NR data format but their reasoning was not known.''

	'''PROPOSAL 4:''' (Mandatory) That the definition of the polarization be '''''"For a magnetically saturated sample with collinear magnetic moments aligned along the polarization axis z, the non-spin-flip component with higher intensity is defined as the <minus, minus> spin state, but denoted here as [-1, -1]"'''''. This definition is to be incorporated in all relevant documentation relating to the production and use of NXcanSAS files.		'''PROPOSAL 4:''' (Mandatory) That the definition of the polarization be '''''"For a magnetically saturated sample with collinear magnetic moments aligned along the polarization axis z, the non-spin-flip component with higher intensity is defined as the <minus, minus> spin state, but denoted here as [-1, -1]"'''''. This definition is to be incorporated in all relevant documentation relating to the production and use of NXcanSAS files.

	''Aside: A definition of the spin states is mandatory if the data is to have any meaning at all! This definition is a less ambiguous statement of the [https://doi.org/10.1103/PhysRev.181.920\| Moon-Riste-Koehler] definition "for a polariser in the Northern hemisphere with the field aligned to the Earth's magnetic field, the transmitted beam is defined as - / minus." And in other literature the <minus, minus> state is said to transmit higher intensity than the <plus, plus> state.''		''Aside: A definition of the spin states is mandatory if the data is to have any meaning at all! This definition is a less ambiguous statement of the [https://doi.org/10.1103/PhysRev.181.920 Moon-Riste-Koehler] definition "for a polariser in the Northern hemisphere with the field aligned to the Earth's magnetic field, the transmitted beam is defined as - / minus." And in other literature the <minus, minus> state is said to transmit higher intensity than the <plus, plus> state.''

	Note: The astute reader will realise that this definition must invert in the Southern hemisphere! Data reduction software for polarized-SANS data measured at facilities there would need to correctly compensate when writing NXcanSAS files.		Note: The astute reader will realise that this definition must invert in the Southern hemisphere! Data reduction software for polarized-SANS data measured at facilities there would need to correctly compensate when writing NXcanSAS files.
Line 82:		Line 82:
	''Aside: This proposal represents an addition to NXcanSAS, but is entirely consistent with NXsample.''		''Aside: This proposal represents an addition to NXcanSAS, but is entirely consistent with NXsample.''

	Note: @direction in NeXus is defined as ''"Any of these values: x \| y \| z"''; ie, just a single axis. For some experiments (eg, if using the [https://www.isis.stfc.ac.uk/Pages/2T-3D-vector-field-magnet.aspx\| ISIS 3D Vector Field Magnet]) this would be too limiting, leading to Proposal 7b.		Note: @direction in NeXus is defined as ''"Any of these values: x \| y \| z"''; ie, just a single axis. For some experiments (eg, if using the [https://www.isis.stfc.ac.uk/Pages/2T-3D-vector-field-magnet.aspx ISIS 3D Vector Field Magnet]) this would be too limiting, leading to Proposal 7b.

	'''PROPOSAL 7b:''' (Recommended) That wherever @direction may be used, an optional alternative ('''@direction_spherical''') be permitted. This would record the ''two'' angles required to describe the field direction in spherical coordinates.		'''PROPOSAL 7b:''' (Recommended) That wherever @direction may be used, an optional alternative ('''@direction_spherical''') be permitted. This would record the ''two'' angles required to describe the field direction in spherical coordinates.

	''Aside: '''@direction_spherical''' would follow the axes coordinate system of Mantid and [https://www.sasview.org/docs/user/qtgui/Perspectives/Fitting/orientation/orientation.html\| SasView], where the neutrons travel horizontally in the direction of -z. Thus, the first angle, θ (theta), would record the angle of the field above (if positive) or below (if negative) the x-z plane. And the second angle, ψ (psi), would record the rotation of the field in the x-y plane with zero degrees at the 3 O'clock position. A positive angle corresponds to a counter-clockwise rotation.		''Aside: '''@direction_spherical''' would follow the axes coordinate system of Mantid and [https://www.sasview.org/docs/user/qtgui/Perspectives/Fitting/orientation/orientation.html SasView], where the neutrons travel horizontally in the direction of -z. Thus, the first angle, θ (theta), would record the angle of the field above (if positive) or below (if negative) the x-z plane. And the second angle, ψ (psi), would record the rotation of the field in the x-y plane with zero degrees at the 3 O'clock position. A positive angle corresponds to a counter-clockwise rotation.

	'''PROPOSAL 8:''' (Recommended) That the magnitude ('''@magnetic_field''') and direction ('''@direction''', or '''@direction_spherical''' if Proposal 7b is adopted) of the magnetic field across polarizers, flippers or analyzers be written under the respective sub-class in <SASinstrument/>.		'''PROPOSAL 8:''' (Recommended) That the magnitude ('''@magnetic_field''') and direction ('''@direction''', or '''@direction_spherical''' if Proposal 7b is adopted) of the magnetic field across polarizers, flippers or analyzers be written under the respective sub-class in <SASinstrument/>.
Line 104:		Line 104:
	'''PROPOSAL 11:''' (Mandatory) That to be able to differentiate multiple instances of polarizers, flippers or analyzers, as may be required for some Magnetic-SANS experiments, an identifer ('''@name''') be written under the respective sub-class in <SASinstrument/>.		'''PROPOSAL 11:''' (Mandatory) That to be able to differentiate multiple instances of polarizers, flippers or analyzers, as may be required for some Magnetic-SANS experiments, an identifer ('''@name''') be written under the respective sub-class in <SASinstrument/>.

	''Aside: This proposal merely extends functionality already permitted for other devices in <SASinstrument>; eg, in [https://www.cansas.org/formats/canSAS1d/1.1/doc/element_SASdetector.html#sasdetector\| <SASdetector>]. It would also provide a secondary means of distinguishing between polarizers and analyzers.'''		''Aside: This proposal merely extends functionality already permitted for other devices in <SASinstrument>; eg, in [https://www.cansas.org/formats/canSAS1d/1.1/doc/element_SASdetector.html#sasdetector <SASdetector>]. It would also provide a secondary means of distinguishing between polarizers and analyzers.'''

	=== For NeXus ===		=== For NeXus ===

← Older revision		Revision as of 15:46, 14 October 2024
Line 92:		Line 92:
	''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the magnetic field in NXpolarizer or NXflipper.''		''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the magnetic field in NXpolarizer or NXflipper.''

	'''PROPOSAL 9:''' (Recommended) That the initial polarization ('''@polarization_initial''') and (decay) time ~~constant~~ ('''@~~time_constant~~''') of 3He polarizers/analyzers and their respective uncertainties ('''@polarization_initial_dev''' and '''@~~time_constant_dev~~'''), along with the gas pressure ('''@pressure''') and exchange distance ('''@length'''), be written under <SASpolarizer/> / <SASanalyzer/>.		'''PROPOSAL 9:''' (Recommended) That the initial polarization ('''@polarization_initial''') and decay time ('''@decay_time''') of 3He polarizers/analyzers and their respective uncertainties ('''@polarization_initial_dev''' and '''@decay_time_dev'''), along with the gas pressure ('''@pressure''') and exchange distance ('''@length'''), be written under <SASpolarizer/> / <SASanalyzer/>.

	''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a 3He cell in NXpolarizer.''		''Aside: This proposal represents an addition to both NXcanSAS and NeXus; there is no provision for the time-dependent polarisation of a 3He cell in NXpolarizer.''

	Note: The decay of polarization in a gas spin-exchange polarizer is a spin-lattice relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @~~time_constant~~).		Note: The decay of polarization in a gas spin-exchange polarizer is a spin-lattice relaxation process with an exponential decay of the form ''exp''(-t / T<sub>1</sub>) where t is the time and T<sub>1</sub> is the relaxation time constant (ie, @decay_time).

	'''PROPOSAL 10:''' (Mandatory) That the order with which the neutron encounters polarizers, flippers or analyzers be specified as the distance ('''@distance''') from the sample (positive = before; negative = after) and written under the respective sub-class in <SASinstrument/>.		'''PROPOSAL 10:''' (Mandatory) That the order with which the neutron encounters polarizers, flippers or analyzers be specified as the distance ('''@distance''') from the sample (positive = before; negative = after) and written under the respective sub-class in <SASinstrument/>.
Line 110:		Line 110:
	In formulating the proposals for NXcanSAS above it became clear that there were places where the type association between NXcanSAs and NeXus broke down. To remedy this, the following additions to the [https://manual.nexusformat.org/index.html\| NeXus standard] are proposed:		In formulating the proposals for NXcanSAS above it became clear that there were places where the type association between NXcanSAs and NeXus broke down. To remedy this, the following additions to the [https://manual.nexusformat.org/index.html\| NeXus standard] are proposed:

	'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@~~time_constant~~'''.		'''PROPOSAL NX1:''' That the '''NXpolarizer''' base class be granted the additional parameters '''@transmission''', '''@transmission_empty''', '''@pressure''', '''@length''', '''@polarization_initial''' and '''@decay_time'''.

	''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He cell.''		''Aside: As currently defined, [https://manual.nexusformat.org/classes/base_classes/NXpolarizer.html#nxpolarizer\| NXpolarizer] is very much predicated on a supermirror polarizer. Although it recognises a polarizer may be of type "3He", almost none of the current parameters would describe a 3He cell.''
Line 187:		Line 187:
	polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell		polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell
	~~time_constant~~: (Recommended) polarization decay time ~~constant~~ of 3He gas in polarizer cell		decay_time: (Recommended) polarization decay time of 3He gas in polarizer cell
	~~time_constant_dev~~: (Recommended) uncertainty on polarization decay time ~~constant~~ of 3He gas in polarizer cell		decay_time_dev: (Recommended) uncertainty on polarization decay time of 3He gas in polarizer cell
	pressure: (Recommended) pressure of 3He gas in the polarizer cell		pressure: (Recommended) pressure of 3He gas in the polarizer cell
	length: (Recommended) exchange distance through 3He gas in the polarizer cell		length: (Recommended) exchange distance through 3He gas in the polarizer cell
Line 209:		Line 209:
	polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell		polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell
	~~time_constant~~: (Recommended) polarization decay time ~~constant~~ of 3He gas in analyzer cell		decay_time: (Recommended) polarization decay time of 3He gas in analyzer cell
	~~time_constant_dev~~: (Recommended) uncertainty on polarization decay time ~~constant~~ of 3He gas in analyzer cell		decay_time_dev: (Recommended) uncertainty on polarization decay time of 3He gas in analyzer cell
	pressure: (Recommended) pressure of 3He gas in the analyzer cell		pressure: (Recommended) pressure of 3He gas in the analyzer cell
	length: (Recommended) exchange distance through 3He gas in the analyzer cell		length: (Recommended) exchange distance through 3He gas in the analyzer cell
Line 283:		Line 283:
	polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell		polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell
	~~time_constant~~: (Recommended) polarization decay time ~~constant~~ of 3He gas in polarizer cell		decay_time: (Recommended) polarization decay time of 3He gas in polarizer cell
	~~time_constant_dev~~: (Recommended) uncertainty on polarization decay time ~~constant~~ of 3He gas in polarizer cell		decay_time_dev: (Recommended) uncertainty on polarization decay time of 3He gas in polarizer cell
	pressure: (Recommended) pressure of 3He gas in the polarizer cell		pressure: (Recommended) pressure of 3He gas in the polarizer cell
	length: (Recommended) exchange distance through 3He gas in the polarizer cell		length: (Recommended) exchange distance through 3He gas in the polarizer cell
Line 315:		Line 315:
	polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell		polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell
	~~time_constant~~: (Recommended) polarization decay time ~~constant~~ of 3He gas in analyzer cell		decay_time: (Recommended) polarization decay time of 3He gas in analyzer cell
	~~time_constant_dev~~: (Recommended) uncertainty on polarization decay time ~~constant~~ of 3He gas in analyzer cell		decay_time_dev: (Recommended) uncertainty on polarization decay time of 3He gas in analyzer cell
	pressure: (Recommended) pressure of 3He gas in the analyzer cell		pressure: (Recommended) pressure of 3He gas in the analyzer cell
	length: (Recommended) exchange distance through 3He gas in the analyzer cell		length: (Recommended) exchange distance through 3He gas in the analyzer cell

← Older revision		Revision as of 13:15, 7 October 2024
Line 188:		Line 188:
	time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in polarizer cell		time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in polarizer cell
	pressure: (Recommended) pressure of 3He gas in the polarizer cell		pressure: (Recommended) pressure of 3He gas in the polarizer cell
	length: (Recommended) ~~pathlength of~~ 3He gas in the polarizer cell		length: (Recommended) exchange distance through 3He gas in the polarizer cell
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction
Line 210:		Line 210:
	time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in analyzer cell		time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in analyzer cell
	pressure: (Recommended) pressure of 3He gas in the analyzer cell		pressure: (Recommended) pressure of 3He gas in the analyzer cell
	length: (Recommended) ~~pathlength of~~ 3He gas in the analyzer cell		length: (Recommended) exchange distance through 3He gas in the analyzer cell
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction
Line 273:		Line 273:
	type: (Recommended) one of: “crystal”, “supermirror”, “3He”		type: (Recommended) one of: “crystal”, “supermirror”, “3He”
	distance: (Mandatory) position of device in beamline		distance: (Mandatory) position of device in beamline
	~~transmission~~: (Recommended) transmission of polarizer		T: (Recommended) transmission of polarizer
	~~transmission_dev~~: (Recommended) transmission uncertainty of polarizer		Tdev: (Recommended) transmission uncertainty of polarizer
	~~transmission_empty~~: (Recommended) transmission of empty 3He cell polarizer		T_empty: (Recommended) transmission of empty 3He cell polarizer
	~~transmission_dev_empty~~: (Recommended) transmission uncertainty of empty 3He cell polarizer		Tdev_empty: (Recommended) transmission uncertainty of empty 3He cell polarizer
	~~efficiency~~: (Recommended) efficiency of polarizer		Eff: (Recommended) efficiency of polarizer
	~~efficiency_dev~~: (Recommended) efficiency uncertainty of polarizer		Effdev: (Recommended) efficiency uncertainty of polarizer
	polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell		polarization_initial: (Recommended) initial polarization of 3He gas in polarizer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in polarizer cell
Line 284:		Line 284:
	time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in polarizer cell		time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in polarizer cell
	pressure: (Recommended) pressure of 3He gas in the polarizer cell		pressure: (Recommended) pressure of 3He gas in the polarizer cell
	length: (Recommended) ~~pathlength of~~ 3He gas in the polarizer cell		length: (Recommended) exchange distance through 3He gas in the polarizer cell
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction
Line 293:		Line 293:
	type: (Recommended) one of: “coil”, “current-sheet”		type: (Recommended) one of: “coil”, “current-sheet”
	distance: (Mandatory) position of device in beamline		distance: (Mandatory) position of device in beamline
	~~transmission~~: (Recommended) transmission of flipper		T: (Recommended) transmission of flipper
	~~transmission_dev~~: (Recommended) transmission uncertainty of flipper		Tdev: (Recommended) transmission uncertainty of flipper
	~~efficiency~~: (Recommended) efficiency of flipper		Eff: (Recommended) efficiency of flipper
	~~efficiency_dev~~: (Recommended) efficiency uncertainty of flipper		Effdev: (Recommended) efficiency uncertainty of flipper
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction
Line 305:		Line 305:
	type: (Recommended) one of: “crystal”, “supermirror”, “3He”		type: (Recommended) one of: “crystal”, “supermirror”, “3He”
	distance: (Mandatory) position of device in beamline		distance: (Mandatory) position of device in beamline
	~~transmission~~: (Recommended) transmission of analyzer		T: (Recommended) transmission of analyzer
	~~transmission_dev~~: (Recommended) transmission uncertainty of analyzer		Tdev: (Recommended) transmission uncertainty of analyzer
	~~transmission_empty~~: (Recommended) transmission of empty 3He cell analyzer		T_empty: (Recommended) transmission of empty 3He cell analyzer
	~~transmission_dev_empty~~: (Recommended) transmission uncertainty of empty 3He cell analyzer		Tdev_empty: (Recommended) transmission uncertainty of empty 3He cell analyzer
	~~efficiency~~: (Recommended) efficiency of analyzer		Eff: (Recommended) efficiency of analyzer
	~~efficiency_dev~~: (Recommended) efficiency uncertainty of analyzer		Effdev: (Recommended) efficiency uncertainty of analyzer
	polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell		polarization_initial: (Recommended) initial polarization of 3He gas in analyzer cell
	polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell		polarization_initial_dev: (Recommended) uncertainty on initial polarization of 3He gas in analyzer cell
Line 316:		Line 316:
	time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in analyzer cell		time_constant_dev: (Recommended) uncertainty on polarization decay time constant of 3He gas in analyzer cell
	pressure: (Recommended) pressure of 3He gas in the analyzer cell		pressure: (Recommended) pressure of 3He gas in the analyzer cell
	length: (Recommended) ~~pathlength of~~ 3He gas in the analyzer cell		length: (Recommended) exchange distance through 3He gas in the analyzer cell
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction
Line 326:		Line 326:

	[https://www.cansas.org/formats/canSAS1d/1.1/doc/element_SASsample.html#sassample\| <SASsample>]		[https://www.cansas.org/formats/canSAS1d/1.1/doc/element_SASsample.html#sassample\| <SASsample>]
	~~transmission~~: (Recommended) transmission of sample		T: (Recommended) transmission of sample
	~~transmission_dev~~: (Recommended) transmission uncertainty of sample		Tdev: (Recommended) transmission uncertainty of sample
	magnetic_field: (Recommended) field strength		magnetic_field: (Recommended) field strength
	@direction or @direction_spherical: (Recommended) field direction		@direction or @direction_spherical: (Recommended) field direction