BioSimSpace is an interoperable Python framework for biomolecular simulation. With it you can:

• Write robust and portable biomolecular workflow components that work on different hardware, with different software packages, and that can be run in different ways, e.g. command-line, Jupyter.
• Interact with molecular-simulation processes in real time.

If you use BioSimSpace in any scientific software, please cite the following paper:

@article{Hedges2019,
  doi = {10.21105/joss.01831},
  url = {https://doi.org/10.21105/joss.01831},
  year = {2019},
  publisher = {The Open Journal},
  volume = {4},
  number = {43},
  pages = {1831},
  author = {Lester Hedges and Antonia Mey and Charles Laughton and Francesco Gervasio and Adrian Mulholland and Christopher Woods and Julien Michel},
  title = {BioSimSpace: An interoperable Python framework for biomolecular simulation},
  journal = {Journal of Open Source Software}
}

Full documentation can be found here.

The easiest way to install BioSimSpace is using our conda channel:

conda install -c conda-forge -c omnia -c michellab biosimspace

To install the latest development version you can use:

conda install -c conda-forge -c omnia -c michellab/label/dev biosimspace

When updating the development version it is generally advised to update Sire at the same time:

conda install -c conda-forge -c omnia -c michellab/label/dev biosimspace sire

If you plan on using BioSimSpace interactively via Jupyter, then you might also need to enable the required notebook extensions within your Conda environment:

jupyter-nbextension enable nglview --py --sys-prefix

Unless you add the required channels to your Conda configuration, then you'll need to add them when updating, e.g., for the development package:

conda update -c conda-forge -c omnia -c michellab/label/dev biosimspace

Note that because of Conda's peculiar scoring metrics you might not end up with the latest version of BioSimSpace when performing a fresh install or update. (It tries to minimise various things, such as the number of dependencies installed, which is difficult when your package depends on many other packages.) To see what packages are available, run:

conda search -c michellab/label/dev biosimspace

You can then install the latest version by explicitly stating the full package name, e.g.:

conda install -c conda-forge -c omnia -c michellab/label/dev biosimspace=2019.1.0=py37h14c3975_85

If you find that Conda is particularly slow to install or upgrade BioSimSpace, particularly on macOS, then we advise using mamba:

conda install -c conda-forge mamba

You can then replace all installation/upgrade commands with mamba, e.g.:

mamba install -c conda-forge -c omnia -c michellab/label/dev biosimspace

The latest self-extracting binary for the development version of BioSimSpace can be downloaded from one of the following links:

• Linux: biosimspace_devel_latest_linux.run
• macOS: biosimspace_devel_latest_osx.run

Once downloaded, the binary can be unpacked as follows:

chmod +x biosimspace_devel_latest_linux.run
./biosimspace_devel_latest_linux.run

Unless a different installation path was given, BioSimSpace can be found in: $HOME/biosimspace.app. BioSimSpace comes with a bundled with a Python interpreter, an interactive Python (IPython) shell, and Jupyter.

For example, to run a BioSimSpace Python script, use:

$HOME/biosimspace.app/bin/python script.py

To launch an interactive BioSimSpace session:

$HOME/biosimspace.app/bin/ipython

To run a BioSimSpace notebook:

$HOME/biosimspace.app/bin/jupyter notebook notebook.ipynb

Alternatively, to install BioSimSpace from source:

(Before starting, you'll need a working Git installation.)

BioSimSpace is built on top of the Sire molecular simulation framework. To download and install Sire:

git clone https://github.com/michellab/Sire
cd Sire
./compile_sire.sh

Assuming the default installation path, this will install Sire into $HOME/sire.app.

(Note that the installation is slow and can take in excess of an hour.)

Next you will need to download BioSimSpace and install it into your Sire application. (The following assumes the default Sire installation path.)

git clone https://github.com/michellab/BioSimSpace
cd BioSimSpace/python
$HOME/sire.app/bin/python setup.py install

Once finished, you can test the installation by running:

$HOME/sire.app/bin/ipython

Then try importing the BioSimSpace package:

import BioSimSpace as BSS

If you don't want to build or install, you can also run BioSimSpace via one of our docker images. The easy way to run the latest development image of BioSimSpace is via:

docker run -it biosimspace/biosimspace-devel:latest

This will download the latest BioSimSpace development container, and will run it, giving you a bash prompt inside the container.

Some BioSimSpace functionality requires OpenMM. Although a bundled version is provided as part of the installation, this may not be appropriate for your GPU drivers. To automatically detect and install a suitable version of OpenMM, simply run the following command post-install:

optimise_openmm

(Note that, depending on your installation method, optimise_openmm may be located in $HOME/sire.app/bin.)

Alternatively, to manually install a particular version of OpenMM you can use a specific Conda label, e.g.:

conda install -c omnia/label/cuda90 openmm

If you have compiled Sire against a custom OpenMM installation, then you'll need to set the OPENMM_PLUGIN_DIR environment variable to point to the correct plugin location. By default this variable is set to the plugin directory of the bundled OpenMM package.

Please follow the developer's guide.

Please report bugs and other issues using the GitHub issue tracker. When reporting issues please try to include a minimal code snippet that reproduces the problem. Additional files can be also be uploaded as an archive, e.g. a zip file. Please also report the branch on which you are experiencing the issue, along with the BioSimSpace version number. This can be found by running:

import BioSimSpace as BSS
print(BSS.__version__)