From 25d3a94e4daec58c6d41950de87503efe14e65f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20S=C3=B8rensen?= <191927387+markbujehein@users.noreply.github.com> Date: Tue, 20 Oct 2026 17:05:55 +0200 Subject: [PATCH 1/2] Add numpydoc References sections to the diffusion models MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cite Vineyard (Brownian), Singwi and Sjölander (jump), Bée, Weinstock and Dianoux, Volino and Hervet (DeltaLorentz), and move the Hassani et al. citation of MittagLefflerDiffusion into References sections, with DOIs. The Brownian and jump tutorial sections cite the same papers. --- docs/docs/tutorials/diffusion_model.ipynb | 14 ++++++++-- .../brownian_translational_diffusion.py | 5 ++++ .../diffusion_model/delta_lorentz.py | 14 ++++++++++ .../jump_translational_diffusion.py | 6 ++++ .../mittag_leffler_diffusion.py | 28 +++++++++++++++---- 5 files changed, 59 insertions(+), 8 deletions(-) diff --git a/docs/docs/tutorials/diffusion_model.ipynb b/docs/docs/tutorials/diffusion_model.ipynb index fa264b753..c10d5f83e 100644 --- a/docs/docs/tutorials/diffusion_model.ipynb +++ b/docs/docs/tutorials/diffusion_model.ipynb @@ -29,7 +29,11 @@ "id": "2", "metadata": {}, "source": [ - "## Brownian Translational Diffusion" + "## Brownian Translational Diffusion\n", + "In Brownian Translational Diffusion the scattering is a Lorentzian whose width grows as $Q^2$, following\n", + "\n", + "> G. H. Vineyard, *Scattering of Slow Neutrons by a Liquid*, Phys. Rev. **110**, 999 (1958),\n", + "> [doi:10.1103/PhysRev.110.999](https://doi.org/10.1103/PhysRev.110.999)." ] }, { @@ -112,7 +116,13 @@ "metadata": {}, "source": [ "## Jump Translational Diffusion\n", - "In Jump Translational Diffusion, the particle waits for a relaxation time $t$ between jumps. At low $Q$ the width follows the Brownian result, $\\Gamma \\approx \\hbar D Q^2$, but at high $Q$ it levels off:\n", + "In Jump Translational Diffusion, the particle waits for a relaxation time $t$ between jumps, as in the model of\n", + "\n", + "> K. S. Singwi and A. Sjölander, *Diffusive Motions in Water and Cold Neutron Scattering*,\n", + "> Phys. Rev. **119**, 863 (1960),\n", + "> [doi:10.1103/PhysRev.119.863](https://doi.org/10.1103/PhysRev.119.863).\n", + "\n", + "At low $Q$ the width follows the Brownian result, $\\Gamma \\approx \\hbar D Q^2$, but at high $Q$ it levels off:\n", "\n", "$$\\Gamma(Q) = \\frac{\\hbar D Q^2}{1 + D t Q^2},$$\n", "\n", diff --git a/src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py b/src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py index c820a37f6..2c1bfe18b 100644 --- a/src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py +++ b/src/easydynamics/sample_model/diffusion_model/brownian_translational_diffusion.py @@ -25,6 +25,11 @@ class BrownianTranslationalDiffusion(DiffusionModelBase): have units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values. + References + ---------- + G. H. Vineyard, *Scattering of Slow Neutrons by a Liquid*, Phys. Rev. **110**, 999 (1958), + [doi:10.1103/PhysRev.110.999](https://doi.org/10.1103/PhysRev.110.999). + Examples -------- **Creating a BrownianTranslationalDiffusion model** diff --git a/src/easydynamics/sample_model/diffusion_model/delta_lorentz.py b/src/easydynamics/sample_model/diffusion_model/delta_lorentz.py index 12048af0c..b9c5f992c 100644 --- a/src/easydynamics/sample_model/diffusion_model/delta_lorentz.py +++ b/src/easydynamics/sample_model/diffusion_model/delta_lorentz.py @@ -35,6 +35,20 @@ class DeltaLorentz(DiffusionModelBase): the same at all $Q$ or be allowed to vary with $Q$. + References + ---------- + 1. M. Bée, *Quasielastic Neutron Scattering: Principles and Applications in Solid State + Chemistry, Biology and Materials Science*, Adam Hilger, Bristol (1988). + 2. R. Weinstock, *Inelastic Scattering of Slow Neutrons*, Phys. Rev. **65**, 1 (1944), + [doi:10.1103/PhysRev.65.1](https://doi.org/10.1103/PhysRev.65.1). + 3. A. J. Dianoux, F. Volino and H. Hervet, *Incoherent scattering law for neutron quasi-elastic + scattering in liquid crystals*, Mol. Phys. **30**, 1181 (1975), + [doi:10.1080/00268977500102721](https://doi.org/10.1080/00268977500102721). + 4. F. Volino and A. J. Dianoux, *Neutron incoherent scattering law for diffusion in a potential + of spherical symmetry: general formalism and application to diffusion inside a sphere*, + Mol. Phys. **41**, 271 (1980), + [doi:10.1080/00268978000102761](https://doi.org/10.1080/00268978000102761). + Examples -------- **Creating a DeltaLorentz model with Q-dependent parameters** diff --git a/src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py b/src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py index 5c29ceb73..ce4bc1bc1 100644 --- a/src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py +++ b/src/easydynamics/sample_model/diffusion_model/jump_translational_diffusion.py @@ -28,6 +28,12 @@ class JumpTranslationalDiffusion(DiffusionModelBase): units of 1/angstrom. Creates ComponentCollections with Lorentzian components for given Q-values. + References + ---------- + K. S. Singwi and A. Sjölander, *Diffusive Motions in Water and Cold Neutron Scattering*, Phys. + Rev. **119**, 863 (1960), + [doi:10.1103/PhysRev.119.863](https://doi.org/10.1103/PhysRev.119.863). + Examples -------- **Creating a JumpTranslationalDiffusion model** diff --git a/src/easydynamics/sample_model/diffusion_model/mittag_leffler_diffusion.py b/src/easydynamics/sample_model/diffusion_model/mittag_leffler_diffusion.py index 1aa730d63..0247c47e2 100644 --- a/src/easydynamics/sample_model/diffusion_model/mittag_leffler_diffusion.py +++ b/src/easydynamics/sample_model/diffusion_model/mittag_leffler_diffusion.py @@ -29,12 +29,7 @@ class MittagLefflerDiffusion(DiffusionModelBase): r""" Multiscale relaxation model of Hassani et al.: Mittag-Leffler internal dynamics damped by - global translational diffusion. - - A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale - relaxation dynamics and diffusion of myelin basic protein in solution studied by quasielastic - neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), - [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). + global translational diffusion (see References). The intermediate scattering function is written as an internal relaxation, described by a Mittag-Leffler function, times a global diffusion factor (their Eqs. 38-39), @@ -65,6 +60,13 @@ class MittagLefflerDiffusion(DiffusionModelBase): Fig. 5); pass ``allow_Q_variation={'A_0': True, 'relaxation_rate': True, 'alpha': True}`` to reproduce that. Q is assumed to be in 1/angstrom and $D$ in m^2/s. + References + ---------- + A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale + relaxation dynamics and diffusion of myelin basic protein in solution studied by quasielastic + neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), + [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). + Examples -------- **Creating a MittagLefflerDiffusion model with the paper's per-Q parameters** @@ -619,6 +621,13 @@ def calculate_relaxation_rate_spectrum(self, rate: np.ndarray, Q: Q_type = None) ------ ValueError If any requested rate is not strictly positive. + + References + ---------- + A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale + relaxation dynamics and diffusion of myelin basic protein in solution studied by + quasielastic neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), + [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). """ rate = np.atleast_1d(np.asarray(rate, dtype=float)) if np.any(rate <= 0): @@ -662,6 +671,13 @@ def calculate_energy_barrier_distribution( ------- np.ndarray Array of shape ``(len(Q), len(barrier_height))`` holding P(h) for each Q. + + References + ---------- + A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale + relaxation dynamics and diffusion of myelin basic protein in solution studied by + quasielastic neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), + [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). """ barrier_height = np.atleast_1d(np.asarray(barrier_height, dtype=float)) From cd087cc38b1cfb8e2099ec9053a8a19e17ad34e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20S=C3=B8rensen?= <191927387+markbujehein@users.noreply.github.com> Date: Tue, 20 Oct 2026 17:05:55 +0200 Subject: [PATCH 2/2] Add numpydoc References sections to the components Cite Cochran and Cowley (DampedHarmonicOscillator), Kohlrausch and Williams and Watts (StretchedExponential), and move the Hassani et al. citation of DiffusionDampedMittagLeffler into a References section. --- .../components/damped_harmonic_oscillator.py | 11 +++++++++++ .../components/diffusion_damped_mittag_leffler.py | 14 ++++++++------ .../components/stretched_exponential.py | 9 +++++++++ 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/src/easydynamics/sample_model/components/damped_harmonic_oscillator.py b/src/easydynamics/sample_model/components/damped_harmonic_oscillator.py index b4dfe9a45..aa3dadb85 100644 --- a/src/easydynamics/sample_model/components/damped_harmonic_oscillator.py +++ b/src/easydynamics/sample_model/components/damped_harmonic_oscillator.py @@ -26,6 +26,17 @@ class DampedHarmonicOscillator(CreateParametersMixin, ModelComponent): width at half max (``width``). area has unit = x_unit * y_unit; center and width have unit = x_unit. + References + ---------- + 1. W. Cochran, *Crystal stability and the theory of ferroelectricity*, Adv. Phys. **9**, 387 + (1960), [doi:10.1080/00018736000101229](https://doi.org/10.1080/00018736000101229). + 2. R. A. Cowley, *The lattice dynamics of an anharmonic crystal*, Adv. Phys. **12**, 421 + (1963), [doi:10.1080/00018736300101333](https://doi.org/10.1080/00018736300101333). + 3. R. A. Cowley, *Anharmonic crystals*, Rep. Prog. Phys. **31**, 123 (1968), + [doi:10.1088/0034-4885/31/1/303](https://doi.org/10.1088/0034-4885/31/1/303). + 4. S. W. Lovesey, *Theory of Neutron Scattering from Condensed Matter*, Clarendon Press, Oxford + (1984). + Examples -------- **Creating a Damped Harmonic Oscillator** diff --git a/src/easydynamics/sample_model/components/diffusion_damped_mittag_leffler.py b/src/easydynamics/sample_model/components/diffusion_damped_mittag_leffler.py index 9e04a60c7..ff6731f3d 100644 --- a/src/easydynamics/sample_model/components/diffusion_damped_mittag_leffler.py +++ b/src/easydynamics/sample_model/components/diffusion_damped_mittag_leffler.py @@ -20,12 +20,7 @@ class DiffusionDampedMittagLeffler(CreateParametersMixin, ModelComponent): Model of the diffusion-damped Mittag-Leffler relaxation spectrum, Eq. (42) of Hassani et al. This is the spectral (energy-domain) form of the multiscale relaxation model used for - intrinsically disordered proteins in - - A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale - relaxation dynamics and diffusion of myelin basic protein in solution studied by quasielastic - neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), - [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). + intrinsically disordered proteins by Hassani et al. (see References). In the time domain the internal dynamics is described by the Mittag-Leffler (ML) relaxation function $\phi_{ML}(t) = E_\alpha(-(|t|/\tau_R)^\alpha)$ (their Eq. 28), damped by global @@ -65,6 +60,13 @@ class DiffusionDampedMittagLeffler(CreateParametersMixin, ModelComponent): positive ``damping`` is enforced, the profile stays regular at $x = 0$, where the undamped ML spectrum would diverge as $|\omega|^{\alpha - 1}$. + References + ---------- + A. N. Hassani, L. Haris, M. Appel, T. Seydel, A. M. Stadler and G. R. Kneller, *Multiscale + relaxation dynamics and diffusion of myelin basic protein in solution studied by quasielastic + neutron scattering*, J. Chem. Phys. **156**, 025102 (2022), + [doi:10.1063/5.0077100](https://doi.org/10.1063/5.0077100). + Examples -------- **Creating a diffusion-damped Mittag-Leffler component** diff --git a/src/easydynamics/sample_model/components/stretched_exponential.py b/src/easydynamics/sample_model/components/stretched_exponential.py index 5caad4429..e5358350b 100644 --- a/src/easydynamics/sample_model/components/stretched_exponential.py +++ b/src/easydynamics/sample_model/components/stretched_exponential.py @@ -471,6 +471,15 @@ class StretchedExponential(CreateParametersMixin, ModelComponent): Note that the x-axis has to be an energy, since the relaxation time is turned into an energy scale through $\hbar$. + References + ---------- + 1. R. Kohlrausch, *Theorie des elektrischen Rückstandes in der Leidener Flasche*, Ann. Phys. + **167**, 179 (1854), + [doi:10.1002/andp.18541670203](https://doi.org/10.1002/andp.18541670203). + 2. G. Williams and D. C. Watts, *Non-symmetrical dielectric relaxation behaviour arising from a + simple empirical decay function*, Trans. Faraday Soc. **66**, 80 (1970), + [doi:10.1039/TF9706600080](https://doi.org/10.1039/TF9706600080). + Examples -------- **Creating a stretched exponential**