ENH: units in wiki API page

[CJ-Wright]

Would it be possible to give the units, where applicable, for the function variables on the API page? For example I was rather confused about whether to use q in inverse Angstroms or inverse nm for the FF_Rayl function.

[tschoonj]

I will look into it next week

[tschoonj]

I improved the documentation a lot over the last two days: could you check if everything is fine now?

Thanks

Tom

[CJ-Wright]

The documentation is better, but I am a little confused about the units on FF_Rayl, when I compared the output of FF_Rayl vs. srFit I get two different scattering factors. It seems the two systems are off by a factor of 10 from one another. Is it possible that FF_rayl q is measured in nm^-1?

[tschoonj]

I checked the code and I am confident that FF_Rayl and SF_Compt expect q to be expressed in Å^-1.

I am not familiar with srFit: which function do you call to produce the form factor?

[CJ-Wright]

from diffpy.srreal.pdfcalculator import DebyePDFCalculator
dpc = DebyePDFCalculator()
dpc.scatteringfactortable.lookup('C', 0)

for the scatter factor of carbon at q = 0 A^-1

[tschoonj]

I agree that there is indeed something weird going on. Documentation in the source code says that it takes Å^-1, but the results then disagree with srFit and also for example this website as you've pointed out.

However, the DCS_Rayl and DCSP_Rayl functions rely on FF_Rayl internally and these output correct results (verified it myself using numerical integration over 0 < θ < π and 0 < φ < 2π and comparing with CS_Rayl). Forcing FF_Rayl to divide q by 10 (replicating your effort) then obviously produced incorrect results.

This part of the code is more than a decade old and was written before I joined the project. I have contacted the original author asking for an explanation and hope to hear from him soon.

[CJ-Wright]

Hmm, that's very interesting. Thank you very much for following up on this!

[CJ-Wright]

Any new news on this?

[tschoonj]

Nope sorry. I will email him again.

[tschoonj]

My former colleague and author of this function Bruno Golosio of the University of Sassari replied to me and provided his take on the situation: essentially it comes down to how you define the momentum transfer. Several definitions appear to be used, one of which uses a multiplication by a factor of 4π (Wikipedia), which I think is the actual scale factor of the argument that you observed in your plots, instead of 10.

I will add a note about this to the manual. Thanks for bringing this matter to our attention.

[tschoonj]

Bruno just wrote me another email with even further clarifications.

1) beware that people from the crystallography/diffraction community often call "theta" the angle between the incident ray and the crystal scattering planes, according to Bragg's law. The "rest of the x-ray world" call "theta" the scattering angle, which in case of Bragg scattering is two times the angle of the previous definition. In my opinion this second definition is more meaningful for us, as we also work with amorphous materials, and with incoherent scattering, where does not make sense to think of scattering planes. Depending on the definition of theta, the argument of the sine function will be theta or theta/2, respectively.

2) All the conventions used in xraylib for momentum transfer, atomic form factor and incoherent scattering function are explained in the third page (page 473 of the journal) of Hubbell et al. "Atomic form factors, incoherent scattering functions, and photon scattering cross sections" J. Phys. Chem. Ref. Data 4 http://www.nist.gov/data/PDFfiles/jpcrd67.pdf (which was my bible at the time...) Hubbell (and many other authors) defines the momentum transfer as sin(theta/2)/lambda Other authors define it as 4_PI_sin(theta/2)/lambda Neither of the two definitions can be considered to be better than the other, as strictly speaking the momentum transfer units should be kg_m/s , and both definitions use the planck constant to scale it. Now, our atomic form factor is expressed in terms of Q_hubbell. If we plot it as a function of Q_others, where Q_others=4_PI*Q_hubbel, we will probably obtain the same plot as those in the website that you mention.

[CJ-Wright]

Thank you very much for the clarification!