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.

ScippNeutron uses a coordinate system aligned with the incident beam and gravity. ScippNeutron’s coordinate system corresponds to that of NeXus when the incident beam is perpendicular to gravity. The image below shows how coordinates are defined with respect to the quantities defined above. 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}_y &= -g / |g| \\ z_{\text{proj}} &= b_1 - (b_1 \cdot \hat{e}_y) \hat{e}_y \\ \hat{e}_z &= z_{\text{proj}} / |z_{\text{proj}}| \\ \hat{e}_x &= \hat{e}_y \times \hat{e}_z\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 y-axis is antiparallel to gravity. The z-axis is defined by projecting the incident beam onto a plane perpendicular to gravity. 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'.