ARM Web Interface - Tutorial

Luca De Vico

August 19, 2017 – Ver. 0.1

This tutorial describes how to use the current version of the Web interface toARM (from here on called WARM). Following the first part of this tutorial, youwill learn how to perform a simple ARM QM/MM calculation on a rhodopsinprotein. In the second part of this tutorial, you will learn how to introducepoint mutations in the protein sequence, and to compute the resulting changein lambda max.

The entire ARM protocol is described in “Toward Automatic RhodopsinModeling as a Tool for High-Throughput Computational Photobiology” J. Chem.Theory Comput., (2016), 12, pp 6020-6034. If using WARM, please cite the pre-vious article.

Contents

I Tutorial 1: first steps with WARM 3

1 Introduction 4

2 Access the web page 4

3 Select a rhodopsin structure 5

4 Prepare the ARM calculation 7

5 Checking a running calculation 10

6 Retrieve a calculation output 12

II Tutorial 2: introducing point mutations 14

7 Introduction 15

8 Preparation 15

9 Insert mutations 15

1

10 Checking the calculation 17

11 Retrieve and analyze the results 1711.1 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911.2 Data analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

III Appendix 20

A Output Tutorial 1 21

B Output Tutorial 2 22

List of Figures

1 The initial page. . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 The companion web page. The list of available rhodopsins will

soon include more structures than those reported here, includingexperimental absorption maxima. . . . . . . . . . . . . . . . . . . 6

3 The beginning of the WARM interface page. . . . . . . . . . . . . 74 Filling up the cavity residues. . . . . . . . . . . . . . . . . . . . . 85 The middle part of the interface, relative to point mutations. . . 86 The lower part part of the interface, relative to dynamic and

QM/MM calculations. . . . . . . . . . . . . . . . . . . . . . . . . 97 An example of possible output when checking for a still running

calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 An example of possible output when checking for a completed

calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Introducing mutations in the protein sequence. . . . . . . . . . . 1610 Example of possible output when checking for a just submitted

calculation, including mutations of the protein sequence. . . . . . 1711 Example of possible output when checking for a completed cal-

culation, which requested also a mutation of the protein sequence. 18

2

Part I

Tutorial 1: first steps withWARM

3

1 Introduction

In this tutorial, you will learn how to use WARM to:

• select an appropriate rhodopsin geometry;

• prepare a set of different protein geometries through the usage of moleculardynamics;

• for each geometry, perform a QM/MM geometry optimization;

• for each optimized geometry, compute QM/MM excitation energy, whichgives the computed absorption maximum (lambda max).

2 Access the web page

Open your favorite web browser, and type the following address:

www.web-arm.org

Figure 1: The initial page.

You will be presented with a simple page (Figure 1), offering you to performthree different tasks:

• perform a ARM calculation;

• check the status of a previous ARM calculation;

• open the WARM companion web page.

During this tutorial we will see what each task does.

4

3 Select a rhodopsin structure

The first step to any ARM calculation is to select an appropriate rhodopsinstructure. This is done by downloading the corresponding structure in pdb fileformat (www.rcsb.org). ARM has a certain flexibility in reading pdb files, butonly up to a certain point. The ARM protocol article describes in details therequirements for a correct pdb file.

Moreover, WARM is, at the moment, unable to:

• check the correctness of a given pdb file;

• check the overall charge of a given pdb structure;

• distribute the necessary counter ions to achieve neutrality;

• compute which residues should be considered as part of the cavity.

Future versions of the interface will tackle all of these issues. For the moment,it is up to the users, of their supervisors, to provide WARM with a suitablestructure, along with correct ionization states, overall charge and conterions,and information about the retinal cavity.

However, to obviate to this problem, we provide a set of already checked andprimed structures in the “Companion Web Page”. This set represents a numberof structures that have already been studied, and are meant to provide a basefrom which start new studies, as, e.g., what described in Part II.

The first step of this tutorial is, then, to click on the “Rhodopsins” buttonon the right. This will take us to the companion web page, as shown in Figure 2.

From the list of available rhodopsins, select one and download its pdb fileto your computer. Moreover, click on its corresponding cavity file. This willopen a new page which reports all residues that we recommend to use as cavityresidues. It is obviously possible also to download such file to your computer.Finally, back on the companion web page, take note of the type of retinal, suchas all-trans, 11-cis, 13-cis, and all-trans with charge 0. For the purposes of thistutorial, select “Bovine Rhodopsin”, thus downloading its pdb file, opening thecavity file and noting that its retinal is 11-cis.

Please note: future versions of the companion page will allow to directly passthe information relative to a given structure directly to the “Compute” page.

5

Figure 2: The companion web page. The list of available rhodopsins will sooninclude more structures than those reported here, including experimental ab-sorption maxima.

6

4 Prepare the ARM calculation

We are now ready to start an ARM calculation. First step is to go back to theinitial page, and then to click on “Compute” on the left. This will take us tothe core page of WARM. The first step for WARM is to provide information toit, as shown in Figure 3.

Figure 3: The beginning of the WARM interface page.

In the top part of the interface page, the user has to provide WARM withthe structure to use for the calculation, in pdb file format. You can upload thestructure of Bovine rhodopsin that was just downloaded from the companionpage. Furthermore, WARM requires a valid email address, to which send com-munications about the status of the ARM calculation. Please, insert your emailin this field.

Afterwards, you should choose which type of retinal is included in the up-loaded structure. In the case of bovine rhodopsin, the retinal is in its 11-cisconformation, and thus you can accept the default value.

Finally, the user must enter the number of cavity residues, and their id.

7

This is reported in the cavity file we previously opened. It might be helpfulto show side-by-side the cavity file and the interface, to help you out filling upthese fields, as shown in Figure 4. Please note that cavity residues are a strictrequirement for any ARM calculation.

Figure 4: Filling up the cavity residues.

The middle part of the interface deals with introducing point mutations inthe protein sequence, and will be discussed in details in Part II. For this tutorial,you can leave the selection to the default “No”, as shown in Figure 5.

Figure 5: The middle part of the interface, relative to point mutations.

The lower part of the interface (Figure 6) deals with the details of the startingdynamics, the number of such dynamics, and some general behavior of theQM/MM calculations.

For the purposes of this tutorial, insert “5” where the interface asks for “In-sert how many dynamics to run”, instead of the default (and maximum allowed)10. This is to speed up the overall calculation and reduce the computationalresources necessary to run it. You can leave all other values to their defaults.

8

Figure 6: The lower part part of the interface, relative to dynamic and QM/MMcalculations.

We recommend to use the default values for most production runs, and changethem only for testing purposes. Check the original ARM article for an explana-tion of the various terms. Future version of the interface will, likely, include thepossibility for further customization of the parameters relative to the QM/MMcalculations.

Now you are ready to run your first ARM calculation! Press the “Compute”button at the bottom of the page. You will see a short message that will reca-pitulate the information you entered, plus will give you the calculation UniqueID. You will need this number to check the status of your calculation, and toretrieve its results, as described in Section 5. You will also receive an email witha similar message, reporting the Unique ID, too.

9

5 Checking a running calculation

Once you successfully submitted a calculation with WARM, the interface willneed at least one one-and-half days to perform all steps, and possibly moretime depending on the available resources on the cluster. To check the statusof a calculation, open again the starting interface page. In the middle pane(Figure 1), write the Unique ID of the calculation you wish to check, which youreceived by email, and then press “Check”.

The interface will present you with something resembling what shown inFigure 7. The page will report some basic data of what was your input, andthe status of the calculation, relative to each starting dynamic run. For eachdynamic, there are 8 steps that need to completed. These are:

Step 1: the actual dynamic calculation with GROMACS;

Step 2: first QM/MM geometry optimization, at the SCF level;

Step 3: QM/MM single point energy calculation at the CASSCF/3-21G* level;

Step 4: second QM/MM geometry optimization, at the CASSCF/3-21G* level;

Step 5: QM/MM single point energy calculation at the CASSCF/6-31G* level;

Step 6: third QM/MM geometry optimization, at the CASSCF/6-31G* level;

Step 7: QM/MM single point energy calculation at the CASPT2//SA-CASSCF/6-31G* level;

Step 8: final collection of the obtained results

Each step can be in any of the following states: R – running, D – doneor E – error. When the interface encounters an error, it will report it briefly,and all subsequent steps in the corresponding dynamic run will be aborted, thusshowing an E. An ARM calculation is completed once all steps of every dynamicrun are either “Done” or having given an error.

10

Figure 7: An example of possible output when checking for a still runningcalculation.

11

6 Retrieve a calculation output

Once your ARM calculation is completed, you will receive an email to alert you.(Please note: this feature is still in beta testing and may not work, yet. Keepchecking your calculation as described in Section 5.) As before (Section 5), usethe first page of the interface to provide the Unique ID of your calculation andpress the “Check” button. You will be presented with a page resembling whatshown in Figure 8.

After the recapitulation of the status of all steps, you will be shown theresults. For each dynamic run, the interface will report the computed CASPT2ground and excited state energies, the energy difference as both kcal/mol and asabsorbance maximum in nm, and the oscillator strength. Under these results,the average values are also reported, each with their respective standard devia-tion. Please note: you should use the average value, with its standarddeviation, when reporting the computed absorbance (lambda max)for a given structure.

Finally, the page reports which of the computed QM/MM optimized struc-tures has an absorbance closest to the average. It is possible to download suchstructure, in pdb file format. It is also possible to download the shown reportas a text file, and a bundle of files necessary to perform subsequent calculations.This bundle (in tar gzipped format) includes the pdb file, a corresponding keyfile, and a parameter file. The final report is also given in Appendix A, for easierreading.

Congratulations on performing your first ARM calculation!

12

Figure 8: An example of possible output when checking for a completed calcu-lation.

13

Part II

Tutorial 2: introducing pointmutations

14

7 Introduction

With this tutorial you will learn how to introduce a mutation in the protein se-quence. In particular we will mutate alanine 292 into serine of bovine rhodopsin.This residue resides in the cavity of the protein, and may influence the absorp-tion maximum (lambda max) of the retinal. At the end of the tutorial, youwill obtain the computed lambda max value for the A292S mutant of bovinerhodopsin, and will be given a set of hints/questions that should guide youtoward understanding and rationalizing the effects of point mutations.

8 Preparation

Follow the steps as described in Sections 2 and 3 to retrieve the structure ofbovine rhodopsin, as in Tutorial 1. Upload the pdb file, insert your emailaddress, choose the correct retinal type and fill in the data for the cavity, asdescribed in the first part of Section 4.

9 Insert mutations

The procedure to substitute an amino acid in the protein sequence for anotheris quite straight-forward. First you need to select “Yes” where the interfaceasks about if you wish to insert mutations. Afterwards, you have to specify howmany mutations you wish to perform. We suggest to do one mutation at thetime, at least at the beginning, and we strongly recommend less than four (evenif the interface will give you such possibility).

For the purposes of this tutorial, we want to substitute the alanine in position292 (which is part of the cavity) with a serine. To achieve this, you should specify1 (the default value) where the interface requests how many mutations, chooseAlanine from the drop-down menu in the column “From”, choose Serine fromthe drop-down menu in the column “To”, and write the residue number (292)in the “Residue’s number” field. This is illustrated in Figure 9.

Afterwards, just proceed as in Tutorial 1, leave all fields to their defaultvalues and press “Compute”.

15

Figure 9: Introducing mutations in the protein sequence.

16

10 Checking the calculation

As described in Section 5, it is possible to check that the just submitted calcu-lation is running. The output from the interface will now include an indicationrelative to the introduced mutations, as shown in Figure 10.

Figure 10: Example of possible output when checking for a just submittedcalculation, including mutations of the protein sequence.

11 Retrieve and analyze the results

Once you receive the email stating that your calculation has been done, you canretrieve its results as previously described in Section 6. (Please note: this featureis still in beta testing and may not work, yet. Keep checking your calculationas described in Section 5.) The output will be similar to what reported inFigure 11. The final report is given in Appendix B for easier reading.

17

Figure 11: Example of possible output when checking for a completed calcula-tion, which requested also a mutation of the protein sequence.

18

11.1 Error handling

As can be seen in Figure 11 and Appendix B, an error occurred during thecalculations relative to one of the dynamics. This is clearly stated, and youcan see the row of “E” in the output. For the moment, the interface does notknow how to handle such problem. Future versions will be, likely, able to dosomething about it.

What you should do is to consider that you cannot meaningfully comparedata obtained as averages over different numbers of dynamics. Thus, if presentedwith a similar problem as the one depicted, you should run again WARM withthe same input as described in Sections 8 and 9, but with only 1 dynamic, tomake up for the missing data. Once obtained the result, you should manuallymake the averages between all the successful dynamic runs.

For the purposes of this tutorial, we will leave this as an exercise for you.

11.2 Data analysis

It is now possible to compare the average lambda max values obtained withthis calculation (ca. 455 nm) with that of the wild type bovine rhodopsin youobtained at the end of Tutorial 1 (ca. 477 nm). This shows that the singlemutation of alanine 292 into serine induced a blue-shift of ca. 20 nm. How canyou rationalize the resulting shift? We give you some hints and suggestions onhow to possibly proceed. Check also with your supervisor.

• Think in terms of polarity of the amino acid residue that you changed,and its position in relationship to the retinal.

• Visualize the pdb file with a protein visualization tool, such as VMD,PyMol or SwissPDB viewer.

• Consider the position of the retinal +1 charge in both its ground andexcited state.

• How do you expect the new amino acid to influence the energy of one orboth states?

• What is needed in terms of energy change, to achieve a blue-shift?

Congratulations on performing your second ARM calculation!

19

Part III

Appendix

20

A Output Tutorial 1The calculation number 15016929908 has been initialized and is going to be submitted.

This arm calculation will be composed of 5 dynamics. Each correspond to a separate run.

Original pdb file: Rh181_NSC_input.pdb

Legend for the steps status. R: running; D: done; E: error

Dynamic ID | Step1 Step2 Step3 Step4 Step5 Step6 Step7 Step8

8043 | D D D D D D D D

8230 | D D D D D D D D

2476 | D D D D D D D D

6991 | D D D D D D D D

5247 | D D D D D D D D

##############################################################

# #

# Results for ARM calculation number 15016929908 #

# #

##############################################################

#####################################################################################################################

# # # # # #

# Dyn ID # Absolute CASPT2 Energies # Energy gap # Absorption wavelength # Oscillator Strength #

# # (Hartree) # (kcal/mol) # (nm) # #

# # S0 S1 S2 # S1-S0 S2-S0 # S0->S1 S0->S2 # S0->S1 S0->S2 #

# # # # # #

#---------#-------------------------------------------#---------------#-----------------------#---------------------#

# # # # # #

# 8043 # -871.81476866 -871.71781499 -871.67823020 # 60.839 85.679 # 469 333 # 0.882 0.438 #

# # # # # #

# # # # # #

# 8230 # -871.81926717 -871.72434263 -871.68444165 # 59.566 84.604 # 479 337 # 0.868 0.453 #

# # # # # #

# # # # # #

# 2476 # -871.82011981 -871.72451910 -871.68382465 # 59.990 85.527 # 476 334 # 0.895 0.431 #

# # # # # #

# # # # # #

# 6991 # -871.81947200 -871.72400300 -871.68398942 # 59.908 85.017 # 477 336 # 0.886 0.449 #

# # # # # #

# # # # # #

# 5247 # -871.81931777 -871.72551238 -871.68601533 # 58.864 83.649 # 485 341 # 0.882 0.447 #

# # # # # #

# # # # # #

#####################################################################################################################

# # # # # #

# Average # # 59.833 84.895 # 477.2 336.2 # 0.883 0.443 #

# St.dev. # # 0.641 0.730 # 5.2 2.8 # 0.009 0.008 #

# # # # # #

#####################################################################################################################

The structure with absorption maximum (lambda max) closest to the average is that relative to Dyn ID 6991.

The corresponding pdb file will be available as 15016929908_final_structure.pdb.

This is the end of this ARM calculation, Thanks for using ARM, and don’t forget to cite us!

21

B Output Tutorial 2The calculation number 15029860757 has been initialized and is going to be submitted.

This arm calculation will be composed of 5 dynamics. Each correspond to a separate run.

Original pdb file: Rh181_NSC_input.pdb

Point mutations:

Residue 292 has been changed from A to S

Legend for the steps status. R: running; D: done; E: error

Dynamic ID | Step1 Step2 Step3 Step4 Step5 Step6 Step7 Step8

2416 | D D D D D E E E

7198 | D D D D D D D D

5903 | D D D D D D D D

2692 | D D D D D D D D

9949 | D D D D D D D D

The calculation number 15029860757 encountered the following error:

The orbital occupation relative to the dynamic number 2416 was not right. I’m sorry, but I don’t know, yet, how to continue. Better luck next time!

Please, check your input, three times minimum. If you still think there is a problem with ARM or its web interface, conctact the developers.

Better luck next time!

The ARM Team

##############################################################

# #

# Results for ARM calculation number 15029860757 #

# #

##############################################################

#####################################################################################################################

# # # # # #

# Dyn ID # Absolute CASPT2 Energies # Energy gap # Absorption wavelength # Oscillator Strength #

# # (Hartree) # (kcal/mol) # (nm) # #

# # S0 S1 S2 # S1-S0 S2-S0 # S0->S1 S0->S2 # S0->S1 S0->S2 #

# # # # # #

#---------#-------------------------------------------#---------------#-----------------------#---------------------#

# # # # # #

# 7198 # -871.83027025 -871.72996177 -871.69309077 # 62.945 86.081 # 454 332 # 0.828 0.485 #

# # # # # #

# # # # # #

# 5903 # -871.83068289 -871.72975449 -871.69226649 # 63.334 86.858 # 451 329 # 0.820 0.485 #

# # # # # #

# # # # # #

# 2692 # -871.83604862 -871.73632881 -871.69812916 # 62.575 86.546 # 456 330 # 0.830 0.490 #

# # # # # #

# # # # # #

# 9949 # -871.82976768 -871.73050716 -871.69399333 # 62.287 85.200 # 459 335 # 0.782 0.512 #

# # # # # #

# # # # # #

#####################################################################################################################

# # # # # #

# Average # # 62.785 86.171 # 455.0 331.5 # 0.815 0.493 #

# St.dev. # # 0.393 0.625 # 2.9 2.3 # 0.019 0.011 #

# # # # # #

#####################################################################################################################

The structure with absorption maximum (lambda max) closest to the average is that relative to Dyn ID 7198.

The corresponding pdb file will be available as 15029860757_final_structure.pdb.

This is the end of this ARM calculation, Thanks for using ARM, and don’t forget to cite us!

22