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, 1–5.
This is the first full release of MDANSE 2.0, consisting of two Python packages, MDANSE (the analysis code) and MDANSE_GUI (the graphical user interface).
Note
Considering the large number of different MD engines and analysis types, it is still possible that some conversion or analysis runs will not produce the expected results. Please report any problems you experience while using MDANSE 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.
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 MDANSE_GUI
If you are using a virtual environment in which you had installed pre-release versions of MDANSE, you can upgrade by typing:
pip install --upgrade MDANSE MDANSE_GUI
Then, 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.
The current default behaviour of the GUI is to create a system tray icon for MDANSE_GUI. The software does not exit when the main window is closed, allowing analysis tasks to continue running in the background. Also, the main window can be restored by double-clicking the system tray icon, or by using the "Show GUI window" option in the context menu.
It is possible to switch back to the old behaviour. One way is to start the GUI with an additional keyword:
mdanse_gui --no-systray
You can also change the settings in the GUI by opening Settings and then the User Settings entry in the GUI menu. The 'startup' group contains the settings controlling the splash screen, system tray icon and the placeholder animation in the 3D view. They all can be disabled by changing the relevant settings. Remember to save the settings after making the changes.
Between releases, MDANSE and MDANSE_GUI 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=MDANSE_GUI&subdirectory=MDANSE_GUI"
Some Python packages are not installed by default, but can be added to enable additional functionality in MDANSE.
The following keywords can be used to install optional dependencies:
- ase (adds ASE, enables the ASE converter and AverageStructure analysis)
- cli (adds tqdm for the command line progress bar)
- finufft (adds FINUFFT, enables StaticStructureFactor3D calculation)
- mdanalysis (adds MDAnalysis, enables the MDAnalysis converter)
- mdtraj (adds MDTraj, enables MDTraj and GROMACS converters)
- pymixbox (adds pymixbox, changes output atom colours in CentreOfMassesTrajectory)
These can be picked individually, as in
pip install mdanse[cli,mdtraj]
It is also possible to install them all using
pip install mdanse[all]
The following keywords can be used to install optional dependencies:
- pymixbox (adds pymixbox, changes colours of curves in the plotter)
- shortcuts (adds pyshortcuts, enables
create_mdanse_linkscript for creating an MDANSE desktop icon and Start Menu entry)
These can be picked individually, as in
pip install mdanse_gui[shortcuts]
It is also possible to install them all using
pip install mdanse_gui[all]
The typical workflow of MDANSE:
- Convert a trajectory from the file format generated by an MD simulation software into the MDANSE trajectory format (MDT),
- Load the converted trajectory into MDANSE,
- Perform an analysis,
- 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 tutorials, can be found in the MDANSE-Examples repository.
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. General-purpose converters are implemented using external libraries:
- ASE,
- MDAnalysis,
- MDTraj,
which means that if your trajectories have worked with any of these libraries, then you can expect them to work with MDANSE too. Additionally, the following converters for specific MD packages are supported:
- CASTEP
- CHARMM
- CP2K
- DCD
- DFTB
- DL_POLY
- Forcite
- Gromacs
- LAMMPS
- NAMD
- VASP
- XPLOR
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:
Dynamics
- Density of States
- Mean Square Displacement
- Position Correlation Function
- Position Power Spectrum
- Reorientational Time Correlation Function
- Root Mean Square Deviation
- Root Mean Square Fluctuation
- van Hove function (self)
- van Hove function (distinct)
- Velocity Correlation Function
Infrared
- Dipole Autocorrelation Function
- Infrared
Scattering
- Current Correlation Function
- Dynamic Coherent Structure Factor
- Dynamic Incoherent Structure Factor
- Elastic Incoherent Structure Factor
- Gaussian Dynamic Incoherent Structure Factor
- Neutron Dynamic Total Structure Factor
- Scattering Length Density Profile
- Static Structure Factor
- Static Structure Factor 3D
- Structure Factor from Scattering Function
- X-Ray Static Structure Factor
Structure
- Area Per Molecule
- Coordination Number
- Eccentricity
- Molecular Trace
- Pair Distribution Function
- Radius of Gyration
- Solvent Accessible Surface
- Voronoi (volume per atom)
Thermodynamics
- Density
- Temperature
Trajectory
- Average Structure
- Center of Masses Trajectory
- Trajectory Editor
- Trajectory Filter
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.
If you used MDANSE in your research, please cite it according to the CITATION.cff file. You can use the "cite this repository" link to generate the citation.
MDANSE is licensed under GPL-3.0. See LICENSE for more information.
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 and ScientificPython.
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.
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 current MDANSE logo is an adapted version of the design contributed by Ashley Meigh in 2024.
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.
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
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)