Rebuild jack

doc/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 905a5d177da0d4d34dc61c5420fd61b9
+tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/html/_sources/applied_efp.rst.txt

@@ -0,0 +1,141 @@
+.. _applied_efp:
+
+*************************
+FMO: Applied flexible EFP
+*************************
+
+Overview
+--------
+
+As is the case with many photoactive proteins,computational methods struggle to reproduce 
+experimental spectra for the Fenna-Matthews-Olson complex (FMO). Work by 
+`Kim et al <https://pubs.acs.org/doi/full/10.1021/acs.jpclett.9b03486>`_ shows that 
+flexible QM/EFP can be applied to FMO to correctly generate computational results in 
+quantitative agreement to experimental spectra. 
+
+The key to applying EFP to your system is to carefully define the active site and EFP region. 
+FMO is a trimeric protein with eight bacteriochloropyll a (BChl) pigments in each monomer. 
+FMO completes energy transfer via excitonic couplings across these eight BChls. A summary 
+of the complete workflow that was performed is the following: 1) molecular dynamics (MD) 
+simiulations of the FMO protein in water and counter ions, 2) QM/MM (not EFP) geometry 
+optimization of *each* active site (active sites consist of one BChl pigment and 
+typically 3 H-bonding amino acids), and 3) flex-EFP excited state energy calculations of 
+each pigment.
+
+In the case of FMO, these steps must be repeated on several snapshots from MD to account 
+for variation in the resting state of the structure, and the QM region must be defined 
+carefully in both the QM/MM and flex-EFP stages. It might not be universally true that one 
+must perform QM/MM geometry optimization. This page is a walkthrough for the flex-EFP procedure 
+only. Molecular dynamics and QM/MM optimizations are assumed to be complete for your 
+system prior to these steps. 
+
+.. image:: ../images/FMO_trimer_BCLs.bmp
+   :width: 350
+
+.. image:: ../images/FMO_mon_pigs.bmp
+   :width: 400
+
+You will need a structure file (.g96) and topology information (.top, for atom charges). In this specific case,
+a structure file is extracted from a GROMACS molecular dynamics trajectory and all water molecules more than 15 angstroms from 
+the protein's surface have been removed. For a chlorophyll-containing protein, you will likely want to optimize the geometry 
+of each active chlorophyl molecule (with very close amino acids/water molecules) separately with more standard QM/MM approaches 
+before proceeding with EFP calculations on the optimized geometry. For this example, the first BChl, residue number 359, 
+has been optimized and will be the QM region for the EFP calcuation.
+
+.. image:: ../images/fmo_waters15a.bmp
+   :width: 400
+
+First, an EFP region must be defined. Every amino acid, (non QM) BChl, and water molecule containing an 
+atom within 15 angstroms of the QM BChl headring. 
+
+The headring is defined by atomnames: MG CHA CHB HB CHC HC CHD HD NA C1A 
+C2A H2A C3A H3A C4A CMA HMA1 HMA2 HMA3 NB C1B C2B C3B C4B CMB HMB1 HMB2 HMB3 CAB OBB CBB HBB1 HBB2 HBB3 NC C1C C2C H2C C3C 
+H3C C4C CMC HMC1 HMC2 HMC3 CAC HAC1 HAC2 CBC HBC1 HBC2 HBC3 ND C1D C2D C3D C4D CMD HMD1 HMD2 HMD3 CAD OBD CBD HBD CGD O1D O2D 
+CED HED1 HED2 HED3
+
+The headring surrounded by EFP region looks like this:
+
+.. image:: ../images/tester.bmp
+   :width: 400
+
+EFP is, of course, a fragmentation method. The protein residues within the 15 angstrom cutoff will be expressed individually. 
+Because amino acids are a continuous chain, we will need to break each residue into its own fragment. Chemically, we would like 
+to divide each residue by the C-C backbone bond, however, standard PDB listing convention divides residues by the C-N 
+bond. To correct this, 'C' and 'O' atom names should be included in the following aminoc acid. This way the 'C' and 'CA' 
+(carbonyl carbon and alpha carbon respectively) bond is the division between bonded fragments.
+See the examples below:
+
+PDB residues are divided like this:
+
+.. image:: ../images/pdb_67_col.bmp
+   :width: 400
+
+For EFP, we would rather these two fragments
+ look like this:
+
+.. image:: ../images/efp_67_col.bmp
+   :width: 400
+
+The desired atoms are contained in the structure file, but they do not completely 'agree' with the amino acid numbering.
+Below is a snippet from the structure file with the desired EFP fragment 8 highlighted. Note that atom names 'C' and 'O' 
+are included in the following fragment.
+
+.. literalinclude:: ../examples/flex-EFP/1.Prepare_Structure/bchl359-50028.g96
+   :linenos:
+   :lines: 79-101
+   :emphasize-lines: 10-21
+
+Next, some of the BChl molecules are closer each other than the 15 angstrom cutoff, so they also appear in the EFP region. It is more cost efficient 
+to treat BChl fragments as separate head and tail groups as is shown below:
+
+.. image:: ../images/efp_headtail.bmp
+   :width: 400
+
+In the case of both amino acid and BChl fragments, we have at least one broken bond; we cannot simply compute a fragment that is 
+missing an atomic bond. To solve this, we will introduce virtual hydrogen atoms to 'cap' the broken bonds. Non terminal 
+amino acid fragments will have two virtual atoms. The first is between the alpha carbon of the previous residue and the 
+carbonyl carbon of the current residue; the other is similarly between the alpha carbon of the current residue and the carbonyl carbon 
+of the following residue. The BChl fragments are split between atoms 'C2A' and 'CAA.' One virtual atom will be added to both 
+head and tail fragments between these atoms. Virtual atoms are added along the vector of the broken bonds with the distance changed 
+to the C-H equilibrium bond distance, 1.09 angstroms.
+
+.. image:: ../images/efp_bothvirt.bmp
+   :width: 400
+
+Once the system is properly fragmented, we can finally run EFP calculations in the precense of the polarizable, solvatochromic environment. 
+
+EFP Workflow
+------------
+
+Extract a single snapshot of MD extracted from GROMACS ie: ``gmx traj -f md_50.trr -s md_50.tpr -o bchl361-79002.g96``\(.g6 format).
+Please note that extracting larger systems can occasionally cause columns to be misaligned due to large atom number indexes. 
+This misalignemnt can make the structure appear strangely in some visualizers (most commonly VMD). Though it shouldn't matter, 
+you can reformat the file with a simple script to realign the columns. `Here <../examples/flex-EFP/Scripts/format.py>`_ is an example of a script that can do this with an output file of 
+``formed_bchl361-79002.g96``.
+
+Now, we need to know which amino acids, cofactors, and water molecules constitute the EFP region. One method to find this is to
+make use of the ``gmx select`` command, but this will take a small amount of footwork. You will need to create an index file 
+that defines the BChl head ring group for reference in gmx selections. The code below will generate this index file with the default 
+name ``index.ndx``; index.ndc contains all standard GROMACS index groups (system, protein, etc), with one final nonstandard group, 'headring'.
+
+.. literalinclude:: ../examples/flex-EFP/Scripts/gen_efp_index.sh
+   :linenos:
+
+Here is a visualization of atoms contained in the newly created index group:
+
+.. image:: ../images/361_headring.bmp
+   :width: 400
+
+Note: the QM region will include the entire BChl, but the EFP region will be defined by distance to this ring group 
+only.
+
+The EFP region should be composed of all residues that contain at least one atom within 15 angstoms of the headring. 
+A new .g96 can be made using the command: ``gmx select -s md_80.tpr -n index.ndx -f formed_bchl361-79002.g96 -select 'same residue as within 1.5 of group "Headring"' -on shell_index.ndx``. 
+This command looks for any atom within our cutoff (1.5 because GROMACS units are in nm), then accepts every atom belonging to 
+the same residue as the found atom, and adds these to the selection. The output of the command is named shell_index.ndx, which as the 
+name suggests, is another index file. This file has exactly one index group that is the EFP region. 
+
+Now, ``gmx editconf -f formed_bchl361-79002.g96 -n shell_index.ndx -o shell_bchl361-79002.g96`` will create a new structure 
+file of the EFP region only. The structure should look like the 'desired EFP region' shared above on this page (in the Overview section).
+
+

doc/html/_sources/bioefp.rst.txt

@@ -0,0 +1,16 @@
+.. _bioefp:
+
+******
+BioEFP
+******
+
+BioEFP is a scheme to split a macromolecule into fragments.
+Proteins can be split along C-Ca bonds, as shown below.
+
+.. image:: ../images/BioEFP.jpg
+   :width: 200
+
+The model is described `here <https://pubs.acs.org/doi/abs/10.1021/acs.jpcb.6b04166>`_.
+The original work used the following script `step2.gen.gamess.pl` **Where is it?**.
+For a new robust version of the script check out this
+`BioEFP tutorial <https://github.itap.purdue.edu/Slipchenko-group/>`_ **The tutorial is not there yet!**

doc/html/_sources/efp_calcs.rst.txt

@@ -0,0 +1,123 @@
+.. _efp_calcs:
+
+****************
+EFP calculations
+****************
+
+EFP energy terms
+----------------
+
+LibEFP can compute four inter-fragment energy terms:
+
+* electrostatic
+* polarization
+* dispersion
+* exchange-repulsion
+
+.. _elec_energy:
+
+Electrostatic term
+^^^^^^^^^^^^^^^^^^
+
+Electrostatic energy is computed as a combination of charge-charge, charge-dipole,
+charge-quadrupole, charge-octupole, dipole-dipole, dipole-quadrupole, and quadrupole-quadrupole
+contributions.
+
+The following parts of the EFP potential are used for electrostatic energy calculations:
+
+- :ref:`COORD`
+- :ref:`MON`
+- :ref:`DIP`
+- :ref:`QUAD`
+- :ref:`OCT`
+- :ref:`SCREEN`
+
+Out of those, only :ref:`COORD` section is mandatory as it determines fragment internal coordinate frame.
+All electrostatic terms (and corresponding parameters) are optional.
+
+Charge-penetration screening
+""""""""""""""""""""""""""""
+
+Two options exist for accounting for charge-penetration contribution to electrostatic
+energy:
+
+- exponential screening ("smearing") of charges. This is achieved by invoking screening parameters
+defined in ``SCREEN2`` section of the `.efp` potential (see :ref:`SCREEN`). The charge-penetration energy
+is not printed separately but included in the electrostatic energy.
+- overlap-based screening. This is a separate energy term derived assuming that localized orbitals
+can be modeled as spherical gaussions (the same approximation is used in the exchange-repulsion term).
+This calculation will utilize exchange-repulsion parameters (:ref:`FOCK`, :ref:`WF`, :ref:`BASIS`, :ref:`LMOC`).
+This overlap-based charge-penetration energy is printed as a separate energy term (see examples in :ref:`libefp`).
+
+Detailed description of damping functions and their benchmarks are published in
+`Damping functions for electrostatic term <http://dx.doi.org/10.1002/jcc.20520>`_
+and `Short-range damping functions <http://dx.doi.org/10.1080/00268970802712449>`_ papers.
+
+.. _pol_energy:
+
+Polarization term
+^^^^^^^^^^^^^^^^^
+
+Polarization energy is computed using distributed anisotropic dipole polarizabilities. Induced dipoles,
+originating at the polarizability points, are converged until self-consistency. The default procedure is to
+solve for induced dipoles iteratively; the direct diagonalization of the induced dipole matrix is implemented
+but not parallelized, making its applicability limited to systems with a few thousands polarizability points
+(see `polarization solver` section in `efpmd manual <https://github.com/libefp2/libefp/tree/master/efpmd#readme>`_).
+Detailed description of the EFP polarization term can be found in
+`the first EFP paper (1996) <https://doi.org/10.1063/1.472045>`_
+and `gradients of polarization energy paper <https://doi.org/10.1063/1.2378767>`_.
+
+The relevant sections of the EFP potential are:
+
+- :ref:`POL_POINT`
+- :ref:`POLAB`
+- :ref:`COORD`
+- :ref:`MON`
+- :ref:`DIP`
+- :ref:`QUAD`
+- :ref:`OCT`
+
+:ref:`POL_POINT` groups provides coordinates and values of the polarizability tensors. Other sections specify
+positions and values of electrostatic multipoles that are used to compute static electric field on polarizability points.
+
+Polarization energies are screened at short range with the Tang-Toennies (or gaussian-type) damping functions described in
+the `short-range damping functions paper <http://dx.doi.org/10.1080/00268970802712449>`_. A value of the damping parameter is controlled
+by an optional :ref:`POLAB` keyword; smaller values provide stronger screening of polarization energies which might be necessary for fragments
+with large multiple moments (charged or strongly polar species) or large polarizabilities (e.g., large conjugated/aromatic molecules).
+
+.. _disp_energy:
+
+Dispersion term
+^^^^^^^^^^^^^^^
+
+Dispersion energy term captures the London interaction between the molecules. Formally, it can be expanded in
+series of (1/R) operator as :math:`E_{disp} = \frac{C_6}{R^6} + \frac{C_8}{R^8} + \frac{C_{10}}{R^{10}} + ....`
+In the case of distributed approach where dispersin contributions are computed as a sum of contributions due to
+individual parts of a molecules, the odd terms :math:`\frac{C_7}{R^7}, \frac{C_9}{R^9}` etc are also non-zero.
+
+The relevant sections of the EFP potential are:
+
+- :ref:`DYN_POINT`
+
+:ref:`DYN_POINT` group section provides coordinates and values of anisotropic dynamic polarizability tensors for computing dispersion energy.
+
+.. _ex_rep:
+
+Exchange Repulsion
+^^^^^^^^^^^^^^^^^^
+
+Exchange repulsion accounts for the antisymmetry of the wave function of the fragments.It is modelled using inter-fragment kinetic and
+overlap integrals, and the Fock matrices of the fragment. 
+
+The relevant sections of the EFP potential are:
+
+- :ref:`BASIS`
+- :ref:`MULTIPLICITY`
+- :ref:`WF`
+- :ref:`FOCK`
+- :ref:`LMOC`
+
+:ref:`BASIS` provides details of the basis set used for calculation of the exchange repulsion energy, :ref:`MULTIPLICITY` contains information
+on the multiplicity of the fragment (LibEFP works only on fragments with multiplicity 1), :ref:`WF` provides the localized wave function of the 
+fragment, while :ref:`FOCK` and :ref:`LMOC` contain information regarding the elements of the Fock matrix of the fragment in the localized basis, and 
+the coordinates of the localized molecular orbital, respectively.