scippneutron.conversion.beamline#

Functions for computing coordinates related to beamline geometry.

Most functions in this module assume a straight beamline geometry. That is, the beams are not curved by, e.g., a beam guide. Specialized functions are provided for handling gravity.

ScippNeutron uses three positions to define a beamline:

source_position defines the point where \(t=0\) (or vice versa). In practice, this can be the actual neutron source, a moderator, or a chopper.
sample_position is the position of the sample that scatters neutrons.
position is the position of the detector (pixel / voxel) that detects a neutron at \(t=\mathsf{tof}\).

Based on these positions, we define:

incident_beam is the vector of incoming neutrons on the sample. It points from the source to the sample. (straight_incident_beam())
L1 (or \(L_1\)) is the length of incident_beam. (L1())
scattered_beam is the vector of neutrons that were scattered off the sample. It points from the sample to the detector pixels. (straight_scattered_beam())
L2 (or \(L_2\)) is the length of scattered_beam. (L2())
Ltotal is the total beam length \(L_\mathsf{total} = L_1 + L_2\). (total_beam_length() and total_straight_beam_length_no_scatter())

Coordinate system#

Note

The coordinate system is not needed by most operations because beamline coordinates are usually relative to the positions. As long as position, source_position, and sample_position are defined consistently, incident_beam, scattered_beam, and two_theta can be computed without knowledge of the coordinate system.

However, we need the actual coordinate system to compute phi.

Two coordinate systems are involved:

The lab frame in which position, source_position, and sample_position are given. ScippNeutron does not define it. Typically, it is the NeXus coordinate system, where the z-axis points along the beam and the y-axis points up.
The beam-aligned frame, which ScippNeutron derives from the incident beam and gravity in order to define angles relative to them, such as phi.

Below, \(x\), \(y\), and \(z\) refer to the beam-aligned frame. It is identical to the NeXus lab frame when the incident beam points along the lab z-axis. The image below shows how coordinates are defined with respect to the quantities defined above, for an incident beam perpendicular to gravity. The plot on the right-hand side shows the view from the sample along the \(z\)-axis, that is, the \(z\)-axis points towards the viewer. (The sample is placed in the origin here; this is only done for illustration purposes and not required.)

The axes are defined by these unit vectors:

\[\begin{split}\hat{e}_z &= b_1 / |b_1| \\ x_\perp &= -g \times \hat{e}_z \\ \hat{e}_x &= x_\perp / |x_\perp| \\ \hat{e}_y &= \hat{e}_z \times \hat{e}_x\end{split}\]

which span an orthogonal, right-handed coordinate system. Here, \(b_1\) is the incident_beam and \(g\) is the gravity vector. This means that the z-axis is along the incident beam and the x-axis is horizontal. The y-axis is antiparallel to gravity if and only if the incident beam is perpendicular to gravity, which is the case on most beamlines. If the incident beam is tilted with respect to the horizontal plane, the y-axis tilts with it, such that phi remains the azimuthal angle about the incident beam. Basis vectors can be computed using beam_aligned_unit_vectors().

\(p = \sqrt{x^2 + y^2}\) is the projection of the scattered beam onto the \(x-y\) plane. It is included here because it is used by some coordinate transformations.

The scattering angles are defined similarly to spherical coordinates as:

\[\begin{split}\mathsf{cos}(2\theta) &= \frac{b_1 \cdot b_2}{|b_1| |b_2|} \\ \mathsf{tan}(\phi) &= \frac{b_2 \cdot \hat{e}_y}{b_2 \cdot \hat{e}_x}\end{split}\]

where \(b_2\) is the scattered beam.

two_theta is the angle between the scattered beam and incident beam. Note the extra factor 2 compared to spherical coordinates; it ensures that the definition corresponds to Bragg’s law.
phi is the angle between the x-axis and the projection of the scattered beam onto the x-y-plane.

These definitions assume that gravity can be neglected. See scattering_angles_with_gravity() for definitions that account for gravity. And scattering_angle_in_yz_plane() for the definition used in reflectometry — which also includes gravity.

Functions

`L1`(*, incident_beam)	Compute the length of the incident beam.
`L2`(*, scattered_beam)	Compute the length of the scattered beam.
`beam_aligned_unit_vectors`(incident_beam, gravity)	Return unit vectors for a coordinate system aligned with the incident beam.
`scattering_angle_in_yz_plane`(incident_beam, ...)	Compute polar scattering angles in the y-z plane using gravity.
`scattering_angles_with_gravity`(...)	Compute scattering angles theta and phi using gravity.
`straight_incident_beam`(*, source_position, ...)	Compute the length of the beam from source to sample.
`straight_scattered_beam`(*, position, ...)	Compute the length of the beam from sample to detector.
`total_beam_length`(*, L1, L2)	Compute the combined length of the incident and scattered beams.
`total_straight_beam_length_no_scatter`(*, ...)	Compute the length of the beam from source to given position.
`two_theta`(*, incident_beam, scattered_beam)	Compute the scattering angle between scattered and transmitted beams.

Classes

`BeamAlignedUnitVectors`	A dict with keys 'beam_aligned_unit_{x,y,z}'.
`SphericalCoordinates`	A dict with keys 'two_theta' and 'phi'.