Decide x,y, and z directions/handedness and how to handle data sets without Qz

[wpotrzebowski]

Description
Define semantics when Qz is absent: (a) infer Qz=0 for planar geometries; (b) compute on import (if metadata allow); or (c) keep None with guarded code paths. Document user-visible behavior.
References
Data formats currently recognise 1D and 2D (Qx,Qy) and SESANS; clarify how “no Qz” is represented.
sasview.org

Acceptance Criteria
Decision note + schema update
Loader/GUI messaging for “no Qz” cases
Tests covering all three modes

[pmneves7]

After discussion with @butlerpd , we have decided that the following handling of Qz should be implemented when no Qz data is provided:

Case 1: If the data is 1D, leave it as 1D. You have already gone down to |Q| from (Qx,Qy) so there is little point trying to handle Qz.

Case 2: If the data is 2D and wavelength is provided as metadata, automatically compute Qz. Qz can be computed from Qx, Qy, and wavelength as:

    k0 = 2*np.pi/wavelength
    twotheta = np.arcsin((qx**2 + qy**2) / k0)
    qz = (1 - np.cos(twotheta)) * k0

I have implemented this function in the refactor_24_3D branch of sasdata in data_util/manipulations.py, though this may be better put somewhere else.

Case 3: If no wavelength is provided for 2D (Qx, Qy) data, then just set Qz to zero. This just makes explicit the implicit approximation that is already being made which is that Qz is approximately zero (which is only a good approximation for small |Q|*wavelength). Should also allow an option for the user to enter a wavelength to calculate Qz (but this should not be an automatically generated prompt otherwise you will get prompted every time you load incompatible data!).

Put simply: 2D data doesn't actually exist in SAS, and should always be treated as 3D.

[marimperorclerc]

After our discussions this week, I checked again the relations for the qz component !
Here is what I obtain:

With q= (4 np.pi/wavelength) np.sin(theta) (modulus of the scattering vector)

qz=(2 np.pi/wavelength) (np.cos(2*theta)-1).
qz is the component along the beam direction, note that qz is negative if z is defined along the beam direction.

and (qx,qy) are the two components perpendicular to the beam direction with a simple relation for the total perpendicular component:
np.sqrt(qx2+qy2)=(2 np.pi/wavelength) (np.sin(2*theta))

(sqrt term seems to be missing in your expression in the arcsin)

Hope that this will help.

[marimperorclerc]

Easier to see on a figure with Ewald sphere !

[pmneves7]

You are right Marie, I made a typo in my algebra and missed the squareroot! I believe the code should then look like this:

k0 = 2*np.pi/wavelength
twotheta = np.arcsin(np.sqrt(qx**2 + qy**2) / k0)
qz = (1 - np.cos(twotheta)) * k0

This agrees with your whiteboard drawing

And this can be further reduced with the identity cos(arcsin(x)) = sqrt(1-x^2) to:

k0 = 2*np.pi/wavelength
qz = k0-np.sqrt(k0**2-qx**2-qy**2)

which is much more efficient to compute

[marimperorclerc]

This is cool ... I like your last expression which is very simple ! :)
In fact, you can get it almost directly from the large triangle in the figure.
Enjoy the end of the contributor camp.

[marimperorclerc]

Here is a .png drawing to explain the q_z component from the Ewald sphere. Might be re-used for documentation later on. Any comments about this figure ?

[butlerpd]

BEAUTIFUL! It looks very nice to me!!

[pmneves7]

Indeed quite nice! The one thing I am concerned about generally is to make sure that x, y, and z form a right handed coordinate system. If x points into the page and z points along the beam, this works. If x points out of the page and z points along the beam (which I believe is the SANS convention) it is left handed. This might lead to some confusion, and even errors! To keep the conventional definition of x and y, I believe we may have to make z point antiparallel to the beam.

[marimperorclerc]

Yes, I fully agree that a right-handed xyz coordinate system is mandatory if we want to avoid some confusions. :)

So we may use different options, all with xyz right-handed.
Which ones sounds the most 'natural' choice to you among these three options ?

• advantage of the first option is that q_z is positive, but with a weird anti-parallel z direction.
• second option is fine, except that image on the detector is looked from the back, and this is weird too ...
• my favorite option is the last one with a vertical z-axis convention. It is the one I'm already using and I see much better xyz this way as a reference coordinate sytem for a SAS instrument. But I guess that qx-qz for the detector might sound weird too ! ;)

And here is a last alternative version ... without any xyz choice !

[butlerpd]

For what its worth, my vote would be the first one. For those (most people) not thinking in terms of $\vec{Q_z}$, the x and y directions in the first representation will be exactly as they are used to. This is also important in terms of quadrants and in fact may affect many things in the code that depend on the sign of $\vec{Q_x}$ and $\vec{Q_y}$? The fact that z is then positive is also a bonus. I don't think many people will notice it is antiparallel to the beam but if they do I agree it will seem a bit weird. Still, I think it is the most "natural" of the options and certainly the least intrusive in terms of other changes to the code and documentation?

[nicoratel]

Hi everyone,
I am new in this topic but here is my opinion about this subject. To me, the most natural representation consistent with the actual convention in sasview (detector frame in xy plane), is the second option proposed by Marianne.
In this option, x axis points into the page, y axis is vertical, and z axis is parallel to the beam. But I agree that having positive $Q_x$ values on the left quadrants is weird....
However, as SAS images are usually centrosymmetric (the direct beam is a inversion symmetry), intensity value at a given $(Q_x,Q_y)$ position is equal to that at $(-Q_x,-Q_y)$. In other words, $I(Q_x,Q_y,Q_z)=I(-Q_x,-Q_y,Q_z)$. We might therefore be allowed to invert Qx and Qy values so that the positive $Q_x$ correspond to the right quadrants. Do you think this approach is valid?
Alternatively, the third representation (beam along y axis) is the most natural to me, with a vertical z axis, xy being the horizontal plane. In this convention, the detector frame is in $(x,z)$ plane. This not consistent with the actual convention in sasview. The choice of this representation may imply huge rework on sasview code.

[pmneves7]

I agree with Paul Butler on this. The third option is indeed the one that crystallographers tend to use with z up. If we were starting from scratch I would go with option 3. However, SANS uses the convention that y is up, and this is what SANS users are used to (and the rest of the code is written around). For this reason, I think the first option is the best choice. This is also how I implemented it previously in GRASP/GRIP to maintain backwards compatibility.

I think if we have consensus, we have a well defined choice for the convention. This is what is currently calculated in my deduce_qz function in the refactor_24_3D branch of sasdata, assuming that the imported data uses the above q_x and q_y convention. We still need to decide where in sasdata to run the deduce_qz as a postprocess step.

[pmneves7]

Hi everyone, I am new in this topic but here is my opinion about this subject. To me, the most natural representation consistent with the actual convention in sasview (detector frame in xy plane), is the second option proposed by Marianne. In this option, x axis points into the page, y axis is vertical, and z axis is parallel to the beam. But I agree that having positive Q x values on the left quadrants is weird.... However, as SAS images are usually centrosymmetric (the direct beam is a inversion symmetry), intensity value at a given ( Q x , Q y ) position is equal to that at ( − Q x , − Q y ) . In other words, I ( Q x , Q y , Q z ) = I ( − Q x , − Q y , Q z ) . We might therefore be allowed to invert Qx and Qy values so that the positive Q x correspond to the right quadrants. Do you think this approach is valid? Alternatively, the third representation (beam along y axis) is the most natural to me, with a vertical z axis, xy being the horizontal plane. In this convention, the detector frame is in ( x , z ) plane. This not consistent with the actual convention in sasview. The choice of this representation may imply huge rework on sasview code.

I do not like the idea of inverting Qx from how it is conventionally defined. This breaks with the conventions and intuition of people used to them, and may have unintended consequences. Further, there may be subtle reasons why Qx may not be symmetric (maybe there is more absorption on one side of the beam than the other from the sample environment, for example). I also do not think we should go about redefining Qy to be Qz for similar reasons and because of the required code reworking.