Metadata-Version: 2.4
Name: MDANSE_GUI
Version: 2.0.2
Summary: MDANSE GUI package - the graphical interface for MDANSE
Maintainer-email: Maciej Bartkowiak <maciej.bartkowiak@stfc.ac.uk>, "Chi Y. Cheng" <chi.cheng@stfc.ac.uk>, Jacob Wilkins <jacob.wilkins@stfc.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: homepage, https://pypi.org/project/MDANSE
Project-URL: documentation, https://mdanse.readthedocs.io/
Project-URL: repository, https://github.com/ISISNeutronMuon/MDANSE
Keywords: molecular dynamics,science,simulation,analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MDANSE
Requires-Dist: matplotlib
Requires-Dist: qtpy
Requires-Dist: vtk>=9.4.0
Requires-Dist: PyQt6
Requires-Dist: PyYAML
Requires-Dist: tomlkit
Requires-Dist: setuptools-git-versioning<4,>=3.0
Provides-Extra: pymixbox
Requires-Dist: pymixbox; extra == "pymixbox"
Provides-Extra: shortcuts
Requires-Dist: pyshortcuts>=1.9.11; extra == "shortcuts"
Provides-Extra: all
Requires-Dist: MDANSE_GUI[pymixbox,shortcuts]; extra == "all"
Dynamic: license-file

# 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](https://pypi.org/project/MDANSE).

> [!NOTE]
> The default behaviour of MDANSE_GUI has changed in version 2.0.2
> where the system tray icon has been added to the interface.
> When the system tray icon of the MDANSE GUI is present, closing
> the main window does not close the software, and the main window
> can be shown again. The system tray icon can be disabled in the
> GUI in Settings -> User Settings, in the 'startup' group.

## 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](https://github.com/scrtwpns/mixbox) 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](https://github.com/newville/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](https://mdanse.readthedocs.io).

Other information, including tutorials, can be found in the
[MDANSE-Examples repository](https://github.com/ISISNeutronMuon/MDANSE-Examples).

## Citing MDANSE

If you used MDANSE in your research, please cite it according to the CITATION.cff file
in the [MDANSE GitHub repository](https://github.com/ISISNeutronMuon/MDANSE).
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](https://github.com/ISISNeutronMuon/MDANSE/blob/protos/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](https://github.com/ISISNeutronMuon/MDANSE/issues)
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)
