Fixing the documentation

cssr-tools · Oct 28, 2022 · c9d8236 · c9d8236
1 parent a475046
commit c9d8236
Show file tree

Hide file tree

Showing 94 changed files with 20,866 additions and 0 deletions.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_images/contents.png b/docs/_images/contents.png
diff --git a/docs/_images/device.png b/docs/_images/device.png
diff --git a/docs/_images/device_pressure.png b/docs/_images/device_pressure.png
diff --git a/docs/_images/device_tracer.png b/docs/_images/device_tracer.png
diff --git a/docs/_images/device_velocity.png b/docs/_images/device_velocity.png
diff --git a/docs/_images/mesh_1e4.png b/docs/_images/mesh_1e4.png
diff --git a/docs/_images/mesh_1e5.png b/docs/_images/mesh_1e5.png
diff --git a/docs/_images/microsystem.png b/docs/_images/microsystem.png
diff --git a/docs/_images/online_pressure.png b/docs/_images/online_pressure.png
diff --git a/docs/_images/online_tracer.png b/docs/_images/online_tracer.png
diff --git a/docs/_images/online_velocity.png b/docs/_images/online_velocity.png
diff --git a/docs/_images/output.png b/docs/_images/output.png
diff --git a/docs/_images/pressure.png b/docs/_images/pressure.png
diff --git a/docs/_images/pymm.gif b/docs/_images/pymm.gif
diff --git a/docs/_images/pymm_logo.png b/docs/_images/pymm_logo.png
diff --git a/docs/_images/size_0_0_0.png b/docs/_images/size_0_0_0.png
diff --git a/docs/_images/size_100_1_1.png b/docs/_images/size_100_1_1.png
diff --git a/docs/_images/size_500_5_5.png b/docs/_images/size_500_5_5.png
diff --git a/docs/_images/tracer.png b/docs/_images/tracer.png
diff --git a/docs/_images/velocity.png b/docs/_images/velocity.png
diff --git a/docs/_sources/about.rst.txt b/docs/_sources/about.rst.txt
@@ -0,0 +1,18 @@
+==========
+About pymm
+==========
+
+.. image:: ./figs/pymm_logo.png
+
+The image-based Python package for computational fluid dynamics **pymm** was funded by 
+NORCE Norwegian Research Centre As [project number 101070]. 
+
+Contributions are more than welcome using the fork and pull request approach.
+
+If you use **pymm** in your research, please cite the following publication:
+
+.. _Manuscript:
+
+    Liu, N., Haugen, M., Benali, B., Landa-Marbán, D., Fernø, M.A., 
+    Pore-scale spatiotemporal dynamics of microbial-induced calcium carbonate growth 
+    and distribution in porous media. Submitted.
diff --git a/docs/_sources/api.rst.txt b/docs/_sources/api.rst.txt
@@ -0,0 +1,12 @@
+===============
+pymm Python API
+===============
+
+The main script for the **pymm** executable is located in the core folder.
+The templates folder contains mako files.
+
+.. figure:: figs/contents.png
+
+    Files in the pymm package.
+
+.. include:: modules.rst
diff --git a/docs/_sources/configuration_file.rst.txt b/docs/_sources/configuration_file.rst.txt
@@ -0,0 +1,107 @@
+==================
+Configuration file
+==================
+Let us consider the image below (this image and the real dimensions can be 
+extracted from Fig. 52 in `Benali2019 <https://hdl.handle.net/1956/21300>`_ and Fig. 1c 
+in :ref:`Liu2022 <Manuscript>`. 
+
+.. figure:: figs/microsystem.png
+
+    Grains and pore space configuration.
+
+This image (2D) consists of 805x252 pixels, and the real dimensions (3D) are 6.74e-3 x 2.5e-3 x 0.03e-3 [m]. 
+We remark that the image of the pattern used in the numerical simulations in :ref:`Liu2022 <Manuscript>`
+has a much higher resolution.
+
+The current implementation allows for the following input parameters:
+
+.. code-block:: python
+    :linenos:
+
+    """Set the framework parameters"""
+    6.74e-3     #Image-related, length of the microsystem [m]
+    2.5e-3      #Image-related, height of the microsystem [m]
+    0.03e-3     #Image-related, depth of the microsystem [m]
+    160         #Image-related, threshold for converting the image to binary
+    1.0         #Image-related, rescaled factor for the input image
+    0           #Image-related, minimum size of the grain clusters
+    0           #Image-related, tolerance to approximate the border as polygon
+    0           #Image-related, tolerance to approximate the grains as polygon
+    1.0         #Figure-related, line width to show the contours in the produced figures
+    0.2e-3      #Device-related, width of the top and bottom channels in the micromodel device [m]
+    8e-6        #Mesh-related, mesh size [m]
+    1e-6        #Fluid-related, kinematic viscosity [Dynamic viscosity/fluid_density, m2/s]
+    1e-12       #Tracer-related, diffusion coefficient [m2/s]
+    5.0e-4      #Simulation-related, inlet boundary condition (Pressure/fluid_density, [Pa/(kg/m3)])
+    120.0       #Simulation-related, end time for the tracer simulation [s]
+    1.0         #Simulation-related, time interval to write the tracer results [s]
+    1e-7        #Solver-related, convergence criterium for the pressure solution in the numerical scheme for the Stokes simulation
+    1e-8        #Solver-related, convergence criterium for the velocity solution in the numerical scheme for the Stokes simulation
+    10000       #Solver-related, maximum number of iterations for the Stokes simulation in case the convergence criteria have not been reached
+    1.0         #Solver-related, time step in the numerical scheme for the Tracer simulation [s]
+    
+.. warning::
+    Do not remove # in each line (in the current implementation this is used for the reading of the parameters).
+
+************************
+Image-related parameters
+************************
+
+The three first parameters set the real dimensions of the microsystem. The next parameter sets the threshold 
+value to convert the image to binary (valid values from 0 to 255). The rescaled factor parameter reduces the number
+of pixels of the image (valid values between 0 and 1, see 
+`skimage.transform.rescale <https://scikit-image.org/docs/stable/api/skimage.transform.html#skimage.transform.rescale>`_. 
+The minimum size of the grain clusters controls the number of pixels to consider for the internal grains (valid values are
+greater than 0, see `porespy.filters.trim\_small\_clusters <https://porespy.org/modules/generated/porespy.filters.trim\_small\_clusters.html>`_ ). 
+The two following parameters, for setting the tolerance to approximate the contours of polygons, reduce the number of points in the extracted border 
+and internal grains respectively (valid values are 0 or greater than 0, see `skimage.measure.approximate\_polygon <https://scikit-image.org/docs/stable/auto\_examples/edges/plot\_polygon.html>`_ ). 
+The following figure shows the internal grains and border for three decreasing values of the minimum size cluster and tolerances.
+
+.. figure:: figs/size_500_5_5.png
+.. figure:: figs/size_100_1_1.png
+.. figure:: figs/size_0_0_0.png
+
+    Extracted contours for minimum size of the cluster grains and tolerances for the polygon approximation of (top) 500, 5, 5, (middle) 100, 1, 1, and (bottom) 0, 0, 0, respectively.
+
+.. tip::
+    The smaller are these numbers, the more detail is included in the mesh; however, this increases the execution
+    time to create the mesh and to run the simulations. 
+
+*************************************
+Figure- and device-related parameters
+*************************************
+
+The figure parameter controls the line width of the contours on the output images, while the device parameter controls the
+width of the channels in the device microsystem (see the following subsection for details about the implemented device).
+
+***********************
+Mesh-related parameters
+***********************
+
+Currently the only input parameter (via de configuration file, one can always modify the template files) for the mesh is 
+the mesh size. The following figure shows the generated mesh for two different mesh sizes.
+
+.. figure:: figs/mesh_1e4.png
+.. figure:: figs/mesh_1e5.png
+
+    Two different generated meshes of sizes (top) 1e-4 and (bottom) 1e-5.
+
+There are currently two template files that define the configuration of the microsystem: image.mako and device.mako.
+The template image.mako considers that the flow is from top to bottom of the image, while device.mako creates the micromodel geometry as in 
+`Benali2019 <https://hdl.handle.net/1956/21300>`_ and :ref:`Liu2022 <Manuscript>`. On the grains and device walls we consider no-slip conditions. Then one could look at those files to modify the values (e.g., the 
+flow direction or create quad elements for the mesh) or to define new micromodel geometries (e.g., a micromodel with a vertical cross-type shape).
+The following figure shows the geometry of the device micromodel.
+
+.. figure:: figs/device.png
+
+    Geometry of the device mode.
+
+********************
+Remaining parameters
+********************
+
+The remaining parameters are OpenFOAM related. Refer to the online OpenFOAM resources for details about
+the simulator and `this nice presentation <https://www.slideshare.net/ElwardiFadli/permeability-of-soils>`_ 
+using the OpenFOAM solver simpleFoam in another micromodel application. Details about the solver simpleFoam 
+and mathematical model can be found `in this link <https://openfoamwiki.net/index.php/OpenFOAM_guide/The_SIMPLE_algorithm_in_OpenFOAM>`_.
+Details about the solver scalarTransportFoam and mathematical model can be found `here <https://openfoamwiki.net/index.php/ScalarTransportFoam>`_.
diff --git a/docs/_sources/device.rst.txt b/docs/_sources/device.rst.txt
@@ -0,0 +1,21 @@
+======
+Device 
+======
+
+Here we consider the same image and configuration file as in the 
+:doc:`Image example <./image>`, but we are interested now on the
+device setup (the flow is from the top-left corner to the bottom-right
+corner of the device). Then we add the corresponding flag to the **pymm**
+executable:
+
+.. code-block:: bash
+
+    pymm -t all -m device
+
+The execution time was ca. 35 minutes and the following are screenshots of the simulation results:
+
+.. figure:: figs/device_pressure.png
+.. figure:: figs/device_velocity.png
+.. figure:: figs/device_tracer.png
+
+    Simulation results of the (top) pressure, (middle) velocity, and (bottom) tracer concentration.
diff --git a/docs/_sources/examples.rst.txt b/docs/_sources/examples.rst.txt
@@ -0,0 +1,9 @@
+********
+Examples
+********
+
+.. include:: image.rst
+
+.. include:: device.rst
+
+.. include:: online.rst
diff --git a/docs/_sources/image.rst.txt b/docs/_sources/image.rst.txt
@@ -0,0 +1,26 @@
+=====
+Image 
+=====
+
+In this example we consider the micromodel described in the
+:doc:`configuration file<./configuration_file>` section.
+
+The image is available in the examples folder in the `Github page <https://github.com/daavid00/pymm>`_
+with the default name 'microsystem.png'. The configuration file corresponds to the one in the 
+:doc:`configuration file<./configuration_file>` section and it is saved as 'parameters.txt' 
+(the default name for the configuration file). Since 'image' is the default entry for the simulation
+setup (i.e., the flow is from top to bottom), and assuming that the command 'gmsh' in the terminal 
+executes Gmsh, then to run the whole framework (meshing, flow, and tracer) it is enough to add the 
+'-t all' command line to the pymm executable:
+
+.. code-block:: bash
+
+    pymm -t all
+
+The execution time was ca. 20 minutes and the following are screenshots of the simulation results:
+
+.. figure:: figs/pressure.png
+.. figure:: figs/velocity.png
+.. figure:: figs/tracer.png
+
+    Simulation results of the (top) pressure, (middle) velocity, and (bottom) tracer concentration.
diff --git a/docs/_sources/index.rst.txt b/docs/_sources/index.rst.txt
@@ -0,0 +1,21 @@
+.. pymm documentation master file
+
+Welcome to pymm's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 4
+
+   introduction
+   configuration_file
+   examples
+   api
+   output_folder
+   about
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/_sources/introduction.rst.txt b/docs/_sources/introduction.rst.txt
@@ -0,0 +1,37 @@
+============
+Introduction
+============
+
+.. image:: ./figs/pymm.gif
+
+This documentation describes the content of the **pymm** package.
+This package relies on python packages (e.g., `porespy <https://porespy.org>`_ and 
+`skimage <https://scikit-image.org>`_) to generate the spatial domains for the simulations from
+the microsystem images, and `Gmsh <https://gmsh.info>`_ as a mesh generator. 
+The numerical simulations for the water flow and tracer are performed using 
+the `OpenFOAM <https://www.openfoam.com>`_ simulator. This framework could be applied to general images and 
+the current implementation could be ('easily') extended to consider further 
+geometry of devices and solvers in OpenFOAM.
+
+Overview
+--------
+
+The current implementation supports the following executable with the argument options:
+
+.. code-block:: bash
+
+    pymm -i image.png -p configuration_file.txt -o output -m image -t all -g gmsh
+
+where 
+
+- \-i, \-image: The base name of the image ('microsystem.png' by default).
+- \-p, \-parameters: The base name of the :doc:`configuration file <./configuration_file>` ('parameters.txt' by default).
+- \-m, \-mode: The configuration of the microsystem, currently only image and device supported ('image' by default).
+- \-t, \-type: Run the whole framework ('all'), only the mesh part ('mesh'), keep the current mesh and only the flow ('flow'), flow and tracer ('flowntracer'), or only tracer ('tracer') ('mesh' by default).
+- \-o, \-output: The base name of the :doc:`output folder <./output_folder>` ('output' by default).
+- \-g, \-gmsh: The full path to the Gmsh executable or simple 'gmsh' if it runs from the terminal ('gmsh' by default).
+
+Installation
+------------
+
+See the `Github page <https://github.com/daavid00/pymm>`_.
diff --git a/docs/_sources/modules.rst.txt b/docs/_sources/modules.rst.txt
@@ -0,0 +1,7 @@
+pymm
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   pymm
diff --git a/docs/_sources/online.rst.txt b/docs/_sources/online.rst.txt
@@ -0,0 +1,50 @@
+======
+Online 
+======
+
+In this example we consider a micromodel available online in Fig. 2a in 
+`Joekar-Niasar et al. 2009 <https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2007WR006641>`_.
+
+The image was extracted by screenshot and saved with the name 'online.png' (1068x1068 pixels).
+The configuration file was saved as 'configuration.txt' and contained the following text:
+
+.. code-block:: python
+    :linenos:
+
+    """Set the framework parameters"""
+    600e-6      #Image-related, length of the microsystem [m]
+    600e-6      #Image-related, height of the microsystem [m]
+    1.8e-6      #Image-related, depth of the microsystem [m]
+    160         #Image-related, threshold for converting the image to binary
+    1.0         #Image-related, rescaled factor for the input image
+    50          #Image-related, minimum size of the grain clusters
+    1.0         #Image-related, tolerance to approximate the border as polygon
+    1.0         #Image-related, tolerance to approximate the grains as polygon
+    1.0         #Figure-related, line width to show the contours in the produced figures
+    6e-6        #Device-related, width of the top and bottom channels in the micromodel device [m]
+    1e-6        #Mesh-related, mesh size [m]
+    1e-6        #Fluid-related, kinematic viscosity [Dynamic viscosity/fluid_density, m2/s]
+    1e-12       #Tracer-related, diffusion coefficient [m2/s]
+    2.0e-3      #Simulation-related, inlet boundary condition (Pressure/fluid_density, [Pa/(kg/m3)])
+    120.0       #Simulation-related, end time for the tracer simulation [s]
+    1.0         #Simulation-related, time interval to write the tracer results [s]
+    1e-7        #Solver-related, convergence criterium for the pressure solution in the numerical scheme for the Stokes simulation
+    1e-8        #Solver-related, convergence criterium for the velocity solution in the numerical scheme for the Stokes simulation
+    10000       #Solver-related, maximum number of iterations for the Stokes simulation in case the convergence criteria have not been reached
+    1.0         #Solver-related, time step in the numerical scheme for the Tracer simulation [s]
+
+Here we used a version of Gmsh built from source, then we gave the path to the executable via the '-g' flag.
+Since we are interested in the flow and tracer simulations, then we add the flag '-t all'.
+Then, the following command was exectued in the terminal:
+
+.. code-block:: bash
+
+    pymm -i online.png -p configuration.txt -m device -t all -gmsh /home/AD.NORCERESEARCH.NO/dmar/Github/gmsh/build/gmsh
+
+The execution time was ca. 15 minutes and the following are screenshots of the simulation results:
+
+.. figure:: figs/online_pressure.png
+.. figure:: figs/online_velocity.png
+.. figure:: figs/online_tracer.png
+
+    Simulation results of the (top) pressure, (middle) velocity, and (bottom) tracer concentration.
diff --git a/docs/_sources/output_folder.rst.txt b/docs/_sources/output_folder.rst.txt
@@ -0,0 +1,18 @@
+=============
+Output folder
+=============
+
+The following screenshot shows the generated files in the selected output folder after 
+executing **pymm**.
+
+.. figure:: figs/output.png
+
+    Generated files after executing **pymm**.
+
+The simulation results are saved in the VTK_flowSTokes and VTK_tracerTransport folders, and
+`paraview <https://www.paraview.orgs>`_ is used for the visualization.
+Then after running **pymm**, one could modify the generated OpenFOAM related files and 
+run directly the simulations calling the OpenFOAM solvers, e.g., to change additional 
+tolerances that are not currently included in the parameters.txt file and/or to change 
+the numerical schemes (see the OpenFOAM documentation 
+`here <https://www.openfoam.com/documentation/user-guide/6-solving/6.2-numerical-schemes>`_.
diff --git a/docs/_sources/pymm.core.pymm.rst.txt b/docs/_sources/pymm.core.pymm.rst.txt
@@ -0,0 +1,8 @@
+pymm.core.pymm module
+=====================
+
+.. automodule:: pymm.core.pymm
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/_sources/pymm.core.rst.txt b/docs/_sources/pymm.core.rst.txt
@@ -0,0 +1,19 @@
+pymm.core package
+=================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pymm.core.pymm
+
+Module contents
+---------------
+
+.. automodule:: pymm.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/_sources/pymm.rst.txt b/docs/_sources/pymm.rst.txt
@@ -0,0 +1,19 @@
+pymm package
+============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pymm.core
+
+Module contents
+---------------
+
+.. automodule:: pymm
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members: