Deploying to gh-pages from @ e4145d4 🚀

.buildinfo

@@ -1,4 +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: 4648b33251884360e1155dd41a4fbab4
+config: 5dce867471c0851f7cbfbc83ef115985
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/installation.rst.txt

@@ -2,54 +2,79 @@ Installation
 ============
 
 Compiling MDI-Tinker and ELECTRIC
-----------------------------------
+---------------------------------
 
-Installation of ELECTRIC and MDI-enabled Tinker are bundled in one convenient build script. 
+.. note::
+    The following instructions assume that you are using the `conda <https://docs.conda.io/en/latest/>`_ package manager and a Linux or Unix based operating system. 
+    If you are not using :code:`conda`, you will need to install the dependencies manually.
+    If you are using the Windows Operating System, we recommend the Windows Subsystem for Linux (WSL).
 
-To install ELECTRIC and MDI-enabled Tinker, you should have cmake and a fortran compiler installed. Then, you can download and build ELECTRIC and MDI-enabled Tinker using the following command in your terminal. Make sure you are in the directory where you want your ELECTRIC driver to be. You should note this location, because you will need to specify the path to some files built during this process in order to perform analysis.
+To install ELECTRIC and MDI-enabled Tinker, you should have :code:`cmake` and a Fortran compiler installed. 
+If you are using the `conda` package manager, you can clone the repository and use the provided `environment.yaml` 
+to create an environment with the required dependencies (including Python packages) using the following command.
 
 .. code-block:: bash
 
     git clone --recurse-submodules https://github.com/WelbornGroup/ELECTRIC.git
     cd ELECTRIC
-    ./build.sh
+    conda create -f environment.yaml
+
+After the environment is created and installed you should activate it:
 
-This will download and build ELECTRIC and MDI-enabled Tinker. 
+.. code-block:: bash
+
+    conda activate electric
 
-Upon successful building, you will have the ELECTRIC driver in ELECTRIC/ELECTRIC/ELECTRIC.py, and the needed Tinker executable (dynamic.x) in ELECTRIC/modules/Tinker/build/tinker/source/dynamic.x . The location of these files can be found in text files in ELECTRIC/test/locations/ELECTRIC and ELECTRIC/test/locations/Tinker_ELECTRIC. You will need these for using ELECTRIC.
+After creating and activating your environment, you will have the necessary compilers and libraries required for compilating, installing, and running ELECTRIC.
+Installation of ELECTRIC and MDI-enabled Tinker are bundled in one convenient build script. 
+Execute the following command in the top level of your cloned repository to build ELECTRIC and MDI-enabled Tinker:
 
-Python Dependencies
--------------------
+.. code-block:: bash
 
-In order to run ELECTRIC, you will need to be in a python environment which has numpy and pandas installed. If you want to run ELECTRIC with more than one engine, you should also install MPI4Py. We recommend installing these packages in a conda environment created for ELECTRIC analysis.
+    ./build.sh
 
-.. code-block:: bash   
 
-    conda install -c anaconda mpi4py
-    conda install -c conda-forge numpy pandas
+Upon successful building, you will have the ELECTRIC driver in :code:`ELECTRIC/ELECTRIC/ELECTRIC.py`, 
+and the needed Tinker executable (:code:`dynamic.x`) in ELECTRIC/modules/Tinker/build/tinker/source/dynamic.x . 
+The location of these files can be found in text files in :code:`ELECTRIC/test/locations/ELECTRIC` and :code:`ELECTRIC/test/locations/Tinker_ELECTRIC`.
+You will need these for using ELECTRIC.
 
 Testing Your Installation
 --------------------------
 
-You can now run a quick test of the driver by changing directory to the `ELECTRIC/test/bench5` directory and running the `tcp.sh` script:
+To continue with testing your installation, make sure your `electric` `conda` environment is activated:
+
+.. code-block:: bash
+
+    conda activate electric
+
+You can now run a quick test of the driver by changing directory to the :code:`ELECTRIC/test/bench5` directory and running the `tcp.sh` script:
 
 .. code-block:: bash
 
+    cd ELECTRIC/test/bench5
     ./tcp.sh
 
-This script will run a short Tinker dynamics simulation that includes periodic boundary conditions. This command is on line 20 of the provided file. This is a standard Tinker call, as you would normally run a simulation. If you are performing post processing on a simulation, you will not use this line.
+This script will run a short Tinker dynamics simulation that includes periodic boundary conditions. 
+This command is on line 20 of the provided file. This is a standard Tinker call, as you would normally run a simulation. 
+If you are performing post processing on a simulation, you will not use this line.
 
 .. code-block:: bash
 
     ${TINKER_LOC} bench5 -k bench5.key 10 1.0 0.001999 2 300.00 > Dynamics.log
 
-The script then launches an instance of Tinker as an MDI engine, which will request a connection to the driver and then listen for commands from the driver. This command is similar to running a simulation with Tinker, except that it uses a modified Tinker input file (more on this below), and adds an additional command line argument which passes information to MDI (`-mdi "role ENGINE -name NO_EWALD -method TCP -port 8022 -hostname localhost"`):
+The script then launches an instance of Tinker as an MDI engine, 
+which will request a connection to the driver and then listen for commands from the driver. 
+This command is similar to running a simulation with Tinker, except that it uses a modified Tinker input file 
+(more on this below), and adds an additional command line argument which passes information to MDI 
+(`-mdi "role ENGINE -name NO_EWALD -method TCP -port 8022 -hostname localhost"`):
 
 .. code-block:: bash
 
     ${TINKER_LOC} bench5 -k no_ewald.key -mdi "-role ENGINE -name NO_EWALD -method TCP -port 8022 -hostname localhost" 10 1.0 0.001999 2 300.00 > no_ewald.log &
 
-The script will then launch an instance of the driver in the background, which will listen for connections from an MDI engine:
+The script will then launch an instance of the driver in the background, 
+which will listen for connections from an MDI engine:
 
 .. code-block:: bash
 

_sources/tutorial.rst.txt

@@ -1,7 +1,9 @@
 Tutorial
 ========
 
-This tutorial will walk you through using ELECTRIC to analyze the electric field in a small protein. This tutorial assumes you have ELECTRIC and MDI-enabled Tinker installed. If you don't, navigate to the installation_ instructions.
+This tutorial will walk you through using ELECTRIC to analyze the electric field in a small protein. 
+This tutorial assumes you have ELECTRIC and MDI-enabled Tinker installed. 
+If you don't, navigate to the installation_ instructions.
 
 .. note::
     This tutorial will assume the following:
@@ -10,8 +12,16 @@ This tutorial will walk you through using ELECTRIC to analyze the electric field
         - You are able to download or clone a directory from git.
         - You are familiar with bash scripts.
 
+To begin the tutorial, first make sure you have your `electric` environment activated:
 
-The pdb code for this protein is 1l2y_, and you can see the structure below. We have chosen a small protein for demonstrative purposes. The image below shows only the protein, but our simulation is solvated.
+.. code-block:: bash
+
+    conda activate electric
+
+
+The pdb code for this protein is 1l2y_, and you can see the structure below. 
+We have chosen a small protein for demonstrative purposes. 
+The image below shows only the protein, but our simulation is solvated.
 
 .. moleculeView:: 
 
@@ -26,9 +36,13 @@ Running an ELECTRIC calculation
 
 Preparing Files
 ----------------
-To follow along with this tutorial, clone the `tutorial repository`_. Included in this repository is folder called :code:`data`. The :code:`data` directory has all of the data you will need for this tutorial.
+To follow along with this tutorial, clone the `tutorial repository`_. 
+Included in this repository is folder called :code:`data`. The :code:`data` directory has all of the data you will need for this tutorial.
 
-ELECTRIC is a post-processing analysis, meaning that you should first run your simulations using the AMOEBA forcefield and save the trajectory. After you have a trajectory from Tinker simulation, use ELECTRIC to perform electric field analysis on that trajectory. We will be analyzing the trajectory included in the tutorial repository, :code:`1l2y_npt.arc`. This trajectory is a text file containing coordinates for a simulation that has already been run.
+ELECTRIC is a post-processing analysis, meaning that you should first run your simulations using the AMOEBA forcefield and save the trajectory. 
+After you have a trajectory from Tinker simulation, use ELECTRIC to perform electric field analysis on that trajectory. 
+We will be analyzing the trajectory included in the tutorial repository, :code:`1l2y_npt.arc`. 
+This trajectory is a text file containing coordinates for a simulation that has already been run.
 
 To get started with ELECTRIC, we will need to prepare our input files. We will need:
     - a molecular dynamics trajectory
@@ -40,11 +54,15 @@ We already have the molecular dynamics trajectory, so let's look at each of thes
 
 Simulation Parameter File
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-This file contains the force field parameters for the simulation you have run. If you are using this software for analysis, use the same force field you used to run the molecular dynamics simulation. For this tutorial, the parameter file is :code:`amoebabio18.prm`. We will need this for our Tinker input file (next section).
+This file contains the force field parameters for the simulation you have run. If you are using this software for analysis, use the same force field you used to run the molecular dynamics simulation. 
+For this tutorial, the parameter file is :code:`amoebabio18.prm`. We will need this for our Tinker input file (next section).
 
 Tinker input file
 ^^^^^^^^^^^^^^^^^
-Next, we must prepare an input file which tells Tinker settings for our calculation. This input file should be a modified version of the one which you used to run your initial simulation. Consider the input file, :code:`tinker.key` used to obtain this trajectory. The parameter file in the previous step is given on :code:`line 1`.
+Next, we must prepare an input file which tells Tinker settings for our calculation. 
+This input file should be a modified version of the one which you used to run your initial simulation. 
+Consider the input file, :code:`tinker.key` used to obtain this trajectory. 
+The parameter file in the previous step is given on :code:`line 1`.
 
 .. code-block:: text
     :linenos:
@@ -73,11 +91,15 @@ Next, we must prepare an input file which tells Tinker settings for our calculat
     printout 1000
 
 
-The input file used for this simulation uses periodic boundaries and an Ewald summation for electrostatics. During a Tinker simulation using AMOEBA, electric fields are evaluated in order to calculate the induced dipoles at each step. In order to get electric field contributions from specific residues, we must calculate the electric field using the real space interactions only (no periodic boundaries or Ewald). 
+The input file used for this simulation uses periodic boundaries and an Ewald summation for electrostatics. 
+During a Tinker simulation using AMOEBA, electric fields are evaluated in order to calculate the induced dipoles at each step. 
+In order to get electric field contributions from specific residues, we must calculate the electric field using the real space interactions only (no periodic boundaries or Ewald). 
 
-Remove settings related to cutoffs (:code:`cutoff` keyword), periodic boundaries (:code:`a-axis`, :code:`b-axis`,:code:`c-axis`) and Ewald summation (:code:`ewald`). You can also remove settings having to do with neighbor lists (:code:`neighbor-list`), as they are not needed and can cause an error for this calculation if included.
+Remove settings related to cutoffs (:code:`cutoff` keyword), periodic boundaries (:code:`a-axis`, :code:`b-axis`,:code:`c-axis`) and Ewald summation (:code:`ewald`). 
+You can also remove settings having to do with neighbor lists (:code:`neighbor-list`), as they are not needed and can cause an error for this calculation if included.
 
-The modifed input file for ELECTRIC is given below. This file is saved in the data directory with the name :code:`noewald.key`.
+The modifed input file for ELECTRIC is given below. 
+This file is saved in the data directory with the name :code:`noewald.key`.
 
 .. code-block:: text
 
@@ -99,9 +121,12 @@ The modifed input file for ELECTRIC is given below. This file is saved in the da
 
 Bash script - run_analysis.sh
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When you run analysis uisng ELECTRIC, ELECTRIC parses your given trajectory sends snapshots to Tinker for electric field calculation. The MDI-enabled version of Tinker then calculates the electric field information for that snapshot. 
+When you run analysis uisng ELECTRIC, ELECTRIC parses your given trajectory sends snapshots to Tinker for electric field calculation. 
+The MDI-enabled version of Tinker then calculates the electric field information for that snapshot. 
 
-You use ELECTRIC from the command line. Consider the following bash script provided for analysis, :code:`run_analysis.sh`. We will explain this script in detail.
+You use ELECTRIC from the command line. 
+Consider the following bash script provided for analysis, :code:`run_analysis.sh`. 
+We will explain this script in detail.
 
 .. code-block:: bash
     :linenos:
@@ -134,17 +159,27 @@ You use ELECTRIC from the command line. Consider the following bash script provi
 
     For this tutorial, we use the approach of having all data needed for analysis in a directory called `data`. During analysis, we copy everything from :code:`data` into a folder :code:`work`. This part of the tutorial is stylistic. The authors prefer this method to keep files separated, and original files unaltered.
 
-In lines :code:`2` and :code:`3`, you should change the location to your installed ELECTRIC.py file and MDI-enabled :code:`dynamic.x`. Recall from the installation instructions that you can find these in the ELECTRIC directory in the files :code:`ELECTRIC/test/locations/ELECTRIC` and :code:`ELECTRIC/test/locations/Tinker_ELECTRIC`. 
+In lines :code:`2` and :code:`3`, you should change the location to your installed ELECTRIC.py file and MDI-enabled :code:`dynamic.x`. 
+Recall from the installation instructions that you can find these in the ELECTRIC directory in the files :code:`ELECTRIC/test/locations/ELECTRIC` and :code:`ELECTRIC/test/locations/Tinker_ELECTRIC`. 
 
-The next section removes the folder called :code:`work` if it exists. This bash script is written to put all analysis files into a folder called :code:`work` to keep our original files clean. 
+The next section removes the folder called :code:`work` if it exists. 
+This bash script is written to put all analysis files into a folder called :code:`work` to keep our original files clean. 
 
 MDI-enabled Tinker is launched on :code:`line 18` with the command
 
 .. code-block:: bash
 
     ${TINKER_LOC} 1l2y -k no_ewald.key -mdi "-role ENGINE -name NO_EWALD -method TCP -port 8022 -hostname localhost"  10 1.0 0.002 2 300.00 > no_ewald.log &
 
-The first thing on this line, :code:`${TINKER_LOC}` fills in the location for :code:`dynamic.x` which you put in line 2. Next, `1l2y` is the file name (without an extension) of the xyz file for this calculation (provided vile :code:`12ly.xyz`). You should have this from your original simulation. However, make sure that there is no box information on line two of this :code:`xyz` file, as this could cause Tinker to use periodic boundaries. Next, we give the input file (key file) we have prepared in the previous step using :code:`-k noewald.key`. Then, we give our MDI options. The given options should work for most analysis. After the MDI options are some Tinker input options. For our analysis, it will not really matter what we put here since we are running calculations on one snapshot at a time. However, you must have these present for Tinker to run. Very importantly, note the ampersand (:code:`&`) at the end of this line. This will launch Tinker in the background, where it will be waiting for commands from ELECTRIC.
+The first thing on this line, :code:`${TINKER_LOC}` fills in the location for :code:`dynamic.x` which you put in line 2. 
+Next, `1l2y` is the file name (without an extension) of the xyz file for this calculation (provided vile :code:`12ly.xyz`). 
+You should have this from your original simulation. 
+However, make sure that there is no box information on line two of this :code:`xyz` file, as this could cause Tinker to use periodic boundaries. 
+Next, we give the input file (key file) we have prepared in the previous step using :code:`-k noewald.key`. 
+Then, we give our MDI options. 
+The given options should work for most analysis. After the MDI options are some Tinker input options. 
+For our analysis, it will not really matter what we put here since we are running calculations on one snapshot at a time. 
+However, you must have these present for Tinker to run. Very importantly, note the ampersand (:code:`&`) at the end of this line. This will launch Tinker in the background, where it will be waiting for commands from ELECTRIC.
 
 .. warning::
 
@@ -156,12 +191,15 @@ In the next command (:code:`line 21`), we launch ELECTRIC.
 
     python ${DRIVER_LOC} -snap 1l2y_npt.arc -probes "78 93 94"  -mdi "-role DRIVER -name driver -method TCP -port 8022" --byres 1l2y_solvated.pdb  --equil 120 --stride 2 &
 
-Here, we first give the location of our ELECTRIC driver. We indicate our trajectory file using the `-snap` argument with the filename to analyze, followed by MDI options.
+Here, we first give the location of our ELECTRIC driver. 
+We indicate our trajectory file using the `-snap` argument with the filename to analyze, followed by MDI options.
 
 Probe Atoms 
 ++++++++++++
 
-To run an ELECTRIC calculation, you must give the indices of your probe atoms. The probe atoms are the atoms which are used as 'probes' for the electric field. ELECTRIC reports the projected total electric field at the midpoint between all probe atom pairs. This allows you to calculate electric fields along bonds `as reported in literature <https://pubs.acs.org/doi/10.1021/jacs.9b05323>`_.
+To run an ELECTRIC calculation, you must give the indices of your probe atoms. 
+The probe atoms are the atoms which are used as 'probes' for the electric field. ELECTRIC reports the projected total electric field at the midpoint between all probe atom pairs. 
+This allows you to calculate electric fields along bonds `as reported in literature <https://pubs.acs.org/doi/10.1021/jacs.9b05323>`_.
 
 You should obtain the number of the probe atoms from the :code:`xyz` file you use to launch MDI-enabled Tinker. Note that the index you use here should match the number given in the first column of your xyz file. The projection of the electric field at the midpoint of these two atoms will be reported for each analyzed frame. If you indicate more than two probes, all pairwise fields will be reported (ie, if using "78 93 94", you will get "78 and 93", "78 and 94" and "93 and 94"). You can see the atoms we have chosen as probes highlighted below: