added sphinx rtd

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = $(HOME)/local/doc/build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,12 @@
+Dependencies for LBPM documentation
+
+# install sphinx
+pip install Sphinx
+
+# foamatting requires sphinx read-the-docs-theme
+pip install sphinx-rtd-theme
+
+# equation rendering requires latex and dvipng command
+sudo apt-get install dvipng
+sudo apt-get install texlive texstudio
+sudo apt-get install texlive-latex-recommended texlive-pictures texlive-latex-extra

docs/source/conf.py

@@ -0,0 +1,70 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'LBPM'
+copyright = '2021, James E McClure'
+author = 'James E McClure'
+
+# The full version, including alpha/beta/rc tags
+release = '1.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.imgmath'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+## Read the docs style:
+if os.environ.get('READTHEDOCS') != 'True':
+    try:
+        import sphinx_rtd_theme
+    except ImportError:
+        pass  # assume we have sphinx >= 1.3
+    else:
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    html_theme = 'sphinx_rtd_theme'
+    
+#def setup(app):
+#    app.add_stylesheet("fix_rtd.css")

docs/source/developerGuide/buildingModels/overview.rst

@@ -0,0 +1,20 @@
+===========================
+Implementing a new LB model
+===========================
+
+While LBPM includes a range of fully-functioning lattice Boltzmann models, the commonly used
+Bhatnager-Gross-Krook (BGK) model has been deliberately excluded. While the physical limitations
+of this model are well-known, implementing the BGK model is an excellent way to understand
+how to implement new LB models within the more general framework of LBPM. In this excercise
+you will
+
+* learn "what goes where"
+
+
+
+* don't modify core data structures (unless you have a really good reason)
+
+* re-use existing components whenever possible
+
+
+

docs/source/developerGuide/designOverview/dataStructures.rst

@@ -0,0 +1,6 @@
+===============
+Data Structures
+===============
+
+LBPM includes a variety of generalized data structures to facilitate the implementation
+of different lattice Boltzmann models. 

docs/source/developerGuide/index.rst

@@ -0,0 +1,18 @@
+###############################################################################
+Developer guide
+###############################################################################
+
+The LBPM developer guide provides essential information on how to add new physics
+into the framework. 
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   designOverview/*
+   
+   buildingModels/*
+
+   testingModels/*
+
+ 

docs/source/developerGuide/testingModels/unitTests.rst

@@ -0,0 +1,9 @@
+=================
+Adding unit tests
+=================
+
+Unit tests in LBPM are implemented using ctest
+
+* general overview
+
+* launching unit tests for GPU (MPI flags etc.)

docs/source/examples/running.rst

@@ -0,0 +1,9 @@
+============
+Running LBPM
+============
+
+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. 

docs/source/index.rst

@@ -0,0 +1,25 @@
+.. LBPM documentation master file, created by
+   sphinx-quickstart on Thu May 20 12:19:14 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+LBPM -- Documentation
+===================================================
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+   :caption: Contents:
+
+   install
+   examples/*
+   userGuide/*
+   developerGuide/*
+   publications/*
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/install.rst

@@ -0,0 +1,10 @@
+============
+Installation
+============
+
+LBPM requires CMake, MPI and HDF5 as required dependencies. 
+
+.. code-block:: bash
+
+    ls $LBPM_SOURCE/sample_scripts
+    

docs/source/publications/publications.rst

@@ -0,0 +1,13 @@
+============
+Publications
+============
+
+* James E McClure, Zhe Li, Mark Berrill, Thomas Ramstad, "The LBPM software package for simulating multiphase flow on digital images of porous rocks" Computational Geosciences (25) 871–895 (2021) https://doi.org/10.1007/s10596-020-10028-9
+
+
+* James E. McClure, Zhe Li, Adrian P. Sheppard, Cass T. Miller, "An adaptive volumetric flux boundary condition for lattice Boltzmann methods" Computers & Fluids (210) (2020) https://doi.org/10.1016/j.compfluid.2020.104670
+
+
+* Y.D. Wang, T. Chung, R.T. Armstrong, J. McClure, T. Ramstad, P. Mostaghimi, "Accelerated Computation of Relative Permeability by Coupled Morphological and Direct Multiphase Flow Simulation" Journal of Computational Physics (401) (2020) https://doi.org/10.1016/j.jcp.2019.108966
+
+ 

docs/source/userGuide/IO/fileformat.rst

@@ -0,0 +1,13 @@
+========================
+I/O conventions for LBPM
+========================
+
+There are three main kinds of output file that are supported by LBPM.
+
+
+* CSV files --
+
+* formatted binary files --
+  
+* unformatted binary files --
+

docs/source/userGuide/analysis/analysis.rst

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

docs/source/userGuide/index.rst

@@ -0,0 +1,17 @@
+###############################################################################
+User Guide
+###############################################################################
+
+Welcome to the LBPM user guide.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   models/*
+
+   analysis/*
+
+   visualization/*
+
+   IO/*

docs/source/userGuide/models/PoissonBoltzmann/PoissonBoltzmann.rst

@@ -0,0 +1,6 @@
+=============================================
+Poisson-Boltzmann model
+=============================================
+
+The LBPM Poisson-Boltzmann solver is designed to solve the Poisson-Boltzmann equation
+to solve for the electric field in an ionic fluid. 

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

@@ -0,0 +1,91 @@
+###############################################################################
+Color model
+###############################################################################
+
+The LBPM color model is implemented by combining a multi-relaxation time D3Q19
+lattice Boltzmann equation (LBE) to solve for the momentum transport with two D3Q7
+LBEs for the mass transport. The color model will obey strict mass and momentum
+conservation while minimizing diffusive fluxes across the interface between fluids.
+The color model is a good choice for modeling dense fluids that are strongly immiscible
+(e.g. water-oil systems). Due to the strong anti-diffusion in the interface region,
+the color model is not suitable for modeling processes such as Ostwald ripening that
+depend on diffusive fluxes between fluid phases.
+
+A typical command to launch the LBPM color simulator is as follows
+
+```
+mpirun -np $NUMPROCS lbpm_color_simulator input.db
+```
+
+where ``$NUMPROCS`` is the number of MPI processors to be used and ``input.db`` is
+the name of the input database that provides the simulation parameters.
+Note that the specific syntax to launch MPI tasks may vary depending on your system.
+For additional details please refer to your local system documentation.
+
+****************************
+Simulation protocols
+****************************
+
+Simulation protocols are designed to make it simpler to design and execute common
+computational experiments. Protocols will automatically determine boundary conditions
+needed to perform a particular simulation. LBPM will internall set default simulation paramaters
+that can be over-ridden to develop customized simulations.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   protocols/*
+
+
+***************************
+Model parameters
+***************************
+
+The essential model parameters for the color model are
+
+- :math:`\alpha` -- control the interfacial tension between fluids with key ``alpha``
+- :math:`\beta`  -- control the width of the interface with key ``beta``
+- :math:`\tau_A` -- control the viscosity of fluid A with key ``tauA``
+- :math:`\tau_B` -- control the viscosity of fluid B with key ``tauB``
+
+****************************
+Model Formulation
+****************************
+
+
+  
+****************************
+Boundary Conditions
+****************************
+
+The following external boundary conditions are supported by ``lbpm_color_simulator``
+and can be set by setting the ``BC`` key values in the ``Domain`` section of the
+input file database
+
+- ``BC = 0`` -- fully periodic boundary conditions
+- ``BC = 3`` -- constant pressure boundary condition
+- ``BC = 4`` -- constant volumetric flux boundary condition
+
+For ``BC = 0`` any mass that exits on one side of the domain will re-enter at the other
+side. If the pore-structure for the image is tight, the mismatch between the inlet and
+outlet can artificially reduce the permeability of the sample due to the blockage of
+flow pathways at the boundary. LBPM includes an internal utility that will reduce the impact
+of the boundary mismatch by eroding the solid labels within the inlet and outlet layers
+(https://doi.org/10.1007/s10596-020-10028-9) to create a mixing layer.
+The number mixing layers to use can be set using the key values in the ``Domain`` section
+of the input database
+
+- ``InletLayers  = 5`` -- set the number of mixing layers to ``5`` voxels at the inlet
+- ``OUtletLayers  = 5`` -- set the number of mixing layers to ``5`` voxels at the outlet
+
+For the other boundary conditions a thin reservoir of fluid  (default ``3`` voxels)
+is established at either side of the domain. The inlet is defined as the boundary face
+where ``z = 0`` and the outlet is the boundary face where ``z = nprocz*nz``. By default a
+reservoir of fluid A is established at the inlet and a reservoir of fluid B is established at
+the outlet, each with a default thickness of three voxels. To over-ride the default label at
+the inlet or outlet, the ``Domain`` section of the database may specify the following key values
+
+- ``InletLayerPhase = 2`` -- establish a reservoir of component B at the inlet
+- ``OutletLayerPhase = 1`` -- establish a reservoir of component A at the outlet
+

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

@@ -0,0 +1,12 @@
+======================================
+Color model -- Centrifuge Protocol
+======================================
+
+The centrifuge protocol is designed to mimic SCAL centrifuge experiments that
+are used to infer the capillary pressure. The centrifuge protocol 
+
+.. code-block:: bash
+
+    image_sequence = "image1.raw", "image2.raw"
+    
+

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

@@ -0,0 +1,63 @@
+======================================
+Color model -- Core Flooding
+======================================
+
+The core flooding protocol is designed to mimic SCAL experiments where one
+immiscible fluid is injected into the sample at a constant rate, displacing the
+other fluid. The core flooding protocol relies on a flux boundary condition
+to ensure that fluid is injected into the sample at a constant rate. The flux
+boundary condition implements a time-varying pressure boundary condition that
+adapts to ensure a constant volumetric flux. Details for the flux boundary
+condition are available
+(see: https://doi.org/10.1016/j.compfluid.2020.104670)
+
+.. code-block:: bash
+
+    protocol = "core flooding"
+    
+
+To match experimental conditions, it is usually important to match the capillary
+number, which is
+
+.. math::
+   \mbox{Ca} = \frac{\mu u_z}{\gamma}
+
+
+where :math:`\mu` is the dynamic viscosity, :math:`u_z` is the fluid
+(usually water) velocity and :math:`\gamma` is the interfacial tension.
+The volumetric flow rate is related to the fluid velocity based on
+
+.. math::
+   Q_z = \epsilon C_{xy} u_z
+
+where :math:`C_{xy}` is the cross-sectional area and :math:`\epsilon`
+is the porosity. Given a particular experimental system 
+self-similar conditions can be determined for the lattice Boltzmann
+simulation by matching the non-dimensional :math:`mbox{Ca}`. It is nearly
+awlays advantageous for the timestep to be as large as possible so
+that time-to-solution will be more favorable. This is accomplished by
+
+* use a high value for the numerical surface tension (e.g. ``alpha=1.0e-2``)
+* use a small value for the fluid viscosity (e.g. ``tau_w = 0.7`` and ``tau_n = 0.7`` )
+* determine the volumetric flow rate needed to match :math:`\mbox{Ca}`
+
+For the color LBM the interfacial tension is
+:math:`\gamma = 6 \alpha` and the dynamic viscosity is :math:`\mu =  \rho(\tau-1/2)/3`,
+where the units are relative to the lattice spacing, timestep and mass
+density. Agreemetn between the experimental and simulated values for
+:math:`\mbox{Ca}` is ensured by setting the volumetric flux
+
+.. math::
+   Q_z = \frac{\epsilon C_{xy} \gamma }{\mu} \mbox{Ca}
+
+where the LB units of the volumetric flux will be voxels per timestep.
+
+In some situations it may also be important to match other non-dimensional numbers,
+such as the viscosity ratio, density ratio, and/or Ohnesorge/Laplace number. This
+can be accomplished with an analogous procedure. Enforcing additional constraints
+will necessarily restrict the LB parameters that can be used, which are ultimately
+manifested as a constraint on the size of a timestep. 
+
+
+
+

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

@@ -0,0 +1,17 @@
+==========================================
+Color model -- Fractional Flow Protocol
+==========================================
+
+The fractional flow protocol is designed to perform steady-state relative 
+permeability simulations by using an internal routine to change the fluid
+saturation by adding and subtracting mass to the fluid phases. The 
+mass density is updated for each fluid based on the locations where
+the local rate of flow is high. 
+
+.. code-block:: bash
+
+	protocol = "fractional flow"
+
+    
+    
+

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

@@ -0,0 +1,27 @@
+======================================
+Color model -- Image Sequence Protocol
+======================================
+
+The image sequence protocol is designed to perform a set steady-state
+simulations based on a sequence of 3D (8-bit) images provided by the user.
+The images might be the output of a previous LBPM simulation, a sequence of
+(segmented) experimental data, or data generated from a custom routine.
+The image sequence protocol will apply the same set of flow conditions
+to all images in the sequence. This means
+
+* the image labels and any associated properties are the same
+* the external boundary conditions are the same
+* the physical simulation parameters are the same
+
+The image sequence protocol does not set boundary conditions by default.
+It is up to the user to determine the flow condition, with the understanding
+that the same set of will be applied to each image in the sequence.
+
+To enable the image sequence protocol, the following keys should be set
+within the ``Color`` section of the input database
+
+.. code-block:: bash
+
+   protocol = "image sequence"
+   image_sequence = "image1.raw", "image2.raw"
+    

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

@@ -0,0 +1,18 @@
+==========================================
+Color model -- Shell Aggregation Protocol
+==========================================
+
+The shell aggregation protocol is designed to perform steady-state relative 
+permeability simulations by using an internal routine to change the fluid
+saturation by moving the interface. The basic design for the shell aggregation
+protocol is described by Wang et al. ( https://doi.org/10.1016/j.jcp.2019.108966 ).
+
+
+.. code-block:: bash
+
+
+	protocol = "shell aggregation"
+
+    
+    
+

docs/source/userGuide/models/freeEnergy/freeEnergy.rst

@@ -0,0 +1,6 @@
+=============================================
+Free energy model
+=============================================
+
+The LBPM free energy model is constructed to solve the Allen-Cahn equations,
+which are typically used to describe liquid-gas systems. 

docs/source/userGuide/models/greyscale/greyscale.rst

@@ -0,0 +1,7 @@
+=============================================
+Greyscale model model
+=============================================
+
+The LBPM greyscale lattice Boltzmann model is constructed to approximate the
+solution of the Darcy-Brinkman equations in grey regions, coupled to a Navier-Stokes
+solution in open regions. 

docs/source/userGuide/models/index.rst

@@ -0,0 +1,23 @@
+###############################################################################
+LBPM model summary
+###############################################################################
+
+Currently supported lattice Boltzmann models
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   color/*
+
+   mrt/*
+
+   nernstPlanck/*
+
+   PoissonBoltzmann/*
+   
+   greyscale/*
+
+   freeEnergy/*
+
+   

docs/source/userGuide/models/mrt/mrt.rst

@@ -0,0 +1,6 @@
+=============================================
+MRT model
+=============================================
+
+The multi-relaxation time (MRT) lattice Boltzmann model is constructed to approximate the
+solution of the Navier-Stokes equations.

docs/source/userGuide/models/nernstPlanck/nerstPlanck.rst

@@ -0,0 +1,6 @@
+=============================================
+Nernst-Planck model
+=============================================
+
+The Nernst-Planck model is designed to model ion transport based on the
+Nernst-Planck equation.

docs/source/userGuide/visualization/visit.rst

@@ -0,0 +1,5 @@
+======================================
+Visualizing simulation data with visit
+======================================
+
+placeholder for visit