💿 Installation#

Installing micromamba#

We highly recommend the latest version of micromamba for the conda environment creation and a fresh environment (as it will be demonstrated here). This is going to ease the resolution of dependencies. See the Official Micromamba Installation Instructions. Mamba may also be used.

Building the environment#

We would like to work in a more relaxed environment, but we have encountered challenging situations. For now, we highly recommend the pinned environment (although the relaxed one is provided for reference).

Select environment style:

Features:
MM(PB/GB)SA capabilities Espaloma force field

Generated environment.yml:

Select options above...

Note

We observed that conda must be configured with channel_priority: flexible instead of strict.

You may get the following error after the environment is created:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behavior is the source of the following dependency conflicts.
tensorflow 2.17.0 requires ml-dtypes<0.5.0,>=0.3.1, but you have ml-dtypes 0.5.4 which is incompatible.

You can safely ignore it. This is may happen in MacOS when Espaloma is selected. The issue arieses because the chain dependency: Espaloma > DLG > TensorFlow > ml-dtypes. We are currently working to get rid of this “error”.

micromamba env create -f environment.yml --channel-priority flexible -y
micromamba activate BindFlow

Final optional pip dependency and BindFlow installation#

With MM(P/G)BSA capabilities

🟢 Stable Release

micromamba activate BindFlow
python -m pip install bindflow --no-deps
python -m pip install -U git+https://github.com/Valdes-Tresanco-MS/gmx_MMPBSA.git@27929e02067bc2321286809818d778a77a872010 --no-deps

🟡 Install from GitHub (latest commit)

micromamba activate BindFlow
python -m pip install git+https://github.com/ale94mleon/BindFlow.git --no-deps
python -m pip install -U git+https://github.com/Valdes-Tresanco-MS/gmx_MMPBSA.git@27929e02067bc2321286809818d778a77a872010 --no-deps

🔵 Developer Mode (editable)

micromamba activate BindFlow
git clone --depth 1 git@github.com:ale94mleon/BindFlow.git
cd BindFlow 
python -m pip install -e . --no-deps
python -m pip install -U git+https://github.com/Valdes-Tresanco-MS/gmx_MMPBSA.git@27929e02067bc2321286809818d778a77a872010 --no-deps

Note

Currently, we are using the gmx_MMPBSA commit 27929e0. This commit has been tested and provides flexibility in selecting the Python version.

Without MM(P/G)BSA capabilities

🟢 Stable Release

micromamba activate BindFlow
python -m pip install bindflow --no-deps

🟡 Install from GitHub (latest commit)

micromamba activate BindFlow
python -m pip install git+https://github.com/ale94mleon/BindFlow.git --no-deps

🔵 Developer Mode (editable)

micromamba activate BindFlow
git clone --depth 1 git@github.com:ale94mleon/BindFlow.git
cd BindFlow 
python -m pip install -e . --no-deps

GROMACS#

GROMACS can be installed in various ways depending on your computer architecture. It is essential to ensure a proper installation that fits your resources. BindFlow relies on GROMACS as its molecular dynamics engine, so it is crucial to have GROMACS installed and ready to use.

Here, we will demonstrate how to build GROMACS from Source (courtesy of Maciej Wójcik). If this method does not work, consult the GROMACS Installation Guide for more information.

Important

At the moment we support GROMACS versions in the range [2022, 2026); BindFlow throws a clean error at the very beginning of the execution of bindflow.runners.calculate() if otherwise.

Linux 🐧

VERSION="2025.4"
TARGET_LOCATION="gromacs/${VERSION}"
SOURCE="https://gitlab.com/gromacs/gromacs.git"
SOURCE_REF="v${VERSION}"

mkdir -p ${TARGET_LOCATION}

git clone --depth 1 --branch ${SOURCE_REF} "${SOURCE}" "${TARGET_LOCATION}-src"

cmake -DGMX_GPU="CUDA" -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 \
    -DGMX_BUILD_OWN_FFTW=ON -DCMAKE_INSTALL_PREFIX="$(pwd)/${TARGET_LOCATION}" -S "${TARGET_LOCATION}-src" -B "${TARGET_LOCATION}-build"

nice -19 cmake --build "${TARGET_LOCATION}-build" --target install -j 8

rm -rf "${TARGET_LOCATION}-build"
rm -rf "${TARGET_LOCATION}-src"

source "${TARGET_LOCATION}/bin/GMXRC.bash"

MacOS 🍏

Assuming brew is installed (a must for Mac developers).

brew install hwloc cmake gcc@13

VERSION=2025.4

git clone --depth 1 --branch v${VERSION} https://gitlab.com/gromacs/gromacs.git gromacs-src
cmake -DGMX_BUILD_OWN_FFTW=ON -DCMAKE_INSTALL_PREFIX="$(pwd)/gromacs-${VERSION}" -DGMX_GPU=OpenCL -DGMX_HWLOC=ON -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -B gromacs-build -S gromacs-src
cmake --build "gromacs-build" --target install -j $(sysctl -n hw.logicalcpu)

rm -rf gromacs-build
rm -rf gromacs-src

source gromacs-${VERSION}/bin/GMXRC.bash

Important

To use the GPU, it is needed to set the following environmental variable:

export GMX_GPU_DISABLE_COMPATIBILITY_CHECK=1

Highly discouraged for production!

Documentation dependencies#

This online Sphinx documentation can also be built and accessed locally.

requirements_doc.txt

myst-nb
myst-parser
sphinx_book_theme
sphinx==7.2.6
sphinx_design
sphinxcontrib-katex
sphinxcontrib-mermaid
sphinx-inline-tabs
sphinx_copybutton
sphinx-autobuild
roman

pip install -r requirements_docs.txt

sphinx-autobuild docs public -a

Open http://localhost:8000. The HTML documentation is in the public directory.

Testing installation#

Finally, it is advised to check if everything is alright. Be patient and go for a coffee ☕, this could take a couple of minutes (~11 min on my Laptop) ⏳.

pip install pytest
pytest --pyargs bindflow.tests

Expected results