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.
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.
For more information please take a look at the project's documentation.
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.omni provides a command line interface for running OpenMM simulations. For example, from the nanover-protocol directory:
nanover-omni --omm examples/ase/openmm_files/nanotube.xmlLearn more about running a NanoVer server here in our documentation.
The examples folder contains Jupyter notebooks for getting started with NanoVer. Please head to the Tutorials page of the project's documentation for more information!
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.
Check out the Installation & Getting Started page in our documentation for detailed instructions on installing NanoVer.
conda list nanover-server to determine the currently installed versionconda update nanover-server to attempt to update to latest versionpython --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.conda create -n nanover-dev "python>3.11"conda activate nanover-devconda install -c conda-forge openmm MDAnalysis MDAnalysisTests ase./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-protocol directory will be directly reflected in your python environment.conda create -n nanover-dev -c conda-forge "python>3.11" openmm MDAnalysis MDAnalysisTests ase mpi4pyconda activate nanover-dev./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-protocol 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:
./compile.sh --no-python to skip installing the python libraries, or just ./compile.sh to build the python libraries as well.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-librariesOptionally, 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 and black:
python -m pip install ruff
python -m pip install black
python -m ruff check python-libraries
python -m black --diff --check python-librariesblack can automatically reformat the files for you:
python -m black python-librariesThe type checks look at the type hints in the code to make sure they are consistent and help find potential errors. Because of the special setup required you will probably not be able to run this locally, but you can try:
python -m pip install mypy
packages=$(find python-libraries -name __init__.py \
| sed 's/__init__.py//g' \
| awk '{split($0, a, /src/); print(a[2])}' \
| sed 's#/#.#g' \
| cut -c 2- \
| sed 's/\.$//g' \
| grep -v '^$' \
| grep -v protocol \
| sed 's/^/-p /g' \
| grep -v '\..*\.' \
| tr '\n' ' ')
python -m mypy --ignore-missing-imports --namespace-packages --check-untyped-defs --allow-redefinition $packages The examples 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.omni provides a command line interface for running serialised OpenMM simulations. For example, from the
nanover-protocol directory:
nanover-omni --omm examples/ase/openmm_files/nanotube.xmlThe 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-protocol directory, run
python ./examples/mdanalysis/example.pyIf you are having autoconnecting to servers, you can run nanover-essd-list to verify which local network servers are visible to your machine.
If you find this project useful, please cite the following papers:
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
M. O’Connor, S.J. Bennie, H.M. Deeks, A. Jamieson-Binnie, A.J. Jones, R.J. Shannon, R. Walters, T. Mitchell, A.J. Mulholland, D.R. Glowacki, “Interactive molecular dynamics from quantum chemistry to drug binding: an open-source multi-person virtual reality framework”, J. Chem Phys 150, 224703 (2019)
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: