TITLE: How to Assign CHARMM Parameters to Desmond-generated System with viparr4
AUTHORS: Dmitry Lupyan

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block">You can use the Schrödinger software suite to prepare systems for molecular dynamics simulations, however, only the OPLS _2005 and OPLS3e force fields can be automatically assigned. This tutorial will show you how to use Desmond with third-party force fields like CHARMM, using the Viparr utility from D.E. Shaw Research.</div><div class = "text-block">You will prepare a protein-ligand complex, generate custom CHARMM parameters for the ligand, and use the Viparr utility to convert the generated CHARMM parameters into a viparr-formatted template, that can be used for simulations. </div><div class = "text-block"><span>You can find the input files for this tutorial here: </span><a href="#" style = "text-decoration:underline;color:blue;cursor:pointer;"><span style = ":;"> </span></a><span style = ":;"> </span></div></div>

[STEPS]
?. [Setting up a Schrödinger Python Environment]
Set up a Python Virtual EnvironmentIn order to avoid compatibility issues with the Python modules, and ensure interoperability with Schrödinger's Python modules, use the Schrödinger software to create a new virtual environment.
?. [Setting up a Schrödinger Python Environment]
Install the Viparr and Msys UtilitiesViparr is a utility developed by D.E. Shaw Research to assign force field parameters to systems, which can then be used to perform MD simulations with Desmond.
?. [Running an MD Simulation with Desmond]
Now that the system is prepared with CHARMM parameters, Desmond can minimize, equilibrate, and run an MD simulation of the system. For further information check the Desmond User Manual.
?. [Running an MD Simulation with Desmond]
Set up an MD SimulationIn Maestro, go to Tasks → Desmond → Molecular Dynamics to open the Molecular Dynamics panel.In the Model system section, choose Import from a file, and click Browse to locate and load charmm-start.cmsIn the Model system section, select Import from file, browse to the file charmm-start.cms, and click Load.Optional: Adjust simulation parameters, such as simulation time. Ensure the Relax model system before simulation checkbox is selected.Optional: Enter a job name, click the gear icon to change job settings, or click the ? icon to open the Help for more information.Click Run to start the MD simulation.
?. [Running an MD Simulation with Desmond]
Analyze the ResultsIn Maestro, go to Tasks → Desmond → Simulation Interactions Diagram (SID) and run the analysis. For comparison, we ran a 10 ns MD simulation. The SID report is attached as PDF:
?. [Assigning CHARMM Force Fields to the Molecular System]
Now, we can reassign the CHARMM force field to the CMS file.  The viparr utility comes with standard sets of protein parameters which we can use for the protein. For the ibuprofen ligand, we can use the viparr template in the directory IBP.
?. [Preparing the Protein-Ligand Complex for Simulation]
First, we download a structure from the protein data base (PDB) and prepare the protein-ligand complex. This tutorial uses a PDB structure  for the human adipocyte lipid-binding protein FABP4 in complex with (S)-ibuprofen (PDB ID: 3p6h).We build the system with Schrödinger's Maestro and Desmond tools. The default force field used by the Schrödinger software is OPLS_2005 (OPLS3e if you have a license). After building the system for MD simulations, we can reassign the forcefield using Viparr.  To prepare the system for MD, open Maestro and follow these steps:
?. [Preparing the Protein-Ligand Complex for Simulation]
Prepare the Protein-Ligand ComplexIn Maestro, go to Tasks  → Protein Preparation and Refinement  → Protein Preparation Wizard or click Protein Preparation in the toolbar.In the Protein Preparation Wizard, enter ‘3p6h’ in the PDB text box, and click Import to download the structure from the PDB database and import it into Maestro.After the PDB has been imported into the 3D workspace, preprocess the protein and the ligand. In the Protein Preparation Wizard, make sure the following options are selected:Assign bond ordersAdd hydrogensCreate disulfide bondsCap terminiFill in missing side chains using Prime (requires a Prime license)Click Preprocess.The Protein Preparation Wizard runs structural sanity checks and displays potential issues in a warning. In this tutorial, you can safely ignore these warnings and click OK to close the warning. In real applications, you should pay close attention to these warnings and resolve issues that may lead to problems during the MD simulations. After the Protein Preparation Wizard finishes, a protein-ligand complex is added to Maestro's Workspace where formal charges, protonation states and bond orders are assigned and hydrogen atoms are added to the protein, ligand and crystallographic water molecules.
For the 3p6h structure, the Protein Preparation Wizard shows missing atoms on the terminal residues. Since we cap the terminals, this is not an issue. Further, overlapping atoms and alternative residue positions can be ignored for this tutorial.
?. [Preparing the Protein-Ligand Complex for Simulation]
Solvate and Neutralize the Protein-Ligand ComplexNow that we have a protein-ligand complex loaded in the Workspace, we can solvate and neutralize the complex to prepare it for MD simulations.In Maestro, go to Tasks → Desmond → System Builder to open the System Builder.Click Run to build the system with the default settings. By default, a water buffer of 10 Å and neutralizing counterions are added to the protein-ligand complex. The System Builder also assigns OPLS_2005 force field parameters (or OPLS3e if you have a license) to the protein-ligand atoms using SPC as the model for water. After the System Builder finishes, a solvated system is added to Maestro's Workspace. The solvated system is also saved to a file desmond_setup_1-out.cms.
?. [Generating Custom CHARMM parameters]
To simulate a molecule that is not covered by the standard CHARMM parameter set, you first need to obtain topology and parameter files for that molecule. You can obtain parameters from one of these sources: Search the CHARMM message board to see if anyone else is willing to share their parameters: CHARMM forumsAdopt parameters from the literatureUse other computational chemistry tools to generate parameters, see the following:A. D. MacKerrel’s slide deck: PDF linkN. Foloppe and A. D. MacKerell (2000). JCC 21 (2): DOI linkUse the CHARMM General Force Field (CGenFF) facility: website, DOI linkUse the Paratool plugin for VMD: websiteUse the SwissParam server: website, DOI linkYou can use any of the above methods to generate CHARMM-compatible parameters.In this tutorial, we use the SwissParam server to generate topology and parameter files.  Please refer to the original SwissParam documentation for more details on parameterization methods.
To ensure that the parameters you intend to use are the ones that are being assigned, it is best if the topology and parameter files are self-contained and do not depend on other parameter files.
?. [Generating Custom CHARMM parameters]
Export the Ligand as Mol2 FileThe 3p6h complex contains a ligand: Ibuprofen (IBP). This ligand is not part of the standard CHARMM parameter set so you have to get its parameters from the SwissParam web server.The SwissParam server requires the ligand structure in a .mol2 file. To prepare a .mol2 file with the prepared ligand structure, follow these steps: Select the ligand atoms in Maestro's Workspace, right-click the selected atoms and select Create New Entry by → Copying Selected Atoms. This creates a new entry in Maestro only containing the ligand atoms.Select the ligand entry in the Entry List on the left side of Maestro, right-click and select Export  → StructuresEnter 'ibp.mol2' as file name.
?. [Generating Custom CHARMM parameters]
Convert the CHARMM Parameters to a Viparr TemplateThe parameters need to be converted into a format that you can use with Desmond, enter the following command to generate a viparr-formatted template: [schrodinger.ve] %> viparr-convert-charmm -p ibp.par -t ibp.rtf IBPAfter the program finishes, a new directory IBP is created, which contains the viparr-formatted CHARMM template for Ibuprofen.
The SwissParam web server renames the ligand's residue name to 'LIG'. Since viparr uses structure-matching to assign force  field parameters, this is not an issue.
?. [Setting up a Schrödinger Python Environment]
Initialize a new Python virtual environment using the Schrödinger software:%> $SCHRODINGER/run schrodinger_virtualenv.py schrodinger.ve
?. [Setting up a Schrödinger Python Environment]
Activate the virtual environment:%> source schrodinger.ve/bin/activate
?. [Setting up a Schrödinger Python Environment]
Upgrade pip:[schrodinger.ve] %> pip install --upgrade pip
?. [Setting up a Schrödinger Python Environment]
Download these two Python packages from D.E. Shaw Research's GitHub repository:MsysViparrThese packages are distributed in the Python 'wheel' format, compatible with 'manylinux2014' Linux distributions.
?. [Setting up a Schrödinger Python Environment]
Install the packages into the virtual environment[schrodinger.ve] %> pip install msys-1.7.318-cp38-cp38-manylinux2014_x86_64.whl[schrodinger.ve] %> pip install viparr-4.7.35-cp38-cp38-manylinux2014_x86_64.whl
?. [Setting up a Schrödinger Python Environment]
Clone the public Viparr parameters from D.E. Shaw Research's GitHub repository:[schrodinger.ve] %> git clone git://github.com/DEShawResearch/viparr-ffpublic.gitAlternatively, you can download the repository as ZIP archive: viparr-ffpublic
?. [Setting up a Schrödinger Python Environment]
Set the VIPARR_FFPATH environment variable[schrodinger.ve] %> export VIPARR_FFPATH=`pwd`/viparr-ffpublic/ff
?. [Generating Custom CHARMM parameters]
Generate Custom CHARMM Parameters with SwissParamUpload the file ibp.mol2  to the SwissParam web server and click Submit. After the SwissParam web server finishes, a ZIP file ibp.zip is generated which contains these results:CHARMM topology file: ibp.rdfCHARMM parameter file: ibp.parExtract these files from the ZIP archive.
?. [Assigning CHARMM Force Fields to the Molecular System]
Run ViparrTo reassign the force field to CHARMM, enter the following command: [schrodinger.ve] %> viparr desmond_setup_1-out.cms charmm-start.cms -f aa.charmm.c36m -f ions.charmm36 -f water.tip3p_charmm -d IBPImporting forcefield from /home/user/viparr-ffpublic/ff/aa.charmm.c36mImporting forcefield from /home/user/viparr-ffpublic/ff/ions.charmm36Importing forcefield from /home/user/viparr-ffpublic/ff/water.tip3p_charmmImporting forcefield from IBPImporting structure from desmond_setup_1-out.cmsWARNING: will NOT fix prochiral atom names because rename_atoms or rename_residues was not enabledExporting parametrized system to charmm-start.cmsVIPARR exited successfullyThis command assigns the CHARMM36m parameters to the proteins and ions, uses CHARMM's Tip3p water model, and uses the template directory IBP for the ibuprofen ligand. After viparr finishes, a new file: charmm-start.cms is created which contains the structure and CHARMM force field information.
?. [Assigning CHARMM Force Fields to the Molecular System]
Clean Properties and Prepare for MDTo prepare the converted system for MD simulations, certain properties need to be removed from the CMS file and the full-system structure needs to be prepared. Run the Python program:%> $SCHRODINGER/run gen_fsys.py charmm-start.cmsThis script will overwrite the file charmm-start.cms. The system is now ready for simulation.