Coordinate Transformations#

About coordinate transformations#

There are a number of essential coordinate transformations specific to neutron-scattering such as conversion from time-of-flight to \(\lambda\) (wavelength) or \(Q\) (momentum transfer). Such coordinate transformations are also frequently referred to as “unit conversion”, but here we avoid this terminology, to clearly distinguish from conversion of array units using sc.to_unit.

Scipp provides coordinate transformations using sc.transform_coords. Scippneutron defines concrete transformations for time-of-flight neutron scattering, as well as building blocks for customizing transformations. Both are discussed in the following.

Built-in transformations#

Overview of time-of-flight transformations#

For background, we refer to PaN-learning on Introduction to neutron scattering and Basics of neutron scattering. Below we also describe the more direct approach.

We define the beamline geometry as in this image:

Where the source position defines the point where \(t=0\) (or vice versa). And \(2\theta\) is the scattering angle, as defined in Bragg’s law, not to be confused with \(\theta_{\mathsf{spherical}}\) in spherical coordinates. In many instruments the beam is roughly aligned with the \(z\)-axis, so \(2\theta = \theta_{\mathsf{spherical}}\). The factor of \(2\) is a recurrent source of bugs.

In addition:

\(h\) is the Planck constant, \(m_{\mathsf{n}}\) is the neutron mass.
\(d\) is the interplanar lattice spacing
\(\lambda\) is the de Broglie wavelength
\(\vec{Q}\) (Q_vec in code) is the momentum transfer and \(Q\) its norm
\(E\) is the energy

In the special case of inelastic neutron scattering we have additionally:

\(E_i\) is the known incident energy. This case is called direct inelastic scattering. We define \(t_0 = \sqrt{L_1^2 \cdot m_{\mathsf{n}} / (2 E_i)}\)
\(E_f\) is the known final energy. This case is called indirect inelastic scattering. We define \(t_0 = \sqrt{L_2^2 \cdot m_{\mathsf{n}} / (2 E_f)}\) In this case \(E_f\) is actually determined by analyzer crystals in the secondary flight path. It is assumed that the detector positions are set to the effective (neutronic) rather than physical positions, since the computation of \(L_2\) assumes a straight line connection between sample and detectors.

Conversions between these quantities are given by the following table:

Input coord	Output coord	Equation used for coord transformation
`tof`	`dspacing`	\(d = \frac{\lambda}{2\sin(\theta)} = \frac{h \cdot t}{L_{\mathsf{total}} \cdot m_{\mathsf{n}} \cdot 2 \sin(\theta)}\)
`tof`	`wavelength`	\(\lambda = \frac{h \cdot t}{m_{\mathsf{n}} \cdot L_{\mathsf{total}}}\)
`wavelength`	`Q`	\(Q = \frac{4 \pi \sin(\theta)}{\lambda}\)
`Q`	`wavelength`	\(\lambda = \frac{4 \pi \sin(\theta)}{Q}\)
`wavelength`	`Q_vec`	\(\vec{Q} = \vec{k}_i - \vec{k}_f = \frac{2\pi}{\lambda} \left(\hat{e}_i - \hat{e}_f\right)\)
`tof`	`energy`	\(E = \frac{m_{\mathsf{n}}L^2_{\mathsf{total}}}{2t^2}\)
`tof`	`energy_transfer` (direct)	\(E = E_i - \frac{m_{\mathsf{n}}L^2_{\mathsf{2}}}{2\left(t-t_0\right)^{2}}\)
`tof`	`energy_transfer` (indirect)	\(E = \frac{m_{\mathsf{n}}L^2_{\mathsf{1}}}{2\left(t-t_0\right)^{2}} - E_f\)

See the reference of scippneutron.conversion for additional conversions and more details.

Transformation graphs#

The above table defines how an output coordinate such as wavelength is computed from inputs such as Ltotal and tof. In practice not all input data directly comes with all the required metadata. For example, instead of Ltotal the metadata may only contain source_position, sample_position, and position. These can then be used to compute derived metadata such as Ltotal. transform_coords can automatically do this by walking a transformation graph.

The transformations typically require two components:

A definition of the beamline geometry which defines, e.g., how scattering angles are to be computed from positions of beamline components such as sample and detector positions.
A definition of the scattering kinematics and dynamics, e.g., how \(\lambda\) or \(Q\) can be computed from time-of-flight for an elastic scattering process.

Pre-defined standard components (transformation graphs and graph building blocks) are available in scippneutron.conversion.graph:

[1]:

import scipp as sc
from scippneutron.conversion import graph

graph.beamline.beamline defines a “simple” (straight) time-of-flight beamline with source-, sample-, and detector positions. Two variants, with and without scattering are provided.

Without scattering, the transformation graph is simple. This intended for use with monitors or imaging beamlines where no scattering from a sample occurs:

[2]:

sc.show_graph(graph.beamline.beamline(scatter=False), simplified=True)

[2]:

../_images/user-guide_coordinate-transformations_3_0.svg

The graph is to be read as follows. Starting with the node for the desired output coordinate, here Ltotal, transform_coords proceeds as follows:

If Ltotal is found in the metadata, no transformation is performed. Return Ltotal.
If Ltotal is not found in the metadata,
1. For each input to the node (arrows pointing to the node, here source_position and position) go to 1., i.e., either find the input, or compute it by continuing to walk upwards in the graph.
2. Compute Ltotal from the found or computed inputs and return it.

If the top of the graph is reached without finding all required inputs, the transformation fails. Refer to the scipp documentation on Coordinate Transformations for a more detailed explanation.

A more complex example is conversions.beamline for a scattering process:

[3]:

sc.show_graph(graph.beamline.beamline(scatter=True), simplified=True)

[3]:

../_images/user-guide_coordinate-transformations_5_0.svg

In addition to defining how beamline parameters can be computed, a second building block defines how, e.g., \(\lambda\) or \(Q\) can be computed from an input coordinate. There are four cases:

conversions.kinematic for straight propagation of neutrons, i.e., without any scattering process. This is intended for use in combination with conversions.beamline(scatter=False).
conversions.elastic for elastic scattering processes.
conversions.direct_inelastic for direct-inelastic scattering processes, i.e., for fixed incident energies.
conversions.indirect_inelastic for direct-inelastic scattering processes, i.e., fixed final energies, typically using analyzer crystals.

The coordinate transformation logic defined by these four cases is as follows:

[4]:

sc.show_graph(graph.tof.kinematic("tof"), simplified=True)

[4]:

../_images/user-guide_coordinate-transformations_7_0.svg

[5]:

sc.show_graph(graph.tof.elastic("tof"), simplified=True)

[5]:

../_images/user-guide_coordinate-transformations_8_0.svg

[6]:

sc.show_graph(graph.tof.direct_inelastic("tof"), simplified=True)

[6]:

../_images/user-guide_coordinate-transformations_9_0.svg

[7]:

sc.show_graph(graph.tof.indirect_inelastic("tof"), simplified=True)

[7]:

../_images/user-guide_coordinate-transformations_10_0.svg

Computing energy transfer for an indirect geometry instrument requires changes to the beamline graph to account for scattering off of the analyzers. This has not yet been implemented in ScippNeutron as the precise input coordinates for relevant instruments are unknown. But an example has been developed for a summer school here.