Multiphase Lattice Boltzmann Method (LBM) for the simulation of water retention behaviour in unsaturated granular media: ======================================================================================================================== This readme file contains metadata describing the context of the code, the simulation and the scientific data made available in this repository. Also information on how to run a simulation is given. 0. Context: ----------- This data set contains a multiphase Lattice Boltzmann model for the simulation of water retention behaviour in granular media. Besides the C++ source code, related files for the model generation as well as results files and results plots are appended. The LBM model is based on CT scanned granular (porous) media based on publications listed in the following. The experimental set-up used in the experiments is fully described in the following publication: [1] Milatz, M. (2020): An automated testing device for continuous measurement of the hysteretic water retention curve of granular media. In: Acta Geotechnica 8 (15). DOI: 10.1007/s11440-020-00922-y. The CT data for numerical simulations is based on the following data set published via TORE: [2] Milatz, M., Andò, E., & Viggiani, G. (2022): Data from in situ X-ray CT imaging of transient water retention experiments with cyclic drainage and imbibition. TUHH Open Research (TORE). DOI: 10.15480/336.4291. The LBM code as well as its application to multiphase flow in granular soils are further described in: [3] Milatz, M. (2022): Investigation of capillary effects on the grain scale by means of in situ experiments, imaging and numerical simulations. Habilitation thesis. Hamburg University of Technology. 1. Multiphase Lattice Boltzmann model: -------------------------------------- The multiphase Lattice Boltzmann model is based on the single-component Shan-Chen multiphase Lattice Boltzmann formulation as presented in the textbook by Huang et al.: [4] Huang, H., M. C. Sukop, and X.-Y. Lu (2015): Multiphase lattice Boltzmann methods: Theory and application. Chichester: Wiley Blackwell. The C++ implementation of the multiphase LBM in this data set is based on the Fortran code presented by Huang et al. (2015) in Chapter 2 and related Appendix of their textbook which is originally intended to model a "single component multiphase droplet contacting a wall". It has also been published online for own use and teaching purposes in the repository of the textbook. For the simulation of water retention behaviour in granular media, the Fortran code from [4] has been transferred to C++ with the possibility of parallelisation using OpenMP and it has been enhanced to consider simulation domains based on CT input data, to initialise density from a perturbed random field of densities leading to an initial phase separation step, to change the macroscopic degree of saturation after phase separation based on a density injection scheme as described in [5], to write relevant macroscopic data, such as macroscopic degree of saturation and capillary pressure, and to follow prescribed paths of degree of saturation as described in [3]. [5] Hosseini, R., K. Kumar, and J.-Y. Delenne (2021): Investigating the effect of porosity on the soil water retention curve using the multiphase Lattice Boltzmann Method. In: Proc. of Powders & Grains 2021 - 9th International Conference on Micromechanics on Granular Media. DOI: 10.1051/epjconf/202124909007. The following files of this repository are related to the multiphase LBM code: LBM.cpp -> C++ source code including the multiphase LBM for the simulation of water retention behaviour params.txt -> Text file containing model parameters 2. Generation of LBM simulation model: -------------------------------------- The LBM model geometry file geometry_data.txt is written by the Python script write_geometry_data.py. This Python script reads a 3D binary tifffile, e. g., from CT scans, including ones for solid nodes and zeros for pore nodes to create the output file geometry_data.txt. The following files are related to model generation: Sand_002_00_solid_phase_400x400x400_bin2.tif -> 3D tifffile containing the model information (can be opened using a tifffile reader, e. g. ImageJ/FiJI) write_geometry_data.py -> Python script for reading a tifffile and creating a geometry file for simulation geometry_data.txt -> Text file containing the model geometry (ones = solid, zeros = pore, read as a matrix of the LBM simulation domain) 3. Instructions for running a simulation: ----------------------------------------- a) Create the file geometry_data.txt by running the Python script write_geometry_data.py to read a 3D tifffile containing the model information (1 = solid node, 0 = pore node). The tifffile needs to be placed in the same folder as the Python script and the tifffile name as well as its 3D dimensions (lx, ly, lz) must be indicated in the script. b) Set up simulation parameters in the text file params.txt: Example contents of params.txt: Droplet radius RR, density of wall rho_w, tau(1), maximum time step, Output every Nwri time steps 15., 0.35084, 1.0, 1500001, 5000 Note: The first entry (Droplet radius) is currently not needed. Leave it as it is. c) Set further global parameters in the LBM.cpp source code: In the case of OpenMP usage, set the number of threads: -> e. g.: int selected_number_of_threads = 28; Set the model dimensions and make sure that they match the dimension of the matrix stored in the tifffile and related file geometry_data.txt: -> e. g.: const int lx = 200, ly = 200, lz = 200; d) Compile the code, e. g., using: g++ -o LBM LBM.cpp -fopenmp -mcmodel=medium -std=gnu++11 Note: Make sure that the files params.txt and geometry_data.txt are in the same folder as the source code. e) Run the compiled code, e. g. using the command: ./LBM Note: Make sure that the available hardware complies with the requested resources (e. g., number of threads). The given example simulation has been run on a HPC-cluster. 4. Model output: ---------------- The simulation produces the following output files: unsat_results.txt -> Results file storing different state variables, e. g., degree of saturation and capillary pressure, in each time step *.plt -> Results files containing temporal field (spatial) output (for all computation cells), e. g., density and pressure. This file is written for the initial time step and on request every Nwri time steps as indicated in the file params.txt. 5. Visualisation of results: ---------------------------- The results files can be read for visualisation using Python or ParaView. The Python script analysis.py reads the file unsat_results.txt in order to create plots, e. g., of the state variables and their temporal evolution. analysis.py -> Python scrit to read the file unsat_results.txt for creating plots, e. g., of the state variables and their temporal evolution For the visualisation of spatial results using ParaView, the *.plt files need to be transformed into .vts-files using the Python script write_spatial_data_to_vts_file.py. This script creates the files pressure_t_*.vts, density_t_*.vts and obstacles_t_*.vts for every desired time step * from the corresponding spatial results file *.plt. The .vts-files can then be interpreted by ParaView. write_spatial_data_to_vts_file.py -> Python script for the transformation of *.plt files into .vts-files containing spatial density and pressure data. Note: write_spatial_data_to_vts_file.py requires the Python package and library PyEVTK by Paulo Herrera which can be found on Github (https://github.com/paulo-herrera/PyEVTK) and which is described in a dedicated Wiki (https://vtk.org/Wiki/VTK/Writing_VTK_files_using_python).