UB matrix in NXsample

[prjemian]

Documentation of the UB matrix in NXsample needs improvement. The email discussion today brings out several good points.

Quoting @vasole from his email:

• trying to map the orientation matrix (UB in the SPEC jargon) to the appropriate place in NXsample

My understanding is that it should be under orientation_matrix however I
face some difficulties:

• The format is [n_comp, 3, 3]. I would be expecting a 3x3 matrix. So, I
  guess if there is only one composition or type of crystal, the format
  has to be [1,3,3]

• Do you call orientation_matrix to the UB product in Busing and Levy or
  just the matrix U? Very often one just has the product UB and it would
  be cumbersome to have different meanings as function of having the
  (optional) cell parameters or not in order to build the B matrix. If you
  actually mean the U matrix, I would strongly advice to add the
  ub[n_comp, 3, 3] representing UB as a sample dataset field.

As a side question, what is the NXsample/sample_orientation that has
three floats? The only thing I find in Busing and Levy corresponding to
three floats is hkl. If it is that, hkl would have been more explicit.
If it is not that, what is it?

[prjemian]

Continue that thread for more discussion. @rayosborn follows up with:

> On Apr 10, 2017, at 2:19 PM, V. Armando Sole <sole at esrf.fr> wrote:
> 
> Hi Ray,
> 
> On 10.04.2017 19:40, Osborn, Raymond wrote:
>> I suppose we could add a UB
>> matrix to the list of stored parameters in a NeXus file even though it
>> is technically redundant.
> 
> We face the problem that people stores the UB matrix and the diffractometer positions together with the images but we do not have any of the other unit cell parameters.
> 
> I guess the best thing I can do then is to use a not-yet-official-and-perhpas-never-official ub term inside NXsample with dimensions [n_comp, 3, 3].
> 
> Concerning the other question concerning sample orientation specified by 3 floats. Is that intended to be hkl?
> 
> Best,
> 
> Armando

Your example provides a good rationale for having a separate UB matrix field, so I would support it. If I’m able to join the next telco, I will raise it then if others don’t.

I have never used the sample_orientation parameter, but the units are specified as NX_ANGLE, so they must refer to omega, chi, and phi, which Busing and Levy discuss in the section on “Coordinate Transformations.” They are used in the sequence of matrix multiplications that transform (hkl) into goniometer lab coordinates (Eq. 19 in Busing and Levy). The documentation is inadequate because it doesn’t state what order they are specified, but it’s either (omega, chi, phi) or the reverse. The other inadequacy is that there could be multiple (omega, chi, phi) angles if the sample is being scanned. 

Thanks for raising the issue because it is something we should sort out. There are a few questionable decisions taken when we were first formalizing the standard, such as the unit_cell field, which contains a mix of lattice parameters and angles, and therefore have mixed units. They are gradually being fixed. This might just need better documentation. I hope others contribute to this discussion if I have misunderstood the definitions. I am not a crystallographer.

[vasole]

Hi!

Mixing distances and angles I guess it is something traditional. At least SPEC provides them that way so a lot of people are used to it. For the time being I am going to ask my colleagues to use a "new" sample field named ub with dimensions [n_comp, 3, 3] containing 9 floats. I hope it will be approved.

If the three floats correspond to the angles, the choice is really unfortunate. The actual angle names should have been used because, in addition, they are scanned during measurements and there is more than just four-circle diffractometers.

On the longer term, a better solution is needed. I am not a crystallographer either but I have been dealing with diffractometer geometries and conversion from lab to reciprocal space coordinates based on the diffractometer angles. For that one needs, among others, the UB matrix, the type of diffractometer and geometry. Some classical articles are Busing & Levy 1967, Lohmaier and Vlieg (1992 or 1993 not sure), Ewans-Lutterodt and Tang (1995) and You (1999). I basically support four-circle and six-circle with the same code base. Given that those articles clearly define the different geometries and provide names to the associated angles, an NXdiffractometer class containing the UB matrix, the diffractometertype, mode and angles would be convenient since it would pave the way for conversion to reciprocal space coordinates. One would still some other things like wavelength, detector pixel sizes, distance and coordinates of the hypothetical the point of incidence on the detector if all the diffractometer angles would be at zero. Surface diffraction people, among others, need that type of description.

So, NXdiffractomer inside NXinstrument and eventually linked to from NXsample would be a nice arrangement, but I am going too far. As I said, for the time being I will just put the UB matrix inside NXsample under the name ub.

[zjttoefs]

Assuming this whole thing checks out to a crystallographer, I’d be in favour of calling the new thing ub_matrix no one refers to it as just “ub” in the emails. It would go into NXsample_component as [3,3] as well, then. Cheers, Tobias From: "V. Armando Solé" <[email protected]> Reply-To: nexusformat/definitions <[email protected]> Date: Tuesday, 11 April 2017 at 08:49 To: nexusformat/definitions <[email protected]> Cc: Subscribed <[email protected]> Subject: Re: [nexusformat/definitions] UB matrix in NXsample (#559) Hi! Mixing distances and angles I guess it is something traditional. At least SPEC provides them that way so a lot of people are used to it. For the time being I am going to ask my colleagues to use a "new" sample field named ub with dimensions [n_comp, 3, 3] containing 9 floats. I hope it will be approved. If the three floats correspond to the angles, the choice is really unfortunate. The actual angle names should have been used because, in addition, they are scanned during measurements and there is more than just four-circle diffractometers. On the longer term, a better solution is needed. I am not a crystallographer either but I have been dealing with diffractometer geometries and conversion from lab to reciprocal space coordinates based on the diffractometer angles. For that one needs, among others, the UB matrix, the type of diffractometer and geometry. Some classical articles are Busing & Levy 1967, Lohmaier and Vlieg (1992 or 1993 not sure), Ewans-Lutterodt and Tang (1995) and You (1999). I basically support four-circle and six-circle with the same code base. Given that those articles clearly define the different geometries and provide names to the associated angles, an NXdiffractometer class containing the UB matrix, the diffractometertype, mode and angles would be convenient since it would pave the way for conversion to reciprocal space coordinates. One would still some other things like wavelength, detector pixel sizes, distance and coordinates of the hypothetical the point of incidence on the detector if all the diffractometer angles would be at zero. Surface diffraction people, among others, need that type of description. So, NXdiffractomer inside NXinstrument and eventually linked to from NXsample would be a nice arrangement, but I am going too far. As I said, for the time being I will just put the UB matrix inside NXsample under the name ub. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub<#559 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AA0ReByZ5ZlDs1lWtCvsNse6Rbnfgn8sks5ruyJdgaJpZM4M5dD->.

[zjttoefs]

Colleagues I would also look at http://mmcif.wwpdb.org/dictionaries/mmcif_std.dic/Items/_diffrn_orient_matrix.UB[2][2].html<http://mmcif.wwpdb.org/dictionaries/mmcif_std.dic/Items/_diffrn_orient_matrix.UB%5B2%5D%5B2%5D.html> since the CIF wonks have probably defined this to 9dp already… You do need to be careful w.r.t. definitions - i.e. upper or lower triangular? Cheers Graeme On 11 Apr 2017, at 08:31, Tobias Richter <[email protected]<mailto:[email protected]>> wrote: Assuming this whole thing checks out to a crystallographer, I’d be in favour of calling the new thing ub_matrix no one refers to it as just “ub” in the emails. It would go into NXsample_component as [3,3] as well, then. Cheers, Tobias From: "V. Armando Solé" <[email protected]<mailto:[email protected]>> Reply-To: nexusformat/definitions <[email protected]<mailto:[email protected]>> Date: Tuesday, 11 April 2017 at 08:49 To: nexusformat/definitions <[email protected]<mailto:[email protected]>> Cc: Subscribed <[email protected]<mailto:[email protected]>> Subject: Re: [nexusformat/definitions] UB matrix in NXsample (#559) Hi! Mixing distances and angles I guess it is something traditional. At least SPEC provides them that way so a lot of people are used to it. For the time being I am going to ask my colleagues to use a "new" sample field named ub with dimensions [n_comp, 3, 3] containing 9 floats. I hope it will be approved. If the three floats correspond to the angles, the choice is really unfortunate. The actual angle names should have been used because, in addition, they are scanned during measurements and there is more than just four-circle diffractometers. On the longer term, a better solution is needed. I am not a crystallographer either but I have been dealing with diffractometer geometries and conversion from lab to reciprocal space coordinates based on the diffractometer angles. For that one needs, among others, the UB matrix, the type of diffractometer and geometry. Some classical articles are Busing & Levy 1967, Lohmaier and Vlieg (1992 or 1993 not sure), Ewans-Lutterodt and Tang (1995) and You (1999). I basically support four-circle and six-circle with the same code base. Given that those articles clearly define the different geometries and provide names to the associated angles, an NXdiffractometer class containing the UB matrix, the diffractometertype, mode and angles would be convenient since it would pave the way for conversion to reciprocal space coordinates. One would still some other things like wavelength, detector pixel sizes, distance and coordinates of the hypothetical the point of incidence on the detector if all the diffractometer angles would be at zero. Surface diffraction people, among others, need that type of description. So, NXdiffractomer inside NXinstrument and eventually linked to from NXsample would be a nice arrangement, but I am going too far. As I said, for the time being I will just put the UB matrix inside NXsample under the name ub. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub<#559 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AA0ReByZ5ZlDs1lWtCvsNse6Rbnfgn8sks5ruyJdgaJpZM4M5dD->.

…

_______________________________________________ NeXus mailing list [email protected]<mailto:[email protected]> http://lists.nexusformat.org/mailman/listinfo/nexus

-- This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail. Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message. Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom

[vasole]

@zjttoefs

I am not going to be picky and I would take whatever is decided. Everybody talks about UB matrix, but among the different formats used at the ESRF nobody has written ub_matrix in the files, just ub. Some people here seem to forget that scientist also look at the data interactively. Following your reasoning, one would have to write miller_indices or hkl_miller_indices instead of just hkl. As I said, I will take whatever is decided but I need an answer before May 10 when we would like to release our software.

[vasole]

@zjttoefs

I may be mistaken, but upper or lower triangular probably refers to the B matrix. If you follow Busing and Levy, B is upper triangular. In any case, what you usually determine is the product UB.

[rayosborn]

Since we have historically added the orientation_matrix to the NXsample class, it makes sense to add ub_matrix (or ub or UB_matrix) there as well, hopefully in time for your May 10 deadline. However, I think there is a strong argument for creating an NXgoniometer class (I would prefer that name to NXdiffractometer), one of whose fields would be to specify which publication is used to define the angles, and whether it is a four-circle or six-circle, etc. It would be useful for our own diffuse scattering software.

[vasole]

@rayosborn

I agree. At this point I have no other official place where to write the information but in the (not-so) long run a class for dealing with the diffractometers is needed. If a working group is setup, I should be able to provide help/feedback for its definition.

[zjttoefs]

In http://www.nexusformat.org/Telco_20170426.html we decided adding ub_matrix is the right thing to do. Mark will do so tomorrow.

[mkoennecke]

The ub_matrix has now been added