adding common issues, #1, related to issue #6396

rosetta_basics/scoring/qm-energy-calculations.md

@@ -2,18 +2,27 @@
 
 Back to [[Rosetta basics|Rosetta-Basics]].
 Page created 16 November 2021 by Vikram K. Mulligan, Flatiron Institute (vmulligan@flatironinstitute.org).
+Fleshed out 1 May 2024 by Noora Azadvari, University of Oregon (eazadvar@uoregon.edu).
 
 [[_TOC_]]
 
+## Citation
+GAMESS needs to be cited when using RosettaQM:
+
+[Barca, G. M. J. et al. The Journal of Chemical Physics 152, 154102 (2020)](https://doi.org/10.1063/5.0005188)
+
+
 ## Summary
 
 Traditionally, Rosetta has used a quasi-Newtonian force field for energy calculations.  This has allowed Rosetta protocols to score a large macromolecular structure rapidly (typically in milliseconds) and repeatedly, permitting large-scale sampling of conformation and/or sequence space.  The downside, however, has been that force fields are of finite accuracy.  In late 2021, we added support for carrying out quantum mechanical energy and geometry optimization calculations in the context of a Rosetta protocol, by calling out to a third-party quantum chemistry software package.  This page summarizes how to set up and use this functionality.
 
+The protocols in RosettaQM use **Single point energy calculation** , **Geometry optimization** or a combination of them. 
+
 ## Important considerations
 
 ### Molecular system size, level of theory, and computation time
 
-TODO
+GAMESS can only process 2000 atoms at time. Therefore, for systems with larger than 2000 atoms, the molecule needs to be fragmented through FMO. This limit can be increased, but it is not recommended. 
 
 ### Computer memory
 
@@ -33,16 +42,64 @@ All Rosetta QM calculations are performed through calls to third-party quantum c
 
 ### The General Atomic and Molecular Electronic Structure System (GAMESS)
 
-[[GAMESS|https://www.msg.chem.iastate.edu/index.html]] is a versatile quantum chemistry package written in FORTRAN, and developed by the [[Gordon group at Iowa State University|https://www.msg.chem.iastate.edu/group/members.html]].  Users may agree to the licence agreement and obtain the software from [[the GAMESS download page|https://www.msg.chem.iastate.edu/gamess/download.html]].
+[GAMESS](https://www.msg.chem.iastate.edu/index.html) is a versatile quantum chemistry package written in FORTRAN, and developed by the [Gordon group at Iowa State University](https://www.msg.chem.iastate.edu/group/members.html).  Users may agree to the licence agreement and obtain the software from [the GAMESS download page](https://www.msg.chem.iastate.edu/gamess/download.html).
 
 #### Installation and setup
 
-To use GAMESS with Rosetta... TODO
+Here we give an example of installing *GAMESS version September 30, 2023 R2 for 64 bit x86_64 under Linux using GNU compilers*. After submitting the request to download, it takes around a day or less to receive an email with the link. After downloading the *.tar.gz file, transfer it 
+to the desired node if needed. Unzip the file with following command:
+
+`tar -xzvf <file-name>`
+
+It will create a directory named `gamess` with files and subfolders inside it. Change the directory to this folder with `cd gamess`. The instructions for installation are provided in `README.md` file. 
+
+Run executable `config` file with `./config`. It will ask you questions about your system. You need to open a new terminal window, to search the answers for those questions. Here are the questions:
+
+| Question | Recommended answer |
+| ------- | -------------------- |
+|What is the type of your machine?|type `uname -a` in the new window. Here we use Linux, so the answer is `linux64`. All possible options are provided as a list on the left column. |
+|Where is the GAMESS software located on your system?| Press enter for default |
+|GAMESS build directory?|This can be the same as where gamess is located. So we provide the same path again.|
+|Please provide a version number for the GAMESS executable.|Press enter for default|
+|Are you building for a specific HPC system?|Press enter for none (unless you use a specific one)|
+|Please enter your choice of FORTRAN:|gfortran|
+|Please enter only the first decimal place, such as 8.2 or 11.2:|type `gfortran -v` in the new window. the last line shows version as `gcc version xx.x.x `, enter the version with first decimal place as an answer.|
+|Enter your math library choice from one of the options below:|These libraries might be installed through modules, so it would be advised to search for them through `module spider <library-name>` and choose the best available one. The path to root can also be found through `module show <library-name>`|
+|communication library|We recommend using `sockets`.|
+|Optional: Build LibXC interface?|If your gcc version was higher that 5.5, then answer `yes`.|
+|Do you want to use LIBCCHEM 2.0?|`no`|
+|other questions|Based on your liking and system. None of them are required though.|
+
+YAY! Now you have all configurations set, and it can be found in `gamess/install.info`. Some options can still be edited, as mentioned above. 
 
 #### Compiling GAMESS
 
+Use `make` or `make -j(number_of_processors)`. You can find the number of processors in your linux system by typing `nproc` in command line. 
+
 #### Using GAMESS with Rosetta
 
+You need to set `gamess_executable_version` and `gamess_path` tags in xml file. `gamess_path` 
+is the directory that contains gamess executable. In this directory you will find a file with format `gamess.$$.x` where `$$` is the executable version. 
+
+An example of using these tags in code (note that this is not a real case, and you need to use other tags to set the basis set and other configurations.)
+```
+<ROSETTASCRIPTS>
+    <SCOREFXNS>
+        <ScoreFunction name="gamess_energy" weights="empty" >
+            <Reweight scoretype="gamess_qm_energy" weight="1.0" />
+            <Set 
+                gamess_path="<path-to-gamess-directory>"
+                gamess_executable_version="<version>"
+            />
+        </ScoreFunction>
+    </SCOREFXNS>
+    <PROTOCOLS>
+        <Add metrics="gamess_energy" />
+    </PROTOCOLS>
+</ROSETTASCRIPTS>
+```
+
+
 ##### Point energy calculations with GAMESS within a Rosetta protocol
 
 A single point energy (SPE) calculation with GAMESS can be run through Rosetta directly from the command line. Depending on the user preference, the user can either use an XML script or run directly from the command-line interface. Here are two tutorials to demonstrate how this can be done:
@@ -97,3 +154,10 @@ TODO
 ### NWChem
 
 TODO
+
+## Common issues
+
+||Problem | Reason| Solution |
+|--|----|-----|----|
+|1|Errors about charge and multiplicity with FMO | open termini | The -ignore_zero_occupancy false flag is often needed. |
+|2|Errors with the `-auto_setup_metals` flag (see the [[Metals]] page) or the [[SetupMetalsMover]], especially with histidine.|Incorrect tautomerization of histidines that coordinate metals can result in the proton being removed from neutral histidine, yielding an improbable negatively-charged histidine and an incorrect electronic configuration of the system.|Use the [[MutateResidueMover]] to manually mutate histidine residues to either "HIS" (protonated on the epsilon nitrogen) or "HIS_D" (protonated on the delta nitrogen) tautomer, to ensure that the proton is on the nitrogen that is _not_ coordinating the metal.  Do this _prior_ to using the [[SetupMetalsMover]]|

scripting_documentation/RosettaScripts/Movers/movers_pages/GamessQMGeometryOptimizationMover.md

@@ -0,0 +1 @@
+[[include:mover_GamessQMGeometryOptimizationMover]]

scripting_documentation/RosettaScripts/Movers/movers_pages/GamessQMRunScanPoseMover.md

@@ -0,0 +1 @@
+[[include:mover_GamessQMRunScanPoseMover]]

scripting_documentation/RosettaScripts/SimpleMetrics/simple_metric_pages/GamessQMEnergyMetric.md

@@ -0,0 +1,7 @@
+# GamessQMEnergyMetric
+*Back to [[SimpleMetrics|SimpleMetrics]] page.*
+
+## Summary
+This simple metric caches in the pose a QM energy externally computed with GAMESS, plus additional values from the calculation.
+
+[[include:simple_metrix_GamessQMEnergyMetric]]