MDANSE

Molecular Dynamics Analysis for Neutron Scattering Experiments

MDANSE is a Python package designed for analysing molecular dynamics (MD) trajectories. One of its functions is calculating the expected results of neutron scattering experiments. The results can be directly compared with neutron scattering experiment results, particularly inelastic and quasi-elastic neutron scattering spectroscopies.

MDANSE contains a family of converters which can be used to transform MD trajectory files into HDF5 files (.MDT format). These are then used as input for MDANSE analysis runs. The analysis results can be saved as HDF5 files, or in text format.

The MDANSE_GUI package is provided as well, which makes it easier to create analysis scripts with valid input parameters, and can visualise both the trajectory and the analysis results.

MDANSE project has been published previously in: \ G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", J. Chem. Inf. Model. 2017, 57, 1, 15.

Version information

This is the 2.x branch of MDANSE, which consists of two Python packages, MDANSE (the analysis code) and MDANSE_GUI (the graphical user interface). The final version in the 1.5.x series can still be found in the legacy branch, but is not being actively developed or supported.

The current version of MDANSE is currently approaching the first release, as the first release candidate has been created. The set of features it contains will not change by the time the full release has been made. However, there still may be some problems with the code at this stage that need to be identified and corrected. You can help the developers by reporting problems you experience while using MDANSE. The preferred way of reporting problems is by adding them to the GitHub issue tracker. You can also send a message to MDANSE-help@stfc.ac.uk to get in touch with MDANSE developers.

Quick start: installation

We recommend that you install MDANSE in a Python virtual environment. You can create a virtual environment named mdanseenv by typing ``` python3 -m venv mdanseenv ```

To activate your virtual environment, type source mdanse_env/bin/activate in a bash console, or mdanse_end\Scripts\activate.bat if you are using cmd.exe on Windows.

While your virtual environment is active, you can install MDANSE: pip install MDANSE MDANSE_GUI and start the graphical interface by typing mdanse_gui

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

Installation: development version

Between releases, MDANSE and MDANSEGUI are undergoing frequent changes. If you would like to try out the latest development version, you can install it directly from GitHub using pip: ``` python3 -m pip install "git+https://github.com/ISISNeutronMuon/MDANSE@protos#egg=MDANSE&subdirectory=MDANSE" python3 -m pip install "git+https://github.com/ISISNeutronMuon/MDANSE@protos#egg=MDANSEGUI&subdirectory=MDANSE_GUI" ```

Installation: optional dependencies

If you prefer running MDANSE via scripts in the command line instead of using the GUI, you can install MDANSE with additional dependencies for CLI runs. This can be done using the command pip install MDANSE[cli] At the moment, the only additional package that will be added is tqdm, which will then be used to display progress bars for MDANSE scripts running in the shell.

Quick start: the 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 (MDT),
2. Load the converted trajectory into MDANSE,
3. Perform an analysis,
4. Check the results with the plotter.

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

Other information including example scripts can be found on the MDANSE website while the most recent tutorials are stored in the MDANSE-Examples repository.

What can MDANSE do?

Firstly, MDANSE can read the output of MD simulation software. It does this by providing converters for different file formats into an .MDT file (HDF format), which is then used for all calculations. The following MD packages are supported:

• CASTEP
• CHARMM
• CP2K
• DCD
• DFTB
• DL_POLY
• Forcite
• Gromacs
• LAMMPS
• NAMD
• VASP
• XPLOR
• ASE

The converted trajectory can then be loaded into MDANSE, where it can be visualised via the Molecular Viewer and animated. Then, various properties can be calculated, which can be compared with neutron (or, for some analysis types, with X-ray) experimental data, or used as a prediction of results of a potential experiment. The following properties can be computed:

Each of these analyses can be controlled using a number of parameters. For example, the user can select a subset of trajectory frames or a subset of atoms on which to perform the calculation, or specified atoms can be substituted with different elements/isotopes. Finally, their results can be saved in an MDA file (HDF5 format), or a set of DAT files (text format), and those can then be plotted directly in MDANSE.

More detailed information on how MDANSE works, what it can do, and the science can all be found on our Read the Docs page.

Citing MDANSE

If you used MDANSE in your research, please cite the following paper:

G. Goret, B. Aoun, E. Pellegrini, "MDANSE: An Interactive Analysis Environment for Molecular Dynamics Simulations", J. Chem. Inf. Model. 2017, 57, 1, 15

License

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

Acknowledgements

MDANSE started as a fork of version 3 of the nMOLDYN program. nMOLDYN was originally developed by Gerald Kneller in 1995 and subsequently also by Konrad Hinsen, Tomasz Rog, Krzysztof Murzyn, Slawomir Stachura, and Eric Pellegrini. MDANSE includes most of the code of nMOLDYN3, and also code from the libraries MMTK, ScientificPython and MDTraj.

For more information see:

nMoldyn 3: Using task farming for a parallel spectroscopy-oriented analysis of molecular dynamics simulations. K. Hinsen, E. Pellegrini, S. Stachura, G.R. Kneller J. Comput. Chem. (2012) 33:2043-2048 [https://doi.org/10.1002/jcc.23035][https://doi.org/10.1002/jcc.23035].

We are grateful to all the people who have helped in some way or another to improve nMOLDYN and/or MDANSE along those years. Apart from the main developers mentioned above, we would like to acknowledge explicitly the contributions done in the past by Bachir Aoun, Vania Calandrini, Paolo Calligari, Gael Goret, Remi Perenon and Rastislav Turanyi.

The MDANSE project is supported by ISIS Neutron and Muon Source, Science and Technology Facilities Council, UKRI. In the past, it was supported by Ada Lovelace Centre and the Institut Laue-Langevin (Grenoble, France). Past financial support from the French Agence Nationale de la Recherche (ANR) through contracts No. ANR-2010-COSI-001-01 and ANR-06-CIS6-012-01, and the Horizon 2020 Framework Programme of the European Union under project number 654000 is also acknowledged.

Joining the project

MDANSE 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)