🚀 Tutorials

🚀 Tutorials#

Get started quickly with ready-to-simulate examples provided in the examples directory of the BindFlow repository. These examples are designed to work out of the box, giving you a hands-on introduction to BindFlow.

Current examples#

In the example directory there are three systems:

  • A2A: membrane protein with a Na ion cofactor,

  • CyclophilinD: soluble protein,

  • SAMPL6-OA: non-protein receptor, ideal for testing as is the smallest system.

For each system you will find:

  • Protein and ligands input files in the inputs directory,

  • BindFlow configuration files for:

    • FEP: config-fep.yml, and

    • MM(PB/GB)SA: config-mmpbsa.yml.

  • BindFlow executor files: executor-fep.py and executor-mmpbsa.py.

Files presented on the examples are those used on the BindFlow’s paper

Here we will only follow step-by-step the CyclophilinD example, the other examples are very similar.

Tips before starting#

  1. Review the examples - Browse through the example simulations to understand how they are structured.

  2. Adjust configurations - Update the configuration files to match your cluster resources and environment. This ensures simulations run smoothly.

  3. Reference configuration files - Several files are provided for illustration in the config directory. Use them as a guide to create or customize your own simulation setups.

  4. Run your simulations - Once configured, execute the examples to see BindFlow in action. For deployment instructions, see the Deploy guide.

  5. Troubleshooting - Check common issues and solutions in the FAQ. If your problem is not listed, questions on how to use BindFlow, or if you want to give feedback or share ideas and new features, please head to the BindFlow’s discussions.

CylophilinD FEP tutorial#

Hardware#

To complete this tutorial we need an HPC with SLURM as task manager. This is not strictly needed for BindFlow to run, but it will be easy to be on the same page for the tutorial.

Hardware accessibility

In case you do not have access to an HPC-like computer environment and you are only interesting in see if BindFlow works, consider to use the small SAMPL6-OA system and only a couple of ligands. So the calculations are doable in your workstation.

Getting ready#

First we need to install BindFlow in our computer system, for that follow the Installation instructions.

Get the files by cloning the BindFlow repo

git clone --depth 1 git@github.com:ale94mleon/BindFlow.git
cd BindFlow/examples/CyclophilinD

Exploring and modifying the executor file#

Explore the directory, check the files and try to understand the logic of executor-fep.py. You will see that only a single function is used: bindflow.runners.calculate(). This is the core function you should get familiar for most of the general cases. Therefore, it is highly recommended to learn its parameters and options. The documentation of bindflow.runners.calculate() is very extensive, but you will learn how to use BindFlow effectively.

Let’s modify executor-fep.py by:

  • using only one of the three force fields,

  • using two replicas,

  • using only two ligands and,

  • submitting the main job to the queue system.

10,17d9
<     "openff_unconstrained-2.0.0": {
<         "type": "openff",
<         "code": "openff_unconstrained-2.0.0.offxml",
<     },
<     "espaloma-0.3.1": {
<         "type": "espaloma",
<         "code": "espaloma-0.3.1",
<     },
43c35
<         ligands=ligands,
---
>         ligands=ligands[:2],
49c41
<         replicas=3,
---
>         replicas=2,
53c45
<         submit=False,
---
>         submit=True,

Tuning the config file#

The provided config-fep.yml offers SLURM configurations for the calculation jobs (cluster:options:calculation) and for the sentinel job (cluster:options:job). The last will only launch jobs and handled the snakemake queue system, but it will not perform heavy calculations, it will be mainly sleeping and waiting. Keywords for these sections are any valid SLURM parameter. You will need to adjust based on your HPC configuration.

extra_directives/dependencies is a list of commands that will be executed sequentially before any GROMACS command. In the provided example, this section is used to load GROMACS package on our system (for sure different in your case) and avoid GROMACS backup on files (this ensures cleaner working directory during production). You must change those sections accordingly to your HPC configuration.

Run BindFlow run#

After you tuned your configurations, you can just:

python executor-fep.py

Checking the run#

BindFlow offers some basic, but powerful CLI functionalities; check the command bindflow -h.

You can also check the SLURM queue and the main snakemake log file located at fep/gaff-2.11/.snakemake/log to see the completion percent of the pipeline.

To debug possible issues, read the Debugging page and the FAQ.

Friendly reminder

The examples are a great way to get hands-on quickly, but they’re not a replacement for the full documentation. For a deeper understanding of BindFlow and its features, we encourage you to explore the documentation–we put a lot of love into it! 😊

Contents