BioSimSpace

About

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.
• Start, stop, and monitor molecular simulation processes within interactive Python environments.

Citation

If you use BioSimSpace in any scientific work, 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}
}

Documentation

Full documentation can be found here.

Installation

Conda package

The easiest way to install BioSimSpace is using our conda channel. BioSimSpace is built using dependencies from conda-forge, so please ensure that the channel takes strict priority. We recommend using Miniforge.

To create a new environment:

conda create -n openbiosim -c conda-forge -c openbiosim biosimspace
conda activate openbiosim

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

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

conda update -c conda-forge -c openbiosim/label/dev biosimspace sire

Unless you add the required channels to your Conda configuration, you'll need to pass them on the command line when updating, as shown above.

Installing from source (standalone)

To install from source using pixi, which will automatically create an environment with all required dependencies (including pre-built Sire):

git clone https://github.com/openbiosim/biosimspace
cd biosimspace
pixi install
pixi shell
pip install -e .

Installing from source (full OpenBioSim development)

If you are developing across the full OpenBioSim stack, first install Sire from source by following the instructions here, then activate its pixi environment:

pixi shell --manifest-path /path/to/sire/pixi.toml -e dev

Next, clone and install BioSimSpace:

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

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

If you need OpenCL support (e.g. for OpenMM), note that pixi does not run conda post-link scripts, so the ocl-icd-system symlink won't be created automatically. This applies to either of the routes above. From within the activated environment, run the following once to fix this:

ln -s /etc/OpenCL/vendors "${CONDA_PREFIX}/etc/OpenCL/vendors/ocl-icd-system"

Once finished, you can test the installation by running:

import BioSimSpace as BSS

Development

Pre-commit hooks are used to ensure consistent code formatting and linting. To set up pre-commit in your development environment:

pixi shell -e dev
pre-commit install

This will run ruff formatting and linting checks automatically on each commit. To run the checks manually against all files:

pre-commit run --all-files

Developers

Please follow the developer's guide.

Issues

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 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__)

• If you experience JAX issues when using BioSimSpace.FreeEnergy.Relative.analyse, try setting the PYMBAR_DISABLE_JAX environment variable to 1.