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.