update visit docs

docs/source/examples/domain/domain.rst

@@ -0,0 +1,52 @@
+*****************
+Input Domain
+*****************
+
+LBPM provides a flexible framework to ingest 3D image data.
+To illustrate the basic capabilities, this tutorial considers a quasi-2D
+flow cell. Source files for the example are included in the LBPM repository
+in the directory ``examples/DiscPack``. A simple python code is included
+to set up the flow domain.
+
+Based on LBPM convention, external boundary conditions are applied in the
+z-direction. This means that the domain should be set up so that the direction
+you want to set boundary conditions is aligned with the z-axis. For the quasi-2D
+example, a depth of ``3`` voxels is used for the x-direction. *Based on LBPM
+internal data structures at least three voxels must be provided in each direction*
+The specified domain decomposition must also observe this rule.
+
+Image data is stored internally within LBPM as signed 8-bit binary data. This means that
+up to 256 labels can be provided in the input image. LBPM convention takes all
+non-positive labels to be immobile (treated as solid). In this example, the solid regions
+are assigned a value of ``0``.  It is possible to provide up to ``128`` different labels
+for the solid. Also, note that python supports only the unsigned 8-bit datatype. For the unsigned data
+type, labels assigned values ``128,...255`` in python will correspond to labels
+``-127,...-1`` when read in as type ``signed char`` within LBPM. 
+
+.. code:: python
+
+	  import numpy as np
+	  import matplotlib.pylab as plt
+	  import pandas as pd
+	  # Set the size of the domain
+	  Nx=3
+	  Ny=128
+	  Nz=128
+	  D=pd.read_csv("discs.csv",sep=" ")
+	  ID = np.ones(Nx*Ny*Nz,dtype='uint8')
+	  ID.shape = (Nz,Ny,Nx)
+	  # Set the solid labels
+	  for idx in range(len(D)):
+             cx=D['cx'][idx] / dx
+             cy=D['cy'][idx] /dx
+             r=D['r'][idx] /dx
+             for i in range(0,Nz):
+                for j in range(0,Ny):
+                   if ( (cx-i)*(cx-i) + (cy-j)*(cy-j) < r*r ):
+                      ID[i,j,0] = 0
+                      ID[i,j,1] = 0
+                      ID[i,j,2] = 0
+        # write input file to disc
+	ID.tofile("discs_3x128x128.raw")
+
+

docs/source/examples/running.rst

@@ -6,5 +6,16 @@ There are two main components to running LBPM simulators.
 First is understanding how to launch MPI tasks on your system,
 which depends on the particular implementation of MPI that you are using,
 as well as other details of the local configuration. The second component is
-understanding the LBPM input file structure. 
+understanding the LBPM input file structure. The examples included provide
+a basic introduction to working with LBPM. 
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   domain/*
+
+   morphology/*	      
+   
+   color/*
    

docs/source/userGuide/analysis/analysis.rst

@@ -1,5 +0,0 @@
-===========================
-Internal Analysis Framework
-===========================
-
-placeholder for analysis 

docs/source/userGuide/visualization/visit.rst

@@ -2,4 +2,48 @@
 Visualizing simulation data with visit
 ======================================
 
-placeholder for visit
+Control over visualization options is set within the ``Visualization`` section of the input file
+
+.. code:: c
+
+   Visualization {
+      write_silo = true     // write SILO databases with assigned variables
+      save_8bit_raw = true  // write labeled 8-bit binary files with phase assignments
+      save_phase_field = true  // save phase field within SILO database
+      save_pressure = false    // save pressure field within SILO database
+      save_velocity = false    // save velocity field within SILO database
+   }
+
+LBPM provides two main options for visualization. The first is the writing of 8-bit raw binary files, which are labeled based on the timestep. For example, if ``visualization_interval = 10000`` (specified within the Analysis section of the input file) the first 8-bit binary file will be written when ``timestep = 1000`` and will be named ``id_t1000.raw``. Additional files will be written subsequently at the specified interval. Similarly, higher fidelity visualization files are written using the SILO format, which are stored within the directories ``vis1000/``. The summary file ``LBM.visit`` enumerates these files so that they can be loaded directly into VisIt or other visualization software. By default, only the phase field will be saved. Visualization for other variables, such as the pressure and velocity fields, can be enabled by setting the associated flags to ``true``.
+
+The VisIt software is able to natively read the SILO format. To import the data fields written by LBPM, open the VisIt GUI and select ``File > Open file`` from the top menu. Then select the LBM.visit file that you would like to read
+
+.. figure:: ../../_static/images/lbpm-visit-workflow-i.png
+	   :width: 600
+	   :alt: VisIt GUI
+
+	   Opening data in the VisIt GUI. 
+
+Once the file has been opened, any database fields within the file will be visible from within the program. Here we construct an 3D countour the phase field to visualize the boundary of the oil. The menu for the ``Contour`` object will show that the data for phase is available. The pressure and velocity fields will only be visible if they have been explicitly enabled within the simulation options (see ``Visualization`` details above)
+	   
+.. figure:: ../../_static/images/lbpm-visit-workflow-ii.png
+	   :width: 600
+	   :alt: VisIt GUI
+
+	   Selecting isosurface contour to represent a surface.
+
+Once the contour has been created, double click the object icon to open the countour plot attributes window. In the field for ``Select by`` choose ``values`` and specify ``0`` as the contour to draw. Note that it is possible to change the color and opacity of the contour, which is useful if you want to draw multiple contours on the same plot
+	   
+.. figure:: ../../_static/images/lbpm-visit-workflow-iii.png
+	   :width: 600
+	   :alt: VisIt GUI
+
+	   Drawing an isosurface.
+
+Once the attributes have been selected, click the Draw button to render the contour. Depending on the machine where you are rendering and the size of the image, it may take several minutes to render the window
+
+.. figure:: ../../_static/images/lbpm-visit-workflow-iv.png
+	   :width: 600
+	   :alt: VisIt GUI
+
+	   Rendering an isosurface.