Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for QM/MM #243

Merged
merged 273 commits into from
Oct 18, 2024
Merged

Add support for QM/MM #243

merged 273 commits into from
Oct 18, 2024

Conversation

lohedges
Copy link
Contributor

@lohedges lohedges commented Oct 10, 2024

This PR adds support for QM/MM simulations in Sire using OpenMM as the MM backend. Though the interface is primarily designed to facilitate support for ML/MM simulations using emle-engine it is completely general and can be used to interface with any external QM engine, or even to implement any custom time-dependent forced based on the local environment around some region.

Available QM engines are:

  • PyQMEngine: This is a general purpose Python callback that can be used to quickly prototype QM/MM code, or to interface with more complex external tools, e.g. those without an C++ or Python API, such as command-line executables.
  • TorchQMEngine: This provides direct support for Torch based ML models. Since Torch isn't (yet) available on WIndows via conda-forge, support for this engine is conditionally compiled.

The above are exposed to the user using the new Sire Python API via the sire.qm sub-module. Convenience functions, such as sire.qm.create_engine and sire.qm.emle simplify the creation of QM engines for running QM/MM dynamics with an existing Sire dynamics object.

QM molecules are treated with the same "perturbable" molecule framework that is used for alchemical free-energy simulations. This allows for interpolation between MM and QM potentials via a "lambda" parameter, which can be used for, e.g., end-state correction simulations.

The code also provides support for using EMLE with the existing OpenMM-ML framework, i.e. you can simply obtain the force used to compute the electrostatic embedding interaction, then add it to an existing OpenMM-ML mixed potential system.

As for BioSimSpace, an additional set of conditional requirements are defined in the requirements_emle.txt file, which allows Sire to be built in a environment that is self-consistent with the requirements of emle-engine. Rather than automatically including these requirements for all builds, I decided to expose them via the SIRE_EMLE environment variable. This allows us to easily disable the requirements, e.g. if we find conflicts for specific platforms, or if the additional requirements lead to unwanted constraints on the environment for other users, e.g. our industrial collaborators.

Note that I haven't selectively checked for CustomCPPImpl support. The logic doesn't work locally for me on Linux, so I needed to remove from my local repository. For the CI, we only ever build for version 8.1+, so this isn't an issue. We could re-instate the logic if you worry that someone might try to do a source build against an older OpenMM, although we should try to figure out why the logic fails. (I see the same problem for updateSomeParametersInContext too, but that will soon be redundant anyway.)

This PR also closes #244 by reinitialising the OpenMM context if constraints change when setting lambda. This is required for the constraint change to propagate context itself, i.e. setting the parameters in the system within the context is not enough. This is quite painful, since it's an expensive operation. Thankfully constraints are only set to lambda specific values at the outset of a simulation and aren't updated when computing energies at other lambda values. This could cause issues for multistate sampling methods, such as HREX, though, where we would need to update the constraints when swapping lambda. If this becomes a problem then we can look deeper into OpenMM itself to see if there are optimisations to make.

  • I confirm that I have merged the latest version of devel into this branch before issuing this pull request (e.g. by running git pull origin devel): [y]
  • I confirm that I have added a test for any new functionality in this pull request: [y]
  • I confirm that I have added documentation (e.g. a new tutorial page or detailed guide) for any new functionality in this pull request: [y]
  • I confirm that I have added a changelog entry to the changelog (we will add a link to this PR as part of the review): [y]
  • I confirm that I have permission to release this code under the GPL3 license: [y]

Suggested reviewers:

@chryswoods

@@ -246,7 +247,7 @@ bool LambdaLever::operator==(const LambdaLever &other) const
name_to_restraintidx == other.name_to_restraintidx and
lambda_schedule == other.lambda_schedule and
perturbable_mols == other.perturbable_mols and
start_indicies == other.start_indicies and
start_indices == other.start_indices and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice typo fix

chryswoods
chryswoods previously approved these changes Oct 17, 2024
Copy link
Contributor

@chryswoods chryswoods left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is all excellent. I really like the new tutorial. Very worthy addition for the 2024.3.0 release :-)

@chryswoods
Copy link
Contributor

Also just to say the whole code feels really coherent. This is a very powerful new bit of functionality

@lohedges
Copy link
Contributor Author

Thanks, I'm looking forward to it having a bit more visibility. I'm very thankful to the current users who have helped find bugs and iron out the rough edges.

@lohedges lohedges merged commit 4d94050 into devel Oct 18, 2024
@lohedges lohedges deleted the feature_emle branch October 18, 2024 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[BUG] Constraints in OpenMM context aren't updated
3 participants