Repository containing the python based implementations of servers for NanoVer, providing a framework for developing interactive molecular dynamics simulations.
This software is designed to be used with NanoVer VR clients, e.g. NanoVer iMD-VR.
This repository is maintained by the Intangible Realities Laboratory, University of Santiago de Compostela, and is distributed under the MIT license. See the list of contributors for the individual authors of the project. If you would like to contribute to NanoVer, please see our contributing file for guidelines on how to do this.
For more information please take a look at the project's documentation.
- Getting started
- User installation
- Developer installation
- Running the tests
- Running the tutorials
- Troubleshooting
- Citation and external libraries
Here are some quick notes to get you started with NanoVer! If you haven't installed NanoVer yet, please go to User installation or Developer installation.
nanover provides a command line interface for running OpenMM simulations. For example, from the nanover-server-py directory:
nanover-server --omm examples/ase/openmm_files/nanotube.xml
Learn more about running a NanoVer server here in our documentation.
The examples folder contains Jupyter notebooks that demostrate how to get started NanoVer. Please head to the Tutorials page of the project's documentation for more information!
The python-libraries folder contains the library to write NanoVer clients and
servers in python, as well as the services implemented in python. The
python-libraries/prototypes directory contains examples and (sometimes
unmaintained) prototypes using the python libraries.
Check out the Installation & Getting Started page in our documentation for detailed instructions on installing NanoVer.
- Run
conda list nanover-serverto determine the currently installed version - Run
conda update nanover-serverto attempt to update to latest version - If you can't seem to update to the latest version, run
python --versionto check your python version is at least as recent as in the installation instructions. If it isn't you will need to create a new conda environment with a newer version of python.
- Install Anaconda
- Clone the nanover-server-py repository
- In the "Anaconda Powershell Prompt":
- Create a conda environment (here we call the environment "nanover-dev") with the required depencies:
conda create -n nanover-dev -c conda-forge "python>3.12" openmm MDAnalysis MDAnalysisTests ase - Activate the conda environment:
conda activate nanover-dev - Install the NanoVer libraries in your conda environment:
./win_compile.ps1. If you do not plan on modifying the python packages, run./win_compile.ps1 -noeditinstead. Otherwise, by default, the nanover packages will be installed in edit mode (pip install -e) meaning that changes in thenanover-server-pydirectory will be directly reflected in your python environment.
- Create a conda environment (here we call the environment "nanover-dev") with the required depencies:
- Install Anaconda
- Clone the nanover-server-py repository
- In a terminal, in the repository root:
- Create a conda environment (here we call the environment "nanover-dev") with the required depencies:
conda create -n nanover-dev -c conda-forge "python>3.11" openmm MDAnalysis MDAnalysisTests ase - Activate the conda environment:
conda activate nanover-dev - Install the NanoVer python libraries in your conda environment:
./compile.sh. If you do not plan on modifying the python packages, you may run./compile.sh --no-editinstead. Otherwise, by default, the NanoVer packages will be installed in edit mode (pip install -e) meaning that changes in thenanover-server-pydirectory will be directly reflected in your python environment.
- Create a conda environment (here we call the environment "nanover-dev") with the required depencies:
All code changes have to pass a series of automatic tests ("the CI") that attempt to verify code quality and continued functionality of the project. You can run these locally to verify your changes in advance.
The unit tests check code functionality of the python libraries. To run them:
python -m pytest python-libraries
Optionally, you can run most of the tests in parallel with pytest-xdist:
python -m pip install pytest-xdist
python -m pytest python-libraries -n auto -m 'not serial'
python -m pytest python-libraries -n0 -m 'serial'
The formatting and linting tests check code style, and require ruff:
python -m pip install ruff
python -m ruff check python-libraries
python -m ruff format --check python-libraries
ruff can also automatically fix and reformat the files for you:
python -m ruff check --fix python-libraries
python -m ruff format python-libraries
The type checks look at the type hints in the code to make sure they are consistent and help find potential errors:
python -m pip install mypy
mypy --ignore-missing-imports --namespace-packages --check-untyped-defs --allow-redefinition nanover-server
The tutorials folder contains Jupyter notebooks for examples of how to use NanoVer. Learn about these Tutorials or how to run a NanoVer server in this project's documentation.
nanover provides a command line interface for running serialised OpenMM simulations. For example, from the
nanover-server-py directory:
nanover-server --omm examples/ase/openmm_files/nanotube.xml
The examples/ase folder contains several Jupyter notebooks that demonstrate visualisation and interaction
from a notebook.
nanover.mdanalysis provides a server for the trajectory service that infinitely loops over the frames of an example
trajectory. To serve the frames on port 54321, from the nanover-server-py directory, run
python ./examples/mdanalysis/example.py
If you are having trouble autoconnecting to servers, you can run nanover-essd-list to verify which local network servers are visible to your machine.
If you try to use the older .traj/.state recordings, you will find NanoVer complaining that they are not zip files. In this case you can use the recording converter in conjunction with NanoVer to convert them to the new format.
Any work that uses NanoVer should cite the following publications:
Stroud, H. J., Wonnacott, M. D., Barnoud, J., Roebuck Williams, R., Dhouioui, M., McSloy, A., Aisa, L., Toledo, L. E., Bates, P., Mulholland, A. J., & Glowacki, D. R. (2025). NanoVer Server: A Python Package for Serving Real-Time Multi-User Interactive Molecular Dynamics in Virtual Reality. Journal of Open Source Software, 10 (110), 8118. https://doi.org/10.21105/joss.08118
Jamieson-Binnie, A. D., O’Connor, M. B., Barnoud, J., Wonnacott, M. D., Bennie, S. J., & Glowacki, D. R. (2020, August 17). Narupa iMD: A VR-Enabled Multiplayer Framework for Streaming Interactive Molecular Simulations. ACM SIGGRAPH 2020 Immersive Pavilion. SIGGRAPH ’20: Special Interest Group on Computer Graphics and Interactive Techniques Conference. https://doi.org/10.1145/3388536.3407891
O’Connor, M., Bennie, S. J., Deeks, H. M., Jamieson-Binnie, A., Jones, A. J., Shannon, R. J., Walters, R., Mitchell, T., Mulholland, A. J., & Glowacki, D. R. (2019). Interactive molecular dynamics from quantum chemistry to drug binding: an open-source multi-person virtual reality framework, The Journal of Chemical Physics, 150 (22), 224703. https://doi.org/10.1021/acs.jcim.0c01030
This project has been made possible by the following open source projects. We gratefully thank them for their efforts, and suggest that you use and cite them:
- ASE (LGPLv3): Atomic simulation environment used for running simulations (citation).
- OpenMM (MIT, LGPLv3): GPU accelerated molecular mechanics library (citation).
- MDAnalysis (GPLv2): Molecular dynamics analysis library (citations).
- NGLView (MIT): IPython/Jupyter widget to interactively view structures and trajectories (citations).
- python-osc (Public domain) - Open sound control library.
- Numpy (BSD) - Numerical computation library.
- Netifaces (MIT) - Portable library for accessing network interface information.
- Pytest (MIT) - Python testing framework
- Hypothesis (Mozilla Public License 2.0) - Python testing framework.