NanoVer Python Server + gRPC Protocol

Repository containing the gRPC protocol and 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.

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.omni provides a command line interface for running OpenMM simulations. For example, from the nanover-server-py directory:

nanover-omni --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 protocol folder contains the definitions of the gRPC services.

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.

The csharp-libraries/NanoVer.Protocol folder contains C# implementations of clients for receiving trajectories and structures.

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

Windows

• Install Anaconda
• Install the .NET core SDK (see https://dotnet.microsoft.com/download)
• 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.11" openmm MDAnalysis MDAnalysisTests ase
  • Activate the conda environment: conda activate nanover-dev
  • Compile the protocol and 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 -noedit instead. Otherwise, by default, the nanover packages will be installed in edit mode (pip install -e) meaning that changes in the nanover-server-py directory will be directly reflected in your python environment.

Mac and Linux

• 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
  • Compile the protocol and install the NanoVer python libraries in your conda environment: ./compile.sh --no-dotnet. If you do not plan on modifying the python packages, you may run ./compile.sh --no-edit --no-dotnet instead. Otherwise, by default, the NanoVer packages will be installed in edit mode (pip install -e) meaning that changes in the nanover-server-py directory will be directly reflected in your python environment.

Here, we installed only the python library. Using the --no-dotnet argument, we skipped building the C# libraries for NanoVer. Would you want to work on these library, you would need to:

• Install dotnet 2.11. This is an old version of the framework that is not maintained anymore. However, Unity still relies on it.
• Run the compile script: ./compile.sh --no-python to skip installing the python libraries, or just ./compile.sh to build the python libraries as well.

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 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'

Formatting & Linting Tests

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

python -m pip install ruff
python -m pip install black
python -m ruff check python-libraries
python -m black --diff --check python-libraries

black can automatically reformat the files for you:

python -m black python-libraries

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 --ignore-missing-imports --namespace-packages --check-untyped-defs --allow-redefinition nanover-server

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.omni provides a command line interface for running serialised OpenMM simulations. For example, from the nanover-server-py directory:

nanover-omni --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.

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:

• gRPC (Apache v2) - Communication protocol.
• 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.