qmlify
==============================
[]: # (Badges)
qmlify
provides python executables for post-processing molecular mechanical (MM) receptor:ligand binding free energy calculations for the purpose of making hybrid machine learning/MM (ML/MM) free energy corrections. Current ML implementations are with Torchani's ANI2x
model.
MM free energy calculations are conducted with Perses
The code is experimental and subject to change.
Installation
Install qmlify
master via git clone
:
git clone https://github.com/choderalab/qmlify.git
cd qmlify
python setup.py install
You will also need the latest conda
release of Perses:
conda install -c omnia perses
as well as a couple of classes from coddiwomple and Arsenic:
git clone https://github.com/choderalab/coddiwomple.git
cd coddiwomple
python setup.py install
git clone https://github.com/openforcefield/Arsenic.git
cd arsenic
python setup.py install
Use
qmlify
postprocesses perses
free energy calculations. You will need perses
MM relative free energy calculation data before you can post-process it with qmlify
Perses
See experiments/mm_data/README.md
for instructions on running perses
replica exchange relative free energy calculations. A set of pre-generated perses
simulation data is provided at experiments/mm_data
, which are queried and analyzed in a demonstration at experiments/free_energy_corrections.ipynb
.
qmlify
qmlify
uses bidirectional nonequilibrium (NEQ) free energy calculations to anneal from the MM thermodynamic states (afforded by perses
) to the hybrid ML/MM thermodynamics states (and back).
Once perses
free energy calculations are complete, you can extract and reformat the necessary perses
files for the purpose of conducting a MM-to-ML/MM corrections using:
from qmlify.executables import perses_extraction_admin
ligand_indices = [(0,12),(0,7),(10,13),(10,6),(11,0),(11,14),(14,2),(14,8),(14,9),(15,14),(15,4),(1,13),(1,6),(2,7),(3,0),(3,13),(4,12),(4,13),(4,14),(4,5),(4,9),(5,0),(6,0),(8,0)] # the full set of ligand index pairs for Tyk2
perses_extraction_admin(ligand_indices,
'<location of perses data directory to extract from>',
'<location of local directory to extract to>',
phases = ['solvent', 'complex'],
delete_execution=False)
Once you have switched to the extract_to
directory, execute forward
NEQ:
from qmlify.executables import propagation_admin
import os
propagation_admin(ligand_indices, annealing_steps=5000, direction = 'forward', parent_dir = os.getcwd(), extraction_indices = range(0, 200, 2), phases = ['solvent', 'complex'], write_log=True, cat_outputs=False, delete_outputs=False)
followed by resampling and decorrelation at the ML/MM endstate:
propagation_admin(ligand_indices, annealing_steps=5000, direction = 'ani_endstate', parent_dir = os.getcwd(), extraction_indices = 100, phases = ['solvent', 'complex'], write_log=True, cat_outputs=True, delete_outputs=False, eq_steps=5000)
and finally, backward
NEQ:
propagation_admin(ligand_indices, annealing_steps=5000, direction = 'backward', parent_dir = os.getcwd(), extraction_indices = 100, phases = ['solvent', 'complex'], write_log=True, cat_outputs=True, delete_outputs=False, eq_steps=5000)
These commands will generate .npz
files containing a numpy
array of cumulative reduced work values (for each ligand in each pair, for each phase, and for each trajectory launched), the last of which is the total reduced work performed on the trajectory over the protocol. Each work
file has a default form of lig{i}to{j}.{phase}.{old/new}.{direction}.idx_{snapshot_index}.{annealing_steps}.works.npz
where i
, j
are ligand index pairs, phase
is either 'complex' or 'solvent', old/new
denotes whether the work array corresponds to ligand i
(old) or j
(new), direction
is 'forward' or 'backward', snapshot_index
is which configuration index is annealed, and annealing_steps
denotes the number of integration steps in the NEQ protocol. Forward and backward work distributions can be extracted, and the free energy correction of each phase can be computed (in kT) with the Bennett Acceptance Ratio (BAR) to find the maximum likelihood estimate of the free energy.
The work
files can be queried and saved for each phase with:
import numpy as np
from qmlify.analysis import aggregate_pair_works, fully_aggregate_work_dict
work_pair_dictionary = aggregate_pair_works(ligand_indices, annealing_steps = {'complex': 5000, 'solvent':5000}) #this may take a few minutes
aggregated_work_dictionary, concatenated_work_dictionary = fully_aggregate_work_dict(work_pair_dictionary) #process the pair dictionary into something that is easier to analyze
np.savez('work_dictionaries.npz', aggregated_work_dictionary, concatenated_work_dictionary) #save into a compressed file
.See the function documentation for kwargs
in qmlify.analysis
for a more complete description. Once the work_dictionary.npz
is generated, see experiments/free_energy_corrections.ipynb
, which demonstrates how to query the work dictionary, calculate BAR free energy estimates, plot the work distributions per ligand, per phase, and perform MM-to-MM/ML free energy corrections (with plots).
Copyright
Copyright (c) 2020, Chodera Lab
Authors
- dominic rufa
- Hannah E. Bruce Macdonald
- Josh Fass
- Marcus Wieder
Acknowledgements
Project based on the Computational Molecular Science Python Cookiecutter version 1.3.
If you found this repository helpful, consider citing:
@article {Rufa2020.07.29.227959,
author = {Rufa, Dominic A. and Bruce Macdonald, Hannah E. and Fass, Josh and Wieder, Marcus and Grinaway, Patrick B. and Roitberg, Adrian E. and Isayev, Olexandr and Chodera, John D.},
title = {Towards chemical accuracy for alchemical free energy calculations with hybrid physics-based machine learning / molecular mechanics potentials},
elocation-id = {2020.07.29.227959},
year = {2020},
doi = {10.1101/2020.07.29.227959},
publisher = {Cold Spring Harbor Laboratory},
URL = {https://www.biorxiv.org/content/early/2020/07/30/2020.07.29.227959},
eprint = {https://www.biorxiv.org/content/early/2020/07/30/2020.07.29.227959.full.pdf},
journal = {bioRxiv}
}