Installation

1. No-installation - Run in a web browser

We run a completely free JupyterHub on which we have BioSimSpace installed.

This is at try.openbiosim.org. You only need a GitHub account, which is used to log into the server.

Simply go to try.openbiosim.org in your web browser, and log in using your GitHub account. This will start a Jupyter Lab instance. In here you can start a terminal, and then use BioSimSpace directly via ipython. Or you can start a Jupyter notebook and use BioSimSpace there.

To import BioSimSpace, at a Python prompt type

>>> import BioSimSpace as BSS

If this imports without errors, then everything is working. We encourage you to take a look at the tutorials to learn how to use BioSimSpace or the quickstart guide if you want an overview.

Note

This free JupyterHub server is limited. You only have up to 2 GB of memory and at most 1 processor core. Disk storage is temporary, and any data will be lost when you log out. Because it only supports a limited number of concurrent users, inactive sessions will be automatically stopped and logged out after 20 minutes. Please only use this service to explore and learn BioSimSpace. Do not use it for production work.

2. Easy installation - Run in a conda environment

The easiest way to install BioSimSpace is in a new conda environment.

You can use any conda environment or installation. We recommend using Miniforge, as this is pre-configured to use conda-forge.

Either… Install a new copy of Miniforge

To install a new copy of Miniforge, first download a Miniforge from this page that matches your operating system and processor.

Install Miniforge following the instructions here.

Once installed, you should be able to run the conda command to install other packages (e.g. conda -h will print out help on how to use the conda command).

Or… Use an existing anaconda/miniconda install

If you want to use an existing anaconda or miniconda installation, then first open a terminal with that distribution activated. For example, open a terminal via anaconda navigator, or open a terminal and run source /path/to/conda/bin/activate, where /path/to/conda is the full path to your anaconda or miniconda installation.

You should now be able to run the conda command to install other packages (e.g. conda -h will print out help on how to use the conda command).

And then… Install BioSimSpace into a new environment

We recommend that BioSimSpace is installed into a new (clean) environment. This minimises the risk of failures caused by incompatible dependencies.

BioSimSpace is currently packaged for Python 3.8 and Python 3.9. We will start by creating a Python 3.9 environment that we will call openbiosim.

$ conda create -n openbiosim "python<3.10"

Note

We use python<3.10 as this will install the most recent 3.9 release of python.

We can now install BioSimSpace into that environment by typing

$ conda install -n openbiosim -c openbiosim biosimspace

Note

The option -n openbiosim tells conda to install BioSimSpace into the openbiosim environment. The option -c openbiosim tells conda to install BioSimSpace from the openbiosim conda channel.

If you want the latest development release, then install by typing

$ conda install -n openbiosim -c "openbiosim/label/dev" biosimspace

To install the latest development version you can use:

conda create -n openbiosim-dev -c conda-forge -c openbiosim/label/dev biosimspace
conda activate openbiosim-dev

To run BioSimSpace, you must now activate the openbiosim environment. You can do this by typing

$ conda activate openbiosim

You can now start a Python session (e.g. running python, or ipython or jupyter lab if you installed those). At the Python prompt you can import BioSimSpace by typing

>>> import BioSimSpace as BSS

If this imports without errors, then everything is working. We encourage you to take a look at the tutorials to learn how to use BioSimSpace or the quickstart guide if you want an overview.

3. Also easy installation - Run in a container

Another route to install BioSimSpace is to download and run our pre-built containers. These can be run via docker (on Linux, MacOS and Windows) or via podman (on Linux) on Intel (X86-64) or ARM64 processors.

To run via docker, simply type;

$ docker run -p 8888:8888 -it openbiosim/biosimspace:latest

or, via podman, type;

$ podman run -p 8888:8888 -it openbiosim/biosimspace:latest

This will download the container from hub.docker.com and will start a command prompt in that container.

You can now type python, ipython or jupyter lab to start a python, ipython or jupyter lab session.

Note

The option -p 8888:8888 tells docker/podman to redirect port 8888 on your computer to port 8888 in the container. This will let you open a browser and navigate to the URL printed by jupyter lab if you are using jupyter. You can drop this option if you don’t want to use jupyter lab.

Note

You can map directories from your computer into the container by using the -v option. For example, -v $HOME/input:/home/openbiosim/input would map your input folder in your home directory to the input folder in the home directory of the container. This will let BioSimSpace read and write files on your computer.

You can now start a Python session (e.g. running python, or ipython or jupyter lab if you installed those). At the Python prompt you can import biosimspace by typing

>>> import BioSimSpace as BSS

If this imports without errors, then everything is working. We encourage you to take a look at the tutorials to learn how to use BioSimSpace or the quickstart guide if you want an overview.

4. Harder installation - Compile from source

The following documents a full installation of 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, follow the instructions here, making sure that BioSimSpace’s dependencies are installed into the Sire conda environment at the point at which Sire is installed.

Next you will need to download BioSimSpace and install it into your Sire Conda environment.

git clone https://github.com/openbiosim/biosimspace
cd biosimspace/python
pip install .

If you plan to develop and want an editable install, use:

pip install -e .

If you want to skip the installation of BioSimSpace dependencies, e.g. if they are already installed, then you can use:

BSS_SKIP_DEPENDENCIES=1 pip install -e .

Once finished, you can test the installation by running:

python

Then try importing the BioSimSpace package:

import BioSimSpace as BSS

If you don’t want to install Sire from source, an alternative is to create a conda environment containing only the dependencies of BioSimSpace, then install the latest development code into that.

conda create -n openbiosim-dev -c conda-forge -c openbiosim/label/dev biosimspace --only-deps
conda activate openbiosim-dev
git clone https://github.com/openbiosim/biosimspace
cd biosimspace/python
BSS_SKIP_DEPENDENCIES=1 pip install -e .

(You may also want to install optional dependencies, such as ambertools and gromacs into your environment.)

5. Common issues

  • If you experience problems with Matplotlib when importing BioSimSpace on macOS, e.g.

RuntimeError**: Python is not installed as a framework.

simply add the following to ~/.matplotlib/matplotlibrc

backend: TkAgg

Note that plotting functionality will be disabled if you are using BioSimSpace on a remote server without X forwarding.

  • If you experience problems with Jupyter permissions, try removing $HOME/.jupyter or $HOME/.local/share/jupyter

6. External dependencies

Several additional packages are required for full access to all of BioSimSpace’s functionality. Please download and install these packages according to their recommended installation instructions.

(Note that BioSimSpace is built to be compatible with the ambertools and gromacs packages from conda-forge, but they are not included as hard requirement. This means that BioSimSpace can be used in conda environments with and without them. We’ve taken this approach to enable the use of stripped down environments, and to avoid clashes with external versions of the packages, which may be better optimised for specific hardware and usage requirements.)

For Amber / AmberTools, we also recommend adding ${AMBERHOME}/bin to your PATH to ensure that its binaries are visible to third-party libraries, such as openff-toolkit.

Please visit our compatibility page to see which versions of the external dependencies BioSimSpace has currently been tested against.