update documentation

docs/data/ef_components.csv

@@ -0,0 +1,13 @@
+Fragment and Dimension,1 - frame 1,40 - frame 1,1 - frame 2,40 - frame 2,1 - frame 3,40 - frame 3,1 - frame 4,40 - frame 4,1 - frame 5,40 - frame 5
+molecule 1 x dimension,1.8262279768579937,-0.0047179926402617514,-0.3723252217837837,-0.017199687043554998,-2.515659725009313,-0.010279485953202713,-4.270870170060251,0.0016770820564744652,-4.708666647031746,-0.000680442496540009
+molecule 1 y dimension,10.148831988077632,0.058665493296096154,10.93003306256905,0.05718132463856401,8.333055241110436,0.0603487311443074,6.5676549587918265,0.06349865642634576,9.058947426975926,0.06291027633226648
+molecule 1 z dimension,-7.060846117656104,-0.11663314496255472,-10.560871168946536,-0.12087971002782381,-7.793605901662684,-0.12593595374623723,-3.382081132873187,-0.12553377468337815,-4.585910327746183,-0.11903989678075207
+molecule 2 x dimension,-0.07791329400452499,0.014470338970554816,-0.0809840593714769,0.03149389669153473,-0.07362334915614296,0.039733486177435315,-0.062339561940880216,0.04451402935631562,-0.05938911137941591,0.058077018755393464
+molecule 2 y dimension,-0.11254244190630665,0.2668289155171329,-0.09274276469029358,0.25338303332977485,-0.08118403694723506,0.23338563904933202,-0.07526950520283013,0.21628561037475763,-0.0674325435148582,0.21551738267523998
+molecule 2 z dimension,-0.011952285818149127,0.06272805619292927,-0.024453086595237938,0.05477790428183829,-0.03514709633294025,0.03769509837863063,-0.04528561653268578,0.017369640435922335,-0.05976420793749163,0.0023435401094188033
+molecule 215 x dimension,-0.08600595280760366,0.5859068538785298,-0.08812062700006139,0.5559680670283079,-0.08482716278108815,0.5202425009749166,-0.0936943190889687,0.41481645414364665,-0.11520016217782579,0.27551503718349835
+molecule 215 y dimension,-0.2288714969900536,1.0287732765817474,-0.23743765178279894,1.0984843015451986,-0.24301652125448248,1.178177774091673,-0.2388253727226811,0.9793992289081226,-0.23113787762285584,0.6228094923608826
+molecule 215 z dimension,0.05333496359933657,4.217728337357757,0.051171677705054715,4.474347015721427,0.04537430961675187,4.704608730820179,0.04629264291151047,4.564616689231048,0.053297010989539456,4.24920612512515
+molecule 216 x dimension,15.225602052452881,0.0834852339341002,15.319748509204915,0.08082436217913609,15.661226311846072,0.07912597466376274,15.64796634718585,0.07716974683122667,15.369595318241316,0.07859475885641187
+molecule 216 y dimension,-21.98290337536478,0.12256926387956626,-21.737783060478684,0.1212509179592026,-22.0662450329982,0.12496425025399872,-22.083492829763294,0.12878078686910324,-21.752263038610153,0.13215284529311944
+molecule 216 z dimension,18.803015852160865,0.13241836916189217,18.210049185681644,0.12187110849792329,18.356553802565898,0.1194881426223918,18.411111366172538,0.12033407621582343,17.98831850319465,0.12007400565795502

docs/index.rst

@@ -8,9 +8,11 @@ ELECTRIC
 
 ELECTRIC: Electric fields Leveraged from multipole Expansion Calculations in Tinker Rapid Interface Code.
 
-ELECTRIC uses the MolSSI Driver Interface to perform electric field analysis of Tinker trajectories which use the AMOEBA forcefield. This currently works as a post-processing tool, meaning that you run simulations as normal using Tinker, then analyze the trajectories using MDI-enabled Tinker and this driver. 
+ELECTRIC uses the `MolSSI Driver Interface <https://molssi.org/software/mdi-2/>`_ to perform electric field analysis of Tinker trajectories which use the AMOEBA forcefield. 
+This currently works as a post-processing tool, meaning that you run simulations as normal using Tinker, then analyze the trajectories using MDI-enabled Tinker and this driver. 
 
-ELECTRIC is written by Jessica A. Nash and Taylor A. Barnes from `The Molecular Sciences Software Institute <https://molssi.org/>`_, in collaboration with `Prof. Valerie Vassier Welborn <https://www.valeriewelborn.com/>`_.
+ELECTRIC is written by Jessica A. Nash and Taylor A. Barnes from `The Molecular Sciences Software Institute <https://molssi.org/>`_, 
+in collaboration with `Prof. Valerie Vassier Welborn <https://www.valeriewelborn.com/>`_.
 
 Using this tool, you can calculate the electric field along a bond or between atoms due to molecules or residues in the system.
 

docs/installation.rst

@@ -10,7 +10,8 @@ Compiling MDI-Tinker and ELECTRIC
     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 :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` 
+If you are using the :code:`conda` package manager, you can clone the repository and use the provided 
+:code:`environment.yaml` 
 to create an environment with the required dependencies (including Python packages) using the following command.
 
 .. code-block:: bash
@@ -67,7 +68,7 @@ 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:`-mdi "role ENGINE -name NO_EWALD -method TCP -port 8022 -hostname localhost"`):
 
 .. code-block:: bash
 
@@ -80,7 +81,7 @@ which will listen for connections from an MDI engine:
 
     python ${DRIVER_LOC} -probes "1 40" -snap bench5.arc -mdi "-role DRIVER -name driver -method TCP -port 8022" --bymol &
 
-The driver's output should match the reference output file (`proj_totfield.csv`) in the `sample_analysis` directory.
+The driver's output should match the reference output file (:code:`proj_totfield.csv`) in the :code:`sample_analysis` directory.
 
 
 

docs/usage.rst

@@ -91,15 +91,44 @@ You can change the options for your electric calculation through command line ar
 Output
 ------
 
-The driver will output a file called :code:`proj_totfield.csv`. This is a CSV file which contains data on the projected electric field at the point between each probe atom due to each fragment , depending on input (`--byres` for by residue, `--bymol` for by molecule, or by atom if neither argument is given.). Each column will contain a header which indicates which probe atoms the measurement is between, followed by the frame number, while the rows will be the electric field at the mean location between the probe atoms due to a particular fragment
+Depending on the input options specified, ELECTRIC will output one or two files.
+As of ELECTRIC version 1.1, the driver will output a file called :code:`ef_components.csv` in addition to :code:`proj_totfield.csv`.
+The file :code:`ef_components.csv` contains the ELECTRIC field components (x, y, and z) direction at each probe due to each fragment.
+The file :code:`proj_totfield.csv` contains the projected electric field at the point between each probe atom due to each fragment.
 
-Consider the example (:code:`bench5`), which was run with the following command:
+For an explanation of the output, consider the example (:code:`bench5`), 
+which was run with the following command:
 
 .. code-block:: bash
 
     python ${DRIVER_LOC} -probes "1 40" -snap bench5.arc -mdi "-role DRIVER -name driver -method TCP -port 8022" --bymol
 
-Here, we have set the probe atoms to be atoms 1 and 40, and we have indicated we want the the electric field between the probe atoms based on contributions by molecule. Headers will be "`i and j - frame n`. Where `i` and `j` are the atom indices of the probes, and `n` is the frame number.
+
+Electric Field Components
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The file :code:`ef_components.csv` will contain the values for the electric field in Mv/cm for each component (x, y, and z) 
+at each probe atom due to each fragment.
+For example, a truncated version of our example output is:
+
+.. datatable::
+
+    csv_file: data/ef_components.csv
+
+The first column is the fragment and dimension, 
+while subsequent columns give information about the probe atom and frame number.
+In the example above, the value in row 1, column 2 is the x-component of the electric field at probe atom 1 due to molecule 1 in frame 1 of the simulation trajectory.
+
+Projected Electric Field
+^^^^^^^^^^^^^^^^^^^^^^^^
+The driver will output a file called :code:`proj_totfield.csv`. 
+This is a CSV file which contains data on the projected electric field at the point between each probe atom due to each fragment , 
+depending on input (`--byres` for by residue, `--bymol` for by molecule, or by atom if neither argument is given.). 
+Each column will contain a header which indicates which probe atoms the measurement is between, followed by the frame number, 
+while the rows will be the electric field at the mean location between the probe atoms due to a particular fragment
+
+Here, we have set the probe atoms to be atoms 1 and 40, 
+and we have indicated we want the the electric field between the probe atoms based on contributions by molecule. 
+Headers will be "`i and j - frame n`. Where `i` and `j` are the atom indices of the probes, and `n` is the frame number.
 
 For the example, headers are:
 
@@ -111,9 +140,13 @@ For the example, headers are:
     "1 and 40 - frame 4"
     "1 and 40 - frame 5"
 
-Since this calculation was run using :code:`--bymol`, there are 216 rows, one for each molecule in the system.
+Since this calculation was run using :code:`--bymol`, 
+there are 216 rows, one for each molecule in the system.
 
-The first entry, column :code:`1 and 40 - frame 1`, header :code:`molecule 1`, gives the projected total electric field at the midway point between :code:`atom 1` and :code:`atom 40` due to :code:`molecule 1`. The electric field has been projected along the vector which points from :code:`atom 1` to :code:`atom 40`. The projection will always be along the vector from atom 1 to atom 2. You can reverse the sign of the number if you would like the vector to point the opposite way.
+The first entry, column :code:`1 and 40 - frame 1`, 
+header :code:`molecule 1`, gives the projected total electric field at the midway point between :code:`atom 1` and :code:`atom 40` due to :code:`molecule 1`. 
+The electric field has been projected along the vector which points from :code:`atom 1` to :code:`atom 40`. 
+The projection will always be along the vector from atom 1 to atom 2. You can reverse the sign of the number if you would like the vector to point the opposite way.
 
 
 Running ELECTRIC in Parallel