merge vis docs

docs/source/developerGuide/doxygen/analysis/Morphology.rst

@@ -0,0 +1,5 @@
+============================================
+Morphology
+============================================
+.. doxygenfile:: morphology.h
+   :project: LBPM Doxygen

docs/source/examples/color/steadyState.rst

@@ -0,0 +1,5 @@
+*******************
+Steady-state flow
+*******************
+
+In this example we simulate a steady-state flow with a constant driving force.

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/morphology/morphOpen.rst

@@ -0,0 +1,110 @@
+*****************************
+Morphological pre-processors
+*****************************
+
+LBPM includes morphological pre-processing tools as utility functions.
+It is often useful to generate initial conditions for a 2-phase flow simulation based on a morphological approach. In particular, morphological tools can be used to provide a physical reasonable initial condition in cases where direct experimental observations are not available. These initial configurations are compatible with any of the 2-phase simulation protocols used by lbpm_color_simulator. These initialization approaches alter the fluid labels within the input files, writing a new file with the new morphologically assigned labels.
+
+There are two main morphological pre-processors in LBPM
+
+* ``lbpm_morphdrain_pp`` -- initialize fluid configuration based on morphological drainage
+* ``lbpm_morphopen_pp`` -- initialize fluid configuration based on morphological opening
+
+Here we demonstrate ``lbpm_morphdrain_pp`` because it offers the most information. Although it is not perfect, the morphological drainage operation does a good job of approximating configurations observed along primary drainage processes performed under water-wet conditions. A limitation is that fluid trapped in the corners will not stop the morphological operation from eroding it. This should not discourage you too much -- morphological tools are very practical and can save you a lot of time! It is also a good thing to be skeptical.
+
+Since the morphological operation works on the input domain, associated parameters are added to the ``Domain`` section of the input file. Here we will set a target saturation Sw = 0.20, which will run the morphological drainage operation until the fluid labeled as 2 occupies 20% of the pore space or less. For the case considered in
+``example/DiscPack`` we specify the following information in the input file
+
+.. code:: c
+
+	  Domain {
+	     Filename = "discs_3x128x128.raw"
+	     ReadType = "8bit"    // data type
+	     N = 3, 128, 128       // size of original image
+	     nproc = 1, 2, 2       // process grid
+	     n = 3, 64, 64         // sub-domain size
+	     voxel_length = 1.0    // voxel length (in microns)
+	     ReadValues = 0, 1, 2  // labels within the original image
+	     WriteValues = 0, 2, 2 // associated labels to be used by LBPM
+	     BC = 0                // fully periodic BC
+	     Sw = 0.35             // target saturation for morphological tools
+	  }
+
+Once this has been set, we launch lbpm_morphdrain_pp in the same way as other parallel tools
+
+.. code:: bash
+
+	  mpirun -np 4 $LBPM_BIN/lbpm_morphdrain_pp input.db
+
+Successful output looks like the following
+
+
+.. code:: bash
+
+
+	  Performing morphological opening with target saturation 0.350000 
+	  voxel length = 1.000000 micron 
+	  voxel length = 1.000000 micron 
+	  Input media: discs_3x128x128.raw
+	  Relabeling 3 values
+	  oldvalue=0, newvalue =0 
+	  oldvalue=1, newvalue =2 
+	  oldvalue=2, newvalue =2 
+	  Dimensions of segmented image: 3 x 128 x 128 
+	  Reading 8-bit input data 
+	  Read segmented data from discs_3x128x128.raw 
+	  Label=0, Count=11862 
+	  Label=1, Count=37290 
+	  Label=2, Count=0 
+	  Distributing subdomains across 4 processors 
+	  Process grid: 1 x 2 x 2 
+	  Subdomain size: 3 x 64 x 64 
+	  Size of transition region: 0 
+	  Media porosity = 0.758667 
+	  Initialized solid phase -- Converting to Signed Distance function 
+	  Volume fraction for morphological opening: 0.758667 
+	  Maximum pore size: 116.773801 
+	     1.000000      110.935111
+	     1.000000      105.388355
+	     1.000000      100.118937
+	     1.000000      95.112990
+	     1.000000      90.357341
+	     1.000000      85.839474
+	     1.000000      81.547500
+	     1.000000      77.470125
+	     1.000000      73.596619
+	     1.000000      69.916788
+	     1.000000      66.420949
+	     1.000000      63.099901
+	     1.000000      59.944906
+	     1.000000      56.947661
+	     1.000000      54.100278
+	     1.000000      51.395264
+	     1.000000      48.825501
+	     1.000000      46.384226
+	     1.000000      44.065014
+	     1.000000      41.861764
+	     1.000000      39.768675
+	     1.000000      37.780242
+	     1.000000      35.891230
+	     1.000000      34.096668
+	     1.000000      32.391835
+	     0.575114      30.772243
+	     0.433119      29.233631
+	     0.291231      27.771949
+	  Final void fraction =0.291231
+	  Final critical radius=27.771949
+	  Writing ID file 
+	  Writing file to: discs_3x128x128.raw.morphdrain.raw
+
+
+The final configuration can be visualized in python by loading the output file
+``discs_3x128x128.raw.morphdrain.raw``.
+
+
+.. figure:: ../../_static/images/DiscPack-morphdrain.png
+    :width: 600
+    :alt: morphdrain
+
+    Fluid configuration resulting from orphological drainage algorithm applied to a 2D disc pack.
+

docs/source/examples/running.rst

@@ -1,10 +1,21 @@
 ==============
-LBPM examples 
+Examples 
 ==============
 
 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/index.rst

@@ -12,9 +12,9 @@ LBPM -- Documentation
    :caption: Contents:
 
    install
-   examples/*
    userGuide/*
    developerGuide/*
+   examples/*
    publications/*
 
 Indices and tables

docs/source/userGuide/IO/fileformat.rst

@@ -5,9 +5,9 @@ I/O conventions for LBPM
 There are three main kinds of output file that are supported by LBPM.
 
 
-* CSV files --
+* CSV files -- space-delimited CSV files are used by the internal analysis framework
 
-* formatted binary files --
+* formatted binary files -- SILO and HDF5 formats are supported for visualization data
   
-* unformatted binary files --
+* unformatted binary files -- ``.raw`` extension
 

docs/source/userGuide/analysis/analysis.rst

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

docs/source/userGuide/index.rst

@@ -10,8 +10,6 @@ Welcome to the LBPM user guide.
 
    models/*
 
-   analysis/*
-
    visualization/*
 
    IO/*

docs/source/userGuide/models/color/index.rst

@@ -266,3 +266,8 @@ the inlet or outlet, the ``Domain`` section of the database may specify the foll
 - ``InletLayerPhase = 2`` -- establish a reservoir of component B at the inlet
 - ``OutletLayerPhase = 1`` -- establish a reservoir of component A at the outlet
 
+****************
+Example data
+****************
+
+Example data can be downloaded from https://www.digitalrocksportal.org/projects/326 

docs/source/userGuide/models/color/protocols/fractionalFlow.rst

@@ -52,7 +52,7 @@ where :math:`\max{|\mathbf{u}_i|}` is the maximum flow speed within fluid :math:
 :math:`U_\epsilon` is a threshold speed that is set to minimize the influence of spurious
 currents on the mass seeding algorithm. The sum of the weighting function is used to normalize
 the local weights so that the added mass will match the value specified by ``mass_fraction_factor``.
-If the flow is slower than :math:`\epsilon_m`, the algorithm will tend to add mass evenly to the system.
+If the flow is slower than :math:`U_\epsilon`, the algorithm will tend to add mass evenly to the system.
 For example, if the water is only present in films that flow very slowly, then mass will
 be evenly seeded throughout entire water film. Alternatively, if one or both fluids
 flows through distinct channels, the mass will be disproportionately added to these

docs/source/userGuide/visualization/visit.rst

@@ -2,6 +2,51 @@
 Visualizing simulation data with visit
 ======================================
 
-placeholder for visit
 
-Paraview > v 5.6 also works
+(Paraview > v 5.6 also works)
+
+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.