Installation#

Binary packages for sire are available on MacOS, Linux and Windows running on Intel/AMD (X86-64) or ARM64 processors.

sire can be compiled on any UNIX or Windows-compatible operating system running on X86-64, ARM64 or PowerPC processors.

You have a range of options for installing the software.

1. No-installation - Run in a Web Browser#

We run a completely free JupyterHub on which we have sire 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 sire directly via ipython. Or you can start a Jupyter notebook and use sire there.

To import sire, at a Python prompt type

>>> import sire as sr

If this imports without errors, then everything is working. We encourage you to take a look at the tutorial to learn how to use sire 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 sire. Do not use it for production work.

2. Easy installation - Run in a conda environment#

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

You can use any conda environment or installation. We recommend using mambaforge, as this is pre-configured to use conda-forge, and bundles mamba, which is a fast drop-in replacement for conda.

Either… Install a new copy of mambaforge#

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

Install Mambaforge following the instructions here.

Once installed, you should be able to run the mamba command to install other packages (e.g. mamba -h will print out help on how to use the mamba 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). We highly recommend that you use mamba as a drop-in replacement for conda, so first install mamba.

$ conda install -c conda-forge mamba

This should install mamba. If this fails, then your anaconda or miniconda environment is likely quite full, or else it is outdated. We recommend going back and following the instructions to install a new copy of mambaforge.

If this works, then you should now be able to run the mamba command to install other packages (e.g. mamba -h will print out help on how to use the mamba command).

And then… Install sire into a new environment#

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

Sire 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.

$ mamba 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 sire into that environment by typing

$ mamba install -n openbiosim -c openbiosim sire

Note

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

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

$ mamba install -n openbiosim -c "openbiosim/label/dev" sire

You may (optionally) want to install additional tools such as ipython and jupyterlab. To do this, type

$ mamba install -n openbiosim ipython jupyterlab

To run sire, 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 sire by typing

>>> import sire as sr

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

3. Also easy installation - Run in a container#

Another route to install sire 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/sire:latest

or, via podman, type;

$ podman run -p 8888:8888 -it openbiosim/sire: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 sire 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 sire by typing

>>> import sire as sr

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

4. Harder installation - Compile from source#

Sometimes you will want to compile and run sire from source. This could be because we don’t distribute a binary package for your operating system, or because you want to use a newer version (e.g. code from the devel branch, or from your own feature branch if you are a developer).

You compile sire into an existing anaconda / miniconda environment. Please create and activate an environment, e.g. by following the instructions to install a fresh mambaforge and then creating and activating Python 3.9 environment called openbiosim.

Next, download the source code. You could download the latest development version of sire by typing;

$ git clone https://github.com/openbiosim/sire

This will download into a directory called sire. Navigate into this directory (e.g. cd sire).

Note

This will fail if git is not installed on your computer. You can easily install git using mamba, e.g. run mamba install git.

You can change to a different branch using the git checkout BRANCH command, e.g.

$ git checkout main

will check out the main branch of sire. This always corresponds to the last released version of sire. Or, you can check out a feature branch using

$ git checkout feat_name

where feat_name should be replaced by the name of the feature branch you want to compile.

Compilation and installation of sire is managed via the setup.py script.

Run

$ python setup.py --help

to get a help on all of the options.

Typically, you just want to compile and install sire. To do this, type

$ python setup.py install

This will download and install all of the dependencies via mamba (or conda if you haven’t installed mamba). It will then compile the sire C++ libraries, and then the Python wrappers. Be patient, as compilation can take quite a while!

Note

You need to have Visual Studio 2017 C++ compiler installed to compile on Windows. The easiest way to do this is to install chocolatey and then install the compilers using the command choco install visualstudio2017-workload-vctools. This is all free, but you will need admin access to install chocolatey. If this doesn’t work, then go to this page and download the “Build Tools for Visual Studio 2017”. Use the installer to select and install only the build tools. You will need a free Microsoft developer account to access this page. If this doesn’t work, then follow the excellent guidance here to set up your Windows computer for compiling conda packages.

If you plan to install BioSimSpace on top of sire, then you should install using;

$ python --install-bss-deps install

This will use mamba (or conda) to download and install all of BioSimSpace’s dependencies as well. This ensures that incompatible versions of shared dependencies are not accidentally installed.

Once sire has installed, you can import it in a python, ipython or jupyter lab session by typing

>>> import sire as sr

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

Please take a look at our developer guide for more information on how to develop and contribute new code to sire.