NanoVer Python Server

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 XR clients, e.g. NanoVer iMD-XR.

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.

Contents

1. Getting started
2. User installation
3. Developer installation
4. Running the tests
5. Running the tutorials
6. Troubleshooting
7. Citation and external libraries

Getting started

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.

Running a server via the command line

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.

Tutorials

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!

Exploring the code

The src folder contains the library to write NanoVer clients and servers in python, as well as the services implemented in python. The prototypes directory contains examples and (sometimes unmaintained) prototypes using the python libraries.

User installation

Check out the Installation & Getting Started page in our documentation for detailed instructions on installing NanoVer.

Updating the conda package

• Run conda list nanover-server to determine the currently installed version
• Run conda update nanover-server to attempt to update to latest version
• If you can't seem to update to the latest version, run python --version to 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.

Developer installation

PyPI

• Clone the nanover-server-py repository:

git clone https://github.com/IRL2/nanover-server-py.git
cd nanover-server-py

• Install the nanover-server package directly from the source code:

pip install -e .[dev]

Conda

• Install Miniforge (or other conda variant)
  • On Windows, run the remaining steps in the provided terminal (e.g "Miniforge Prompt", "Anaconda Powershell Prompt", etc)
• Create a conda environment (we choose the name "nanover-dev"):

conda create -n nanover-dev -c conda-forge irl::nanover-server

• Activate the environment:

conda activate nanover-dev

• Clone the nanover-server-py repository:

git clone https://github.com/IRL2/nanover-server-py.git
cd nanover-server-py

• Reinstall the nanover-server package directly from the source code:

# windows
.\install-dev.bat

# linux and mac
./install-dev.sh

Running the tests

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.

Unit Tests

The unit tests check code functionality of the python libraries. To run them:

python -m pytest tests

Optionally, you can run most of the tests in parallel with pytest-xdist:

python -m pip install pytest-xdist
python -m pytest tests -n auto -m 'not serial'
python -m pytest tests -n0 -m 'serial'

Formatting & Linting Tests

The formatting and linting tests check code style, and require ruff:

python -m pip install ruff
python -m ruff check src
python -m ruff format --check src

ruff can also automatically fix and reformat the files for you:

python -m ruff check --fix src
python -m ruff format src

Type Checks

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 src

Running the tutorials

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.

OpenMM IMD Simulations

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

ASE IMD Simulations Jupyter Notebooks

The examples/ase folder contains several Jupyter notebooks that demonstrate visualisation and interaction from a notebook.

MD Analysis Trajectories

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

Troubleshooting

Autoconnect

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.

Old recordings

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.

Citation and external libraries

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.
• psutil (BSD) - Cross-platform lib for process and system monitoring in Python.
• pytest (MIT) - Python testing framework
• Hypothesis (Mozilla Public License 2.0) - Python testing framework.