More documentation

README.rst

@@ -12,8 +12,8 @@ What wlcsim is
 --------------
 
 This is a project started by the Spakowitz lab to make varioius polymer physics
-simulations / calulations.  The bulk of the codebalse is build around a FORTRAN
-code that is designed to efficiently simulate various simualtions of wormlike
+simulations / calulations.  The bulk of the codebalse is built around a FORTRAN
+code that is designed to efficiently simulate various systems of wormlike
 chain polymer(s) using various coarse-grainings where applicable.  This code
 performs Monte Carlo or Brownian dynamics simulations.
 
@@ -29,8 +29,8 @@ More details on how the code is structured see :ref:`wlcsimf`
 Setting up a simulation
 -----------------------
 
-To define the system you would like to simulate set the approparte values
-``src\defines.inc``.  Discriptions of each parameter are found along with the
+To define the system you would like to simulate, set the approparte values
+``src\defines.inc``.  Discriptions of each parameter are found along with their
 definitions in ``src\defines.inc``.  In pracatice, the best approach is often to
 start from examples provided in ``input/example_defines/``.
 
@@ -39,16 +39,19 @@ from compiling. This is on purpose so that the code is not accidentally run with
 something arbitrary for these values (like the length of the chain, the
 persistence length, etc).
 
+For tips on setting up and running simulations see :ref:`tips`.
+
 To Run
 ------
 
+
 Simply typing ``make`` in the top level directory will build the simulator
 from source. The executable created (``wlcsim.exe``) will data from the ``input/``
 directoyr and write its output to the ``data`` directory.
 To force a rerun without having to manually delete all the old output files, you
 can also simply type ``make run`` at any time.
 
-By default, pecifying multiple polymers just simulates them in parallel in the same
+By default, specifying multiple polymers just simulates them in parallel in the same
 reaction volume, no interactions are assumed.
 
 To scan parameters, the Python script ``scan_wlcsim.py`` should be used. It takes

doc/index.rst

@@ -20,6 +20,7 @@ Contents:
    features
    output
    parallel_temp
+   tips
    homolog.ipynb
    FrankExample.ipynb
 

doc/tips.rst

@@ -0,0 +1,49 @@
+.. _tips:
+
+Tips
+####
+
+This page contains usefull tips that we have found usefull for using this
+codebase.  These may be helpful for your workflow.
+
+Running Remotely
+================
+
+When running wlcsim remotely you may want to use tmux so that you don't get
+logged off while wlcsim is running.  More documentation on this comming
+shortly.
+
+The defines.inc file
+====================
+
+You will likely end up with many different defines.inc files.  Generally I
+keep a few examples around in `input/exampledefines`.  One of the best tools for comparing defines files is `vim -d defines.inc path/other_defines.inc`.  Look up vim diff online for more shortcuts when using this, they are really helpfull.
+
+Each setting comes with a description.  But you will likely run into cases where the description isn't enough.  Because the settings are named with uinque strings, it is easy to grep the code base for them.  For example:
+
+grep -r "WLC_P__WHATEVERSETTING" src/
+
+Running / storing simulations
+=============================
+
+Genearally I coppy the *entire* code base around when I want to run it again with different settings.  The code is small compaired to the output so this donesn't really take up much extra space.  I recompile every time I run with `make clean`.  Since compiling `wlcsim` is fast compaired to running you might as well.
+
+Compiling options
+=================
+
+When debugging you likely want to run with `FCFLAGS = ${PEDANTICFLAGS}` in `Makefile`.  When running long simulations you likely want to switch to `FCFLAGS = ${FASTFLAGS}`.  Be sure to `make clean` after changing this setting.
+
+Trouble Shooting
+================
+
+When running Monte Carlo many different runtime errors will lead to the integrated energy differing from the energy when it is calculated again from scratch. You'll want to moniter the error output for this warning. This check is one of the best features of this codebase when it comes to code testing, trust us you want it! Here are some tips for if this should occure:
+
+- Turn off some moves and not others.  If the error only occures on some subset that can be informative.
+
+- Are the energies really big?  This may have tripped this error.  You likely don't acctually want them to be that big.
+
+- Which energy type is not matching?  Are there multiple that arn't matching.
+
+If the text in the error message appears to be refering to text that isn't actually there.
+
+- The text may have been replaced by the precomilier to the values givin in `src/defines.inc`.  This probably means there's an error with one of your settings.

doc/wlcsimf.rst

@@ -3,6 +3,10 @@
 wlcsim Fortran Codebase Structure
 #################################
 
+.. image:: code_diagram.png
+    :width: 500
+    :alt: Should show image of code diagram
+
 .. f:program:: wlcsim
 
     Use a universal discretization scheme to simulate from WLCs through
@@ -31,8 +35,15 @@ the input in `defines.inc`.
 `mcsim.f03` calls different subroutines that define possible Monte Carlo moves
 (like `MC_reptationMove.f03`) and then checks for whether the move should
 succeed by summing the various energies that are turned on (like `mc_wlc.f90`).
+Diagrams describing a few of the moves are provided here:
+
+.. image:: moves.png
+    :width: 600
+    :alt: Should show images of moves
 
-.. f:autosrcfile:: MC_reptationMove.f03
+.. image:: spider_move.png
+    :width: 400
+    :alt: Should show the image of spider move
 
 :ref:`MC_wlc`