Introduction

QENSmodels is a repository containing Python models ( i.e., mathematical functions) that can be used to fit Quasi Elastic Neutron Scattering (QENS) data S(Q, omega).

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 654000.

Getting started

To get a glimpse of what can be done with the library, click on launch binder below. Please note that the notebooks can be slow to load.

Install the QENS models

Currently the QENS models library has not been released on pypi. Please use the alternative method described below to install it.

• If not already installed on your computer, download and install Python (version>=3.8), for example, from https://www.python.org/downloads/. In the following instructions, replace python by the path to the version of python you want to use.

• Create and go to, e.g., QENSmodels directory (optional)

  mkdir QENSmodels && cd QENSmodels

• Create a virtual environment and activate it (optional)

  • on Unix or MacOS

    python -m venv .venv
    source .venv/bin/activate

  • on Windows

    python -m venv .venv
    .\.venv\Scripts\activate

  Note that the prompt of the terminal will change and start with (.venv). You can choose the folder name that contains your virtual environment when you create it by passing a name other than .venv. Once done working with this virtual environment, you can deactivate it by typing deactivate in the terminal. The prompt should go back to its initial version.

• Upgrade pip (optional)

  python -m pip install --upgrade pip

• Install the library

  • method 1: if you want to modify the models at a later stage

    • download or clone the repository at https://github.com/QENSlibrary/QENSmodels

    • In a terminal run

      python -m pip install full_path_to_QENSmodels_folder

      For example, if you are in the main directory of the library with the virtual environment activated, simply type

      python -m pip install .

  • method 2: if you only want to use the version of the models available in the repository

    python -m pip install git+https://github.com/QENSlibrary/QENSmodels.git@main

  See the documentation on pip install for additional information. Run pip show QENSmodels to display details about the installed package.

To test the installation, type the following command in a terminal

python -c "import QENSmodels"

To uninstall the library, type

python -m pip uninstall QENSmodels

Documentation

The documentation is available at https://qensmodels.readthedocs.io .

Note that the Jupyter notebooks are available in the repository in the docs/examples folder. But they require the installation of additional libraries. Please refer to the README file in the same folder for instructions.

Quick example to use the models

import QENSmodels
value = QENSmodels.lorentzian(1, 1, 1, 1)

Physical units

For information about unit conversion, please refer to the jupyter notebook called Convert_units.ipynb in the tools folder.

Needing help / Reporting a bug

Bugs and feature requests are collected at https://github.com/QENSlibrary/QENSmodels/issues.

If you are reporting a bug, please include:

• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

Contributing

If you are interested in contributing to this project, please refer to the CONTRIBUTING document

Referring to the library

If you found this package useful, please don't forget to acknowledge its use in your publications as suggested below and reference this publication

Quasi Elastic Neutron Scattering model library Céline Durniak, Miguel Angel González, Anders Markvardsen, Sanghamitra Mukhopadhyay, Franz Lang, Thomas Holm Rod, EPJ Web Conf. 286 06001 (2023) DOI: 10.1051/epjconf/202328606001

Please also consider letting us know by sending us the reference to your work. This will help us to ensure the long term support and development of the software.

This work benefited from the use of the QENSmodels library, which contains code developed with funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No 654000.

License

Redistribution of the software is permitted under the terms of the BSD 3-Clause license.