QENSmodels package

Submodules

QENSmodels.background_polynomials module

QENSmodels.background_polynomials.background_polynomials(x: float | list | ndarray, list_coefficients: float | list = 0.0) → Polynomial

Polynomials of variable w and with coefficients contained in list_coefficients

Parameters:

• x (list or ndarray) – domain of the function

• list_coefficients (list or float) – list of coefficients for the polynomials in ascending order, i.e. the first element is the coefficient for the constant term. Default to 0 (no background).

Returns:

output number or array

Return type:

numpy.float64 or ndarray

Examples

>>> background_polynomials(5, 1)
1.0

>>> background_polynomials(5, [1, 2])
11.0

>>> background_polynomials([1,2,3], [1,2,3])
array([ 6., 17., 34.])

Mathematically, background_polynomials(x, [1,2,3]) corresponds to :math: 1 + 2x + 3x^2.

QENSmodels.brownian_translational_diffusion module

QENSmodels.brownian_translational_diffusion.hwhmBrownianTranslationalDiffusion(q: float | list | ndarray, D: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Lorentzian model with half width half maximum equal to \(Dq^2\)

Returns some characteristics of BrownianTranslationalDiffusion as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (ndarray) – momentum transfer (non-fitting, in 1/Angstrom).

• D (float) – diffusion coefficient (in Angstrom**2/ps). Default to 1.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmBrownianTranslationalDiffusion(1.)
>>> hwhm[0]
1.0
>>> eisf[0]
0.0
>>> qisf[0]
1.0

>>> hwhm, eisf, qisf = hwhmBrownianTranslationalDiffusion([1., 2.], 1.)
>>> hwhm[0]
1.0
>>> hwhm[1]
4.0
>>> eisf[0]
0.0
>>> eisf[1]
0.0
>>> qisf[0]
1.0
>>> qisf[1]
1.0

QENSmodels.brownian_translational_diffusion.sqwBrownianTranslationalDiffusion(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, D: float = 1.0) → float | list | ndarray

Lorentzian model with half width half maximum equal to \(Dq^2\)

It corresponds to a continuous long-range isotropic translational diffusion.

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – peak center. Default to 0.

• D (float) – diffusion coefficient (in Angstrom**2/ps). Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwBrownianTranslationalDiffusion(1, 1, 1, 0, 1)
>>> round(sqw[0], 3)
0.159

>>> sqw = sqwBrownianTranslationalDiffusion([1, 2, 3], [0.3, 0.4], 1, 0, 1)
>>> round(sqw[0, 0], 3)
0.028
>>> round(sqw[0, 1], 3)
0.007
>>> round(sqw[0, 2], 3)
0.003
>>> round(sqw[1, 0], 3)
0.05
>>> round(sqw[1, 1], 3)
0.013
>>> round(sqw[1, 2], 3)
0.006

Notes

• The sqwBrownianTranslationalDiffusion is expressed as

\[S(q, \omega) = \text{Lorentzian}(\omega, \text{scale}, \text{center}, Dq^2)\]

• The incoherent dynamic structure factor sqwBrownianTranslationalDiffusion corresponds to

  • in real space, the probability of finding a particle at a distance r from its initial position is a Gaussian function of space r

    \[G(r, t)=(\frac{\text{scale}}{4\pi D t})^{3/2}\exp (-\frac{r^2}{4Dt})\]

  • in reciprocal space, the autocorrelation function is

    \[I(q, t) = \int G(r, t) dr = \text{scale} \exp (-Dq^2 t)\]

• This model works reasonably well at low q. Other models, such as “Chudley-Elliott”, have been developed to describe the microscopic mechanisms that deviate from the Fickian behavior (hwhm proportional to q squared)

References

• T. Springer, Quasielastic neutron scattering for the investigation of diffusive motions in liquids and solids, Springer Tracts in Modern Physics 64 (1972) link

• 7. 8. Vineyard, Phys. Rev. 110, 999-1010 (1958)

QENSmodels.chudley_elliott_diffusion module

QENSmodels.chudley_elliott_diffusion.hwhmChudleyElliottDiffusion(q: float | list | ndarray, D: float = 0.23, L: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of ChudleyElliottDiffusion as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• D (float) – diffusion coefficient (in Angstrom^2/ps). Default to 0.23.

• L (float) – jump length (in Angstrom). Default to 1.0.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmChudleyElliottDiffusion([1., 2.], 0.5, 1.5)
>>> round(hwhm[0], 3), round(hwhm[1], 3)
(0.447, 1.271)
>>> eisf
array([0., 0.])
>>> qisf
array([1., 1.])

QENSmodels.chudley_elliott_diffusion.sqwChudleyElliottDiffusion(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1, center: float = 0, D: float = 0.23, L: float = 1.0) → float | list | ndarray

Lorentzian model with half width half maximum equal to \(\frac{6D}{L^2}(1 - \frac{sin(QL/pi)}{QL/pi})\)

It is a model originally developed for jump diffusion in liquids. But it can also be applied to diffusion in crystalline lattices.

Atoms or molecules are caged by other atoms and jump into a neighbouring cage from time to time.

The jump length L is identical for all sites.

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom).

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• D (float) – diffusion coefficient (in Angstrom^2/ps). Default to 0.23.

• L (float) – jump distance (in Angstrom). Default to 1.0.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwChudleyElliottDiffusion([1, 2, 3], 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.159
>>> round(sqw[1], 3)
0.062
>>> round(sqw[2], 3)
0.031

>>> sqw = sqwChudleyElliottDiffusion(1, 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.159

Notes

• The sqwChudleyElliottDiffusion is expressed as

  \[S(q, \omega) = \text{Lorentzian}(\omega, \text{scale}, \text{center}, \frac{6D}{l^2}(1 - \frac{sin(Ql/pi)}{Ql/pi}))\]

• Note that an equivalent expression is

  \[S(q, \omega) = \text{Lorentzian}(\omega, \text{scale}, \text{center}, \frac{1}{\tau}(1 - \frac{sin(Ql/pi)}{Ql/pi}))\]

  with \(\tau=\frac{l^2}{6D}\).

References

• R. Hempelmann, Quasielastic Neutron Scattering and Solid State Diffusion (Oxford, 2000).

• C. T. Chudley and R. J. Elliott, Proc. Phys. Soc. 77, 353-361 (1961) link

QENSmodels.delta module

QENSmodels.delta.delta(x: float | list | ndarray, scale: float | list | ndarray = 1, center: float | list | ndarray = 0) → float | list | ndarray

Dirac Delta function

It is equal to zero except for the value of x closest to center.

Parameters:

• x (list or ndarray) – domain of the function

• scale (float) – integrated intensity of the curve. Default to 1.

• center (float) – position of the peak. Default to 0.

Returns:

output array containing an impulse signal

Return type:

ndarray

Examples

>>> delta([0, 1, 2], 1, 0)
array([1., 0., 0.])

>>> delta([0, 1, 2, 3, 4], 5, 2)
array([0., 0., 5., 0., 0.])

Notes

• A Delta (Dirac) function is defined as

\[\text{Delta}(x, \text{scale}, \text{center}) = \text{scale}\ \delta(x - \text{center})\]

• For non-zero values, the amplitude of the Delta function is divided by the x-spacing.

• Equivalence between different implementations

  QENSmodels	Mantid
  delta	DeltaFunction
  scale	Height
  center	Centre

QENSmodels.delta_lorentz module

QENSmodels.delta_lorentz.sqwDeltaLorentz(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, A0: float | list | ndarray = 0.0, hwhm: float | list | ndarray = 1.0) → float | list | ndarray

Model corresponding to a delta representing a fraction p of fixed atoms and a Lorentzian corresponding to a Brownian Translational diffusion model for the remaining (1 - p) atoms.

Model = A0*delta + (1-A0)*Lorentz(Gamma)

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – peak center. Default to 0.

• A0 (float, list or ndarray of the same size as q) – proportion of immobile atoms, must be between 0 and 1. Default to 0.

• hwhm (float, list or ndarray of the same size as q) – half width half maximum. Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwDeltaLorentz([1, 2, 3], 0.1)
>>> round(sqw[0], 1)
0.2
>>> round(sqw[1], 3)
0.064
>>> round(sqw[2], 3)
0.032

Notes

The sqwDeltaLorentz is expressed as

\[\begin{split}S(q, \omega) &= A_0 \delta(\omega, \text{scale}, \text{center}) \\ &+ (1 - A_0) \text{Lorentzian}(\omega, \text{scale}, \text{center}, \text{hwhm})\end{split}\]

QENSmodels.delta_two_lorentz module

QENSmodels.delta_two_lorentz.sqwDeltaTwoLorentz(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1, center: float = 0, A0: float | list | ndarray = 1, A1: float | list | ndarray = 1, hwhm1: float | list | ndarray = 1, hwhm2: float | list | ndarray = 1) → float | list | ndarray

Model corresponding to a delta representing a fraction p of fixed atoms and two Lorentzians corresponding to Brownian Translational diffusion model at different time scales for the remaining atoms.

Model = A0*delta + A1*Lorentzian1 + (1-A0-A1)*Lorentzian2

Parameters:

• w (float) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – peak center. Default to 0.

• A0 (float, list or ndarray of the same size as q) – amplitude of the delta function. Default to 1.

• A1 (float, list or ndarray of the same size as q) – amplitude of the first Lorentzian. Default to 1.

• hwhm1 (float, list or ndarray of the same size as q) – half-width half maximum of the first Lorentzian. Default to 1.

• hwhm2 (float, list or ndarray of the same size as q) – half-width half maximum of the second Lorentzian. Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwDeltaTwoLorentz([1, 2, 3], [0.1, 0.2], 1, 1, [1, 1], [1, 1], [0.01, 0.01], [0.01, 0.01])  # noqa: E501
>>> round(sqw[0, 0])
1
>>> sqw[0, 1]
0.0
>>> sqw[0, 2]
0.0
>>> round(sqw[1, 0])
1
>>> sqw[1, 1]
0.0
>>> sqw[1, 2]
0.0

>>> sqw = sqwDeltaTwoLorentz([1, 2, 3], [0.05, 0.3], 0.5, 2, [0.75, 0.5], [1, 2], [0.05, 0.04], [0.02, 0.03])  # noqa: E501
>>> round(sqw[0, 0], 3)
0.001
>>> round(sqw[0, 1], 3)
0.499
>>> round(sqw[0, 2], 3)
0.001
>>> round(sqw[1, 0], 3)
0.001
>>> round(sqw[1, 1], 3)
0.499
>>> round(sqw[1, 2], 3)
0.001

Notes

\[\begin{split}S(q, \omega) &= A_0 \text{delta}(\omega - \text{center}) \\ &+ A_1 \text{Lorentzian}(\omega, \text{scale}, \text{center}, \text{hwhm}_1) \\ &+ (1 - A_0 - A_1) \text{Lorentzian}(\omega, \text{scale}, \text{center}, \text{hwhm}_2)\end{split}\]

QENSmodels.equivalent_sites_circle module

QENSmodels.equivalent_sites_circle.hwhmEquivalentSitesCircle(q: float | list | ndarray, Nsites: int = 3, radius: float = 1.0, resTime: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of EquivalentSitesCircle as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• Nsites (integer) – number of sites in circle (non-fitting). Default to 3.

• radius (float) – radius of the circle (in Angstrom). Default to 1.

• resTime (float) – residence time (in ps). Default to 1.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmEquivalentSitesCircle([1., 2.], 6, 0.5, 1.5)
>>> round(hwhm[0, 1], 3)
0.333
>>> round(hwhm[0, 3], 3)
1.333
>>> round(eisf[0], 3)
0.92
>>> round(eisf[1], 3)
0.713
>>> round(qisf[0, 1], 6)
0.000503
>>> round(qisf[1, 4],6)
0.13616

QENSmodels.equivalent_sites_circle.sqwEquivalentSitesCircle(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, Nsites: int = 3, radius: float = 1.0, resTime: float = 1.0) → float | list | ndarray

Model Jumps between Nsites equivalent sites on a circle with a radius equal to `radius ` = A_0 delta + Sum of Lorentzians …

It models a circular random walk among these Nsites sites.

Parameters:

• w (list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• Nsites (integer) – number of sites in circle (non-fitting). Default to 3.

• radius (float) – radius of rotation (in Angstrom). Default to 1.

• resTime (float) – residence time in a site before jumping to another site (in ps). Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwEquivalentSitesCircle(1, 1, 1, 0, 4, 1, 1)
>>> round(sqw[0], 3)
0.045

>>> sqw = sqwEquivalentSitesCircle([1, 2, 3], [0.3, 0.4], 1, 0, 5, 1, 1)
>>> round(sqw[0, 0], 3)
0.004
>>> round(sqw[0, 1], 3)
0.001
>>> round(sqw[0, 2], 3)
0.001
>>> round(sqw[1, 0], 3)
0.008
>>> round(sqw[1, 1], 3)
0.003
>>> round(sqw[1, 2], 3)
0.001

Notes

• The sqwEquivalentSitesCircle is expressed as

  \[S(q, \omega) = \text{delta}(\omega, A_0(q), \text{center} ) + \sum_{i=1}^{N-1} \text{Lorentzian}(\omega, A_i(q)\text{scale}, \text{center}, \Gamma_i)\]

  where

  \[ \begin{align}\begin{aligned}A_i(q) = \frac{1}{N}\sum_{j=1}^N j_0(qr_j)\cos(2ij\pi/N)\\r_j = 2R \sin(j\pi/N)\\\Gamma_i = \frac{2}{\text{resTime}}\sin^2(i\pi/N)\end{aligned}\end{align} \]

• The number of sites N is converted to an integer by the function. It should not be used as a fitting parameter.

References

• R. Hempelmann, Quasielastic Neutron Scattering and Solid State Diffusion (Oxford, 2000).

• J. D. Barnes, Journal of Chemical Physics 58, 5193-5201 (1973). link

QENSmodels.gaussian module

QENSmodels.gaussian.gaussian(x: float | list | ndarray, scale: float = 1.0, center: float = 0.0, sigma: float = 1.0) → float | list | ndarray

Gaussian model

Parameters:

• x (float or list or ndarray) – domain of the function

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• sigma (float) – width parameter. Default to 1.

Returns:

output number or array

Return type:

float or ndarray

Examples

>>> round(gaussian(1, 1, 1, 1), 3)
2.507

>>> round(gaussian(3, 2, 2, 5), 3)
24.57

>>> result = gaussian([1, 3], 1, 1, 1)
>>> round(result[0], 3)
0.881
>>> round(result[1], 3)
0.119

Notes

• A Gaussian function is defined as:

\[\text{Gaussian}(x, \text{scale}, \text{center}, \sigma) = \frac{\text{scale}}{\sqrt{2\pi}\sigma}\exp \big(-\frac{(x-\text{center})^2}{2\sigma^2}\big)\]

• The Full Width Half Maximum of a Gaussian equals \(2\sqrt{2\ln 2}\sigma\)

• Equivalence between different implementations

  Gaussian corresponds to the following implementations in Mantid

  QENSmodels	Mantid
  Gaussian	Gaussian
  scale	Height=scale/sigma/\(\sqrt{2\pi}\)
  center	PeakCentre
  sigma	Sigma

• Numerical issues: The definition of the Lorentzian function used here is such that the integral between \(-\infty\) and \(-\infty\) is 1. However, when the hwhm is comparable or smaller than the x step, the sampling of the function will result in a numerical integral > 1. E.g., in the extreme case where hwhm tends to zero, the numerical sampling at x points will result in a delta-like function, but with a value at maximum approaching \(-\infty\) instead of the value 1/\(\Delta x\) used in the definition of the delta function. Therefore, the value of the integral of the function is checked and used to renormalize the returned function whenever the integral is larger than 1.

QENSmodels.gaussian_model_3d module

QENSmodels.gaussian_model_3d.hwhmGaussianModel3D(q: float | list | ndarray, D: float = 1.0, variance_ux: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of GaussianModel3D as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• D (float) – diffusion coefficient (in Angstrom**2/ps). Default to 1.

• variance_ux (float) – variance <u_x**2> of Gaussian random variable u_x (in Angstrom**2), displacement from the origin. Default to 1.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmGaussianModel3D([1., 2.], 0.5, 1.5)
>>> round(hwhm[0,10], 3), round(hwhm[1, 10], 3)
(3.333, 3.333)
>>> round(hwhm[0,99], 3), round(hwhm[1, 99], 3)
(33.0, 33.0)
>>> round(eisf[0], 3)
0.223
>>> round(eisf[1], 3)
0.002
>>> round(qisf[0, 1], 4)
0.3347
>>> round(qisf[1, 1], 4)
0.0149

QENSmodels.gaussian_model_3d.sqwGaussianModel3D(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1, center: float = 0, D: float = 1.0, variance_ux: float = 1.0) → float | list | ndarray

Model based on Gaussian statistics

It describes localized diffusive translational motion in 1, 2 or 3D

Considering a particle moving along the direction x about a fixed point taken as the origin and u_x being the displacement from the origin, the model assumes that u_x is a Gaussian random variable with variance <u_x^2>, which quantifies the size of the region of confinement.

For the 3D case, the model assumes also <u_x^2> = <u_y^2> = <u_z^2>.

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) –

  momentum transfer (non-fitting, in 1/Angstrom).

  scale: float

  scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• D (float) – diffusion coefficient (in Angstrom**2/ps). Default to 1.

• variance_ux (float) – variance \(<u_x^2>\) of Gaussian random variable u_x (in Angstrom^2), displacement from the origin. Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwGaussianModel3D([1, 2, 3], 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.089
>>> round(sqw[1], 3)
0.044
>>> round(sqw[2], 3)
0.025

>>> sqw = sqwGaussianModel3D(1, 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.089

Notes

• The sqwGaussianModel3D is expressed as

  \[ S(q, \omega) = \text{delta}(\omega, A_0(q), \text{center} ) + \sum_{i=1}^{N-1} A_i(Q) \text{Lorentzian}(\omega, A_i(Q)\Gamma_i, \text{center}, \Gamma_i)\]

  where

  \[\begin{split}A_i(Q) &= \exp(-q^2<u_x^2>) \frac{(q^2<u_x^2>)^i}{i!} \\ \Gamma_i &= \frac{i D}{<u_x^2>}\end{split}\]

• The number of terms in the infinite sum is limited to 100. According to Volino’s paper, as a rule of thumb, the number of terms to be considered in practical calculations must be (much) larger than \(Q^2<u_x^2>\). Therefore this condition should be checked when using this model.

References

F. Volino, J.-C. Perrin, and S. Lyonnard, J. Phys. Chem. B 110, 11217-11223 (2006) link

QENSmodels.isotropic_rotational_diffusion module

QENSmodels.isotropic_rotational_diffusion.hwhmIsotropicRotationalDiffusion(q: float | list | ndarray, radius: float = 1.0, DR: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of IsotropicRotationalDiffusion as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• radius (float) – radius of rotation (in Angstrom). Default to 1.

• DR (float) – rotational diffusion coefficient (in 1/ps). Default to 1.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmIsotropicRotationalDiffusion(1., 1., 1.)
>>> hwhm[0, 0]
0.0
>>> hwhm[0, 1]
2.0
>>> hwhm[0, 2]
6.0
>>> hwhm[0, 3]
12.0
>>> hwhm[0, 4]
20.0
>>> hwhm[0, 5]
30.0
>>> round(eisf[0], 3)
0.708
>>> qisf[0, 0]
0.0
>>> round(qisf[0, 1], 3)
0.272
>>> round(qisf[0, 2], 3)
0.019
>>> round(qisf[0, 3], 3)
0.001
>>> round(qisf[0, 4], 3)
0.0
>>> round(qisf[0, 5], 3)
0.0

QENSmodels.isotropic_rotational_diffusion.sqwIsotropicRotationalDiffusion(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, radius: float = 1.0, DR: float = 1.0) → float | list | ndarray

Model Isotropic rotational diffusion = A_0 delta + Sum of Lorentzians …

Continuous rotational diffusion on the surface of a sphere of radius radius

In this model, the reorientation of the molecule is due to small-angle random rotations.

Parameters:

• w (list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• radius (float) – radius of rotation (in Angstrom). Default to 1.

• DR (float) – rotational diffusion coefficient (in 1/ps). Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwIsotropicRotationalDiffusion([1,2,3], 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.036
>>> round(sqw[1], 3)
0.023
>>> round(sqw[2], 3)
0.014

>>> sqw = sqwIsotropicRotationalDiffusion([-0.1, 0., 0.1], [0.3, 0.4], 1, 0, 1, 0.5)  # noqa: E501
>>> round(sqw[0, 0], 3)
0.009
>>> round(sqw[0, 1], 3)
9.713
>>> round(sqw[0, 2], 3)
0.009
>>> round(sqw[1, 0], 3)
0.016
>>> round(sqw[1, 1], 3)
9.494
>>> round(sqw[1, 2], 3)
0.016

Notes

• There are 6 terms in the sum (see the mathematical expression below)

• The sqwIsotropicRotationalDiffusion is expressed as

\[\begin{split}S(q, \omega) &= j_0^2(q\ \text{radius})\delta(\omega, \text{scale}, \text{center})\\ &+ \sum_{i=1} ^6 (2i + 1) j_i^2(q\ \text{radius}) \text{Lorentzian}(\omega, \text{scale}, \text{center}, i(i+1)\text{DR})\end{split}\]

where \(j_i, i=1..6\) are spherical Bessel functions of order i.

References

P. A. Egelstaff, J. Chem. Phys. 53, 2590-2598 (1970) link

QENSmodels.jump_sites_log_norm_dist module

QENSmodels.jump_sites_log_norm_dist.hwhmJumpSitesLogNormDist(q: float | list | ndarray, Nsites: float = 3, radius: float = 1.0, resTime: float = 1.0, sigma: float = 1.0) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of JumpSitesLogNormDist as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• Nsites (integer) – number of sites in circle (non-fitting). Default to 3.

• radius (float) – radius of the circle (in Angstrom). Default to 1.

• resTime (float) – residence time (in ps). Default to 1.

• sigma (float) – standard deviation of the Gaussian distribution (no unit). Default to 1.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmJumpSitesLogNormDist([1., 2.], 4, 0.5, 1.5, 1.0)
>>> round(hwhm[1, 3, 20], 3), round(hwhm[1, 1, 5], 3)
(5.7, 0.228)
>>> round(eisf[0], 3)
0.92
>>> round(eisf[1], 3)
0.713
>>> round(qisf[0, 2, 19], 6), round(qisf[1, 1, 5], 6)
(0.000538, 0.000712)

Notes

QENSmodels.jump_sites_log_norm_dist.sqwJumpSitesLogNormDist(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, Nsites: int = 3, radius: float = 1.0, resTime: float = 1.0, sigma: float = 1.0) → float | list | ndarray

Model of jumps between Nsites equivalent sites in a circle with a log-norm distribution of relaxation times

For each jumping distance, instead of a single \(\Gamma_i\) value, a distribution of HWHMs is used. The distribution is represented by L values of the HWHM (\(\Gamma_{i,j}\)) with associated weights \(g_j\) taken from a log-Gaussian distribution of standard distribution \(\sigma\) and normalized such that \(\sum_{j=1}^L g_j=1\). The \(\Gamma_{i,j}\) are chosen equally spaced in logarithmic scale in the range [\(\exp(-\sigma\sqrt{-2\ln A_{min}})\), \(\exp(\sigma\sqrt{-2\ln A_{min}})\)] where \(A_{min}\) is the cut-off chosen for the value of the distribution function with respect to its maximum. This model uses \(L=21\) and \(A_{min}=0.1\)

Parameters:

• w (list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• Nsites (integer) – number of sites in circle (non-fitting). Default to 3.

• radius (float) – radius of rotation (in Angstrom). Default to 1.

• resTime (float) – residence time in a site before jumping to another site (in 1/ps). Default to 1.

• sigma (float) – standard deviation of the Gaussian distribution (no unit). Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwJumpSitesLogNormDist([1, 2, 3], [0.3, 0.4], 1, 0, 5, 1, 1, 1)
>>> round(sqw[0, 0], 4)
0.0035
>>> round(sqw[0, 1], 4)
0.0014
>>> round(sqw[0, 2], 4)
0.0008
>>> round(sqw[1, 0], 4)
0.0061
>>> round(sqw[1, 1], 4)
0.0025
>>> round(sqw[1, 2], 4)
0.0014

>>> sqw = sqwJumpSitesLogNormDist(1, 1, 1, 0, 4, 1, 1, 1)
>>> round(sqw[0], 4)
0.0344

Notes

• The sqwJumpSitesLogNorm is expressed as

  \[S(q, \omega) = \text{delta}(\omega, A_0(q), \text{center} ) + \sum_{i=1}^{N-1} A_i(q) \Big(\sum_{j=1}^L g_j \frac{1}{\pi} \frac{\Gamma_{i,j}}{(\omega-\text{center})^2+\Gamma_{i,j}^2} \Big)\]

  where

  \[\begin{split}A_i(Q) &= \frac{1}{N}\sum_{j=1}^N j_0(qr_j)\cos(2ij\pi/N) \\ r_j &= 2R \sin(j\pi/N) \\ \Gamma_i &= \frac{2}{\tau}\sin^2(i\pi/N) \\ g_j &= \frac{1}{\sigma \sqrt{2\pi}} \exp \Big(-\frac{1}{\sigma^2}\ln^2(\Gamma_{i,j}/\Gamma_i) \Big)\end{split}\]

• The number of sites (N in the previous two formula) is converted to an integer by the function. It should not be used as a fitting parameter.

References

A. Chahid, A. Alegria, and J. Colmenero, Macromolecules 27, 3282-3288 (1994) link

QENSmodels.jump_translational_diffusion module

QENSmodels.jump_translational_diffusion.hwhmJumpTranslationalDiffusion(q: float | list | ndarray, D: float = 0.23, resTime: float = 1.25) → Tuple[ndarray, ndarray, ndarray]

Returns some characteristics of JumpTranslationalDiffusion as functions of the momentum transfer q: the half-width half-maximum (hwhm), the elastic incoherent structure factor (eisf), and the quasi-elastic incoherent structure factor (qisf)

Parameters:

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• D (float) – diffusion coefficient (in Angstrom^2/ps). Default to 0.23.

• resTime (float) – residence time (in ps). Default to 1.25.

Returns:

• hwhm (ndarray) – half-width half maximum

• eisf (ndarray) – elastic incoherent structure factor

• qisf (ndarray) – quasi-elastic incoherent structure factor

Examples

>>> hwhm, eisf, qisf = hwhmJumpTranslationalDiffusion([1., 2.], 0.5, 1.5)
>>> round(hwhm[0], 3), round(hwhm[1], 3)
(0.286, 0.5)
>>> eisf
array([0., 0.])
>>> qisf
array([1., 1.])

Notes

The default values for the fitting parameters come from the values for water at 298K and 1 atm, water has D=0.23 Angstrom^2/ps and ResTime=1.25 ps.

QENSmodels.jump_translational_diffusion.sqwJumpTranslationalDiffusion(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1.0, center: float = 0.0, D: float = 0.23, resTime: float = 1.25) → float | list | ndarray

Lorentzian model with half width half maximum equal to \(\frac{Dq^2}{1+ \text{resTime}Dq^2}\)

It models a particle which performs jumps, randomly, between sites where it spends an average time resTime. resTime is very long compared to the duration of the jump.

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom).

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• D (float) – diffusion coefficient (in Angstrom \(^2\) /ps). Default to 0.23.

• resTime (float) – residence time (in ps). Default to 1.25.

Returns:

output array

Return type:

ndarray

Examples

>>> sqw = sqwJumpTranslationalDiffusion([1, 2, 3], 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.127
>>> round(sqw[1], 3)
0.037
>>> round(sqw[2], 3)
0.017

>>> sqw = sqwJumpTranslationalDiffusion(1, 1, 1, 0, 1, 1)
>>> round(sqw[0], 3)
0.127

Notes

• The sqwJumpTranslationalDiffusion is expressed as

  \[S(q, \omega) = \text{Lorentzian}(\omega, \text{scale}, \text{center}, \frac{D q^2}{ 1 + \text{resTime}\ D q^2})\]

• The default values for the fitting parameters come from the values for water at 298K and 1 atm, water has D = 0.23 Angstrom^2/ps and resTime = 1.25 ps.

• If resTime is equal to 0, this model reduces to sqwBrownianTranslationalDiffusion.

• At small q, hwhm is similar to the hwhmBrownianTranslationalDiffusion, i.e. equivalent to \(Dq^2\). And at large q, hwhm \(\propto\) 1/resTime.

References

J. Teixeira, M.-C. Bellissent-Funel, S.H. Chen, and A.J, Dianoux, Phys. Rev. A 31, 1913-1917 (1985) link

QENSmodels.lorentzian module

QENSmodels.lorentzian.lorentzian(x: float | list | ndarray, scale: float | list | ndarray = 1.0, center: float | list | ndarray = 0.0, hwhm: float | list | ndarray = 1.0) → float | list | ndarray

Lorentzian model

Parameters:

• x (float or list or ndarray) – domain of the function

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• hwhm (float) – Half Width at Half Maximum. Default to 1.

Returns:

output number or array

Return type:

float or ndarray

Examples

>>> round(lorentzian(1, 1, 1, 1), 3)
0.318

>>> round(lorentzian(3., 2., 2., 5.), 3)
0.122

>>> result = lorentzian([1, 3.], 1., 1., 1.)
>>> round(result[0], 3)
0.318
>>> round(result[1], 3)
0.064

Notes

• A Lorentzian function is defined as

\[\text{Lorentzian}(x, \text{scale}, \text{center}, \text{hwhm}) = \frac{\text{scale}}{\pi} \frac{\text{hwhm}} {(x-\text{center})^2+\text{hwhm}^2}\]

• Note that the maximum of a Lorentzian is \(\text{Lorentzian}(\text{center}, \text{scale}, \text{center}, \text{hwhm})=\frac{\text{scale}}{\pi \text{hwhm}}\).

• Equivalence between different implementations Lorentzian corresponds to the following implementations in Mantid and DAVE

  QENSmodels	Mantid	DAVE
  Lorentzian	Lorentzian	Lorentzian
  scale	Amplitude	A
  center	PeakCentre	\(x_0\)
  hwhm	FWHM /2	W/2

• Numerical issues: The definition of the Lorentzian function used here is such that the integral between \(-\infty\) and \(-\infty\) is 1. However, when the hwhm is comparable or smaller than the x step, the sampling of the function will result in a numerical integral > 1. E.g., in the extreme case where hwhm tends to zero, the numerical sampling at x points will result in a delta-like function, but with a value at maximum approaching \(-\infty\) instead of the value 1/\(\Delta x\) used in the definition of the delta function. Therefore, the value of the integral of the function is checked and used to renormalize the returned function whenever the integral is larger than 1.

QENSmodels.water_teixeira module

QENSmodels.water_teixeira.sqwWaterTeixeira(w: float | list | ndarray, q: float | list | ndarray, scale: float = 1, center: float = 0, D: float = 0.23, resTime: float = 1.25, radius: float = 1, DR: float = 1) → float | list | ndarray

Model corresponding to the convolution of Jump Translational diffusion (model T) and Isotropic rotational diffusion (model R)

Model = convolution(T, R), where

T = Jump Translational diffusion = Lorentz(Gamma_T)

R = Isotropic rotational diffusion = A0 + A1*L1 + A2*L2 + …

This results in

Model = A0*Lorentz(Gamma_T) + A1*Lorentz(Gamma_T+Gamma_1) + A2*Lorentz(Gamma_T+Gamma_2) + …

Parameters:

• w (float, list or ndarray) – energy transfer (in 1/ps)

• q (float, list or ndarray) – momentum transfer (non-fitting, in 1/Angstrom)

• scale (float) – scale factor. Default to 1.

• center (float) – center of peak. Default to 0.

• D (float) – Diffusion coefficient (in Angstrom^2/ps). Default to 1.

• resTime (float) – Residence time (in ps). Default to 1.

• radius (float) – radius of rotation (in Angstrom). Default to 1.

• DR (float) – rotational diffusion coefficient (in 1/ps). Default to 1.

Returns:

output array

Return type:

ndarray

Examples

>>> result = sqwWaterTeixeira(1, 1, 1, 1, 1, 1, 1, 1)
>>> round(result[0], 3)
0.486

Notes

The default values for the fitting parameters come from the values for water at 298K and 1 atm, water has D=0.23 Angstrom^2/ps and ResTime=1.25 ps.

References

J. Teixeira, M.-C. Bellissent-Funel, S.H. Chen, and A.J, Dianoux, Phys. Rev. A 31, 1913-1917 (1985) link

Module contents

QENS models library

Python scripts to define fitting models ( i.e., mathematical functions) that can be used to fit Quasi Elastic Neutron Scattering (QENS) data S(Q, omega).