Definitions used in the Abstract Diffractometer work

[pkeller]

@beteva has defined a set of directions and roles for motors in AbstractDiffractometer.py and diffractometer.md. The terms "floor" and "ground" have been used without being defined. Assuming that they both mean "a plane perpendicular to the gravitational force", we suggest that the existing definition of the axis directions are reworded as follows:

• the z axis is the direction of the gravitational force
• the x axis is the direction of the projection of the beam onto a plane perpendicular to z. The positive direction is from the sample position towards the beam source.
• the y axis completes a right-handed set of directions with z and x

If the beam is exactly perpendicular to the gravitational vector, it follows from these definitions that the beam travels in the direction -x

Further points:

• The set of directions x, y and z have been referred to as a "coordinate system" (for example verbally at the MXCuBE meeting at DLS on 2025-11-19). This is not the case because no origin is defined, and Antonia (correctly) does not use the term "coordinate system" in her original text.
• The use of the right-hand rule (which is universal in this type of context) means that only two mutually perpendicular directions need to be defined, with the third direction being derived from the other two. This removes an ambiguity that is present in the current definitions.

Any comments or questions?

We have some other comments about the motor object definitions, but let's start with the definitions of the directions.

[beteva]

This removes an ambiguity that is present in the current definitions.

Could you, please, tell us what the ambiguity you refer to.

[pkeller]

I was referring to this:

x axis is parallel to the beam. Positive direction is from right to left.

where the position of the observer is not stated, so it is unclear what right and left mean. The ambiguity can be resolved by taking y and z to define the set of directions with x completing a right-handed set, but it is not stated explicitly this ought to be done.

The wording I suggested does several things:

• it doesn't involve specifying the position of an observer
• it clarifies which direction is the one that is implied by the other two directions, and separates the description of that direction from the actual definition
• it caters for cases where the beam is not exactly horizontal

Thanks for the question, I should probably have explained this in my opening remarks.

[pkeller]

We see two problems with these two definitions:

  sample_horizontal - x axis, combination of sampx and sampy. Equivalent to
                      sampx at omega=0 and sampy for omega=90.
  samle_vertical - y axis, combination of sampx and sampy. Equivalent to
                   sampy at omega=0 and sampx for omega=90.

• The terms "horizontal" and "vertical" don't mean much for a vertically mounted goniostat. The defining properties of these directions are that they are parallel and perpendicular to the beam. It should be possible to find better names. @MartinSavko, @epanepucci, @JieNanMAXIV maybe you have some ideas? (I'll e-mail Ana and Gleb, I haven't been able to find GitHub user ids for them.)
• It is not necessarily true that these virtual axes coincide with sampx/sampy when omega=0 or 90. We have seen deviations of 10° or even more. I suggest that the statements "Equivalent to..." are deleted. Alternatively, if the equivalence between the real and virtual axes is more than descriptive, i.e. is used or expected to be used in code, the value of omega for which the statements are true needs to be made an attribute of the class.

There is also a typo here: "samle" should be "sample".

[glebbourenkov]

Per previous email exchange with Peter:

The definitions in AbstractDiffractometer.py generallly appear to apply to MD series of diffractometers only, and definitions of sample_horizontal and samle_vertical pseudo motors to horizontal-spindle MDs only.

In the context of Arinax MDs only, and following preceding definitions, I would suggest to call these pseudo motors "sample_focus" and "sample_lateral", i.e. using the terms bound to the OAV microscope . The statement on equivalence at 90 degree etc. is not true for MD3. Correct statement would be e.g. "at an Omega='Omega reference"' in the internal MD Centring Table configuration". But, there is no use of this information in MXCuBE* , i.e. maybe best to just omit that definition.

[pkeller]

This description is ambiguous:

omega - the rotation axis, independent of the orientation (up, down or side).
Pisitive direction is clockwise.

because the actual direction of rotation implied by "clockwise" depends on the position of the observer and the direction of view. Another problem with this description is that the direction of positive rotation of a particular type of instrumentation is a design and engineering choice. It is not possible to state that the omega motor rotates in a specific direction, while also maintaining generality across MX diffractometer setups.

A better alternative IMO is to state that the direction of the omega motor rotation axis follows the right-hand rule. This allows for the specification of all four conventional possibilities for the orientation and rotational direction of the omega axis in terms of the directions defined above: the omega axis is +y or -y for horizontally-mounted goniostats, or +z or -z for vertically-mounted goniostats. A particular instrumental setup can then specify which of these choices applies to it.

[rhfogh]

An alternative proposal for definitions, expanded from the discussion in the 20260222 MXCuBE meeting.
Ther could be many variants on this:

• We define a right-handed lab-based coordinate system based on the direction of the rotation axis (exactly on axis) and the beam direction (approximately on axis, and assumed to be approx 90deg from the rotation axis). This proposal assumes that the lab- coordinate system is based on physical directions (diffractometer to sample) rather than omega axis rotation direction, but it could be done the other way around. Let us arbitrarily say that the axis parallel to the rotation axis is called Y
• The three centring motors are assumed to be orthogonal, with one of the motors parallel to the rotation axis.
• We call the centring motors sampX, sampY and sampZ, where sampZ is parallel to the rotation axis. SampX, sampY, sampZ form a right-handed coordinate system with the zero-point defined as motor position 0,0,0
• We need three more parameters: First, whether the sampX motor direction is along +Y or -Y. Second whether positive rotation for the omega axis is along +Y or -Y Third the value of omega for which the sampX centring axis points (approximately) along the beam from the sample to the detector.
• If the centring motors are only approximately orthogonal (is this a real possibility??) we would have to give directions for the sampX and sampY motors, but we would still have the omega value for which the sampX motor was in the plane of the rotation axis and the beam.

Will this work in practice, with real motors? Are there problems with motor names and direction not necessarily fitting togetehr in right-handed coordinate systems?

[marcus-oscarsson]

The system we are currently using could be defined like this:

x̂: Is in the direction of the beam, pointing, positive direction, towards the detector
ẑ: Is in the, negative, direction of gravity, pointing "upwards"
ŷ: Is orthogonal to the other two, assuming R3 ;), what one could loosely refer to as horizontal. Pointing out from the synchtoron ring

Once we have this we can then define, depending on diffractometer setup, which is our rotation axis.

The motors phix, phiz and phiy of the diffractometer corresponds to x̂, ẑ and ŷ respectively

On horizontal goniometer that would mean that we rotate around phiy and around phiz on a vertical.

The diffractometer has a x-y translation stage after the rotation meaning that the directions is a function of ω. These motors are defined as:

• at ω=0, sampx is parallel to x̂
• at ω=0, sampy is parallel to ŷ

[rhfogh]

It could. But it leaves the two problems that

1. with a vertical goniostat neither sampx nor sampy can parallel to ẑ whatever the value of ω.
2. It i s not always the case that the translation motors are parallel to the axes at ω=0.

Using gravity rather than the omega axis is a valid choice. Still, for curiosity, do you actually measure the precise omega rotation vector in this coordinate system? Or do you in practice assume that it is horizontal and orthogonal to the beam?

[marcus-oscarsson]

I just wanted to outline what we are using today, which is the above.

For your points 1 and 2:

I'm not sure I understand why that would be a problem. There is maybe a confusion between the names used by the de-facto standard given by the Arinax MD and what you have described above. I have, above, used the motor names and functions that are used by the MD. We should perhaps be careful with those names because for many of us sampx and sampy is actual motors, while sampz does not exist.

The advantage of using gravity and beam is that the reference frame is fixed. The rotation axis is calibrated to be "fixed" in the beam and should not move. Using the rotation axis would rotate the entire coordinate system with the orientation of the goniometer.

[rhfogh]

It is just that if what you are giving is a definition (you say 'These motors are defined as ...'), then the definition will break for a vertical goniostat. If it is just a description of what you have there is no such problem.

[marcus-oscarsson]

I was just giving what we are currently using as an example and I think there are things the we are currently using that make sense like the definitions of x̂, ẑ and ŷ.

In our case we define the rotation axis depending on the orientation of the goniometer, either phiz or phiy. You are right that the definition would need to be generalized. However, we do need to be care full with the naming because using the name sampx would (or could for many) sort of imply that we mean the sampx motor that is the motor after the rotation stage.

Perhaps defining something called rotation_axis at κ=0 to either x̂, ẑ or ŷ. would work. Meaning that rotation_axis at κ=0 would ŷ for a horiztonal goniometer and ẑ for a vertical.

[rhfogh]

Yeah, my proposal should be OK for its structure, but the actual names could and probably should be changed. Take them as fungible - it was quickly written. And, as you say, we do need to be care full with the naming.

[marcus-oscarsson]

Yes you are right, to me any sample-x̂,-ẑ or -ŷ would imply that its after ω