From ae2e542cf50269f6a91acd6a1acb5ed6f7e9d8bb Mon Sep 17 00:00:00 2001 From: James McClure Date: Mon, 25 Oct 2021 17:06:05 -0400 Subject: [PATCH] updating documentation --- docs/source/examples/color/steadyState.rst | 5 + docs/source/examples/morphology/morphOpen.rst | 106 ++++++++++++++++++ docs/source/examples/running.rst | 2 +- docs/source/index.rst | 2 +- docs/source/userGuide/IO/fileformat.rst | 6 +- docs/source/userGuide/index.rst | 1 + docs/source/userGuide/models/color/index.rst | 5 + 7 files changed, 122 insertions(+), 5 deletions(-) create mode 100644 docs/source/examples/color/steadyState.rst create mode 100644 docs/source/examples/morphology/morphOpen.rst diff --git a/docs/source/examples/color/steadyState.rst b/docs/source/examples/color/steadyState.rst new file mode 100644 index 00000000..997f882e --- /dev/null +++ b/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. diff --git a/docs/source/examples/morphology/morphOpen.rst b/docs/source/examples/morphology/morphOpen.rst new file mode 100644 index 00000000..6f06d08b --- /dev/null +++ b/docs/source/examples/morphology/morphOpen.rst @@ -0,0 +1,106 @@ +***************************** +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 = "16bit" // 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 = 7.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 + InletLayers = 0, 0, 6 // specify 6 layers along the z-inlet + BC = 0 // fully periodic BC + Sw = 0.20 // 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.500000 + 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.805149 30.772243 + 0.727353 29.233631 + 0.719791 27.771949 + 0.714883 26.383352 + 0.710861 25.064184 + 0.637249 23.810975 + 0.444570 22.620426 + Final void fraction =0.444570 + Final critical radius=22.620426 + 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``. diff --git a/docs/source/examples/running.rst b/docs/source/examples/running.rst index 43536b75..70a36dfa 100644 --- a/docs/source/examples/running.rst +++ b/docs/source/examples/running.rst @@ -1,5 +1,5 @@ ============== -LBPM examples +Examples ============== There are two main components to running LBPM simulators. diff --git a/docs/source/index.rst b/docs/source/index.rst index fc5225d1..4e093bab 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,9 +12,9 @@ LBPM -- Documentation :caption: Contents: install - examples/* userGuide/* developerGuide/* + examples/* publications/* Indices and tables diff --git a/docs/source/userGuide/IO/fileformat.rst b/docs/source/userGuide/IO/fileformat.rst index faec04a6..c1da21cf 100644 --- a/docs/source/userGuide/IO/fileformat.rst +++ b/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 diff --git a/docs/source/userGuide/index.rst b/docs/source/userGuide/index.rst index a3b8f198..6c42a02a 100644 --- a/docs/source/userGuide/index.rst +++ b/docs/source/userGuide/index.rst @@ -12,3 +12,4 @@ Welcome to the LBPM user guide. visualization/* + IO/* diff --git a/docs/source/userGuide/models/color/index.rst b/docs/source/userGuide/models/color/index.rst index 82a3c919..8a7f2519 100644 --- a/docs/source/userGuide/models/color/index.rst +++ b/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