Getting Started

a3fe is a package for running alchemical absolute binding free energy calculations with SOMD (Sire / OpenMM Molecular Dynamics) through SLURM. It is based on Sire(https://sire.openbiosim.org/) and also uses BioSimSpace(https://biosimspace.openbiosim.org/) during the set-up stages. For a discussion of the algorithms used, please see (https://pubs.acs.org/doi/10.1021/acs.jctc.4c00806).

Installation

Please see the instructions in the github repo README (https://github.com/michellab/a3fe).

Quick Start

  • Activate your a3fe conda environment

  • Create a base directory for the calculation and create an directory called input within this

  • Move your input files into the the input directory. For example, if you have parameterised AMBER-format input files, name these bound_param.rst7, bound_param.prm7, free_param.rst7, and free_param.prm7. Ensure that the ligand is named LIG and is the first molecule in the system. For more details see Preparing Input for a3fe. Alternatively, copy the pre-provided input from a3fe/a3fe/data/example_run_dir/input to your input directory.

  • In the calculation base directory, run the following python code, either through ipython or as a python script (you will likely want to run this with nohup/ through tmux to ensure that the calculation is not killed when you lose connection). Running though ipython will let you interact with the calculation while it’s running.

import a3fe as a3
calc = a3.Calculation(ensemble_size=5) # Run with 5 independent replicates and default engine is SOMD
calc.setup()
calc.get_optimal_lam_vals()
calc.run(adaptive=False, runtime = 5) # Run non-adaptively for 5 ns per replicate
calc.wait()
calc.set_equilibration_time(1) # Discard the first ns of simulation time
calc.analyse()
calc.save()

  • Check the results in the output directories (separate output directories are created for the Calculation, Legs, and Stages)

Quick Tips

Some handy commands and code snippets, assuming that you have set up the calculation following the code above:

Terminate all the SLURM jobs: calc.kill()

Delete all the output (but not input files), ready to run again: calc.clean()

Delete the large trajectory and restart files calc.lighten()

Return any failed simulations and find out where to look for output:

for failed_sim in calc.failed_simulations:
    print(failed_sim.base_dir)

Check how many GPU hours your calculation has cost:

print(f"Total GPU hours: {calc.tot_gpu_time:0.2f}")
print("#"*10)
for leg in calc.legs:
    print(f"Total GPU hours for leg {leg.leg_type}: {leg.tot_gpu_time:.2f}")

Get a detailed summary of free energy components as a pandas dataframe:

df = calc.get_results_df()
print(df)

Save the current state of the calculation:

calc.save()