Questions about imitating your QM/MM interface

[Wodnerstruck]

Dear Dr. Ragnar Bjornsson:
I am a PhD student in Theoretical Chemistry, and I would like to follow your program to provide an interface to OpenMM for our group's own QM program, but I don't want to write it as large as your Ash. We need to implement QM/MM single-point computation and QM/MM MD, on top of which we can add functions such as energy decomposition analysis. I would like to know what parts I need to keep from your code and what parts can be removed?
Thank you for your help!

[RagnarB83]

ASH is a pretty light-weight code in general and is meant to be a general approach to QM/MM. Bespoke standalone interfaces are in my opinion a thing to avoid.

Why don't you just create a new interface within ASH to your group's QM program?
Then you have access to all of ASH's features and you only use (or import) the ones you want to use.
You can mimic one of the QM-code interfaces here:
https://github.com/RagnarB83/ash/tree/master/ash/interfaces

Basically you would just create a MyQMcodeTheory class in a new file, make sure it has the basic init, run and cleanup methods. You can then add other methods or standalone functions within the same file.
I'm happy to help out but only if you make the interface public.

[Wodnerstruck]

ASH is a pretty light-weight code in general and is meant to be a general approach to QM/MM. Bespoke standalone interfaces are in my opinion a thing to avoid.

Why don't you just create a new interface within ASH to your group's QM program? Then you have access to all of ASH's features and you only use (or import) the ones you want to use. You can mimic one of the QM-code interfaces here: https://github.com/RagnarB83/ash/tree/master/ash/interfaces

Basically you would just create a MyQMcodeTheory class in a new file, make sure it has the basic init, run and cleanup methods. You can then add other methods or standalone functions within the same file. I'm happy to help out but only if you make the interface public.

Thanks for your response! The reason I wanted to rewrite a short version is that to me the structure and logic of the ash code seemed complicated. But I am also not familiar with the use of OpenMM and its interface calls, so I wanted to keep the important code about OpenMM.

Since you recommend me to create a new interface within ASH directly, I will do as you say and the code will be public!

If I want to write a new interface to implement QM/MM single point energy, structure optimization and MD or metaMD, what parts of the code do you recommend I read at least first? Which parts of the code should I focus on and which can I familiarize myself with later? Do you have a document like a developer's manual?

By the way, I see that your interface supports many QM programs, which is a feature not found in many popular QM/MM interface programs, so it might be a good idea to publish its description as a journal paper, so that we can cite your article when we use the interface added to ash in the future!

[RagnarB83]

I can understand that it may look complicated since ASH is trying to accomplish a lot of things but underneath it is actually quite simple and modular. Source-code comments may not always be that great, though.
A developer's manual is a great idea, unfortunately not available, hopefully one day. What would be nice right now to have, is a simple guide to creating an interface for a new QMcode, like your case. I will try to see if I can throw something together soon.
An ASH paper is finally being written that will describe the code in detail, should be submitted relatively soon.
Getting all of the details of QM/MM and the OpenMM interface was months of work, I don't really think you want to repeat any of that process or try to maintain a portion of it.

The key thing about ASH is that supporting a new QM code is really quite easy. You just need to create a new Class in a new Python source file, that mimics one of the existing classes and if everything is done right within the class (including the QM-pointcharge handling) then all the QM/MM coupling, geometry optimization, dynamics and metadynamics will work automatically without you having to touch any of the code behind those modules.

If you want to understand how ASH works in a top-down fashion, take a look in those order:

1. Singlepoint energy function: https://github.com/RagnarB83/ash/blob/bdf9c896126df7f0353948805629a07d305e78a5/ash/modules/module_singlepoint.py
   You will notice that the function calls the run method within a theory object. That theory object can be a QMTheory object or a QMMMTheory object. Most ASH job functions (e.g. Optimizer) will do a theory.run like shown in this function.
   For a new QMcode-interface, nothing would change in this file.

2. The QMMMTheory class is decribed here:
   https://github.com/RagnarB83/ash/blob/bdf9c896126df7f0353948805629a07d305e78a5/ash/modules/module_QMMM.py
   Notice that it knows nothing about any specific QMTheory interfaces but there are some OpenMMTheory-specific things there (this is because OpenMMTheory has special status within ASH). A QMMMTheory object almost always links together some QMTheory object and an OpenMMTheory object.
   For a new QMcode-interface, nothing would change in this file.

3. The OpenMMTheory class is here: https://github.com/RagnarB83/ash/blob/bdf9c896126df7f0353948805629a07d305e78a5/ash/interfaces/interface_OpenMM.py
   The class and this file is probably the most complicated within ASH, the file also contains a lot of stuff that will eventually be moved elsewhere.
   Notice that there is nothing QM-code specific in the OpenMMTheory class at all.
   For a new QMcode-interface, nothing would change in this file.

4. Let's now take a look at the interface for a specific QM-code. Here choosing the NWChem program as the interface to the program is relatively simple, yet it fully supports QM/MM.
   If you search the ASH repository for "nwchem" you will find that code dealing with the NWChem program is limited to the files:

• ash/interfaces/interface_NWChem.py
• ash/init.py (a line importing NWChemTheory to the namespace)
  (other search hits are just mentions of nwchem in a different context)

This should give you a hint that supporting a new QM code within ASH would be as simple as creating a new file: interface_XXXX.py
as well as adding an equivalent line to ash/init.py

The interface_NWChem.py file:
https://github.com/RagnarB83/ash/blob/bdf9c896126df7f0353948805629a07d305e78a5/ash/interfaces/interface_NWChem.py

contains the following:
A NWChemTheory class with the following methods: init, run, set_numcores.
The file also contains some independent functions that are outside the class (to make the logic of the class easier to understand).
The entire interface is 292 lines. Assuming the code works similar to NWChem (i.e. uses an ASCII inputfile, writes to an outputfile etc.) then this is roughly what you would have to mimic for a new QMcode. If it's radically different then the interface may have to look different but very likely you can find a template in one of the other interfaces.

What is the QM-code in question btw?
Send me an email if you want to discuss privately btw.

[Wodnerstruck]

Thanks for your help, I will fork your master branch and try to add a new interface, if in doubt I will ask you via email, thanks again!

[RagnarB83]

Sounds good, keep me posted.

[RagnarB83]

A very preliminary guide to writing a new QM-code interface:
https://ash.readthedocs.io/en/latest/Dev-writing-newQMinterface.html

and:
https://github.com/RagnarB83/ash/blob/NEW/ash/interfaces/interface_example.py