MDANSE_GUI

MDANSE_GUI Python Module

This is the module containing the Graphical User Interface (GUI) of the Molecular Dynamics Analysis for Neutron Scattering Experiments (MDANSE) software package.

The GUI depends on the MDANSE package.

Quick start: installation

We recommend that you install MDANSE in a Python virtual environment. You can create a virtual environment named mdanse_env by typing

python3 -m venv mdanse_env

To activate your virtual environment, type

source mdanse_env/bin/activate

in a bash console, or

mdanse_env\Scripts\activate.bat

if you are using cmd.exe on Windows.

While your virtual environment is active, you can install MDANSE:

pip install MDANSE_GUI

and start the GUI by typing

mdanse_gui

If you are using a virtual environment in which you had installed MDANSE in the past, you can upgrade MDANSE to the current version by typing:

pip install --upgrade MDANSE

If you experience problems with the installation, you may want to upgrade pip

pip install --upgrade pip

and try again.

Please remember to activate your virtual environment when you start a new shell before you run mdanse_gui.

Additional installation options

MDANSE_GUI has optional dependencies, which are not installed unless they are requested by the user. It is possible to install all the optional dependencies by running

pip install mdanse_gui[all]

The alternative is to install specific dependencies individually. This is described in the subsections below.

pymixbox

An optional dependency, pymixbox can be installed to enable an alternative mechanism of colour mixing. It will be used in the MDANSE_GUI plotter when plotting a 2D data set as a series of 1D curves. The colours of consecutive curves will be generated from the initial and final colour values using pymixbox. (If pymixbox is not installed, the colours of intermediate curves will be generated by linear interpolation.)

To install MDANSE_GUI with pymixbox, replace the normal installation command with

pip install mdanse_gui[pymixbox]

pyshortcuts

Users who want to create a desktop shortcut and a start menu entry for MDANSE_GUI can install MDANSE_GUI with pyshortcuts. It can be done by replacing the normal installation command with

pip install mdanse_gui[shortcuts]

Once MDANSE_GUI and its dependencies have been installed, run the script

create_mdanse_link

to create a desktop icon and a start menu entry for MDANSE_GUI (or just one of the two, depending on the operating system you are running.)

Quick start: workflow

The typical workflow of MDANSE:

1. Convert a trajectory from the file format generated by an MD simulation software into the MDANSE trajectory format,
2. Load the converted trajectory into MDANSE,
3. Perform an analysis,
4. Check the results with the plotter.

Each one of these operations has its own dedicated tab in the GUI. The plotter consists of two tabs, one for selecting the data for plotting, and the other for viewing and customising the plot.

The most complete user documentation of MDANSE can be found on our Read the Docs page.

Other information, including tutorials, can be found in the MDANSE-Examples repository.

Citing MDANSE

If you used MDANSE in your research, please cite it according to the CITATION.cff file in the MDANSE GitHub repository. On GitHub, you can use the "cite this repository" link to generate the citation.

License

MDANSE_GUI is licensed under GPL-3.0. See LICENSE for more information.

Acknowledgements

The VTK-based 3D viewer was taken and adapted from another software project authored by Eric Pellegrini. We would like to thank Eric for making his code available.

Joining the project

MDANSE_GUI is currently maintained and developed by software developers from ISIS and ILL, but we are fully open to new collaborators who would like to contribute code, documentation, tutorials or usage examples. If you want to join the project contact:

Dr. Sanghamitra Mukhopadhyay (sanghamitra.mukhopadhyay@stfc.ac.uk)
ISIS Neutron and Muon Source
Rutherford Appleton Laboratory
Didcot, UK

Software Inquiries

You are welcome to use the issue tracker to submit ideas for extending the MDANSE code or to report problems you encountered. However, if you prefer to contact the MDANSE developers directly, you can send us a message:

MDANSE Help (MDANSE-help@stfc.ac.uk)