[TUTORIAL] Steered MD

[lohedges]

This is a thread to discuss the creation of a tutorial showing how to implement steered molecular dynamics in BioSimSpace.

[jmichel80]

Adding current diagram summarising use case:

[AdeleHardie]

I have started testing GROMACS+PLUMED for steered MD here.

I looked at BioSimSpace.Metadynamics.CollectiveVariable and the only available ones at the moment are distance, funnel and torsion. So for now I prepared PLUMED input and structure reference files as I did before, and it was simple to add PLUMED used usage to BioSimSpace.Protcol.Production through using BioSimSpace.Process.Gromacs.setArgs().

I have also looked at creating a BioSimSpace.Protcol.Metadynamics with a dummy BioSimSpace.Metadynamics.CollectiveVariable.Distance and simply modify the plumed.dat file to change to RMSD, but it uses METAD whereas I've been using MOVINGRESTRAINT. An alternative would be to simply replace that file completely, and that would save the need to extend the command line arguments of the protocol. That however doesn't change the need for an appropriately numbered and weighted reference structure which I don't think BSS prepares at the moment.

[AdeleHardie]

Following today's discussion, I'm linking the functions I use to prepare input PLUMED files for steered MD. renumber_pdb() and rmsd_reference() here are used to prepare the reference PDB structure, and steered_md_plumed_input() here prepares plumed.dat.

The CV itself (RMSD here) and the MOVINGRESTRAINT in PLUMED are separate so it should be easy to extend this to other CVs.

[lohedges]

Thanks, @AdeleLip, that's really useful. I'll see what's possible to re-implement within BioSimSpace.

FYI: I've just pushed an update that adds a .getFrame method to all BioSimSpace.Process classes. This allows you to extract individual trajectory frames from a process, rather than first having to get the entire trajectory, or pass the full paths to the trajectory and top files to BioSimSpace.Trajectory.getFrame. The indices are validated against the expected range and the method returns None if a corresponding frame isn't found. Note that the SOMD trajectory writer is a bit funky so there is sometimes a mismatch between the number of frames written in the header and what is actually in the file. GROMACS also is sometimes off by one too, i.e. there is one extra frame in the file.

[lohedges]

Yes, most functionality for doing this already exists in BioSimSpace so I'll cook up an example tomorrow. Do you have example input files for the system and target (RMSD reference) that you could share? (Perhaps they are already in the repository, but I missed them.)

Would the system and target normally be separate files to begin with, or could the target be extracted from the system with the coordinates replaced with the those of the desired target conformation? I'm just trying to figure out the logical workflow within BioSimSpace, i.e. would the user load two PDB files to start with, one for the system, one for the target, or could we actually create the target in BioSimSpace? (Apologies for any incorrect notation.)

[AdeleHardie]

Yes I've adjusted the trajectory analysis notebook to use getFrame() and it works great for extracting snapshots.

Here are some example input files. The system files are just results of equilibration, and the target is a crystal structure (with a bit of modification since I use it to prepare other systems).

The way I prepare RMSD reference is to simply take the PDB file and replace the atom indices with the corresponding atom indices from the system itself. I wrote that code very early on (before I used BSS), but it simply loops over all of the residues of the system and the target protein, and within each residue finds atoms with the same names, then changes target protein indices with the ones from the system. This assumes that the proteins have the same sequence start (e.g. in my case the target has to have an ACE cap as well) but can handle things like hydrogens missing from the reference PDB (so you can get residues with indices like [6, 8, 10] where the hydrogens were just ignored).

One of the things that it doesn't handle (which I think it really should) is to check that the sequences match, e.g. that the residues with the same index have the same name. Because of the nature of my system, the renumbering gets cut off when it reaches the NME cap, which in the target is a GLY, so only the N atom matches and gets carried over. It isn't used for RMSD calculations and doesn't affect the alignment for this particular system but this is a patchy solution.

It could also be possible to replace the system coordinates with those extracted from the PDB, and then save the BioSimSpace molecule as a PDB for plumed to use. I get the indices directly from the whole system PDB, which can be useful especially if the protein isn't the first molecule, but I remember you mentioning you have ways to deal with that.

[lohedges]

Thanks for the detailed explanation. For the example files that you provided there are residues in the target PDB that aren't found in the system. Using the Sire/BioSimSpace search functionality I find 284 out of the 301 residues. Is this to be expected? If so, can I safely ignore any unmatched residues and only update the indices of the ones that I find.

With regards to the PDB file required by PLUMED: Do you use the target PDB with the indices updated (and the beta and occupancy columns tweaked)? Would it also work if I wrote a PDB for the corresponding molecule in the system after updating the coordinates? (Perhaps only writing the residues that match.)

[AdeleHardie]

In this case the target protein (WPD loop closed) sequence is a bit longer than the system (WPD loop open) since the C terminus of the WPD loop open is disordered and we are modelling this protein truncated. It is safe to ignore any unmatched residues, since PLUMED doesn't care about continuity, just the atom index. In some of their RMSD examples they only pass the few atoms they want to use for the calculation (we need the others for system alignment, but it illustrates the point).

I use the target PDB with the indices updated and then the beta and occupancy columns tweaked. All PLUMED needs is that the indices are the same between the target and the system, and the two columns let it know which indices to use for alignment and which for RMSD calculation. So if it's easier in BSS to find the matching residues/atoms and update coordinates in some copy of the system that should work perfectly.

[AdeleHardie]

I have now added some more tutorial background in the setup-sMD notebook. Some of it is subject to change depending on what you decide to implement in BSS, but it might also give more background on how I prepare the simulation at the moment.

[lohedges]

Okay, here is an archive containing a hokey script that uses Sire/BioSimSpace to create a PDB file for PLUMED. Just run test.py in the extracted directory, which should create a test.pdb output (which is already included, in case you don't want to run it.) Could you check this file and see if it all looks okay?

The logic is as follows:

• Load the system and the target.
• Match residues in the target to those in the system by name, and work out the unique molecule to which they match, i.e. all target residues must match to a single molecule of interest.
• Remove duplicate matches (there will be residues with the same name) by looping through the residues in the target and taking the first match from the system until we've exhausted all matches. If the residue was already matched, we take the next, and so on. As mentioned above, we don't end up matching all residues from the target, since the molecule in the system is a truncated version. The molecule in the system has 284 residues and the target has 301. I match 277 of the target residues.
• Create a mapping between the residue indices in the system to those in the target.
• Loop over residues in the system. If it is in the map, then loop through atoms and match by name against the first match in the target, copy across coordinates and set occupancy and beta factor. If it's not, then use normal coords and set occupancy / beta to the opposite value.

The code would be simplified massively if we could be sure that the target PDB file contained all residues from the matching molecule in the system, since we could use the ResIdxAtomNameMatcher from Sire.Mol. This would directly return a mapping between the atoms in the system that match those in the target. Here I guess the target PDB might contain a subset of the molecule, so we might be missing residues, or there could be gaps in the indexing. Let me know if this isn't the case and I'll simplify the code. (The current implementation could be causing by taking the first match it finds.)

I've not extensively tested this, so let me know if there is something obviously wrong with the logic. For example, I'm not sure if I'm correctly setting the occupancy and beta factors for atoms that aren't matched, or whether I'm including too many atoms in the PDB. (It contains the entire molecule from the system.) It should also work for cases where the matched molecule isn't the first in the system (which it is in this example). The PDB writer already uses the atom number, which accumulates across all molecules, rather than the index, which counts from 0 for each molecule.

It should be easy for me to revise this to get something that works a little more robustly.

Cheers.

[lohedges]

Note that if we don't need additional info in the PDB file, e.g. MODEL and CONECT records, then we can use Sire.IO.PDB2 directly and strip these from the output.

[AdeleHardie]

I think the problem at the moment is the beta and occupancy columns - with how they are now, PLUMED will use the atoms that do not exist in the target structure to align the system and the all the atoms that matched to calculate the RMSD.

I can see you are copying the molecule and updating coordinates. In that context the logic once you've created the atom mapping I think should be:

1. Loop over each atom in the copy molecule
2. If it does not exist in target, delete it
3. If it does exist in the target but does not fall in the 'RMSD residue' range, set the occupancy column to 1.00 and beta to 0.00
4. If it does exist in the target and does fall in the 'RMSD residue' range, set the occupancy column to 0.00 and beta to 1.00

At the moment the alignment will be carried out to the first frame of the system's H atoms and some left over residues, which wouldn't work to correctly align to the target structure, and the RMSD would be calculated to the entire protein, which also wouldn't make steering possible. I'm attaching example renumbered and modified target files to illustrate this (apologies, I should have included them before).

About simplifying the code, in this case it would be easy to make the target PDB contain only what it contained in the system, since I could just also truncate it and leave out the N terminus cap, that would only require deleting some lines. But in the cases where it is swapped around, i.e. the system has the loop closed (and 301 residues) and the target has the loop open (and 284 residues) that would involve adding those residues to the target structure, and I'm not sure if the additional residues would throw off alignments. This is what I meant by saying RMSD is annoying to work with...

I see the script does a lot of things to determine which molecule the target structure is for - could we just ask the users to specify this? From my own usage of the scripts, I wouldn't mind that at all. Then there could be two assumptions to make:

1. All the residues in the target PDB appear in the system
2. All the residues indices in the target PDB are the same as in the system (i.e. residue 20 in target is the same as residue 20 in system, even though some atoms may be missing)

I feel like those are reasonable expectations and would only need some modification when preparing target structure. This would be able to handle mismatched sequence length (assuming they are numbered accordingly) and also gaps in the system (full residues and one off atoms). The only issue for the user would be to make sure the residues are numbered correctly if there is an offset (e.g. sequence start is longer in the system or the target) or if there are any gaps. What do you think?

[lohedges]

Ah brilliant, thanks for the clarification, I thought I was missing something obvious ;-) I had also assumed that all atoms in the target PDB that appear in the system were used for the RMSD, rather than using a subset of the atoms using the "RMSD residue range". (Looking again at your code, this is obvious.)

I think both of the assumptions that you suggest are perfectly sensible and would massively simplify the problem. If we are clear with the expectations for the target PDB file, then it will likely save a lot of headaches. The only reason for trying to detect the target molecule was in case the system had been re-ordered since it was originally loaded. I am imagining a situation where the user might load a single molecule, then solvate it, do some other operations, delete things, recombine things, etc. If we make the assumption that all residues in the target PDB are in the system, then this would simplify the search too. (I imagine we could just take the molecule with the closest number of residues, which would likely work in the majority of cases.) We could provide an option to pass the index, which always takes precedence. (For example, this is what I do with the funnel metadyamics code when detecting the ligand.)

With regards to the "RMSD residue range": Is this always contiguous, or are there cases were you might want multiple ranges, or the ability to pass specific indices rather than a range, or a combination of indices and ranges? This would complicate the atom matching a little, but it could be broken up into stages for each contiguous chunk.

I'll rework things on Monday.