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, 3.9 and Python 3.10. We will start by creating a Python 3.10 environment that we will call openbiosim.

$ mamba create -n openbiosim "python<3.11"

Note

We use python<3.11 as this will install the most recent 3.10 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.10 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.

5. Hardest install - build your own custom conda packages#

The sire conda packages that we build have a lot of dependencies that may conflict with your own environment. This is because we build sire to be compatible with the latest version of BioSimSpace, which itself optionally depends on a large number of simulation packages.

You can build your own sire conda package that has fewer dependencies, or which is compatible with the packages already installed in your conda environment. There are a few steps you need to complete.

A. Define your runtime environment#

The first step is to describe the desired runtime environment for the package. The easiest way to do this is to create that environment, e.g. by installing the packages you want, and to then create an environment.yml file that describes that environment. You can do this by running

$ conda env export -f environment.yml

This will create an environment file called environment.yml that creates pins for the exact version of all of the packages installed in your environment.

If you want, you can edit this file to add or remove pins. Simply delete lines describing the version of packages that you don’t need pinned, add new lines if there are additional packages that you do want pinned, or even update the version number of the pins if you can allow more flexibility for the installation.

B. Check out the sire source code#

The next step is to check out the sire source code (if you haven’t already).

$ git clone https://github.com/openbiosim/sire -b main

This checks the main branch of the code out into a directory called sire. You can build a package for any branch of the code. Typically, you will want to choose the main branch, as this always corresponds to the last release. You can checkout the main branch by changing into the sire directory and running;

$ git checkout main

C. Create the conda build environment#

While you could build in your existing environment, it is cleaner to build in a dedicated build environment. Here, we will create a build environment called build_sire. You can use any name you want.

$ conda env create -n build_sire -f environment.yml

Activate that environment

$ conda activate build_sire

And then install the tools needed to run conda-build

$ conda install -y -c conda-forge mamba
$ mamba install -y -c conda-forge boa anaconda-client packaging=21 pip-requirements-parser

D. Create the conda recipe#

Next, we need to create the conda recipe to build the package. We do this by running the script actions/update_recipe.py. You can add the path to your environment.yml file as an argument. This tells the script to create a recipe that includes all of the pins in the environment.yml. For example;

$ python actions/update_recipe.py environment.yml

would create the recipe using the pins in environment.yml (assuming this file was in the current directory).

The recipe is written to recipes/sire/meta.yaml. You can (optionally) edit the pins in this file too, if you want to do some fine-tuning.

Note

You may need to edit the recipe to fix version inconsistencies. This is especially the case for rdkit - you need to to make sure that if you specify a version for rdkit in your environment.yml that you also use the same version for the rdkit-devel package.

E. Building the package#

You can now run conda-build to create the package.

$ conda mambabuild -c conda-forge -c openbiosim/label/dev recipes/sire

This will take a while. At the end, it will print out the location of the sire conda package, e.g.

Note

The above command assumes that you don’t need any other channels included to install all of the packages included in your environment.yml. The actions/update_recipe.py script will print out the correct conda mambabuild command at the end, which includes any extra channels that are needed.

# To have conda build upload to anaconda.org automatically, use
# conda config --set anaconda_upload yes
anaconda upload \
    /path/to/mambaforge/envs/build_sire/conda-bld/osx-64/sire-2023.3.0-py310hf95ea87_25.tar.bz2
anaconda_upload is not set.  Not uploading wheels: []

INFO :: The inputs making up the hashes for the built packages are as follows:
{
  "sire-2023.3.0-py310hf95ea87_25": {
    "recipe": {
      "c_compiler": "clang",
      "cxx_compiler": "clangxx",
      "numpy": "1.22",
      "target_platform": "osx-64"
    }
  }
}

In this case, you can see that the package is the file /path/to/mambaforge/envs/build_sire/conda-bld/osx-64/sire-2023.3.0-py310hf95ea87_25.tar.bz2.

Copy this conda package to wherever you need (e.g. into a channel, upload to conda, etc.).

Note

A full set of tests will be run on the package after it has been built. Some of these tests may fail if you have edited the recipe to remove some of the dependencies. If this happens, you can decide to ignore the tests, e.g. by removing them from the conda recipe (meta.yml) or by just copying the file that is produced and has been placed into the conda-bld/broken directory.

You can then install it, either via the channel you’ve uploaded to, or by directly running conda install on the package file itself.