Introduction

Here we present an overview of the workflow for calculating free energies in OpenFE, in the broadest strokes possible This workflow is reflected in both the Python API and in the command line interface, and so we have a section for each.

Workflow overview

The overall workflow of OpenFE involves three stages:

1. Setup: Defining the simulation campaign you are going to run.

2. Executation: Running and performing initial analysis of your simulation campaign.

3. Gather results: Assembling the results from the simulation campaign for further analysis.

In many use cases, these stages may be done on different machines – for example, you are likely to make use of HPC or cloud computing resources to run the simulation campaign. Because of this, each stage has a certain type of output, which is the input to the next stage.

The output of setup is an AlchemicalNetwork. This contains all the information about what is being simulated (e.g., what ligands) and the information about how to perform the simulation (the protocol).

The output of the executation stage is the basic results from each edge. This can depend of the specific analysis intended, but will either involve a ProtocolResult representing the calculated \(\Delta G\) for each edge or the ProtocolDAGResult linked to the data needed to calculate that \(\Delta G\).

The gather results stage takes these results and produces something useful to the user. For example, the CLI’s gather command will create a table of the \(\Delta G\) for each leg.

CLI Workflow

We have separate CLI commands for each stage of setup, running, and gathering results. With the CLI, the Python objects of AlchemicalNetwork and ProtocolResult are stored to disk in an intermediate representation between the commands.

The commands used for set up the CLI are:

• the plan-rbfe-network command

• the plan-rhfe-network command

These will save the alchemical network represented as a JSON file for each edge of the AlchemicalNetwork (i.e., each leg of the simulation).

To run a given transformation, use the quickrun command; for example:

$ openfe quickrun mytransformation.json -d dir_for_files -o output.json

In many cases, you will want to create a job script for a queuing system (e.g., SLURM) that wraps that command. You can do this for all JSON files from the network planning command with something like this:

Finally, to gather the results of that, use the ref:cli_gather:

$ openfe gather -o

This will output a tab-separated file with the ligand pair, the estimated \(\Delta G\) and the uncertainty in that estimate.

The CLI provides a very straightforward user experience that works with the most simple use cases. For use cases that need more workflow customization, the Python API makes it relatively straightforward to define exactly the simulation you want to run. The next sections of this user guide will illustrate how to customize the behavior to your needs.