Physical Models

All models live in the qens.models subpackage and are importable directly from the top-level qens namespace.

Three Built-in Forward Models

Pass these names to find_map() and run_mcmc().

Name	Parameters	Parameter names	When to use
translation_only	2	D*, ⟨u²⟩	Atoms, monatomic ions — no rotation present.
isotropic_rotor	3	D*, ⟨u²⟩, Dr	Rotation present but no anisotropy expected (spherical molecules).
anisotropic_rotor	4	D*, ⟨u²⟩, Dt, Ds	Oblate axial rotors — e.g. benzene, toluene, naphthalene.

Translational HWHM Functions

These return the quasi-elastic linewidth Γ(Q) in meV and are used directly for the classical HWHM workflow.

qens.models.fickian_hwhm(q, d)

Fickian (continuum) diffusion: Γ = ℏ D Q².

Parameters:

• q (array) – Momentum transfer in Å⁻¹.

• d (float) – Self-diffusion coefficient in Ų/ps.

Return type:

ndarray

Returns:

Γ in meV.

qens.models.ce_hwhm(q, d, ell)

Chudley-Elliott jump-diffusion HWHM in meV.

Parameters:

• q (array)

• d (float) – Self-diffusion coefficient in Ų/ps.

• ell (float) – Mean jump length in Å.

Return type:

ndarray

Returns:

Γ in meV.

qens.models.ss_hwhm(q, d, tau_s)

Singwi-Sjölander HWHM: Γ = ℏ D Q² / (1 + D Q² τ_s).

Parameters:

• q (array)

• d (float) – Self-diffusion coefficient in Ų/ps.

• tau_s (float) – Residence time in ps.

Return type:

ndarray

Returns:

Γ in meV.

Rotational Structure Factor

The full incoherent scattering function (Sears/Bée formalism):

\[S_\text{inc}(Q,\omega) = e^{-Q^2\langle u^2\rangle/3} \left[j_0^2(QR)\,L_T(\omega) + \sum_{l=1}^{2}(2l+1)\,j_l^2(QR)\,\bigl(L_T \ast L_R^{(l)}\bigr)(\omega) \right] + b(Q)\]

where \(L_T\) is a Lorentzian of width \(\hbar D^* Q^2\), \(L_R^{(l)}\) are rotational Lorentzians, and \(j_l(QR)\) are spherical Bessel functions evaluated at molecular radius R (default 2.48 Å for benzene).

qens.models.bessel_weights(q, R=2.48)

Spherical-Bessel weights “(j₀², j₁², j₂²)” at this Q.

These weight the l = 0, 1, 2 channels of the rotational structure factor. “j₀²(QR)” is the elastic-rotational weight (the EISF in the rotation-only limit). At low Q, j₀² → 1; at high Q it falls off and j₂² dominates.

Parameters:

• q (float) – Momentum transfer in Å⁻¹.

• R (float) – Radius of gyration in Å. Defaults to 2.48 Å (benzene).

Return type:

tuple[float, float, float]

Returns:

(j0², j1², j2²)

qens.models.rot_widths_isotropic(d_r)

HWHMs for the isotropic axial-rotor model.

Returns “(Γ_1, Γ_2)” in meV, the widths of the l = 1 and l = 2 Lorentzian channels:

\[\Gamma_1 = 2 \hbar D_r,\quad \Gamma_2 = 6 \hbar D_r\]

Parameters:

d_r (float) – Rotational diffusion coefficient in ps⁻¹.

Return type:

tuple[float, float]

qens.models.rot_widths_anisotropic(d_t, d_s)

HWHMs for the anisotropic axial-rotor model (oblate top, e.g. benzene).

Returns (Γ_1, Γ_2, Γ_3)” in meV

Parameters:

• d_t (float) – Tumbling rotational diffusion coefficient in ps⁻¹.

• d_s (float) – Spinning rotational diffusion coefficient in ps⁻¹.

Return type:

tuple[float, float, float]

For the anisotropic rotor the widths are:

\[\Gamma_1 = \hbar(D_s + D_t), \quad \Gamma_2 = 6\hbar D_t, \quad \Gamma_3 = \hbar(4D_s + 2D_t)\]

qens.models.predict_sqw(omega, q, *, d_translation, u2, rotation, rotation_model='anisotropic', sigma_res, radius=2.48)

Predict the resolution-convolved S_inc(Q, ω) for one Q-bin.

Parameters:

• omega (array, shape (N,)) – Energy grid in meV. Must be uniformly spaced.

• q (float) – Momentum transfer in Å⁻¹.

• d_translation (float) – Translational self-diffusion coefficient D* in Ų/ps.

• u2 (float) – Mean-square displacement ⟨u²⟩ in Ų (Debye-Waller factor).

• rotation (tuple) – “(D_r,)” for isotropic, “(D_t, D_s)” for anisotropic. Both in ps⁻¹.

• rotation_model (str) – “”isotropic”” or “”anisotropic””.

• sigma_res (float or array) – Resolution: Gaussian sigma in meV (scalar) or measured kernel (1-d array same length as “omega”).

• radius (float) – Radius of gyration in Å. Default 2.48 (benzene).

Return type:

ndarray

Returns:

array, shape (N,) – Predicted shape, unscaled — the inference layer fits an overall amplitude and a flat background per Q-bin via NNLS, so this function only encodes the physics.

Lineshape Primitives

qens.models.lorentz(omega, gamma)

Area normalised Lorentzian, half-width-at-half-maximum gamma.

\[L(\omega; \Gamma) = \frac{1}{\pi} \frac{\Gamma}{\omega^2 + \Gamma^2}\]

Parameters:

• omega (array) – Energy-transfer grid (any unit; HWHM gamma must match).

• gamma (float) – HWHM. Will be clipped to GAMMA_FLOOR if smaller, to avoid producing a δ-function and breaking later FFT-convolutions.

Return type:

ndarray

qens.models.gnorm(omega, sigma)

Area-normalised Gaussian with standard deviation sigma.

\[G(\omega; \sigma) = \frac{1}{\sigma\sqrt{2\pi}} \exp\!\left( -\frac{\omega^2}{2\sigma^2} \right)\]

For FWHM use sigma = FWHM / 2.355.

Return type:

ndarray

Parameters:

• omega (ndarray)

• sigma (float)

qens.models.lorentz_sum(omega, weights, gammas)

Weighted sum of Lorentzians: Σ w_i L(ω; Γ_i).

Vectorised — useful for evaluating multi-channel rotational models on a Q-grid efficiently.

Parameters:

• omega (array, shape (N,))

• weights (array, shape (M,))

• gammas (array, shape (M,))

Return type:

ndarray

Returns:

array, shape (N,)

Model Registry

qens.models.available_models()

Return the list of currently-registered model names.

Return type:

list[str]

qens.models.get_model(name)

Look up a forward model by name.

Raises KeyError if not registered.

Return type:

ForwardModel

Parameters:

name (str)

qens.models.register_model(name, *, param_names, prior_lo, prior_hi, predict, extras=None, overwrite=False)

Add a new forward model to the registry, or replace an existing one.

Parameters:

• name (str) – Identifier used everywhere (in qens.fitting.find_map(), qens.sampling.run_mcmc(), etc.).

• param_names (tuples) – Same length. Defines a uniform prior box.

• prior_lo (tuples) – Same length. Defines a uniform prior box.

• prior_hi (tuples) – Same length. Defines a uniform prior box.

• predict (callable) – predict(omega, q, params, sigma_res, **extras) -> array.

• extras (dict, optional) – Extra kwargs passed to predict (e.g. radius for a rotor).

• overwrite (bool) – Required to overwrite an existing model.

Return type:

ForwardModel

Returns:

The registered ForwardModel instance.

For how to write and register a custom model, see Custom Models.